supabase-schema-gate

name

supabase-schema-gate

description

Verify production Supabase schema before shipping code that touches it. Use BEFORE writing or reviewing ANY code that reads or writes a Supabase table in the Nexus — new queries, inserts, updates, CHECK-constrained values, RLS-dependent reads, cron data access — even one-line changes and even when the table "obviously" exists. Also use immediately when a query fails with "column does not exist", when inserts appear to succeed but produce no rows, or when generated TypeScript types disagree with runtime behaviour.

Supabase schema gate

Two real Nexus incidents motivate this gate:

1. social_channels.founder_id and social_channels.is_connected did not exist in prod. The marketing coach and analytics-sync crons failed silently from March to July 2026 — months of missing data.
2. dr_contractor_portal inserts into agent_actions were silently rejected by the source CHECK constraint until the constraint was widened (PR #734).

Both shipped because code was checked against assumptions (local types, memory) instead of prod. This gate makes that class of bug unshippable.

Procedure

1. Enumerate assumptions. List every table, column, CHECK-constrained value, and RLS policy the diff reads or writes. Include indirect access through shared helpers.

2. Verify read-only against prod. Generated types and local databases drift; prod is the only authority. Run (read-only — never mutate during verification):

-- Columns the code depends on
select column_name, data_type, is_nullable
from information_schema.columns
where table_schema = 'public'  table_name  ;


 conname, pg_get_constraintdef(oid)
 pg_constraint
 conrelid  ::regclass  contype  ;


 policyname, cmd, qual, with_check
 pg_policies
 schemaname    tablename  ;