SupaForge

supaforge

Diff and sync your Supabase environments.

SupaForge compares two Supabase projects (dev and prod, say) across everything that makes up a project, not just the schema. It reports every difference and makes the target match the source. Fixes run in dependency order, in one transaction, and can be proved on a throwaway copy before anything changes. With a single project, it snapshots, restores and clones it.

• The whole project. It covers schema, RLS, storage, auth, Edge Functions, cron, webhooks, Realtime, queues, partition sets, Vault, extensions, grants, reference data and migration history.
• Safe by default. Every write needs --apply, and anything that loses data or opens up access also needs --allow-destructive. A failed apply leaves the target exactly as it was.
• Production-aware. Each fix says what it does to a live database: the lock it holds and on which table, whether it may rewrite the table or scan every row, whether it can't run in a transaction.
• Provable. --prove rehearses the migration and refuses to apply one that wouldn't reproduce the source or would lose rows.
• Anywhere. It works with Supabase Cloud, self-hosted stacks, plain PostgreSQL targets, CI pipelines and AI agents (MCP).

Built by Akal.

Quick start

npm install -g @akal/supaforge

supaforge init # create supaforge.config.json supaforge diff # what has drifted? supaforge diff --detail # with the SQL supaforge diff --apply # fix the target

Everything that writes previews first. Add --apply to make it happen.

Install

It needs Node.js 20 or newer. DBDiff, its diff engine, comes with it as a native binary for your platform, so there is nothing else to install. The Docker image needs nothing at all, and carries the PostgreSQL client tools --prove uses; pass connection strings with -e, and mount the project at /work.

What it compares

The schema check covers tables, columns, keys, indexes, partitions, views, materialized views, functions, aggregates, triggers, event triggers, rules, sequences, enums, composite and range types, domains, casts, extended statistics, text search configurations and dictionaries, foreign servers, user mappings and foreign tables, policies, default privileges, replica identity, statistics targets, extensions and comments. A renamed column, table or sequence is renamed, keeping its rows, rather than dropped and created again. It runs in every schema except Supabase's own (auth, storage, and so on) and those in ignoreSchemas. Objects owned by an extension belong to it and aren't compared. Objects of a kind it doesn't compare, such as operator classes, are named under the check so you can look at them by hand; they aren't counted as drift.

A check that can't run, for example without API credentials, says so and why. It's never reported as a clean pass.

Commands

supaforge init                    Create a config interactively

supaforge diff Report drift (alias: hukam) supaforge sync Alias for diff --apply

supaforge snapshot --apply Capture an environment's structure and configuration supaforge restore --apply Rebuild a database from a snapshot or migrations supaforge clone --apply Copy a remote database to a local one

supaforge migrate create Write a migration file from the current drift supaforge migrate list Local migrations, applied and pending supaforge migrate run --apply Run pending migrations supaforge migrate baseline --apply Mark migrations applied without running them

supaforge report Recent runs, from a local log supaforge mcp MCP server for AI agents supaforge help Every flag, e.g. help diff

Useful diff flags:

Applying fixes safely

• Preview first. diff, snapshot, restore, clone and migrate run write nothing without --apply.
• Destructive fixes need a second flag. Dropping a schema, table or column, deleting or truncating rows, and removing an RLS policy are reported but skipped until you add --allow-destructive. migrate run uses the same gate.
• Dependency order. Fixes run in dependency order: functions before the triggers that call them, columns before their indexes, drops last. A changed object that has to be dropped and recreated is a single fix.
• One transaction. If a fix fails, the whole set rolls back and the target is unchanged. A fix the target can't hold, because it needs an extension or a Supabase schema the target lacks, is skipped with the reason, and the rest still applies.
• `--prove`. The fixes are replayed on a copy of the target's structure, made on the target's own server, the way the apply will run them, with a sample of each table's rows. Nothing is applied unless the result matches the source and the rows survive, and nothing is applied if the proof can't run. It also names the tables the fixes rewrite. Changes a copy can't hold, such as cron jobs (pg_cron lives in one database per server), are listed as not proved.

supaforge diff --dry-run                 # the plan, in order

supaforge diff --apply --prove # rehearse, then apply supaforge diff --apply --only='schema-create-*'

Posture checks

RLS coverage and migration history look at the target alone, so they report the same findings whichever pair you diff. They're scored separately (Posture score), don't set the exit code unless you pass --fail-on-posture, and their fixes apply only with --apply-posture, or when you name the check, as in --check=rls-coverage --apply. Applying them blindly would move the target away from the source.

Snapshot, restore and clone

supaforge snapshot --env=prod --apply                     # capture

supaforge snapshot --env=prod --migration --apply # and write what changed since the last one supaforge restore --env=local --from-snapshot=latest --apply supaforge clone --env=prod --apply # local copy, data included

A snapshot records a project's structure and configuration: schema, RLS policies, cron, webhooks, extensions, storage, auth, Edge Functions, reference data, Realtime, Vault names and grants. It is not a backup. It holds no rows beyond checks.data.tables, and no stored files. Its schema is written as SQL by pg_dump, which has to be at least as new as the server; without one the snapshot can still be diffed but not restored, and snapshot exits 1 unless --allow-schema-json-only says that is enough.

restore --from-snapshot puts back:

It can't put back auth config, Edge Functions (deploy them with supabase functions deploy), or Vault secret values. Each of these is named in the output.

• Targets. Restore runs as one transaction and expects an empty database. --force clears the snapshot's own schemas first (never Supabase's) and puts back the triggers and policies outside them that depended on what it cleared. A restore or apply that looks likely to need more locks than the target allows in one transaction says so before it starts; --no-transaction commits as it goes instead.
• Plain PostgreSQL. Restoring into plain PostgreSQL works. What can't exist there is skipped and named: a foreign key to auth.users, a webhook, an extension the server doesn't ship, and everything that needs it.
• Exit code. A restore that left anything out exits 1. So does one that refused to run.
• JSON. --json prints only JSON, for a preview too.

clone copies a remote database into a local server with pg_dump and pg_restore (--schema-only to leave the rows behind). Extensions the local server has are installed first. Objects it couldn't restore are listed by cause. Afterwards the config's target points at the clone, so a bare diff --apply writes there rather than to the remote.

Migrations

supaforge migrate create --name=add_orders   # from the drift between source and target

supaforge migrate run --env=prod # preview supaforge migrate run --env=prod --apply

• Files and history. Files live in supabase/migrations (set checks.migrations.dir to change it). Applied versions are recorded in supabase_migrations.schema_migrations, the Supabase CLI's