Migrations

Change schemas without drift

Migrations apply versioned project schema and policy changes through the trusted administration surface.

Stable IDs, checksums, and explicit ordering make schema state auditable and prevent accidental drift.

Use them for every durable application-schema change, including policy DDL.

Requirements for Migrations

• Prerequisite — A linked project and trusted developer credential.
• Prerequisite — A reviewed migration with a unique stable ID and tested forward/rollback behavior.
• Required value — Migration ID, ordered SQL statements, expected checksum, and target project.
• Required value — A backup and maintenance decision for destructive or long-running changes.

Migration format

Both directions are required. ffdb migration create add_documents writes <epoch-milliseconds>_add_documents.sql in the current directory; 1754179200000 is an illustrative timestamp. The CLI hashes the stable id, name, up SQL, and down SQL to match the Rust protocol.

-- migrate:up
CREATE TABLE documents (id TEXT PRIMARY KEY, owner_id TEXT NOT NULL, title TEXT NOT NULL);

-- migrate:down
DROP TABLE documents;

Apply and inspect

mkdir -p migrations
cd migrations
ffdb migration create add_documents
# Example output: { "path": "1754179200000_add_documents.sql" }
ffdb --project "$FFDB_PROJECT_ID" --key "$FFDB_DEVELOPER_KEY" \
  migration apply 1754179200000_add_documents.sql
ffdb migration status

Migrations workflow

• 1. Create the migration file and keep statements deterministic.
• 2. Test it against representative schema and RLS fixtures.
• 3. Apply it with the packaged CLI.
• 4. Inspect migration history and live schema.
• 5. Run application and isolation checks before promotion.

Verify migrations

The migration appears once with its stable checksum and the live schema matches the reviewed change.

Troubleshoot migrations

• An ID exists with different SQL — create a new migration instead of rewriting history.
• A protected-table change is rejected — split or redesign it within current SQL support.

Continue from Migrations

• Regenerate SDK types.
• Review policy behavior and rollback readiness.