PostgreSQL engineering protocol for Supabase
SQL Steward
Install a SQL-first PostgreSQL workflow for Supabase, then let your AI agent prepare changes that you review and deploy.
1. Install the protocol
Run this once from the root of your application repository. It downloads the canonical protocol and creates empty locations for migrations, deployment evidence, and sanitized snapshots. It does not connect to Supabase or apply SQL.
Install in your project
Creates SQL Steward folders and downloads the protocol Markdown.
mkdir -p supabase/migrations supabase/deployments supabase/snapshots
touch supabase/migrations/.gitkeep
touch supabase/deployments/.gitkeep
touch supabase/snapshots/.gitkeep
curl --fail --location --output supabase/README-db-workflow.md \
"https://www.devflow.ca/downloads/sql-steward/protocol?channel=terminal"2. Connect your AI agent
An installed protocol is only useful when the agent is told to read it. This command creates AGENTS.md if needed, or appends the SQL Steward instructions to the existing file. Existing project and framework instructions remain intact.
Add instructions to AGENTS.md
Append-only and idempotent. Scroll to inspect; Copy includes every line.
touch AGENTS.md
if ! grep -q '<!-- BEGIN SQL STEWARD -->' AGENTS.md; then
cat >> AGENTS.md <<'SQL_STEWARD'
<!-- BEGIN SQL STEWARD -->
# Database Instructions
Before designing, editing, or reviewing any PostgreSQL, Supabase, data-access,
authorization, or storage-backed feature, read
`supabase/README-db-workflow.md` and follow its AI-assisted database protocol.
Database schema ownership is SQL-first through new migration files in
`supabase/migrations/`. Reviewed migration SQL is committed before a human
manually applies it in the Supabase SQL Editor. After successful application
and verification, record deployment evidence under
`supabase/deployments/<environment>/`.
Do not use `supabase db push`, Docker/local-stack database workflows, or
CLI-managed migration deployment. Never apply hosted migration SQL through AI
tooling.
<!-- END SQL STEWARD -->
SQL_STEWARD
fi3. Begin database work
Ask your agent for a real database feature after installation. It should first establish actors, ownership, visibility and risk, then prepare a migration, RLS/grant design, and verification plan for your review.
The deployment boundary
SQL Steward is designed for version-controlled SQL with human-controlled hosted deployment. Review and commit migrations before a human applies the exact SQL in Supabase SQL Editor; then verify real user access paths and commit a deployment record. This is not a compliance certification or a replacement for qualified review of consequential changes.