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 <command>          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 table.
• Destructive statements. migrate create lists any it wrote, and migrate run needs --allow-destructive to run them.
• History table permissions. On a self-hosted stack the history table can belong to an admin role. SupaForge then says which GRANT is needed instead of failing with a bare permission error.
• Projects without a tracked history. checks.migrations.mode decides how the migration-history check reports them: auto (one note when nothing is tracked), warn or ignore.

Configuration

{
  "environments": {
    "dev":  { "dbUrl": "$DEV_DATABASE_URL",  "projectRef": "abc123", "accessToken": "$SUPABASE_ACCESS_TOKEN" },
    "prod": { "dbUrl": "$PROD_DATABASE_URL", "projectRef": "xyz789", "accessToken": "$SUPABASE_ACCESS_TOKEN" }
  },
  "source": "dev",
  "target": "prod",
  "checks": {
    "data": { "tables": ["plans", "feature_flags"] },
    "exclude": ["edge-functions"]
  }
}

• Per environment. checks.exclude and checks.schema.timeout can also be set on an environment, and apply when it's the target.
• .env files. .env files are loaded the Next.js way: .env.{NODE_ENV}.local, .env.local, .env.{NODE_ENV}, .env. Values already in the environment win.
• Single database. A config with a single environment and no source/target is fine. Use snapshot, clone and restore.

Self-hosted Supabase

Set apiUrl to the gateway and accessToken to the service-role key. All checks run.

• Edge Functions. Self-hosted has no management endpoint for Edge Functions, so set studioUrl (Studio's port, not the gateway's) or functionsPath (the mounted functions directory). The two can be mixed across environments. Studio's functions API is unauthenticated, so don't expose it publicly.
• Auth config. On self-hosted, auth config is read from GoTrue's settings endpoint, which carries fewer keys and can't be written. Change the deployment's environment instead.

Diffing a clone

A local clone is plain PostgreSQL. Storage, auth, Edge Functions, Vault, Realtime and Supabase's roles have nothing to compare there, so skip those checks:

{ "checks": { "exclude": ["storage", "auth", "edge-functions", "vault", "realtime", "roles"] } }

When the source is a clone and the target isn't, diff warns that --apply would push the clone's shape, absences included, onto the target.

CI and exit codes

The GitHub Action runs diff --ci and adds a summary of the drift to the job page:

- uses: akalsoftware/supaforge-action@v1
  env:
    DEV_DATABASE_URL: ${{ secrets.DEV_DATABASE_URL }}
    PROD_DATABASE_URL: ${{ secrets.PROD_DATABASE_URL }}

Anywhere else, run the CLI:

npx @akal/supaforge diff --ci

--ci fails on critical drift by default. Set the threshold with --fail-on=warning or --fail-on=any.

MCP (AI agents)

SupaForge runs as an MCP server, so an AI agent in your editor can scan for drift and fix it, asking you before anything is written.

• Claude Desktop: download the extension for your platform (supaforge-<version>-<platform>.mcpb) from the latest release and open it. It asks for your project directory.

• Claude Code: install the plugin, which adds the MCP server and a skill for applying fixes safely:

  /plugin marketplace add akalsoftware/claude-plugins
  /plugin install supaforge@akalsoftware
  

  or add just the server: claude mcp add supaforge -- npx -y @akal/supaforge mcp

• Any other client:

  { "mcpServers": { "supaforge": { "command": "npx", "args": ["-y", "@akal/supaforge", "mcp", "--project", "/path/to/project"] } } }
  

It is listed in the MCP Registry as io.github.akalsoftware/supaforge.

The server exposes these tools:

diff and sync take the same arguments, so the plan an agent shows you is the plan that runs. Fixes that drop tables or columns are held back unless allowDestructive is set.

It reads supaforge.config.json in the directory given by --project (or the one it starts in), and refuses a configPath from a client unless started with --allow-config-path.

Hooks

import { HookBus, scan, createDefaultRegistry, loadConfig } from '@akal/supaforge'

const bus = new HookBus()
bus.on('supaforge.check.after', ({ check, result }) => {
  if (result.status === 'drifted') console.log(`Drift in ${check}`)
})
await scan(createDefaultRegistry(), { config: await loadConfig() }, bus)

Development

cd packages/cli
npm install
npm test                 # unit tests
npm run lint             # type-check
./bin/dev.js diff        # run from source

The release-candidates script builds DBDiff's binary and the npm packages from local checkouts the way a release does, installs SupaForge against them as a user would, and runs every suite above against that install. It tests changes that span the three projects together, before any of them is released.

The scenario suite migrates every case in the @akal/pg-conformance corpus in both directions. It checks the result against the corpus's own state oracle and against --prove.

License

MIT