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.
- Read the release notes between your version and the target, especially any Breaking and Upgrade note entries.
- 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.
- Stop the old server (SIGTERM; it drains requests and exits).
- Start the new version on the same store and settings.
- Check
GET /v0/version,GET /v0/health(200,writer: "ok") and the startup log, then run a few representative queries. - Optionally run
POST /v0/admin/compactto 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.
| From | To | Rule |
|---|---|---|
| 3.1.x or later | 3.0.x | Flush first (POST /v0/admin/flush). 3.1 writes WAL format v2, which 3.0 refuses. |
| 3.x | 2.x | Not 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-intervalabove 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 504timeout. 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_BYTESnow 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 413query_memory_limitinstead of growing until the process is killed. Before upgrading, check that your largest legitimate queries fit; size or disable the budget withNAMIDB_QUERY_MEMORY_MAX_BYTES(0turns 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_codeandgql_status; itserrortext 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) andfrom(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=…®ion=…) 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/restorein 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_pathyields a fourth column,path. Calls thatYIELDnamed columns are unaffected; clients that read columns by position are.MATCHnever binds one relationship twice in a pattern, and anOPTIONAL MATCHmatches its whole pattern or nothing. Some queries return fewer (correct) rows.- Python:
merge_nodesnow merges into existing nodes (the old replace behaviour isput_nodes), and bulk rows take the node id from_id(rows keyed byidstill work and also keepidas 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-authexplicitly. - Since 2.2.0 the official image runs as uid
65532; bind-mounted data directories needchown -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.