Upgrading & Migration

Relata DB 3.0
See the "Upgrading to 3.0" section below. The sections that follow describe upgrades between 2.x versions.

This page records the compatibility facts the code actually guarantees. Anything not verified by a test or an explicit version check is marked untested — verify before relying rather than claimed as a guarantee. Source: the repo's upgrading guide.

Always back up first. Take and relata verify-backup <path> a full snapshot before touching any node. Restore forward (old → new), not backward — backward format/version compatibility is untested.

Upgrading to 3.0

Upgrade path not tested
An in-place upgrade of a real 2.7.1 (or later 2.x) data directory to 3.0 is not tested; the procedure documented for 3.0 is a migration into a fresh node. Rehearse on a copy with a verified backup, and treat the list below as the set of changes to plan for, not as a tested path.

3.0 is a major release with these breaking changes:

  • HTTP routes move under /v1/ with no aliases. Update base URLs, scripts and monitoring. Old paths answer 404. See HTTP route restructure.
  • Protocol doors are retired: PostgreSQL wire, Arrow Flight, the S3-compatible listener, Redis, MongoDB, ClickHouse, Neo4j HTTP, Bolt and /sparql. Stored data is kept. See Migrating from retired doors.
  • Single machine, single tenant. Clustering, multi-tenancy, tenant administration, platform administration and tamper-evident audit are Enterprise. The server and cluster values of RELATA_PROFILE are being retired, and RELATA_TENANCY_MODE=multi is a fatal startup error in the open edition.
  • SDK changes: removed and reshaped wrappers; see the SDK changes.
  • ETL boundary: connectors, Sigma conversion, document preparation and model-backed extraction move to OpenETL.
  • Removed SQL operators: the face, voice and perceptual-hash match operators.

There is no relata upgrade command. Moving versions is a package or binary swap, and the supported rollback is relata restore of a backup taken before the swap. Take and verify a backup first (Backup and restore). For moving data from another system see SIEM/SOC migration. What is and is not evidenced: 3.0 evidence status.

Upgrading to 2.4.0

2.4.0 is not a breaking release in the semver sense — no format or SQL changes — but it carries several server/cluster-profile boot-time enforcement changes that will crash-loop an existing deployment upgraded in place unless the required env vars are already set:

  • RELATA_ERASURE_SIGNING_KEY is now a hard boot dependency on server/cluster (#4797). The GDPR erasure-proof preflight now FATAL-exits at startup if this key is unset — previously it only failed lazily, on the first erasure request. Before upgrading a server/cluster deployment, set RELATA_ERASURE_SIGNING_KEY. free-profile deployments are unaffected (an unset value still derives a key from RELATA_BEARER_TOKEN, #1389). Data is never at risk — only availability (the container will not start until the var is present).
  • Lone weak-security opt-outs no longer boot (#4945). RELATA_KMS_LOCAL_DEV (and siblings RELATA_UNSAFE_LOCAL_FENCING, RELATA_GRPC_PLAINTEXT_OK) now require RELATA_SECURITY_MODE=open to take effect on server/cluster — set alone, they FATAL at boot instead of silently degrading security. If your dev/lab deployment (commonly copied from pre-2.4.0 docs or compose files) sets any of these, add RELATA_SECURITY_MODE=open alongside them before upgrading — or remove them if the opt-out was unintentional.
  • RELATA_MAX_TENANTS now clamps to the profile/license ceiling instead of overriding it (#4967). A deployment that set this above its actual license or profile ceiling to work around the old bug will silently get the lower, correct ceiling after upgrading — not a boot failure, but worth checking if you rely on tenant capacity near the limit.
  • /query is read-only; writes go through the ingest door. This has been the engine's contract since #782, but pre-2.4.0 quickstarts (including earlier versions of this portal's) documented an INSERT-via-query() write path by mistake — 2.4.0's #4977 corrected them. Any script still sending INSERT/UPDATE through /query's query()/execute() path gets 400 Purpose rejected: /query is read-only; use the SDK ingest client (IngestClient.bulk() / POST /ingest).

2.4.1 is a patch on top with no new boot gates — its headline fix is the org-isolation Guard 6 fallback to dynamic ownership records (#5088), so under multi-tenant mode a custom ontology type no longer needs to be pre-declared in RELATA_TYPE_OWNERS to be readable by its own owning tenant. Full details: the project's CHANGELOG.

Validate the exact upgrade shape you use (container recreated on preserved volumes, or a fresh deploy pointed at existing storage) against a staging copy first — see Rolling-upgrade ordering for the general procedure.

Upgrading to 2.2.0

2.2.0 is not a breaking release — no format, config, or SDK changes.

Full details: the project's CHANGELOG.

Upgrading to 2.1.0

2.1.0 is not a breaking release — no format, config, or SDK changes — but it carries two security fixes worth knowing about before you upgrade, since they change what previously worked as a credential:

  • RELATA_BEARER_TOKEN no longer authenticates the HTTP data plane, with no opt-out. In earlier 2.x builds this was an opt-in-hardened behavior; it is now mandatory on every profile. If anything in your deployment was still using the raw bearer token against /query, /ingest, /search, etc. (rather than a registry-minted, tenant-scoped token from POST /admin/tokens or /tokens/self/*), it will start getting 401s after upgrading — mint and switch to a tenant-scoped token first. See Auth & Security.
  • Tenant self-service token routes (/tokens/self/list, /tokens/self/:id, /tokens/self/audit) no longer accept a sys-admin credential. If any tooling was relying on RELATA_ADMIN_TOKEN working there, switch it to the tenant's own token, or to the loopbound /admin/tokens* routes for cross-tenant management.

Also in this release: POST /admin/tokens can now bootstrap the first tenant-scoped credential for a brand-new tenant directly (pass tenant_id in the request body as the static admin) — see Reaching the admin listener from a second (sidecar) container if you need a durable credential for a long-running second container/service. Full details: the project's CHANGELOG.

Upgrading to 2.0.0

2.0.0 is a major release with breaking changes (semver-mandated by the Zero-Trust / licensing / tenancy work). Review before upgrading from 1.x:

  • Multi-tenant gating. RELATA_TENANCY_MODE=multi was restricted in 2.0.0 to the clustered profile. In 3.0 it is refused on the open build; several tenants are Relata Enterprise DB. See Editions and Limits.
  • Licensing changed. The earlier binary storage capability was replaced; see Editions and Limits for the current position.
  • Zero-Trust admin surface. /admin/* and /platform/* moved to a separate loopbound listener (RELATA_ADMIN_BIND, default 127.0.0.1:9091); they are no longer served on RELATA_HTTP_BIND. Set RELATA_ADMIN_TOKEN and reach the surface via port-forward / sidecar.
  • Auth posture uniform. No more implicit free-profile dev bypass — set RELATA_OPEN_DEV_ALLOWED=true explicitly for unauthenticated local dev, on every profile.
  • Go SDK → github.com/relatadb/sdk-go/v2. The major-version import-path suffix is mandatory; update your imports. See SDKs.
  • Version lockstep. Server and all SDKs/tray/Grafana/Helm now ship one version, enforced by the repo's check_versions.py.

Validate on a staging copy of your data first; back up before upgrading.

On-disk / artefact format compatibility

Manifest (object-store layout)

relata-storage::manifest::ManifestVersion is the source of truth for the commit-manifest layout. Two variants exist: V1Single (legacy single file) and V2Sharded (sharded layout) — new writes always emit V2Sharded. Readers detect the version from the index object. There is no in-place V1→V2 rewriter; the migration story for an existing V1 store is untested — verify before relying (prefer a fresh V2 store seeded from a restore over an in-place flip).

Backup snapshot format

relata-storage::backup::BackupPayload is a self-describing JSON artefact (full-<ts>.json / incr-<ts>.json) with schema_version: u32 (currently 1). Cross-tenant restores are enforced (assert_agency aborts a payload/organisation mismatch). Tenant-scoped restore (POST /admin/restore {"tenant": "..."}) is rejected outright (501) — the store-swap is an unconditional whole-store replacement, so a tenant-scoped request would silently wipe every other tenant. Restore only without a tenant field until a true per-tenant merge ships.

Restoring a backup taken by a newer build into an older binary is untested — verify before relying. Always run relata verify-backup <path> before depending on a snapshot.

Ontology version monotonicity

relata-ontology::OntologyVersion(u64) is a monotonically-increasing counter, bumped on every type addition/modification and stored in the commit manifest. The version only ever moves forward within a branch; it never rewrites history. Downgrading the binary does not roll the ontology version back — an older binary reading a higher ontology version is untested — verify before relying.

Rolling-upgrade ordering (recommendation)

This ordering is a recommendation, not an enforced/tested invariant:

  1. Back up first — take and verify-backup a full snapshot before touching any node.
  2. Validate config — the CLI fails fast (exit 78, EX_CONFIG) on an invalid RELATA_* enum/numeric value. Apply config changes to one node and confirm it starts clean before rolling out.
  3. Stop cleanly — relata stop (or SIGTERM) drains in-flight work and flushes the WAL; wait for the process to exit and release the data-directory lock before starting the new binary.
  4. Start the new binary on the same data directory and wait for GET /health/ready to return 200 before routing traffic. A 3.0 node is a single process, so an upgrade has a short interruption; plan for it.
  5. Rolling upgrades across nodes (followers first, drain before stopping) apply only to Relata Enterprise DB clusters and are not described here.
  6. Roll back by restoring, not by downgrading in place — backward format/version compatibility is untested.

Config migration

relata config --migrate          # migrate relata.toml / env vars across versions

The CLI now fails fast on invalid RELATA_* enum/numeric values and logs the offending variable, so config drift surfaces at startup rather than at runtime.

Data migration

PathWhenDocs
relata import --from postgres|csvMigrate an existing database into RelataConnectors & Extensions · Ingestion
relata config --migrateMigrate config across versionsabove
Embedding-model migrationChange the sidecar model / vector dimensionLLM & Embedding configuration
Backup → restoreWhole-store migration / disaster recoveryBackup & Restore

For Neo4j / MongoDB / ClickHouse, relata import --from <source> is an honest stub today — each prints the documented CSV/NDJSON export workaround and exits non-zero.

v1.4.2 → v1.5.0 (reference)

A backward-compatible upgrade. /query responses added processing_time_ms alongside elapsed_ms (the latter retained for one release, removed in v1.6.0). QueryError exposed stable REL_* codes; the RFC 7807 type URI changed from about:blank to https://relatadb.dev/errors/{code}. 429 responses added X-RateLimit-* headers. Admission control moved to a real cost estimate (row count × join multiplier). Rolling: upgrade reader/indexer nodes first, writers last; all in-flight writes are safe (formats compatible).

See also