SurrealDB Migration Release Notes

Sibyl now starts the SurrealDB runtime by default. New installs should use SurrealDB for graph, content, and auth. Do not start new deployments on FalkorDB or PostgreSQL auth.

Legacy FalkorDB runtime support was retired after the v0.6.0 compatibility release. PostgreSQL auth was removed after the same release, and active content/RAG runtime paths now resolve through SurrealDB. Structured auth/content archive export now reads SurrealDB; retained postgres.sql payloads are restore-only evidence for rehearsal or rollback validation, not ambient runtime sidecars.

What changed

• moon run dev starts the SurrealDB runtime.
• SIBYL_STORE=surreal and SIBYL_AUTH_STORE=surreal are the default settings.
• The local moon run dev-legacy fallback has been retired after the v0.6.0 compatibility release.
• moon run dev detects local legacy data before creating a fresh Surreal dev runtime.
• The live local FalkorDB migration wrapper has been retired; use archive import instead.
• Graphiti Core is no longer a supported sibyl-core dependency. Legacy Graphiti-shaped archives and records are handled by Sibyl-owned Surreal projection and import code.

Existing local installs

If you have an old local FalkorDB + PostgreSQL install, export an archive from the v0.6 compatibility release before upgrading, then import it into SurrealDB:

uv run --directory apps/api sibyld migrate import <archive> \
  --source-type legacy-archive \
  --target-mode surreal \
  --dry-run

uv run --directory apps/api sibyld migrate import <archive> \
  --source-type legacy-archive \
  --target-mode surreal \
  --yes \
  --clean

Every archive import, rehearsal, and cutover now requires an explicit source type and target mode. Use --source-type surreal-archive --target-mode surreal for Surreal-native archive restores. Use --source-type legacy-archive --target-mode surreal for historical FalkorDB/PostgreSQL migration archives imported into SurrealDB.

Use --restore-database-dump only for PostgreSQL rehearsal evidence, and always pair it with --source-type legacy-archive --target-mode postgres-rehearsal. postgres.sql is a historical migration payload, not the default restore path.

Existing production installs

Use the full migration playbook, not the local shortcut:

1. Back up the legacy install.
2. Export the legacy archive.
3. Rehearse the archive against a disposable SurrealDB target.
4. Import into SurrealDB.
5. Start a Surreal-backed API on a private cutover endpoint.
6. Run archive verification.
7. Run the auth-flow replay against the Surreal-backed API.
8. Run the auth-flow replay against the target API.
9. Run the Surreal cutover gate while writes are frozen.
10. Freeze legacy auth/RBAC writes during the rollback window.

Start with Migrating from FalkorDB.

Use SurrealDB 3.x for the target runtime, and pin the exact server image/tag used during rehearsal before cutting over production.

Release owners should execute the live gate checklist in docs/_archive/SURREALDB_PHASE2_LIVE_GATES.md before tagging the SurrealDB-first release.

sibyld migrate auth-flow-compare refuses to compare one API to itself by default. Start one legacy-auth API and one Surreal-auth API, then pass distinct --postgres-base-url and --surreal-base-url values. Use --allow-same-base-url only when debugging the harness itself.

Phase 3 archive policy

These paths remain available as migration and rollback evidence while Phase 3 closes the old storage surface:

• archive import, verify, and cutover commands for existing legacy installs
• Surreal-native archive restore through explicit --source-type surreal-archive --target-mode surreal
• retained postgres.sql restore through explicit --restore-database-dump --source-type legacy-archive --target-mode postgres-rehearsal rehearsal commands
• graph archive payload import into SurrealDB with dry-run restore review before writes

The old PostgreSQL auth/RBAC runtime, active PostgreSQL content sidecars, ambient PostgreSQL startup/sync code, local FalkorDB runtime fallback, and Graphiti FalkorDB adapter have been removed. SIBYL_STORE=legacy is now source-side migration context for old installs, not a supported product runtime for new deployments.

The active backup job writes Surreal auth/content snapshots and graph exports. It does not produce new postgres.sql sidecars in fully Surreal mode.

Rollback posture

The migration is explicit and archive-backed. Upgrading does not destructively rewrite your legacy data. If a cutover fails before SurrealDB accepts new writes, point traffic back to the legacy API.

Once SurrealDB accepts new production writes, treating PostgreSQL or FalkorDB as an instant read-write rollback is unsafe. Restore from Surreal backups or replay any affected writes deliberately.