@rebasepro/server-postgres 0.13.0 → 0.13.1-canary.g06dbe5b

package/src/schema/introspect-db-logic.ts

@@ -218,7 +218,14 @@ export function singularize(word: string): string {
  * e.g. "company_token" -> "companyTokenCollection"
  */
 export function toCollectionVarName(tableName: string): string {
-    return tableName.replace(/_([a-z])/g, (_g, letter: string) => letter.toUpperCase()) + "Collection";
+    const camel = tableName.replace(/_([a-z])/g, (_g, letter: string) => letter.toUpperCase()) + "Collection";
+    // Only reshapes names that are not identifiers already, so every table that
+    // generated a working file keeps the exact variable name it had. A table
+    // called `2024 archive` used to emit `const 2024 archiveCollection`, which
+    // is three syntax errors rather than a declaration.
+    if (JS_IDENTIFIER.test(camel)) return camel;
+    const sanitized = camel.replace(/[^A-Za-z0-9_$]/g, "_");
+    return /^[0-9]/.test(sanitized) ? `_${sanitized}` : sanitized;
 }
 
 export function getIconForTable(tableName: string): string {
@@ -616,6 +623,31 @@ function quote(value: string): string {
     return JSON.stringify(value);
 }
 
+const JS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * An object key for the generated file: verbatim when the name is a JavaScript
+ * identifier, quoted otherwise.
+ *
+ * Postgres constrains an identifier only by quoting, so `order`, `full name`
+ * and `2fa_enabled` are all ordinary column names — and all three produced a
+ * file that did not parse when written as a bare key.
+ */
+function propKey(name: string): string {
+    return JS_IDENTIFIER.test(name) ? name : quote(name);
+}
+
+/**
+ * Text safe to put after `//`.
+ *
+ * A table comment or a classification reason is free text out of the database.
+ * A newline in one ended the comment and let the rest of the value continue as
+ * code.
+ */
+function commentText(value: string): string {
+    return value.replace(/\s*[\r\n]+\s*/g, " ");
+}
+
 /**
  * The first candidate key not already used, or a numbered fallback.
  *
@@ -688,7 +720,7 @@ export function generateCollectionFile(
      */
     const importCollection = (otherTable: string): string => {
         const varName = toCollectionVarName(otherTable);
-        if (otherTable !== tableName) imports.add(`import ${varName} from "./${otherTable}";`);
+        if (otherTable !== tableName) imports.add(`import ${varName} from ${quote(`./${otherTable}`)};`);
         return varName;
     };
 
@@ -737,7 +769,7 @@ export function generateCollectionFile(
         // Enum values — generate real enum from the PG enum
         if (isEnumColumn && colEnumValues) {
             const enumEntries = colEnumValues
-                .map((v) => `{ id: "${v}", label: "${humanize(v)}" }`)
+                .map((v) => `{ id: ${quote(v)}, label: ${quote(humanize(v))} }`)
                 .join(", ");
             extra += `\n            enum: [${enumEntries}],`;
         } else if (columnChecks?.enumValues && !inferenceExtra.includes("enum:") && propType === "string") {
@@ -776,9 +808,9 @@ export function generateCollectionFile(
                 else if (innerType === "boolean") colType = "boolean[]";
             }
             if (colType) {
-                extra += `\n            columnType: "${colType}",`;
+                extra += `\n            columnType: ${quote(colType)},`;
             }
-            extra += `\n            of: { name: "${humanize(col.column_name)} Item", type: "${innerType}" },`;
+            extra += `\n            of: { name: ${quote(`${humanize(col.column_name)} Item`)}, type: ${quote(innerType)} },`;
         } else if (finalPropType === "map" && !inferenceExtra.includes("keyValue: true") && !inferenceExtra.includes("properties: {")) {
             extra += "\n            keyValue: true,";
         }
@@ -789,7 +821,7 @@ export function generateCollectionFile(
             const isMedia = colNameLower.includes("image") || colNameLower.includes("avatar") || colNameLower.includes("photo") || colNameLower.includes("logo") || colNameLower.includes("cover");
 
             if (isMedia) {
-                extra += `\n            storage: {\n                storagePath: "${tableName}/${col.column_name}"\n            },`;
+                extra += `\n            storage: {\n                storagePath: ${quote(`${tableName}/${col.column_name}`)}\n            },`;
             } else if (isUrl) {
                 extra += "\n            url: true,";
             } else if (colNameLower === "description" || colNameLower === "summary" || colNameLower === "excerpt") {
@@ -872,7 +904,7 @@ export function generateCollectionFile(
         // Identify IDs (unless already inferred as UUID/CUID by inferenceEngine)
         if (meta.pks.includes(col.column_name)) {
             if (isCompositePk) {
-                extra += `\n            // Part of composite primary key (${meta.pks.join(", ")})`;
+                extra += `\n            // Part of composite primary key (${commentText(meta.pks.join(", "))})`;
             } else if (finalPropType === "number" && !inferenceExtra.includes("isId:")) {
                 extra += "\n            isId: \"increment\",";
             } else if (col.data_type.toLowerCase() === "uuid" && !inferenceExtra.includes("isId:")) {
@@ -913,10 +945,10 @@ export function generateCollectionFile(
         });
 
         propertyBlocks.set(col.column_name, `
-        ${col.column_name}: {
-            name: "${humanName}",
-            columnName: "${col.column_name}",
-            type: "${finalPropType}",${extra}
+        ${propKey(col.column_name)}: {
+            name: ${quote(humanName)},
+            columnName: ${quote(col.column_name)},
+            type: ${quote(finalPropType)},${extra}
         },`);
     }
 
@@ -962,14 +994,14 @@ export function generateCollectionFile(
             const relHumanName = humanize(relName);
 
             propertyBlocks.set(relName, `
-        ${relName}: {
-            name: "${relHumanName}",
+        ${propKey(relName)}: {
+            name: ${quote(relHumanName)},
             type: "relation",
-            // mapped from foreign key: ${fk.column_name} -> ${targetTableName}(${fk.foreign_column_name})
+            // mapped from foreign key: ${commentText(fk.column_name)} -> ${commentText(targetTableName)}(${commentText(fk.foreign_column_name)})
             relation: {
                 kind: "belongsTo",
                 target: () => ${targetCollectionCamel},
-                localKey: "${fk.column_name}"
+                localKey: ${quote(fk.column_name)}
             }
         },`);
         }
@@ -986,10 +1018,10 @@ export function generateCollectionFile(
         relationsOutput += `
         {
             kind: "hasMany",
-            relationName: "${sourceTableName}",
+            relationName: ${quote(sourceTableName)},
             target: () => ${targetCollectionCamel},
-            // the ${sourceTableName}.${fk.column_name} FK points back here
-            foreignKeyOnTarget: "${fk.column_name}"
+            // the ${commentText(sourceTableName)}.${commentText(fk.column_name)} FK points back here
+            foreignKeyOnTarget: ${quote(fk.column_name)}
         },`;
     }
 
@@ -1018,12 +1050,12 @@ export function generateCollectionFile(
             relationsOutput += `
         {
             kind: "manyToMany",
-            relationName: "${relPropName}",
-            target: () => ${tableName}Collection,
+            relationName: ${quote(relPropName)},
+            target: () => ${toCollectionVarName(tableName)},
             through: {
-                table: "${jt}",
-                sourceColumn: "${thisFk.column_name}",
-                targetColumn: "${otherFk.column_name}"
+                table: ${quote(jt)},
+                sourceColumn: ${quote(thisFk.column_name)},
+                targetColumn: ${quote(otherFk.column_name)}
             }
         },`;
             continue;
@@ -1045,13 +1077,13 @@ export function generateCollectionFile(
             const thisFk = joinFks.find((fk) => fk.foreign_table_name === tableName);
 
             const throughCode = thisFk
-                ? `\n            through: {\n                table: "${jt}",\n                sourceColumn: "${thisFk.column_name}",\n                targetColumn: "${otherFk.column_name}"\n            }`
+                ? `\n            through: {\n                table: ${quote(jt)},\n                sourceColumn: ${quote(thisFk.column_name)},\n                targetColumn: ${quote(otherFk.column_name)}\n            }`
                 : "";
 
             relationsOutput += `
         {
             kind: "manyToMany",
-            relationName: "${targetTableName}",
+            relationName: ${quote(targetTableName)},
             target: () => ${targetCollectionCamel},${throughCode}
         },`;
         }
@@ -1071,7 +1103,7 @@ export function generateCollectionFile(
     // config, where they have not belonged since the admin block was split out:
     // `PostgresCollectionConfig` does not declare them, so every generated file
     // was a type error, and the panel — which reads the block — never saw them.
-    const adminEntries: string[] = [`icon: "${icon}"`];
+    const adminEntries: string[] = [`icon: ${quote(icon)}`];
 
     if (classification) {
         const derivedFacts = context.metadata
@@ -1089,7 +1121,7 @@ export function generateCollectionFile(
 
         if (derivedFacts) {
             const titleProperty = deriveTitleProperty(derivedFacts);
-            if (titleProperty) adminEntries.push(`titleProperty: ${quote(titleProperty)}`);
+            if (titleProperty) adminEntries.push(`display: { title: ${quote(titleProperty)} }`);
 
             const kanbanProperty = deriveKanbanProperty(derivedFacts);
             if (kanbanProperty) adminEntries.push(`kanban: {\n            columnProperty: ${quote(kanbanProperty)}\n        }`);
@@ -1116,17 +1148,17 @@ export function generateCollectionFile(
     // decision the reader may disagree with. Naming the evidence tells them
     // which line to delete when they do.
     const classificationNote = classification && classification.role !== "entity"
-        ? `\n// Introspected as a ${classification.role}: ${classification.reason}.\n`
+        ? `\n// Introspected as a ${commentText(classification.role)}: ${commentText(classification.reason)}.\n`
         : "";
 
     const collectionVarName = toCollectionVarName(tableName);
     const fileContent = `${Array.from(imports).join("\n")}
 ${classificationNote}
 const ${collectionVarName}: PostgresCollectionConfig = {
-    name: "${collectionName}",
-    singularName: "${singular}",
-    slug: "${tableName}",
-    table: "${tableName}",${descriptionBlock}
+    name: ${quote(collectionName)},
+    singularName: ${quote(singular)},
+    slug: ${quote(tableName)},
+    table: ${quote(tableName)},${descriptionBlock}
     properties: {${propsOutput}
     },${relationsBlock}${adminBlock}
 };
@@ -1146,7 +1178,7 @@ export function generateIndexContent(fileNames: string[]): string {
     let arrayElements = "";
     for (const f of sorted) {
         const varName = toCollectionVarName(f);
-        imports += `import ${varName} from "./${f}";\n`;
+        imports += `import ${varName} from ${quote(`./${f}`)};\n`;
         arrayElements += `    ${varName},\n`;
     }
     return `${imports}\nexport const collections = [\n${arrayElements}];\n`;
@@ -1168,7 +1200,7 @@ export function mergeIndexContent(existingContent: string, newFileNames: string[
     for (const f of sorted) {
         if (!existingImports.has(f)) {
             const varName = toCollectionVarName(f);
-            newImports += `import ${varName} from "./${f}";\n`;
+            newImports += `import ${varName} from ${quote(`./${f}`)};\n`;
             newElements += `    ${varName},\n`;
         }
     }

package/src/schema/non-sql-collections.test.ts

@@ -0,0 +1,131 @@
+/**
+ * A collection served by another engine is not this engine's to provision.
+ *
+ * Firestore and MongoDB collections are declared in the same
+ * `config/collections` directory as the Postgres ones — that is what
+ * `dataSource` routing is for — and every stage of the SQL toolchain used to
+ * read "the collections" as all of them. So a Firestore collection got a
+ * `pgTable` in the generated schema, a `CREATE TABLE` at boot, RLS policies,
+ * and an entry in the `db push` include list, while the app went on reading its
+ * documents from Firestore.
+ *
+ * The include list is the one that can lose data: a name on it is a name Atlas
+ * is *allowed to drop*, so a Firestore collection called `exercises` removed a
+ * real, unrelated `public.exercises` table's protection from the next
+ * auto-approved `db push`.
+ */
+import { describe, expect, it } from "@jest/globals";
+import type { CollectionConfig } from "@rebasepro/types";
+
+import { generateSchema } from "./generate-drizzle-schema-logic";
+import {
+    generatePostgresDdl,
+    generatePostgresPoliciesDdl,
+    planCollectionPolicies
+} from "./generate-postgres-ddl-logic";
+import { planCollectionSchemaEnsure, type ExistingSchema } from "./ensure-collection-tables";
+import { getTableIncludesFromCollections } from "../cli-helpers";
+
+const sqlCollection = {
+    name: "Customers",
+    slug: "customers",
+    properties: {
+        id: { name: "ID", type: "string", isId: "uuid" },
+        email: { name: "Email", type: "string" }
+    },
+    securityRules: [{ operation: "read", policy: "true" }]
+} as unknown as CollectionConfig;
+
+const firestoreCollection = {
+    name: "Exercises",
+    slug: "exercises",
+    engine: "firestore",
+    dataSource: "firestore",
+    properties: {
+        id: { name: "ID", type: "string" },
+        title: { name: "Title", type: "string" },
+        difficulty: {
+            name: "Difficulty",
+            type: "string",
+            enum: [{ id: "easy", label: "Easy" }, { id: "hard", label: "Hard" }]
+        }
+    }
+} as unknown as CollectionConfig;
+
+const mongoCollection = {
+    name: "Events",
+    slug: "events",
+    engine: "mongodb",
+    properties: { id: { name: "ID", type: "string" } }
+} as unknown as CollectionConfig;
+
+/** Routed by `dataSource` alone — no `engine` field to read. */
+const dataSourceOnlyCollection = {
+    name: "Articles",
+    slug: "articles",
+    dataSource: "firestore",
+    properties: { id: { name: "ID", type: "string" } }
+} as unknown as CollectionConfig;
+
+const all = [sqlCollection, firestoreCollection, mongoCollection, dataSourceOnlyCollection];
+
+describe("the Drizzle schema generator", () => {
+    it("emits a table for the Postgres collection only", async () => {
+        const schema = await generateSchema(all);
+
+        expect(schema).toContain("customers");
+        expect(schema).not.toContain("exercises");
+        expect(schema).not.toContain("events");
+        expect(schema).not.toContain("articles");
+    });
+
+    it("does not emit enum types for a document store's fields", async () => {
+        const schema = await generateSchema(all);
+        expect(schema).not.toContain("difficulty");
+    });
+});
+
+describe("the Postgres DDL generator", () => {
+    it("creates no table for a non-SQL collection", async () => {
+        const ddl = await generatePostgresDdl(all, { includePolicies: false });
+
+        expect(ddl).toContain('CREATE TABLE "public"."customers"');
+        expect(ddl).not.toContain("exercises");
+        expect(ddl).not.toContain("events");
+    });
+
+    it("plans no RLS for a store that has none", () => {
+        const policies = generatePostgresPoliciesDdl(all);
+        expect(policies).not.toContain("exercises");
+
+        const plans = planCollectionPolicies(all);
+        expect(plans.map(p => p.qualified)).toEqual(["public.customers"]);
+    });
+});
+
+describe("the boot-time schema ensure", () => {
+    const empty = (): ExistingSchema => ({ tables: new Map(), enums: new Set() });
+
+    it("creates nothing for collections another engine stores", () => {
+        const plan = planCollectionSchemaEnsure(all, empty());
+
+        expect(plan.actions.map(a => a.target)).toEqual(
+            expect.arrayContaining(["public.customers"])
+        );
+        for (const action of plan.actions) {
+            expect(action.target).not.toContain("exercises");
+            expect(action.target).not.toContain("events");
+            expect(action.target).not.toContain("articles");
+        }
+    });
+});
+
+describe("the db push include list", () => {
+    it("does not claim a table for a Firestore collection", async () => {
+        // Anything absent from this list is *excluded* from the declarative
+        // apply, which is what protects it from being dropped.
+        const includes = await getTableIncludesFromCollections(all);
+
+        expect(includes).toEqual(["public.customers"]);
+    });
+});

package/src/schema/rls-bootstrap-sql.ts

@@ -0,0 +1,288 @@
+import { LEGACY_RLS_SCHEMA, REBASE_SCHEMA } from "@rebasepro/types";
+
+/**
+ * Canonical SQL bootstrap for the RLS helper functions.
+ *
+ * Generated RLS policies reference `rebase.uid()` / `rebase.roles()` /
+ * `rebase.jwt()`, so any SQL stream that can contain policies must be
+ * self-contained: it has to (re)create these helpers first. This matters for
+ * the migration directory in particular — Atlas replays migrations against a
+ * clean dev database where no out-of-band bootstrap has ever run, so a
+ * migration carrying policies without this preamble fails with
+ * "function rebase.uid() does not exist".
+ *
+ * Idempotent (`IF NOT EXISTS` / `OR REPLACE`) so it can be prepended to every
+ * policies block and re-applied freely. The runtime boot path
+ * (`auth/ensure-tables.ts`) creates the same functions under an advisory lock
+ * for HMR-safety; keep the definitions in sync.
+ *
+ * ## Creating the `rebase` schema here is now safe, and required
+ *
+ * It deliberately did not, once. These functions lived in a schema called
+ * `auth`, and the note here read: creating `rebase` would leak it into Atlas's
+ * replayed migration state, and — absent from the desired `schema.sql` — Atlas
+ * would then plan `DROP SCHEMA "rebase" CASCADE`, taking the auth tables with
+ * it. That reasoning still holds; what changed is the second half of it. The
+ * DDL generator now emits `CREATE SCHEMA IF NOT EXISTS "rebase"`
+ * unconditionally, so the schema is always in the desired state and the diff is
+ * empty. (It used to appear only when some collection happened to declare
+ * `schema: "rebase"` — true for the scaffold's users collection, and not a
+ * property anything guaranteed.) `db push` additionally excludes the whole
+ * schema from the declarative apply.
+ *
+ * See `@rebasepro/types`' `rls-functions` for why the functions moved out of
+ * `auth` at all: the short version is that the name was Supabase's, and
+ * `CREATE OR REPLACE FUNCTION auth.uid() RETURNS text` cannot be applied over
+ * Supabase's `RETURNS uuid` — Postgres refuses, and the refusal used to be
+ * swallowed.
+ */
+/**
+ * The bootstrap as individual statements.
+ *
+ * Kept as an array because the two consumers need different shapes and only one
+ * of them can take a multi-command string: the migration preamble is written to
+ * a file and replayed by Atlas, but the boot path runs through drizzle, whose
+ * node-postgres handle speaks the extended query protocol and rejects more than
+ * one command per call. Splitting a joined string back apart on `$$;` would be
+ * a parser for a problem that does not need one.
+ */
+export const RLS_BOOTSTRAP_STATEMENTS: readonly string[] = [
+    `CREATE SCHEMA IF NOT EXISTS ${REBASE_SCHEMA}`,
+
+    // Falls back to the pre-rename `app.user_id` so a database that has taken
+    // the new schema but is still served by an older backend keeps resolving
+    // the principal. Drop the COALESCE once no such deployment remains.
+    `CREATE OR REPLACE FUNCTION ${REBASE_SCHEMA}.uid() RETURNS text AS $$
+    SELECT COALESCE(
+        NULLIF(current_setting('app.uid', true), ''),
+        NULLIF(current_setting('app.user_id', true), '')
+    );
+$$ LANGUAGE sql STABLE`,
+
+    `CREATE OR REPLACE FUNCTION ${REBASE_SCHEMA}.jwt() RETURNS jsonb AS $$
+    SELECT COALESCE(
+        NULLIF(current_setting('app.jwt', true), ''),
+        '{}'
+    )::jsonb;
+$$ LANGUAGE sql STABLE`,
+
+    `CREATE OR REPLACE FUNCTION ${REBASE_SCHEMA}.roles() RETURNS text AS $$
+    SELECT COALESCE(NULLIF(current_setting('app.user_roles', true), ''), '');
+$$ LANGUAGE sql STABLE`
+];
+
+/** The same statements as one script, for migration files and raw clients. */
+export const RLS_BOOTSTRAP_SQL =
+    "-- Rebase schema + RLS helper functions (required by the policies below)\n" +
+    RLS_BOOTSTRAP_STATEMENTS.map(s => `${s};`).join("\n\n") + "\n";
+
+/**
+ * Removes the pre-1.0 `auth` schema, but only when Rebase is what put it there.
+ *
+ * ## Why this is safe against a Supabase database
+ *
+ * Two independent guards, and both have to pass:
+ *
+ *  1. **Each function is identified before it is dropped.** Ours returns `text`
+ *     and reads the `app.uid` GUC; Supabase's returns `uuid` and reads
+ *     `request.jwt.claims`. Nothing is dropped on a signature we did not write,
+ *     so a Supabase database — where our `CREATE OR REPLACE` could never have
+ *     succeeded in the first place, Postgres refusing to change a return type —
+ *     matches nothing and this is a no-op.
+ *  2. **`DROP SCHEMA … RESTRICT`**, never CASCADE. If anything else at all still
+ *     lives in `auth` (Supabase's `users` table, its other helpers), the drop
+ *     fails and the schema stays. CASCADE here would be unrecoverable.
+ *
+ * ## Why it cannot run too early
+ *
+ * Postgres records a dependency from every RLS policy to the functions its body
+ * calls, so `DROP FUNCTION auth.uid()` fails for as long as a single policy
+ * still references it. That is the interlock, and it is load-bearing: the drop
+ * can only succeed once every policy has been recompiled to \`rebase.uid()\`.
+ * Callers therefore run this *after* applying policies, and treat a failure as
+ * "not yet — try again next boot" rather than as an error.
+ */
+export const DROP_LEGACY_AUTH_SCHEMA_SQL = `
+DO $rebase_drop_legacy$
+DECLARE
+    dropped_any boolean := false;
+BEGIN
+    -- Each function is matched on its own result type and body, so a schema
+    -- that merely shares the name keeps everything it has.
+    IF EXISTS (
+        SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+        WHERE n.nspname = 'auth' AND p.proname = 'uid'
+          AND pg_get_function_result(p.oid) = 'text'
+          AND p.prosrc LIKE '%app.uid%'
+    ) THEN
+        DROP FUNCTION auth.uid();
+        dropped_any := true;
+    END IF;
+
+    IF EXISTS (
+        SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+        WHERE n.nspname = 'auth' AND p.proname = 'jwt'
+          AND pg_get_function_result(p.oid) = 'jsonb'
+          AND p.prosrc LIKE '%app.jwt%'
+    ) THEN
+        DROP FUNCTION auth.jwt();
+        dropped_any := true;
+    END IF;
+
+    IF EXISTS (
+        SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+        WHERE n.nspname = 'auth' AND p.proname = 'roles'
+          AND pg_get_function_result(p.oid) = 'text'
+          AND p.prosrc LIKE '%app.user_roles%'
+    ) THEN
+        DROP FUNCTION auth.roles();
+        dropped_any := true;
+    END IF;
+
+    -- RESTRICT: only an empty schema goes. Anything else in there — including a
+    -- Supabase installation left untouched above — keeps it.
+    IF dropped_any THEN
+        BEGIN
+            EXECUTE 'DROP SCHEMA auth RESTRICT';
+        EXCEPTION WHEN OTHERS THEN
+            NULL;
+        END;
+    END IF;
+END
+$rebase_drop_legacy$;
+`;
+
+/** Somebody's policy that still calls a pre-1.0 helper. */
+export interface LegacyRlsDependent {
+    schema: string;
+    table: string;
+    policy: string;
+}
+
+/**
+ * Policies whose body still calls `auth.uid()` / `auth.roles()` / `auth.jwt()`.
+ *
+ * Postgres will not drop a function a policy depends on, so this is exactly the
+ * set standing between a database and losing the legacy schema. Rebase's own
+ * policies leave the list on the next push or boot, when they are recompiled —
+ * anything still here afterwards is hand-written, will never be recompiled by
+ * anybody, and is the reason the drop keeps being skipped. Silence there would
+ * leave an operator staring at a schema the release notes said would go.
+ */
+export const LEGACY_RLS_DEPENDENTS_SQL = `
+    SELECT n.nspname AS schema, c.relname AS "table", p.polname AS policy
+    FROM pg_policy p
+    JOIN pg_class c ON c.oid = p.polrelid
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE pg_get_expr(p.polqual, p.polrelid) ~* '\\m${LEGACY_RLS_SCHEMA}\\.(uid|jwt|roles)\\s*\\('
+       OR pg_get_expr(p.polwithcheck, p.polrelid) ~* '\\m${LEGACY_RLS_SCHEMA}\\.(uid|jwt|roles)\\s*\\('
+    ORDER BY 1, 2, 3
+`;
+
+/** Somebody's *function* that still calls a pre-1.0 helper from its own body. */
+export interface LegacyRlsFunctionDependent {
+    schema: string;
+    function: string;
+}
+
+/**
+ * Functions whose body calls `auth.uid()` / `auth.roles()` / `auth.jwt()`.
+ *
+ * This is the half `DROP FUNCTION ... RESTRICT` cannot see, and the reason it
+ * needs its own query. Postgres records a dependency for a *policy* that calls a
+ * function, which is why the drop is safe against the policies above — but a
+ * `LANGUAGE sql` function whose body is a **string literal** is not parsed when
+ * it is created, so nothing is recorded and `RESTRICT` has nothing to refuse on.
+ * The drop succeeds and the caller is left pointing at a function that no longer
+ * exists, which fails at *query* time rather than at boot.
+ *
+ * A downstream project building on these helpers is not hypothetical: the Rebase
+ * control plane defines `auth.is_org_member(uuid)` and `auth.is_org_admin(uuid)`
+ * in this very schema, each calling `auth.uid()` in a string body, and eleven of
+ * its row-level-security policies go through them. Every one of those would have
+ * started failing the first time a recompile left no policy referencing
+ * `auth.uid()` directly — the drop's own precondition.
+ *
+ * Matching on the body text is the only option available, and it is deliberately
+ * broad: a false positive costs a schema that stays one release longer and says
+ * why, while a false negative costs somebody their policies.
+ */
+export const LEGACY_RLS_FUNCTION_DEPENDENTS_SQL = `
+    SELECT n.nspname AS schema, p.proname AS function
+    FROM pg_proc p
+    JOIN pg_namespace n ON n.oid = p.pronamespace
+    WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
+      AND NOT (n.nspname = '${LEGACY_RLS_SCHEMA}' AND p.proname IN ('uid', 'jwt', 'roles'))
+      AND p.prosrc ~* '\\m${LEGACY_RLS_SCHEMA}\\.(uid|jwt|roles)\\s*\\('
+    ORDER BY 1, 2
+`;
+
+/**
+ * Retire the pre-1.0 `auth` schema, reporting what is holding it back.
+ *
+ * The shared implementation behind the CLI's post-push step and the runtime's
+ * post-policy step. Both used to just fire {@link DROP_LEGACY_AUTH_SCHEMA_SQL}
+ * and swallow whatever came back, which is right for the ordinary case — a
+ * table not recompiled *yet* — and wrong for the one that never resolves: a
+ * hand-written policy nothing will ever rewrite. Then the schema stays forever
+ * and nothing ever says why.
+ */
+export async function dropLegacyAuthSchema(
+    run: (sql: string) => Promise<Record<string, unknown>[]>,
+    report: { info: (m: string) => void; warn: (m: string) => void }
+): Promise<void> {
+    let blockers: LegacyRlsDependent[];
+    try {
+        blockers = (await run(LEGACY_RLS_DEPENDENTS_SQL)) as unknown as LegacyRlsDependent[];
+    } catch {
+        return; // No catalogue access; nothing here is worth failing a boot for.
+    }
+
+    if (blockers.length > 0) {
+        report.warn(
+            `The pre-1.0 \`${LEGACY_RLS_SCHEMA}\` schema cannot be removed yet: ${blockers.length} ` +
+            `${blockers.length === 1 ? "policy still calls" : "policies still call"} ` +
+            `\`${LEGACY_RLS_SCHEMA}.uid()\` and friends, and Postgres will not drop a function a policy ` +
+            `depends on. Rebase's own policies are ` +
+            `rewritten automatically — anything listed here is hand-written SQL that has to be updated to ` +
+            `\`${REBASE_SCHEMA}.uid()\` by hand, after which the schema goes on its own:\n` +
+            blockers.map(b => `  • ${b.schema}.${b.table} → "${b.policy}"`).join("\n")
+        );
+        return;
+    }
+
+    // The half Postgres will not refuse on. See LEGACY_RLS_FUNCTION_DEPENDENTS_SQL:
+    // a string-literal SQL body records no dependency, so `DROP FUNCTION` drops
+    // out from under a caller that is still using it and nothing complains until
+    // a query runs.
+    let borrowers: LegacyRlsFunctionDependent[];
+    try {
+        borrowers = (await run(LEGACY_RLS_FUNCTION_DEPENDENTS_SQL)) as unknown as LegacyRlsFunctionDependent[];
+    } catch {
+        return;
+    }
+
+    if (borrowers.length > 0) {
+        report.warn(
+            `The pre-1.0 \`${LEGACY_RLS_SCHEMA}\` schema cannot be removed yet: ${borrowers.length} ` +
+            `${borrowers.length === 1 ? "function calls" : "functions call"} ` +
+            `\`${LEGACY_RLS_SCHEMA}.uid()\` and friends from its own body. Postgres records no dependency ` +
+            `for that — a SQL body written as a string literal is never parsed — so dropping the helpers ` +
+            `would leave these pointing at nothing, and they would fail when a query reached them rather ` +
+            `than now. Repoint them at \`${REBASE_SCHEMA}.uid()\`, after which the schema goes on its own:\n` +
+            borrowers.map(b => `  • ${b.schema}.${b.function}()`).join("\n")
+        );
+        return;
+    }
+
+    try {
+        await run(DROP_LEGACY_AUTH_SCHEMA_SQL);
+    } catch (err) {
+        // Something else depends on it, or the connection does not own it.
+        // Not fatal: the schema is inert either way now that no policy calls it.
+        report.info(
+            `Left the \`${LEGACY_RLS_SCHEMA}\` schema in place: ` +
+            (err instanceof Error ? err.message : String(err))
+        );
+    }
+}