How to Diff Against a Local Clone

The Post-Clone Drift Problem

supaforge clone copies a remote environment's schema and data into a local PostgreSQL database so you can develop locally. However, several Supabase features live outside Postgres — they are managed through the Supabase API and have no local equivalent:

• storage — S3-compatible buckets and their policies.
• auth — OAuth providers, JWT settings, email templates.
• vault — Supabase Vault secret names and metadata.
• edge-functions — deployed Deno functions.
• realtime — Realtime publication configuration.

When you run supaforge diff with source set to your local clone and target set to the remote environment, these checks will always report drift — not because anything is wrong, but because the local database genuinely doesn't have those features. Fixing them is not the goal; the goal is to track Postgres-level changes like schema, RLS, and reference data.

Suppress for a Single Run with --skip

Use the --skip flag (short: -x) to exclude specific checks from a single diff run. The flag is repeatable:

supaforge diff --skip=storage --skip=auth --skip=vault --skip=edge-functions --skip=realtime

You can combine --skip with other flags. To see full SQL for just the checks that matter locally:

supaforge diff --detail --skip=storage --skip=auth --skip=vault --skip=edge-functions --skip=realtime

To apply only the Postgres-level drift without touching the Supabase-only checks:

supaforge diff --apply --skip=storage --skip=auth --skip=vault --skip=edge-functions --skip=realtime

Make It Permanent with checks.exclude

Typing five --skip flags every run gets old quickly. Add achecks.exclude array to your supaforge.config.json and those checks are silently skipped on every run — no flags needed:

{
  "environments": { ... },
  "source": "local",
  "target": "production",
  "checks": {
    "exclude": ["storage", "auth", "vault", "edge-functions", "realtime"]
  }
}

With this config in place, a plain supaforge diff behaves as if you had passed all five --skip flags. The excluded checks never appear in output, and their drift is never counted in the drift score.

Tip: commit this config to version control alongside your project so every team member and CI environment inherits the same exclusion list automatically.

When to Use Each Approach

• --skip — one-off runs where you want to quickly check Postgres-level changes without noise, but your config still targets two full Supabase environments most of the time.
• checks.exclude — your project always diffs against a local clone and you will never have local equivalents for those five checks. Embed this permanently in config.

Full Local Development Workflow

After cloning:

supaforge clone --env=production --apply

# supaforge.config.json now has:
#   "source": "local", "target": "production"
#   "checks": { "exclude": ["storage","auth","vault","edge-functions","realtime"] }

# Now develop locally — make schema changes, update RLS, etc.

supaforge diff

supaforge diff --apply

Install

npm i -g @akalforge/supaforge

Summary

Supabase-only checks (storage, auth, vault, edge-functions, realtime) will always report drift when diffing against a local clone because those features don't exist in a plain Postgres database. Use --skip for a one-off suppression or addchecks.exclude to your config to permanently silence them and keep your diff output focused on the Postgres changes you actually care about.