Skip to content

Upgrades

Versioning

Released surfaces follow Semantic Versioning: the server and CLI binaries, the HTTP, Bolt and Cypher surfaces, the Python package, the container images and the on-disk formats. A breaking change bumps the major version and is listed under Breaking in the changelog. Minor and patch releases can still change on-disk details in a forward-compatible way, which matters for downgrades (see below).

Container images are tagged X.Y.Z, X.Y, X and latest. Pin X.Y.Z in production and upgrade deliberately.

Procedure

A namespace has exactly one writer, so do not run old and new servers on the same namespace at once: they fence each other.

  1. Read the release notes between your version and the target, especially any Breaking and Upgrade note entries.
  2. Back up every namespace you serve (Backup and restore). A backup taken before the upgrade is the only way back if the new version rewrites data files in a format the old one cannot read.
  3. Stop the old server (SIGTERM; it drains requests and exits).
  4. Start the new version on the same store and settings.
  5. Check GET /v0/version, GET /v0/health (200, writer: "ok") and the startup log, then run a few representative queries.
  6. Optionally run POST /v0/admin/compact to move old data files to the new format sooner; otherwise compaction does it as data is rewritten.

For the Python client, upgrade the wheel (pip install -U namidb==X.Y.Z) in every process that opens the namespace; stop writers before switching versions, as above.

If an orchestrator replaces instances with overlap, run every instance with --fence-policy yield, so a replaced writer stops writing and reports itself degraded instead of reclaiming the namespace.

Downgrades

Downgrading is only safe to a version that can read everything the newer one wrote. When in doubt, restore the pre-upgrade backup into the older version instead.

FromToRule
3.1.x or later3.0.xFlush first (POST /v0/admin/flush). 3.1 writes WAL format v2, which 3.0 refuses.
3.x2.xNot possible in place once 3.x has written or compacted data files: 2.x fails reading them with corrupted artefact errors. Restore a backup taken before the upgrade.

Version notes

3.3.0

  • No on-disk format changes. 3.3.0 and 3.2.x can replace each other in place. Retention leases written by 3.3.0 carry a scope; 3.2.x reads every lease as a floor, which keeps more history, never less.
  • Restore points are off by default. Turning them on (--restore-point-retention) needs --compaction-interval above zero, or the server refuses to start. Budget the extra storage first: about what each namespace writes during the window. The window starts empty and fills up from there.
  • Timeouts and cancel now stop every operator. Statements that used to run past --query-timeout (cross products, large sorts and aggregations over rows already in memory) now fail at the deadline with 504 timeout. If a job relied on that, raise its budget or narrow the query.

3.2.1

  • Per-query memory budget. A server that sets NAMIDB_MEMORY_MAX_BYTES now also bounds each running statement to half of that ceiling, and all running statements together to 75% of it. A query that needs more than its budget fails with 413 query_memory_limit instead of growing until the process is killed. Before upgrading, check that your largest legitimate queries fit; size or disable the budget with NAMIDB_QUERY_MEMORY_MAX_BYTES (0 turns it off). Servers without a ceiling are unchanged. See Memory.
  • The 503 for a statement refused at memory admission now has a JSON body with code: "memory_pressure", neo4j_code and gql_status; its error text is unchanged.
  • No on-disk format changes: 3.2.1 and 3.2.0 can replace each other in place.

3.2.0

  • Backup allowlist is enforced on parsed URIs. to (backup) and from (restore) must use the prefix’s scheme and bucket, stay at or below its path, and repeat its query parameters exactly. Put store options in --backup-target-uri (s3://bucket/backups?endpoint=…&region=…) and have clients repeat them; a request that adds or changes one is now refused with 403.
  • Numeric keys declared before data. A unique constraint or index declared on an empty label is now typed by the first value written, so numeric keys get their index. A namespace whose 3.1.0 manifest already committed such a declaration as a string keeps it; reload that label into a fresh namespace to get the numeric index.
  • New: POST /:namespace/v0/admin/restore in multi-tenant mode.

3.1.0

  • Vectors, bytes and number lists are written to the WAL in binary (WAL format v2). 3.0.0 cannot read the new segments; flush before downgrading.

3.0.0

Breaking changes:

  • Data-file format. Node data files and their exact-record side-cars use a new layout that 2.x cannot read. 3.0 reads 2.x files and converts them as compaction rewrites them. A downgrade needs a backup from before the upgrade.
  • CALL algo.* rejects unknown options instead of ignoring them (algo.louvain({seed: 1}) now errors). Remove stray keys.
  • algo.shortest_path yields a fourth column, path. Calls that YIELD named columns are unaffected; clients that read columns by position are.
  • MATCH never binds one relationship twice in a pattern, and an OPTIONAL MATCH matches its whole pattern or nothing. Some queries return fewer (correct) rows.
  • Python: merge_nodes now merges into existing nodes (the old replace behaviour is put_nodes), and bulk rows take the node id from _id (rows keyed by id still work and also keep id as a property).

Also new in 3.0: read-only Python clients, timeout_ms / max_rows, --fence-policy, NAMIDB_MAX_CONCURRENT_QUERIES_PER_NAMESPACE, and Bolt read transactions that no longer take the writer lock.

Coming from 2.x

  • Since 2.2.0 the server refuses to start without an auth source; set a token or pass --no-auth explicitly.
  • Since 2.2.0 the official image runs as uid 65532; bind-mounted data directories need chown -R 65532:65532.
  • Bolt error codes for timeouts and result limits changed in 2.2.0 (Neo.ClientError.Transaction.TransactionTimedOut, Neo.ClientError.Statement.ResourceLimitExceeded).

The full history is in the changelog and the engine’s CHANGELOG.md.