Skip to content
akalsoftwarePublic

About

Supabase & Postgres diff, sync, clone (Supabase Cloud, self-hosted & local) inc. table schema, data migrations, RLS, storage, auth, functions, extensions etc.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

SupaForge

Diff, sync and clone Supabase and Postgres environments - and prove every change before it reaches production.

CI npm version npm downloads MCP Registry License: MIT

Website · Documentation · Guides · GitHub Action


Dev, staging and production drift apart, and nothing tells you until something breaks. A policy added in staging never reaches production. A bucket is public in one place only. A cron job, webhook or grant exists on one side and not the other. A migration that worked on your laptop locks a live table.

SupaForge finds every one of those differences across the whole project, not just the schema, and makes the target match the source safely. It works with Supabase Cloud, self-hosted Supabase, local stacks and plain PostgreSQL.

npx @akal/supaforge init     # point it at two environments
npx @akal/supaforge diff     # see everything that differs

Why teams use it

  • 🔒 Catch security gaps before users do. An RLS policy that never reached production leaves a table open to anyone with the anon key - CVE-2025-48757 exposed real apps exactly this way. SupaForge reports missing or changed policies, tables with RLS switched off, and what anon, authenticated and service_role can touch on each side.
  • 🧭 The whole project, not just tables. Schema and reference data, RLS policies, roles and grants, storage buckets and their policies, auth config, Edge Functions, cron jobs, queues, webhooks, Realtime, Vault, extensions and migration history.
  • 🛡️ Fixes you can trust on a live database. Fixes run in dependency order, in one transaction, and roll back cleanly if anything fails. Each says which lock it takes and whether it rewrites a table. Anything that loses data or opens up access waits for --allow-destructive.
  • ✅ Proof before change. --prove rehearses the migration on a throwaway copy of the target, rows included, and applies nothing unless the result matches the source.
  • 🤖 Safe for AI agents. A built-in MCP server lets Claude, Cursor and VS Code agents diff and sync your environments, showing you the plan before anything is written.
  • ⚙️ Built for pipelines. --ci adds GitHub annotations and meaningful exit codes, --json is machine-readable throughout, and the GitHub Action puts a drift summary on every run.

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
supaforge diff --apply --prove   # rehearse on a copy first, then fix

Only one project? Snapshot it, restore it anywhere, or clone it locally:

supaforge snapshot --env=prod --apply                       # record it
supaforge restore --env=local --from-snapshot=latest --apply
supaforge clone --env=prod --apply                          # local copy, data included

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

Use it where you work

Where How
Terminal npm install -g @akal/supaforge, npx @akal/supaforge, or brew install akalsoftware/tap/supaforge
Docker docker run --rm -v "$PWD:/work" ghcr.io/akalsoftware/supaforge diff
GitHub Actions akalsoftware/supaforge-action
Claude Code /plugin marketplace add akalsoftware/claude-plugins, then /plugin install supaforge@akalsoftware
Claude Desktop, Cursor, VS Code One-click MCP installs - see MCP

Full documentation →: every check, command and flag, the safety model, snapshots and restore, migrations, configuration, self-hosted Supabase, CI and MCP.

Under the hood

The schema and data checks are powered by DBDiff, installed automatically as a native binary with no PHP needed. Every release is tested by migrating a corpus of PostgreSQL shapes in both directions, and checking each result against an independent catalog oracle and against --prove.

Path What
packages/cli The supaforge CLI and library, published as @akal/supaforge
packages/vscode The VS Code extension
packages/mcp A standalone build of the MCP server, not published. Use supaforge mcp

Development

git clone https://github.com/akalsoftware/supaforge.git
cd supaforge/packages/cli
npm install
npm test && npm run lint
./bin/dev.js diff

The integration, database e2e, scenario and Supabase e2e suites are described in the package README. CI runs all of them on every pull request.

Releasing

Run the Trigger Release workflow (Actions → Trigger Release) with patch, minor, major or an exact version. It bumps the version, tags it, and publishes to npm.

node scripts/release.js patch does the same steps locally, as a dry run unless given --apply.

Contributing

See CONTRIBUTING.md.

Security

To report a vulnerability, see SECURITY.md.

License

MIT. Built by Akal Software. Copyright (c) 2026 Akal Software Ltd

About

Supabase & Postgres diff, sync, clone (Supabase Cloud, self-hosted & local) inc. table schema, data migrations, RLS, storage, auth, functions, extensions etc.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages