How to Keep Reference Data & Feature Flags in Sync

The Problem with Reference Data

Most applications have tables that are not user-generated but are required for the app to function: lookup tables (countries, currencies, roles), feature flags, configuration rows, pricing tiers, and email templates. These tables are usually seeded once in development and then manually recreated in staging and production.

When someone updates a feature flag in staging, adds a new role, or changes a pricing tier, those rows rarely make it to production through a formal process. The result is subtle environment drift that causes bugs that are impossible to reproduce locally.

What SupaForge Does

The data check compares specified tables row by row between source and target. It identifies missing rows, modified rows, andextra rows — then generates the SQL to reconcile the target.

Under the hood, this uses the DBDiff engine for row-level diffing, so you get precise INSERT, UPDATE, and DELETE statements.

Step 1 — Configure

npm i -g @akalforge/supaforge

{
  "environments": {
    "staging": {
      "dbUrl": "postgresql://user:pass@db.STAGING_REF.supabase.co:5432/postgres",
      "projectRef": "STAGING_REF",
      "apiKey": "your-staging-service-role-key"
    },
    "production": {
      "dbUrl": "postgresql://user:pass@db.PROD_REF.supabase.co:5432/postgres",
      "projectRef": "PROD_REF",
      "apiKey": "your-production-service-role-key"
    }
  },
  "source": "staging",
  "target": "production",
  "checks": {
    "data": {
      "tables": ["roles", "countries", "feature_flags", "pricing_tiers"]
    }
  }
}

List the tables you consider reference data in the checks.data.tables array. Only these tables are compared — user-generated data is never touched.

Step 2 — Scan the Data Check

supaforge scan --check data

The output shows each table with its row diff: how many rows are missing, modified, or extra in the target environment.

Step 3 — Review the Diff

For each table, SupaForge lists:

• Missing rows — exist in source but not target. Fix: INSERT.
• Modified rows — same primary key, different column values. Fix: UPDATE.
• Extra rows — exist in target but not source. Fix: DELETE (optional — review carefully).

Step 4 — Promote

supaforge promote

supaforge promote --check data --apply

Best Practices

• Be explicit about which tables are reference data. Never scan all tables — only tables whose content is controlled by the development team.
• Handle extra rows with care. An extra row in production might be intentional (e.g. a production-only feature flag). Review DELETE statements before promoting.
• Version your config. Commit supaforge.config.json to your repo so the list of reference tables is tracked alongside your schema.
• Combine with schema scans. If you add a new column to a reference table, run both schema and data checks to catch the full drift.

Summary

Reference data drift is one of the most common causes of environment parity issues. SupaForge compares specific tables row-by-row and generates the exact SQL to bring production in line with staging — no more hand-written seed scripts.