@rebasepro/server-postgres 0.12.1-canary.gf5f1d39 → 0.13.1-canary.g06dbe5b

package/src/PostgresBootstrapper.ts

@@ -37,7 +37,7 @@ import { ensureHistoryTableExists } from "./history/ensure-history-table";
 import { patchPgArrayNullSafety } from "./utils/pg-array-null-patch";
 import { buildCollectionsFromSchema, introspectSchema, readRlsStatus } from "./schema/introspect-runtime";
 import { buildDrizzleTablesFromSchema, buildDrizzleRelationsFromSchema } from "./schema/dynamic-tables";
-import { detectConnectionPosture, ensureAppRole, validatePolicyPgRoles, warnOnAnonymousGrants, REBASE_USER_ROLE, type RawSqlRunner } from "./security/rls-enforcement";
+import { detectConnectionPosture, ensureAppRole, validatePolicyPgRoles, warnOnAnonymousGrants, warnOnLegacyRlsFunctions, warnOnRoleSchemaCollision, REBASE_USER_ROLE, type RawSqlRunner } from "./security/rls-enforcement";
 import { provisionTriggerCdc, type CdcTableRef } from "./services/cdc/trigger-cdc";
 import { collectJunctionLinks } from "./services/cdc/junction-tables";
 import { createChannelBus, resolveChannelBusSetting } from "./services/channel-bus";
@@ -102,6 +102,40 @@ export interface PostgresDriverInternals {
 
 // Re-export from shared CLI error utilities
 import { isEconnrefused } from "./cli-errors";
+import { classifyConnectFailure } from "./utils/pg-error-utils";
+
+/**
+ * Which table name the boot-time drift check should look for, for one collection.
+ *
+ * A declared `table` IS the table name, not a hint to be second-guessed. This
+ * used to ask the registry whether it had indexed the declared name and fall
+ * back to the SLUG when it had not — but "the registry does not know this table"
+ * is exactly the condition the drift check exists to report, so the fallback
+ * fired precisely when it was most harmful.
+ *
+ * A collection with `slug: "usage-daily", table: "usage_daily"` was reported as
+ * missing table `usage-daily`: a name that does not exist, should never exist,
+ * and that nobody can find by looking. Worse, the remediation the caller prints
+ * says to run `rebase db push` — which would then CREATE that invented table
+ * beside the correct one, the same "second copy" hazard the misplaced-schema
+ * branch further down exists to prevent. Seen in production, where a correctly
+ * migrated database reported drift on every boot.
+ *
+ * The slug is used only when nothing was declared, which is the config shape
+ * where the slug genuinely is the table name.
+ *
+ * Exported for its own test: the caller needs a live pool and a real database,
+ * and this is the part that was wrong.
+ */
+export function resolveDriftCheckName(
+    col: CollectionConfig,
+    registeredTableNames: string[]
+): string {
+    const declaredTable = isRelationalCollectionConfig(col) ? col.table : undefined;
+    return declaredTable
+        ?? registeredTableNames.find((k) => k === col.slug)
+        ?? col.slug;
+}
 
 /**
  * Default PostgreSQL bootstrapper.
@@ -260,9 +294,45 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
                     throw new Error(`Cannot connect to PostgreSQL at ${hostInfo}: connection refused. Is the database running?`);
                 }
 
-                // For other errors (timeouts, auth failures, etc.) warn but continue —
-                // the pool may recover on subsequent attempts.
-                logger.error("❌ Failed to connect to PostgreSQL", { error: err });
+                /*
+                 * Everything else.
+                 *
+                 * Two problems with what used to happen here. First, the logged
+                 * error was Drizzle's wrapper — `Failed query: SELECT 1` and a
+                 * stack through drizzle internals — while the sentence that
+                 * actually says what is wrong ("password authentication failed
+                 * for user …", "database … does not exist") sits in `.cause`
+                 * and was never printed. A developer with a typo in their
+                 * DATABASE_URL got two walls of stack trace and no cause.
+                 *
+                 * Second, "continuing… the pool may recover" is only true for
+                 * a transient fault. A wrong password or a missing database is
+                 * settled: the next query fails the same way, so the process
+                 * died seconds later anyway — after printing a reassurance.
+                 * Those now fail here, where the message can be about the
+                 * cause rather than about whichever query ran next.
+                 */
+                const { fatal, reason, code } = classifyConnectFailure(err);
+                const detail = code ? ` [${code}]` : "";
+
+                if (fatal) {
+                    logger.error(
+                        `\n` +
+                        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+                        `  ❌  PostgreSQL refused the connection\n` +
+                        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+                        `\n` +
+                        `  ${reason}${detail}\n` +
+                        `\n` +
+                        `  The server is reachable, so this is the credentials or the\n` +
+                        `  database name in DATABASE_URL — check them in your .env.\n` +
+                        `\n` +
+                        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`
+                    );
+                    throw new Error(`PostgreSQL refused the connection: ${reason}${detail}`);
+                }
+
+                logger.error(`❌ Failed to connect to PostgreSQL: ${reason}${detail}`, { error: err });
                 logger.warn("⚠️ Continuing without initial database verification. Drizzle/PG will attempt to connect on subsequent queries.");
             }
 
@@ -294,20 +364,33 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
             // bypasses RLS. Detect the posture and, when privileged, provision
             // the restricted `rebase_user` role and route authenticated
             // requests (reads AND writes) through it. The server context (base
-            // driver / dataAsAdmin / auth flows) stays on the owner connection
-            // and bypasses. Default-on: a privileged connection that cannot be
+            // driver / auth flows / `rebase.sql`) stays on the owner connection
+            // and bypasses; `rebase.dataAsAdmin` does NOT — it is scoped with
+            // `withAuth({ uid: "service", roles: ["admin"] })` at boot, so it
+            // runs as `rebase_user` and its policies are evaluated.
+            // Default-on: a privileged connection that cannot be
             // isolated fails the boot rather than serving unenforced requests.
             {
                 const runSql: RawSqlRunner = async (text) => {
                     const res = await schemaAwareDb.execute(sql.raw(text));
                     return (res.rows ?? []) as Record<string, unknown>[];
                 };
+                // Said before anything else touches the schema: if the role and
+                // a schema share a name, unqualified SQL from any tool that does
+                // not pin `search_path` has been landing in the wrong place, and
+                // that is worth knowing before reading the drift report below.
+                await warnOnRoleSchemaCollision(runSql);
+
                 const posture = await detectConnectionPosture(runSql);
                 if (posture.privileged) {
                     const collectionSchemas = registry.getCollections()
                         .map((c) => (c as { schema?: string }).schema)
                         .filter((s): s is string => typeof s === "string");
-                    await ensureAppRole(runSql, ["public", "rebase", "auth", ...collectionSchemas]);
+                    // `auth` is deliberately absent: the RLS helpers moved into
+                    // `rebase`, and granting USAGE on a schema Rebase does not
+                    // own would, on a Supabase database, hand the end-user role
+                    // access to theirs.
+                    await ensureAppRole(runSql, ["public", "rebase", ...collectionSchemas]);
                     driver.rlsUserRole = REBASE_USER_ROLE;
                     realtimeService.rlsUserRole = REBASE_USER_ROLE;
                     logger.info(`🔐 RLS enforcement active: authenticated requests run as "${REBASE_USER_ROLE}" (connection "${posture.role}" bypasses RLS: ${posture.superuser ? "superuser" : posture.bypassRLS ? "BYPASSRLS" : "table owner"})`);
@@ -336,6 +419,11 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
                 // a rule that reads as "signed in only" but is true for every
                 // caller grants the data away rather than hiding it.
                 warnOnAnonymousGrants(registry.getCollections() as never);
+
+                // Raw policy SQL written against the pre-1.0 helper schema. It
+                // is rewritten on compile, so this is the only place the project
+                // is ever told the spelling moved.
+                warnOnLegacyRlsFunctions(registry.getCollections() as never);
             }
 
             // Ensure branch metadata table exists when branching is available
@@ -487,22 +575,28 @@ table: link.table });
             try {
                 const registeredCollections = registry.getCollections();
                 if (registeredCollections.length > 0) {
-                    const schemasToCheck = Array.from(new Set(
-                        registeredCollections.map(c => "schema" in c && c.schema ? c.schema : "public")
-                    ));
-                    const schemasList = schemasToCheck.map(s => `'${s}'`).join(",");
+                    // Deliberately unfiltered by schema: a table that is missing
+                    // from where the collection says it lives is very often
+                    // sitting in another schema entirely (see the misplaced-table
+                    // report below), and knowing *which* is the whole answer.
                     const result = await schemaAwareDb.execute(sql.raw(`
                         SELECT table_name, table_schema
                         FROM information_schema.tables
-                        WHERE table_schema IN (${schemasList})
+                        WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
                           AND table_type = 'BASE TABLE'
                     `));
+                    const tablesByName = new Map<string, string[]>();
+                    for (const row of result.rows as Array<{ table_name: string; table_schema: string }>) {
+                        const schemas = tablesByName.get(row.table_name) ?? [];
+                        schemas.push(row.table_schema);
+                        tablesByName.set(row.table_name, schemas);
+                    }
                     const dbTables = new Set(
                         (result.rows as Array<{ table_name: string; table_schema: string }>).map(r =>
                             r.table_schema === "public" ? r.table_name : `${r.table_schema}.${r.table_name}`
                         )
                     );
-                    const missing: Array<{ slug: string; table: string }> = [];
+                    const missing: Array<{ slug: string; table: string; foundIn: string[] }> = [];
                     for (const col of registeredCollections) {
                         // Auth owns its table and creates it later in this same
                         // boot (initializeAuth → ensureAuthTablesExist), so it is
@@ -513,41 +607,72 @@ table: link.table });
                         if ((col as { auth?: { enabled?: boolean } }).auth?.enabled) continue;
 
                         const schemaName = "schema" in col && col.schema ? col.schema : "public";
-                        const declaredTable = isRelationalCollectionConfig(col) ? col.table : undefined;
-                        const tableName = registry.hasTableForCollection(
-                            declaredTable ?? col.slug
-                        )
-                            ? (declaredTable ?? col.slug)
-                            : col.slug;
-                        // Resolve the actual table name the registry stored
-                        const resolvedTable = registry.getTableNames().find((k) =>
-                            k === tableName ||
-                            k === col.slug
-                        );
-                        const checkName = resolvedTable ?? tableName;
+                        const checkName = resolveDriftCheckName(col, registry.getTableNames());
                         const fullCheckName = schemaName === "public" ? checkName : `${schemaName}.${checkName}`;
                         if (!dbTables.has(fullCheckName)) {
                             // Report what was actually looked up: an unqualified
                             // "users" sends people hunting for public.users.
                             missing.push({ slug: col.slug,
-table: fullCheckName });
+table: fullCheckName,
+foundIn: (tablesByName.get(checkName) ?? []).filter(s => s !== schemaName) });
                         }
                     }
                     if (missing.length > 0) {
                         const lines = missing.map(
-                            m => `    • collection "${m.slug}" → table "${m.table}"`
+                            m => `    • collection "${m.slug}" → table "${m.table}"` +
+                                (m.foundIn.length > 0
+                                    ? ` — but a table of that name exists in ${m.foundIn.map(s => `"${s}"`).join(", ")}`
+                                    : "")
                         );
+                        // A table that exists under the same name in another
+                        // schema is not ordinary drift: it is almost always this
+                        // framework's own `search_path` hazard. Postgres resolves
+                        // unqualified SQL through `"$user", public`, and this
+                        // project creates a schema named `rebase` while every
+                        // template names the database role `rebase` too — so an
+                        // unqualified CREATE TABLE (a hand-written migration, the
+                        // SQL editor, drizzle-kit) lands in `rebase`, and the
+                        // runtime, which now pins `search_path=public`, cannot see
+                        // it. Say so, because "missing table" sends people to
+                        // re-run a push that will create a *second* copy.
+                        const misplaced = missing.filter(m => m.foundIn.length > 0);
+                        const misplacedHelp = misplaced.length === 0 ? [] : [
+                            "  Those tables exist — in the wrong schema. Unqualified SQL run by a",
+                            "  role whose name matches a schema (`rebase` is both, by default)",
+                            "  resolves through search_path's \"$user\" and creates there. Move them:",
+                            ...misplaced.map(m =>
+                                `      ALTER TABLE "${m.foundIn[0]}"."${m.table.split(".").pop()}" SET SCHEMA "${m.table.includes(".") ? m.table.split(".")[0] : "public"}";`
+                            ),
+                            "  and qualify the SQL that created them, or pin search_path in DATABASE_URL",
+                            "  (`?options=-c%20search_path%3Dpublic`).",
+                            ""
+                        ];
+                        // This runtime creates collection tables (and their RLS)
+                        // at boot unless REBASE_MIGRATE_ON_BOOT=none, so a drift
+                        // this late means that step was disabled, could not run,
+                        // or failed — the guidance names a path for both a managed
+                        // tenant (whose in-cluster database `pnpm db:push` cannot
+                        // reach) and a self-host. Naming only the pnpm scripts, as
+                        // this once did, told a managed operator to run a command
+                        // that structurally cannot touch their database.
                         logger.warn([
                             "",
-                            "┌──────────────────────────────────────────────────────────────┐",
-                            "│  ⚠️  SCHEMA DRIFT — Missing tables in database               │",
-                            "├──────────────────────────────────────────────────────────────┤",
-                            ...lines.map(l => `│ ${l.padEnd(60)}│`),
-                            "├──────────────────────────────────────────────────────────────┤",
-                            "│  Run one of:                                                 │",
-                            "│    pnpm db:push      (dev — fast, no migration files)        │",
-                            "│    pnpm db:migrate   (prod — creates migration files)        │",
-                            "└──────────────────────────────────────────────────────────────┘",
+                            "⚠️  SCHEMA DRIFT — the database is missing tables this backend serves:",
+                            ...lines,
+                            "",
+                            ...misplacedHelp,
+                            "  This runtime applies the collection schema at boot unless",
+                            "  REBASE_MIGRATE_ON_BOOT=none. Check the \"Collection schema\" / \"policies\"",
+                            "  log lines above — this drift means that step was off, skipped, or failed.",
+                            "    • Managed cloud: redeploy with REBASE_MIGRATE_ON_BOOT unset or",
+                            "      \"ensure\"; the runtime applies the schema to the tenant DB.",
+                            "      If the log above says the driver does not implement collection-table",
+                            "      creation, THIS driver is too old to do it. A driver is installed from",
+                            "      your bundle's dependencies, not supplied by the platform image, so a",
+                            "      newer runtime will not update it: bump \"@rebasepro/server-postgres\"",
+                            "      in your project's package.json and redeploy.",
+                            "    • Self-host: run `rebase db push` (dev) or `rebase db migrate` (prod)",
+                            "      against DATABASE_URL.",
                             ""
                         ].join("\n"));
                     }
@@ -711,7 +836,90 @@ schemaHealthCheck: () => probeAuthSchema(db, resolveAuthSchema(authCollection))
                 collections as Parameters<typeof ensureCollectionTables>[1],
                 log
             );
-            return { applied: plan.actions.length };
+            for (const failure of plan.failures) {
+                logger.warn(
+                    failure.kind === "comment-column"
+                        // The stamp records which `search` block the generated
+                        // column was built from. Without it the next boot cannot
+                        // tell a changed block from an unchanged one and adopts
+                        // the column again instead of refusing.
+                        ? `🔍 [schema] Could not record the search fingerprint on "${failure.target}" — search works, ` +
+                          `but a later change to the \`search\` block will not be detected: ${failure.error}`
+                        : `🔗 [schema] Could not add foreign key "${failure.target}" — the column exists and the ` +
+                          `collection still serves, but rows are not policed by this constraint: ${failure.error}`
+                );
+            }
+            return { applied: plan.actions.length - plan.failures.length };
+        },
+
+        /**
+         * Apply the collections' RLS policies — ENABLE ROW LEVEL SECURITY and the
+         * `securityRules` compiled to `CREATE POLICY` — so a freshly provisioned
+         * database serves data instead of denying every user-context read.
+         *
+         * The companion to {@link ensureCollectionSchema}: that creates the
+         * tables, this makes them servable. Boot runs it *after* auth
+         * initialization, because the generated policies call `auth.uid()` /
+         * `auth.roles()`, and `CREATE POLICY` validates those functions exist.
+         *
+         * Runs through the same drizzle handle, one statement at a time (that
+         * handle speaks the extended query protocol, which rejects multi-command
+         * strings). Failures are per-table and non-fatal: a table left un-policed
+         * stays RLS-enabled, so it denies rather than leaks.
+         */
+        async ensureCollectionPolicies(
+            collections: unknown[],
+            driverResult: InitializedDriver,
+            log?: (message: string) => void
+        ): Promise<{ applied: number }> {
+            const internals = driverResult.internals as PostgresDriverInternals;
+            const { ensureCollectionPolicies } = await import("./schema/ensure-collection-policies");
+            const queryable = {
+                async query<T>(text: string): Promise<{ rows: T[] }> {
+                    const result = await internals.db.execute(sql.raw(text));
+                    const rows = (result as unknown as { rows?: T[] }).rows;
+                    return { rows: rows ?? (Array.isArray(result) ? (result as T[]) : []) };
+                }
+            };
+            const outcome = await ensureCollectionPolicies(
+                queryable,
+                collections as CollectionConfig[],
+                log
+            );
+
+            for (const skip of outcome.skipped) {
+                logger.warn(`🔐 [rls] Policies not applied to "${skip.table}": ${skip.reason}`);
+            }
+            for (const failure of outcome.failures) {
+                logger.warn(
+                    `🔐 [rls] Could not fully apply policies to "${failure.table}" — it stays locked (denies) until this is resolved: ${failure.error}`
+                );
+            }
+
+            // Retire the pre-1.0 `auth` schema now that the policies above no
+            // longer call into it. Deliberately after, and deliberately quiet:
+            // Postgres refuses to drop a function an RLS policy still
+            // references, so on a database where some table has not been
+            // recompiled yet this is expected to fail and succeed on a later
+            // boot. See DROP_LEGACY_AUTH_SCHEMA_SQL for the guards that keep it
+            // off a Supabase `auth` schema.
+            try {
+                const { dropLegacyAuthSchema } = await import("./schema/rls-bootstrap-sql");
+                await dropLegacyAuthSchema(
+                    async (text) => {
+                        const res = await internals.db.execute(sql.raw(text));
+                        return (res.rows ?? []) as Record<string, unknown>[];
+                    },
+                    { info: (m) => logger.info(m), warn: (m) => logger.warn(m) }
+                );
+            } catch (err) {
+                logger.info(
+                    "Left the legacy `auth` schema in place: " +
+                    (err instanceof Error ? err.message : String(err))
+                );
+            }
+
+            return { applied: outcome.policiesApplied };
         },
 
         getAdmin(driverResult: InitializedDriver): DatabaseAdmin | undefined {