Upgrade/Migration Planning, Store Compatibility, Rolling vs Offline Constraints, Plugins, and Rollback

Learning outcomes

Reproducible AtlasMart setup

The drill adds one tiny course-owned marker so recovery correctness has a deterministic invariant even if your earlier AtlasMart graph has grown. The marker is not a substitute for business reconciliation; it is a canary.

CYPHER 25
CREATE CONSTRAINT recovery_marker_id IF NOT EXISTS
FOR (m:RecoveryMarker) REQUIRE m.markerId IS UNIQUE;
MERGE (c:Customer {customerId:'C-1001'})
ON CREATE SET c.name = 'Mina Rahimi'
MERGE (m:RecoveryMarker {markerId:'DR-CH16-001'})
SET m.createdAt = datetime('2026-09-09T17:00:00Z'),
    m.expectedState = 'before-dump',
    m.exercise = 'chapter-16'
MERGE (c)-[:HAS_RECOVERY_MARKER]->(m);
MATCH (m:RecoveryMarker {markerId:'DR-CH16-001'})
RETURN m.markerId, m.expectedState;

1. Upgrade is a dependency graph

AtlasMart does not run “Neo4j” in isolation. It runs a server version against a store format, JVM, Cypher language mode, drivers/Bolt, procedures/plugins, operating system, certificates, automation and application queries. Upgrade safety requires an inventory of all of them plus a validated rollback artifact.

2. Store version and server version are not the same concept

A store format is the on-disk representation. Current docs version formats independently from the calendar server release. Minor format evolution can occur automatically on startup; changing to a higher major format or another format is an explicit neo4j-admin database migrate operation.

SHOW DATABASES YIELD name, currentStatus, store
RETURN name, currentStatus, store;

3. Current format choices and legacy deprecation

The current Community default is aligned. Enterprise uses block as the modern default for new databases. standard and high_limit have been deprecated since 5.23. Current documentation warns that the upcoming vNext LTS planned for November 2026 is the last line to support legacy high_limit operations, so format inventory must happen before that window closes.

4. Pre-upgrade gate: capture evidence before changing anything

CYPHER 25
MATCH (m:RecoveryMarker {markerId:'DR-CH16-001'}) RETURN m.expectedState;
SHOW CONSTRAINTS;
SHOW INDEXES;
SHOW SETTINGS YIELD name, value
WHERE name IN ['db.tx_log.rotation.retention_policy']
RETURN name, value;

neo4j --version
java -version
python -c "import neo4j; print(neo4j.__version__)"
# If APOC is installed, record: RETURN apoc.version();
# If GDS is installed, record its reported version and compatibility matrix.
sha256sum ./neo4j-dr/backups/neo4j.dump

5. Migrate only when the target requires it

neo4j-admin database migrate is an offline administrative operation and is not available as an Aura workflow. It should follow an explicit compatibility plan and backup validation. Do not run it merely because an option exists.

# Inspect the exact target-version migration guide first.
# Stop the disposable target database before a real migration.
neo4j-admin database migrate neo4j

6. Plugin, driver and Cypher compatibility gate

APOC relies on internal Neo4j APIs, so its year/month must match the Neo4j release family. GDS publishes its own compatibility matrix. Drivers are more decoupled but still need supported server/Bolt combinations. Queries should be tested in the language mode you deploy: current development is Cypher 25, while Cypher 5 is frozen for compatibility.

7. Rolling vs offline is a topology/licensing question

A standalone Community DBMS cannot become highly available by performing “rolling restart” steps copied from a cluster guide. Cluster rolling procedures require Enterprise topology, quorum/capacity headroom and the exact upgrade guide for source/target versions. If your required migration/store change is offline, plan downtime or a controlled parallel migration instead of claiming zero downtime.

8. Rollback decision tree

Production judgment

Summary and next step

An upgrade is safe only when compatibility and rollback are proved before production change. Lesson 5 combines artifact recovery, timing, reconciliation, application smoke tests and operator evidence into one repeatable disaster-recovery drill.

Authoritative references

• Current Neo4j versions — Current server and 5.26 LTS release snapshot.
• Backup and restore — Edition-aware entry point for dump/load, online backup, restore and planning.
• Backup and restore planning — RPO/RTO, backup mode, storage location, cadence and retention planning.
• Back up an offline database — neo4j-admin database dump semantics and Community offline boundary.
• Restore a database dump — neo4j-admin database load semantics, overwrite rules and edition differences.
• Back up an online database — Enterprise full/differential backup artifacts and chain semantics.
• Restore a database backup — Enterprise recovery of backup chains and restore-until predicates.
• Check database consistency — neo4j-admin database check for stores, dumps and recovered full backups.
• Transaction logging — Transaction-log retention, checkpointing and pruning behavior.
• Store formats — Current aligned/block formats, limits and legacy-format deprecation.
• Migrate a database — neo4j-admin database migrate and store-format migration boundaries.
• System requirements — Supported Java/runtime and platform requirements for current Neo4j.
• APOC installation — APOC/server release compatibility and restart/deployment coupling.
• GDS compatibility — Graph Data Science and Neo4j version compatibility matrix.
• Python driver installation — Current 6.x driver/server compatibility baseline.