Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

ci: flag pull requests that change a migration so the apply step is not forgotten (#736)

Gökhan Geyik2fba1331b85a
diff --git a/.github/workflows/migration-guard.yml b/.github/workflows/migration-guard.yml
new file mode 100644
index 000000000..3e8b86d91
--- /dev/null
+++ b/.github/workflows/migration-guard.yml
@@ -0,0 +1,110 @@
+name: Migration guard
+
+# A migration file is only half of a migration. The other half — applying it
+# to the hosted database — happens by hand after merge, and nothing in the
+# process carried that reminder across a merge. It has been missed twice
+# (#709, and 00050 in #700), both times on a contributor PR, and both times
+# the gap surfaced as a customer-visible error rather than as something we
+# caught ourselves.
+#
+# This marks such pull requests with a label instead of failing a check. A
+# hard failure would block a PR for something that is not wrong with the code,
+# and a plain annotation scrolls away — which is precisely how this was missed.
+# A label is visible in the PR list, survives on the merged PR, and can be
+# searched for later (`is:merged label:needs-migration`).
+#
+# Triggers `pull_request_target` rather than `pull_request` so the workflow
+# runs in the base repo's context and holds the write permission needed to
+# label a PR opened from a fork — which is where both incidents came from.
+# It never checks out or executes the PR's code: the file list comes from the
+# API, so there is nothing here for an untrusted branch to influence.
+
+on:
+ pull_request_target:
+ types: [opened, synchronize, reopened]
+
+permissions:
+ contents: read
+ # Labels on a pull request are managed through the issues API, and creating a
+ # repo label needs `issues: write` specifically — `pull-requests: write`
+ # alone is enough to attach an existing label but not to create a missing one.
+ issues: write
+ pull-requests: write
+
+jobs:
+ label:
+ name: flag migrations that still need applying
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/github-script@v7
+ with:
+ script: |
+ const LABEL = 'needs-migration';
+ const PREFIX = 'supabase/migrations/';
+
+ const files = await github.paginate(github.rest.pulls.listFiles, {
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ pull_number: context.payload.pull_request.number,
+ per_page: 100,
+ });
+
+ // `removed` files need no apply step, but a renamed or modified
+ // migration does — an edited migration is as unapplied as a new one.
+ const touched = files
+ .filter((f) => f.filename.startsWith(PREFIX) && f.status !== 'removed')
+ .map((f) => f.filename)
+ .sort();
+
+ const labelled = context.payload.pull_request.labels.some((l) => l.name === LABEL);
+
+ if (touched.length === 0) {
+ // Migrations can be dropped from a branch after review. Clearing
+ // the label keeps it meaning "this still needs applying" rather
+ // than "this once contained a migration".
+ if (labelled) {
+ await github.rest.issues.removeLabel({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: context.payload.pull_request.number,
+ name: LABEL,
+ });
+ core.info(`No migrations left in this PR — removed the ${LABEL} label.`);
+ }
+ return;
+ }
+
+ core.warning(
+ `This PR changes ${touched.length} migration file(s). Apply them to the hosted ` +
+ `database before or immediately after merge, or the merged code will call ` +
+ `objects that do not exist:\n${touched.join('\n')}`,
+ );
+
+ if (labelled) return;
+
+ // Create on demand rather than assuming a repo-level setup step:
+ // a fork or a self-hosted copy of this repo has no such label, and
+ // a missing one must not fail the run.
+ try {
+ await github.rest.issues.createLabel({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ name: LABEL,
+ color: 'B60205',
+ description: 'Adds or edits a migration — apply it to the hosted database',
+ });
+ } catch (err) {
+ // Already exists (422) is the normal case once the first PR has
+ // run. Anything else is logged rather than thrown: attaching the
+ // label is the job, and failing the run over the setup step for
+ // it would put a red mark on the PR while telling nobody
+ // anything useful.
+ core.info(`createLabel: ${err.status} ${err.message}`);
+ }
+
+ await github.rest.issues.addLabels({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: context.payload.pull_request.number,
+ labels: [LABEL],
+ });
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 62044f506..74f98b6e2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -151,14 +151,41 @@ We follow [GitHub Flow](https://docs.github.com/en/get-started/using-github/gith
npm run version:check
```
-4. Push and open a pull request against `main`.
+4. If you added or edited a file under `supabase/migrations/`, regenerate the
+ consolidated schema and commit the result — CI fails if it is out of date:
-5. In your PR description, include:
+ ```bash
+ bash supabase/build-schema.sh
+ ```
+
+ Your PR will be labelled `needs-migration` automatically. That label is a
+ reminder for the maintainer merging it: the file is only half of a
+ migration, and the other half is applying it to the hosted database. You do
+ not need to do anything about the label yourself.
+
+5. Push and open a pull request against `main`.
+
+6. In your PR description, include:
- **What** changed and **why**
- **How to test** the change
- Screenshots if there are UI changes
-6. Wait for review, address feedback, and your PR will be merged.
+7. Wait for review, address feedback, and your PR will be merged.
+
+### Checking for schema drift
+
+A migration that was committed but never applied leaves the database missing
+something the code calls, which surfaces as a runtime error rather than a
+failing build. To check a database against what this repo expects:
+
+```bash
+bash supabase/check-drift.sh # prints SQL; paste it into the SQL Editor
+```
+
+It reads the repo and writes a read-only query — no credentials, no
+connection, nothing written. An empty result means no drift; any row is
+something the code expects and that database does not have. Worth running
+after applying a migration, and after pulling a batch of merged changes.
## Commit Messages
diff --git a/supabase/check-drift.sh b/supabase/check-drift.sh
new file mode 100755
index 000000000..4afb628fe
--- /dev/null
+++ b/supabase/check-drift.sh
@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+#
+# Prints a read-only SQL query that reports anything this repo expects to exist
+# in the database but which may not.
+#
+# A migration file is only half of a migration; the other half is applying it.
+# That step has been missed twice (#709, and 00050 in #700), and both times the
+# gap surfaced as a customer-visible error rather than as something we caught.
+# The CI label (.github/workflows/migration-guard.yml) is the reminder; this is
+# the way to confirm afterwards that the reminder was acted on.
+#
+# It reads the repo and writes SQL. It never connects to anything, so it needs
+# no credentials and cannot change any data:
+#
+# bash supabase/check-drift.sh | pbcopy # then paste into the SQL Editor
+# bash supabase/check-drift.sh > /tmp/drift.sql
+#
+# An empty result means no drift. Any row is something the code expects and the
+# database does not have.
+#
+# Three checks, weakest to strongest:
+# 1. every function the migrations declare exists
+# 2. every table the migrations declare exists
+# 3. every RPC the application actually calls resolves to a function
+#
+# The third is the one that matters most: it checks what the code calls rather
+# than what the migrations declare, so it catches a function that was renamed,
+# never applied, or applied with a different argument list.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# Deduplicated, sorted identifiers. `|| true` throughout: a grep that matches
+# nothing exits 1 under `set -e`, and "no functions declared" is a valid state.
+# Quotes are stripped before the name is read. Migrations here are written
+# both ways — `public.topics` and `"public"."topics"` — and a pattern that
+# keeps the quotes reads the second form as the schema name, silently checking
+# `public` 26 times instead of the 26 tables it stands for.
+strip_quotes() { tr -d '"'; }
+
+# Greedy `.*` so the split happens at the LAST keyword: it lands after
+# `EXISTS` when the statement has it, and after `TABLE`/`FUNCTION` when not.
+functions=$(grep -rhoiE 'CREATE (OR REPLACE )?FUNCTION[[:space:]]+[a-z0-9_."]+' supabase/migrations/ 2>/dev/null |
+ strip_quotes | sed -E 's/.*FUNCTION[[:space:]]+//I; s/^public\.//' |
+ tr '[:upper:]' '[:lower:]' | sort -u || true)
+
+tables=$(grep -rhoiE 'CREATE TABLE[[:space:]]+(IF NOT EXISTS[[:space:]]+)?[a-z0-9_."]+' supabase/migrations/ 2>/dev/null |
+ strip_quotes | sed -E 's/.*(TABLE|EXISTS)[[:space:]]+//I; s/^public\.//' |
+ tr '[:upper:]' '[:lower:]' | sort -u || true)
+
+# Matches supabase.rpc('name') and .rpc('name', {...}) in both apps.
+rpcs=$(grep -rhoE "\.rpc\(\s*'[a-z0-9_]+'" web/src server/src 2>/dev/null |
+ sed -E "s/.*'([a-z0-9_]+)'.*/\1/" | sort -u || true)
+
+# One-per-line -> a SQL VALUES list. Emits NULL when empty so the query stays
+# valid rather than becoming a syntax error on a repo with none of that kind.
+as_values() {
+ if [ -z "$1" ]; then
+ echo " (NULL)"
+ else
+ printf '%s\n' "$1" | sed -E "s/^/ ('/; s/\$/'),/" | sed '$ s/,$//'
+ fi
+}
+
+cat <<SQL
+-- ============================================================================
+-- ansvisor — schema drift check (read-only; generated by check-drift.sh)
+--
+-- Paste into the Supabase SQL Editor. No rows = no drift.
+-- Each row is something the repo expects and this database does not have.
+-- ============================================================================
+
+WITH expected_functions(name) AS (VALUES
+$(as_values "$functions")
+),
+expected_tables(name) AS (VALUES
+$(as_values "$tables")
+),
+called_rpcs(name) AS (VALUES
+$(as_values "$rpcs")
+)
+SELECT 'missing function' AS problem, e.name AS object,
+ 'declared in supabase/migrations/ but absent from pg_proc' AS detail
+FROM expected_functions e
+WHERE e.name IS NOT NULL
+ AND NOT EXISTS (
+ SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+ WHERE n.nspname = 'public' AND p.proname = e.name
+ )
+
+UNION ALL
+
+SELECT 'missing table', e.name,
+ 'declared in supabase/migrations/ but absent from pg_tables'
+FROM expected_tables e
+WHERE e.name IS NOT NULL
+ AND NOT EXISTS (
+ SELECT 1 FROM pg_tables t WHERE t.schemaname = 'public' AND t.tablename = e.name
+ )
+
+UNION ALL
+
+-- The strongest of the three: what the application calls at run time, which is
+-- what a user hits when it is missing.
+SELECT 'unresolved rpc', c.name,
+ 'called via .rpc() in web/src or server/src but no such function exists'
+FROM called_rpcs c
+WHERE c.name IS NOT NULL
+ AND NOT EXISTS (
+ SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+ WHERE n.nspname = 'public' AND p.proname = c.name
+ )
+
+ORDER BY 1, 2;
+SQL
+
+{
+ echo ""
+ echo "-- Checking $(printf '%s\n' "$functions" | grep -c . || true) function(s), \
+$(printf '%s\n' "$tables" | grep -c . || true) table(s), \
+$(printf '%s\n' "$rpcs" | grep -c . || true) called RPC(s)."
+} >&2