docs(operations): document upgrade and rollback compatibility

Merged
GK
5d ago
+172-5

Summary

Publish a dedicated Upgrades, Downgrades, and Compatibility policy so operators can find FalkorDB's rollback commitment and distinguish graph storage compatibility from Redis/Valkey and replication compatibility.

The maintainer confirmed the intended policy for this change: graph storage-format compatibility is guaranteed between patch releases within the same major.minor line; transitions across minor or major releases require explicit source/target compatibility confirmation.

Changes

  • Add the compatibility policy to Operations navigation and cross-link it from Docker, durability, persistence, replication, and the Operations overview.
  • Include a source-linked graph encoding matrix for the exact 4.20.7, 4.22.3, and 6.0.3 tags; distinguish it from whole-deployment compatibility certification.
  • Document the 19 to 20 storage-format change and why 4.20.7 cannot load a snapshot written by 4.22.3.
  • Separate Redis/Valkey RDB/AOF compatibility, other module requirements, and the documented 4.x/6.0 replication restriction from graph encoding compatibility.
  • Explain pre-upgrade backups, isolated rehearsal, compatible-data rollback, backup-based recovery, and loss of post-backup writes. Explicitly require enabling AOF on a validated running instance after an RDB-only restore, waiting for successful rewrite completion, and persisting configuration before restarting.
  • Keep latest in runnable Docker examples, as requested by the maintainer. Explain in the opening note and best practices that production deployments should replace it with a tested x.y.z release tag or an image digest after reviewing data compatibility; do not lock the Docker guide to 6.0.3.
  • Specify compatibility disclosures required in future release notes, including an explicit statement when the storage format is unchanged. Existing upstream release notes are not modified by this PR.
  • Add Valkey and encodings to the spellcheck dictionary.

Testing

  • node scripts/check_mdx.mjs — 197 MDX files, no syntax errors.
  • mint broken-links — no broken internal links.
  • python3 -m pyspelling -c .spellcheck.yml -n Markdown -S 'operations/upgrades-downgrades-compatibility.mdx' -S 'operations/index.mdx' -S 'operations/docker.mdx' -S 'operations/durability/index.mdx' -S 'operations/durability/persistence.mdx' -S 'operations/replication.mdx' — passed; reran spelling on each subsequently revised page.
  • git diff --check — passed before each commit.
  • Verified all seven runnable falkordb/falkordb-server example tags remain latest, production guidance uses x.y.z, and the Docker page no longer contains a 6.0.3 pin.
  • Cross-checked the encoding matrix against tagged encoding definitions and decoder implementations and the upgrade restrictions against published release notes. Verified the RDB-to-AOF restore procedure against Redis's persistence documentation. No database upgrade/downgrade integration tests were run; this is a documentation-only change.

Memory / Performance Impact

N/A — documentation only.

Related Issues

N/A — addresses user feedback that the public documentation lacked a clear upgrade, downgrade, and rollback policy.

Summary by cubic

Adds a dedicated upgrade, downgrade, and compatibility policy so operators have a documented rollback commitment for FalkorDB's graph storage.

The new page guarantees graph storage compatibility only between patch releases of the same major.minor line, pins the graph encodings written and readable by the 4.20.7, 4.22.3, and 6.0.3 tags, and explains why a 4.20.7 binary cannot load data saved by 4.22.3. It separates graph encoding compatibility from Redis/Valkey persistence and replication restrictions and documents pre-upgrade backup and backup-based rollback procedures, including enabling AOF on a validated running instance after an RDB-only restore, keeping appendonly yes across Docker REDIS_ARGS/Compose startup overrides, and limiting CONFIG REWRITE to writable startup files without overriding arguments so a configuration-only restart cannot discard restored data. Release notes must explicitly state when the storage format changes.

The page is added to Operations navigation and cross-linked from the Docker, durability, persistence, replication, and Operations overview pages. Docker examples keep latest tags; a note directs production deployments to pin an explicit tag or digest and review the policy before reusing an existing data volume.

Summary by CodeRabbit

  • Documentation
    • Added a guide to upgrade, downgrade, and persistence compatibility, with guidance on backups, testing version changes, and rollback.
    • Updated Docker and durability guidance to recommend explicit image versions, verified pre-upgrade backups, and compatibility checks before reusing data volumes.
    • Added a warning against mixing FalkorDB 4.x and 6.0 in a replication group, and linked to compatibility information.
    • Updated the Operations navigation and overview to include the new guide.