db-schema-sync

DB Schema Sync — Frontend ↔ Backend Column Parity

DB writes go through db-guardian. Schema-sync work always touches DB scope, so the guardian applies any rename/migration; FE primaries propose via dbProposals[] and update consumers after the guardian publishes. For T3 multi-table syncs, fan out one quartet per table via parallel-dispatch plus one shared guardian.

Code field names MUST equal the DB column they map to. This skill catches and repairs drift.

Core rule

Source of truth = the live Supabase schema. Code adapts to the DB, not the other way around. Only rename a DB column if the user explicitly asks — and then do it via a migration through the Supabase MCP, never with a hand-edited SQL file.

Procedure

1. Pull live schema

Use the Supabase MCP to read the current schema. Prefer the user-level connector if both are wired:

mcp__claude_ai_Supabase__list_tables       # tables + columns + types
mcp__claude_ai_Supabase__list_migrations    # to see what landed recently

If a project keeps a derived snapshot (e.g. .claude/docs/db-schema.md or lib/types/database.ts generated by supabase gen types), check whether it is fresher than the live read; if not, regenerate it before continuing.

2. Inventory every code → column reference

For each table the user asks about (or all tables for a full audit), use the Grep tool (never Bash grep):

• Pattern \.from\(['"]<table>['"]\) over **/*.{ts,tsx,js,jsx} — finds every Supabase query against this table.
• Pattern <table>\.\w+ — property accesses on returned rows.
• Pattern pickFields|select\(|insert\(|update\(|upsert\(|\.eq\(|\.match\(|\.order\( over app/api/**/route.ts — find columns named in writes/filters.
• Read lib/types/database.ts (or equivalent) with the Read tool for the generated row/insert/update types.

3. Compare names

Build a table in the response:

Table	Column (DB)	Code ref site	Code name	Match?

Flag every row where Code name !== Column (DB).

4. Decide direction

For each mismatch:

• Default: rename in code to match the DB. (Fastest safe path; obeys the rule.)
• Only rename in DB if the user explicitly says "rename the column" — then use mcp__claude_ai_Supabase__apply_migration to create a ALTER TABLE ... RENAME COLUMN migration, and update all code to match.

5. Fix in code

Use Edit / MultiEdit. Touch:

• The Supabase query (select, insert, update, pickFields whitelist).
• Any TypeScript interface or Zod schema that mirrors the row.
• Form field name= attributes if they are sent verbatim to the API.
• Email / PDF templates that reference the field.
• database.ts regeneration if it lags the live schema.

6. Verify

• Run npm run type-check — drift in types surfaces here first.
• Run npm run lint.
• If the project has a verify skill or /verify command, route the claim through it.
• For UI-visible fields, screenshot via Claude in Chrome MCP to confirm the value renders.

Red-flag patterns (use Grep tool)

Pattern	What it catches
\.from\(['"]\w+['"]\)\.select\(['"]	Explicit column lists in select()
pickFields\(.+,\s*\[	Whitelist drift in API writes
as\s+\w+:\s*['"]\w+['"]	as alias aliasing — watch for FE/BE divergence
camelCase ↔ snake_case translations	Never silently translate; alias explicitly or rename in code

Common drift causes

• Migration renamed a column but database.ts was not regenerated.
• Developer renamed a TS interface field for "readability" without renaming the column.
• A pickFields whitelist forgot to add a new column, so writes silently drop it.
• An RLS policy still references an old column name after a rename.

Output format

End every run with:

1. Mismatches found: N (with file:line references).
2. Fixes applied: list each Edit.
3. Verifications run: type-check, lint, browser screenshot.
4. Open items: anything that needs a DB-side change (always paused for explicit user OK before applying).