@rebasepro/server-postgresql 0.6.1 → 0.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/server-postgresql",
   "type": "module",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "PostgreSQL data source backend implementation for Rebase with Drizzle ORM",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -29,11 +29,23 @@
     "backend",
     "rebase"
   ],
+  "scripts": {
+    "watch": "vite build --watch",
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
+    "test:lint": "eslint \"src/**\" --quiet",
+    "test": "jest --passWithNoTests",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f"
+  },
   "jest": {
     "transform": {
       "^.+\\.tsx?$": "ts-jest"
     },
     "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$",
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "test/e2e/"
+    ],
     "moduleFileExtensions": [
       "ts",
       "tsx",
@@ -62,42 +74,36 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@rebasepro/common": "workspace:*",
+    "@rebasepro/sdk-generator": "workspace:*",
+    "@rebasepro/server-core": "workspace:*",
+    "@rebasepro/types": "workspace:*",
+    "@rebasepro/utils": "workspace:*",
     "arg": "^5.0.2",
-    "chalk": "^5.6.2",
+    "chalk": "^4.1.2",
     "chokidar": "5.0.0",
     "dotenv": "^17.4.2",
     "drizzle-orm": "^0.45.2",
     "execa": "^9.6.1",
     "hono": "^4.12.25",
     "pg": "^8.21.0",
-    "ws": "^8.21.0",
-    "@rebasepro/types": "0.6.1",
-    "@rebasepro/server-core": "0.6.1",
-    "@rebasepro/sdk-generator": "0.6.1",
-    "@rebasepro/common": "0.6.1",
-    "@rebasepro/utils": "0.6.1"
+    "ws": "^8.21.0"
   },
   "devDependencies": {
+    "@ariga/atlas": "^1.2.2",
     "@types/jest": "^30.0.0",
     "@types/node": "^25.9.3",
     "@types/pg": "^8.20.0",
     "@types/ws": "^8.18.1",
     "@vitejs/plugin-react": "^6.0.2",
-    "drizzle-kit": "^0.31.10",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11",
     "typescript": "^6.0.3",
-    "vite": "^8.0.16"
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9"
   },
   "gitHead": "d935eefa5aa8d1009a2398cfac2c1e4ee9aeb6b6",
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "watch": "vite build --watch",
-    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
-    "test:lint": "eslint \"src/**\" --quiet",
-    "test": "jest --passWithNoTests",
-    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f"
   }
-}
+}

package/src/PostgresBackendDriver.ts

@@ -31,6 +31,8 @@ import { PostgresCollectionRegistry } from "./collections/PostgresCollectionRegi
 import { HistoryService } from "./history/HistoryService";
 import { mergeDeep } from "@rebasepro/utils";
 import { logger } from "@rebasepro/server-core";
+import { isRoleSwitchingPermissionError } from "./utils/pg-error-utils";
+import { classifyTable, detectJunctionTables } from "./utils/table-classification";
 
 export class PostgresBackendDriver implements DataDriver {
     key = "postgres";
@@ -44,6 +46,14 @@ export class PostgresBackendDriver implements DataDriver {
     public data: RebaseData;
     public client?: RebaseClient;
 
+    /**
+     * Auto-set to `true` when a SET LOCAL ROLE fails with insufficient
+     * privileges, so subsequent queries skip the doomed attempt.
+     * Mirrors the static `DISABLE_DB_ROLE_SWITCHING` env var but is
+     * learned at runtime.
+     */
+    private _roleSwitchingDisabled = false;
+
     /**
      * When true, realtime notifications are deferred until after the
      * wrapping transaction commits.  Set by `withAuth` → `withTransaction`.
@@ -684,10 +694,11 @@ export class PostgresBackendDriver implements DataDriver {
 
     async executeSql(sqlText: string, options?: {
         database?: string,
-        role?: string
+        role?: string,
+        params?: unknown[]
     }): Promise<Record<string, unknown>[]> {
         if (!options?.database && !options?.role) {
-            return this.entityService.executeSql(sqlText);
+            return this.entityService.executeSql(sqlText, options?.params);
         }
 
         const targetDb = this.getTargetDb(options?.database);
@@ -698,7 +709,7 @@ export class PostgresBackendDriver implements DataDriver {
             // as it's a no-op that can fail on managed Postgres setups where the connection
             // user doesn't have permission to SET ROLE.
             let needsRoleSwitch = false;
-            if (options?.role && process.env.DISABLE_DB_ROLE_SWITCHING !== "true") {
+            if (options?.role && process.env.DISABLE_DB_ROLE_SWITCHING !== "true" && !this._roleSwitchingDisabled) {
                 try {
                     const currentRoleResult = await targetDb.execute(drizzleSql.raw("SELECT current_user AS role"));
                     const currentRole = (currentRoleResult.rows?.[0] as Record<string, unknown>)?.role as string | undefined;
@@ -711,14 +722,57 @@ export class PostgresBackendDriver implements DataDriver {
 
             if (needsRoleSwitch && options?.role) {
                 const safeRole = options.role.replace(/"/g, "\"\"");
-                return await targetDb.transaction(async (tx) => {
-                    await tx.execute(drizzleSql.raw(`SET LOCAL ROLE "${safeRole}"`));
-                    const result = await tx.execute(drizzleSql.raw(sqlText));
-                    return result.rows as Record<string, unknown>[];
-                });
+                try {
+                    return await targetDb.transaction(async (tx) => {
+                        await tx.execute(drizzleSql.raw(`SET LOCAL ROLE "${safeRole}"`));
+                        let result;
+                        if (options?.params && options.params.length > 0) {
+                            const parts = sqlText.split(/\$(\d+)/);
+                            const chunks: ReturnType<typeof drizzleSql.raw | typeof drizzleSql.param>[] = [];
+                            for (let i = 0; i < parts.length; i++) {
+                                if (i % 2 === 0) {
+                                    if (parts[i].length > 0) chunks.push(drizzleSql.raw(parts[i]));
+                                } else {
+                                    chunks.push(drizzleSql.param(options.params[Number(parts[i]) - 1]));
+                                }
+                            }
+                            result = await tx.execute(drizzleSql.join(chunks, drizzleSql.raw("")));
+                        } else {
+                            result = await tx.execute(drizzleSql.raw(sqlText));
+                        }
+                        return result.rows as Record<string, unknown>[];
+                    });
+                } catch (roleError: unknown) {
+                    if (isRoleSwitchingPermissionError(roleError)) {
+                        logger.warn(
+                            `[PostgresBackendDriver] SET LOCAL ROLE "${safeRole}" failed — ` +
+                            `the connection user lacks permission. Falling back to executing ` +
+                            `without role switching. To suppress this warning, set ` +
+                            `DISABLE_DB_ROLE_SWITCHING=true in your .env file.`
+                        );
+                        this._roleSwitchingDisabled = true;
+                        // Fall through to execute without role switching below
+                    } else {
+                        throw roleError;
+                    }
+                }
             }
 
-            const result = await targetDb.execute(drizzleSql.raw(sqlText));
+            let result;
+            if (options?.params && options.params.length > 0) {
+                const parts = sqlText.split(/\$(\d+)/);
+                const chunks: ReturnType<typeof drizzleSql.raw | typeof drizzleSql.param>[] = [];
+                for (let i = 0; i < parts.length; i++) {
+                    if (i % 2 === 0) {
+                        if (parts[i].length > 0) chunks.push(drizzleSql.raw(parts[i]));
+                    } else {
+                        chunks.push(drizzleSql.param(options.params[Number(parts[i]) - 1]));
+                    }
+                }
+                result = await targetDb.execute(drizzleSql.join(chunks, drizzleSql.raw("")));
+            } else {
+                result = await targetDb.execute(drizzleSql.raw(sqlText));
+            }
             return result.rows as Record<string, unknown>[];
         } catch (error: unknown) {
             const msg = error instanceof Error ? error.message : String(error);
@@ -780,48 +834,15 @@ export class PostgresBackendDriver implements DataDriver {
             ORDER BY table_name;
         `);
 
-        const internalPrefixes = ["_rebase_", "_auth_"];
-        const internalExact = [
-            "users", "roles", "user_roles", "refresh_tokens",
-            "password_reset_tokens", "email_verification_tokens"
-        ];
-
         const allTables = result
             .map((r: Record<string, unknown>) => r.table_name as string)
-            .filter((name: string) => {
-                if (internalPrefixes.some(prefix => name.startsWith(prefix))) return false;
-                if (internalExact.includes(name)) return false;
-                return true;
-            });
+            .filter((name: string) => classifyTable(name, "public") !== "rebase-internal");
 
         // Detect junction tables: tables where every column is part of a foreign key.
         // These are typically many-to-many connection tables and shouldn't be suggested.
         let junctionTables = new Set<string>();
         try {
-            const junctionResult = await this.executeSql(`
-                SELECT t.table_name
-                FROM information_schema.tables t
-                WHERE t.table_schema = 'public'
-                  AND t.table_type = 'BASE TABLE'
-                  AND NOT EXISTS (
-                    -- Find columns that are NOT part of any foreign key
-                    SELECT 1
-                    FROM information_schema.columns c
-                    WHERE c.table_schema = t.table_schema
-                      AND c.table_name = t.table_name
-                      AND c.column_name NOT IN (
-                        SELECT kcu.column_name
-                        FROM information_schema.key_column_usage kcu
-                        JOIN information_schema.table_constraints tc
-                          ON tc.constraint_name = kcu.constraint_name
-                          AND tc.table_schema = kcu.table_schema
-                        WHERE tc.constraint_type = 'FOREIGN KEY'
-                          AND kcu.table_schema = t.table_schema
-                          AND kcu.table_name = t.table_name
-                      )
-                  );
-            `);
-            junctionTables = new Set(junctionResult.map((r: Record<string, unknown>) => r.table_name as string));
+            junctionTables = await detectJunctionTables(this.executeSql.bind(this));
         } catch (e) {
             logger.warn("Could not detect junction tables", { error: e });
         }

package/src/PostgresBootstrapper.ts

@@ -55,6 +55,9 @@ export interface PostgresDriverInternals {
     poolManager?: DatabasePoolManager;
 }
 
+// Re-export from shared CLI error utilities
+import { isEconnrefused } from "./cli-errors";
+
 /**
  * Default PostgreSQL bootstrapper.
  *
@@ -117,10 +120,39 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
                 : connection) as import("pg").Pool;
             const schemaAwareDb = createDrizzle(rawClient, { schema: mergedSchema });
 
-            // Verify connection
+            // Verify connection — fail fast if the database is unreachable
             try {
                 await schemaAwareDb.execute(sql`SELECT 1`);
-            } catch (err) {
+            } catch (err: unknown) {
+                const isConnectionRefused = isEconnrefused(err);
+                if (isConnectionRefused) {
+                    // Parse host/port from connection string for a helpful message
+                    let hostInfo = pgConfig.connectionString || "unknown";
+                    try {
+                        const parsed = new URL(pgConfig.connectionString || "");
+                        hostInfo = `${parsed.hostname}:${parsed.port || 5432}`;
+                    } catch { /* use raw string */ }
+
+                    const message =
+                        `\n` +
+                        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+                        `  ❌  Cannot connect to PostgreSQL at ${hostInfo}\n` +
+                        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+                        `\n` +
+                        `  The database server is not running or is not accepting\n` +
+                        `  connections. Common fixes:\n` +
+                        `\n` +
+                        `    • brew services start postgresql@18\n` +
+                        `    • docker compose up -d postgres\n` +
+                        `    • Verify DATABASE_URL in your .env file\n` +
+                        `\n` +
+                        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
+                    logger.error(message);
+                    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 });
                 logger.warn("⚠️ Continuing without initial database verification. Drizzle/PG will attempt to connect on subsequent queries.");
             }

package/src/auth/ensure-tables.ts

@@ -82,7 +82,37 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Ent
         const passwordResetTokensTableName = `"${authSchema}"."password_reset_tokens"`;
         const appConfigTableName = `"${authSchema}"."app_config"`;
 
-        // ── Create tables (idempotent) ──────────────────────────────────
+        // ── Create users table (idempotent) ─────────────────────────────
+        // The users table MUST be created before any dependent auth tables
+        // (user_identities, refresh_tokens, etc.) because they all hold
+        // foreign keys referencing users(id).  When a developer runs
+        // `pnpm dev` for the first time without `db:migrate`, this ensures
+        // the server can self-bootstrap.
+        const idDefault = userIdType === "UUID"
+            ? "DEFAULT gen_random_uuid()"
+            : userIdType === "INTEGER"
+                ? "GENERATED ALWAYS AS IDENTITY"
+                : "DEFAULT gen_random_uuid()::text";
+
+        await db.execute(sql`
+            CREATE TABLE IF NOT EXISTS ${sql.raw(usersTableName)} (
+                id ${sql.raw(userIdType)} PRIMARY KEY ${sql.raw(idDefault)},
+                email VARCHAR(255) UNIQUE NOT NULL,
+                display_name VARCHAR(255),
+                photo_url VARCHAR(500),
+                roles TEXT[] DEFAULT '{}' NOT NULL,
+                password_hash VARCHAR(255),
+                email_verified BOOLEAN DEFAULT FALSE NOT NULL,
+                email_verification_token VARCHAR(255),
+                email_verification_sent_at TIMESTAMP WITH TIME ZONE,
+                is_anonymous BOOLEAN DEFAULT FALSE NOT NULL,
+                metadata JSONB DEFAULT '{}' NOT NULL,
+                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
+                updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
+            )
+        `);
+
+        // ── Create dependent auth tables (idempotent) ───────────────────
 
         // Create user_identities table
         await db.execute(sql`
@@ -155,6 +185,31 @@ export async function ensureAuthTablesExist(db: NodePgDatabase, collection?: Ent
             ON ${sql.raw(passwordResetTokensTableName)}(user_id)
         `);
 
+        // Create magic link tokens table
+        const magicLinkTokensTableName = `"${authSchema}"."magic_link_tokens"`;
+        await db.execute(sql`
+            CREATE TABLE IF NOT EXISTS ${sql.raw(magicLinkTokensTableName)} (
+                id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+                user_id ${sql.raw(userIdType)} NOT NULL REFERENCES ${sql.raw(usersTableName)}(id) ON DELETE CASCADE,
+                token_hash TEXT NOT NULL UNIQUE,
+                expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
+                used_at TIMESTAMP WITH TIME ZONE,
+                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+            )
+        `);
+
+        // Create index on token_hash for magic link lookups
+        await db.execute(sql`
+            CREATE INDEX IF NOT EXISTS idx_magic_link_tokens_hash 
+            ON ${sql.raw(magicLinkTokensTableName)}(token_hash)
+        `);
+
+        // Create index on user_id for magic link cleanup
+        await db.execute(sql`
+            CREATE INDEX IF NOT EXISTS idx_magic_link_tokens_user 
+            ON ${sql.raw(magicLinkTokensTableName)}(user_id)
+        `);
+
         // Create app config table
         await db.execute(sql`
             CREATE TABLE IF NOT EXISTS ${sql.raw(appConfigTableName)} (

package/src/auth/services.ts

@@ -2,7 +2,7 @@ import { eq, getTableName, sql } from "drizzle-orm";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { getTableConfig } from "drizzle-orm/pg-core";
 import type { RebasePgTable } from "../types";
-import { users, refreshTokens, passwordResetTokens, userIdentities } from "../schema/auth-schema";
+import { users, refreshTokens, passwordResetTokens, userIdentities, magicLinkTokens } from "../schema/auth-schema";
 import {
     UserRepository,
     RoleRepository,
@@ -15,6 +15,7 @@ import {
     CreateRoleData,
     RefreshTokenInfo,
     PasswordResetTokenInfo,
+    MagicLinkTokenInfo,
     UserIdentityData,
     ListUsersOptions,
     PaginatedUsersResult,
@@ -693,6 +694,68 @@ export class PasswordResetTokenService {
     }
 }
 
+/**
+ * Magic link token service.
+ * Handles magic link token storage for passwordless email login.
+ */
+export class MagicLinkTokenService {
+    private magicLinkTokensTable: RebasePgTable;
+
+    constructor(
+        private db: NodePgDatabase,
+        tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>
+    ) {
+        this.magicLinkTokensTable = (magicLinkTokens as unknown as RebasePgTable);
+    }
+
+    private getQualifiedTableName(): string {
+        const name = getTableName(this.magicLinkTokensTable);
+        const schema = getTableConfig(this.magicLinkTokensTable).schema || "public";
+        return `"${schema}"."${name}"`;
+    }
+
+    async createToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void> {
+        // Delete any existing unused tokens for this user
+        const tableName = this.getQualifiedTableName();
+        await this.db.execute(sql`
+            DELETE FROM ${sql.raw(tableName)} 
+            WHERE user_id = ${userId} AND used_at IS NULL
+        `);
+
+        await this.db.insert(this.magicLinkTokensTable).values({
+            userId,
+            tokenHash,
+            expiresAt
+        });
+    }
+
+    async findValidByHash(tokenHash: string): Promise<MagicLinkTokenInfo | null> {
+        const tableName = this.getQualifiedTableName();
+        const result = await this.db.execute(sql`
+            SELECT user_id, expires_at 
+            FROM ${sql.raw(tableName)} 
+            WHERE token_hash = ${tokenHash} 
+              AND used_at IS NULL 
+              AND expires_at > NOW()
+        `);
+
+        if (result.rows.length === 0) return null;
+
+        const row = result.rows[0] as { user_id: string; expires_at: string | number | Date };
+        return {
+            userId: row.user_id,
+            expiresAt: new Date(row.expires_at)
+        };
+    }
+
+    async markAsUsed(tokenHash: string): Promise<void> {
+        await this.db
+            .update(this.magicLinkTokensTable)
+            .set({ usedAt: new Date() })
+            .where(eq(this.magicLinkTokensTable.tokenHash, tokenHash));
+    }
+}
+
 /**
  * PostgreSQL implementation of TokenRepository.
  * Combines refresh token and password reset token operations.
@@ -700,6 +763,7 @@ export class PasswordResetTokenService {
 export class PostgresTokenRepository implements TokenRepository {
     private refreshTokenService: RefreshTokenService;
     private passwordResetTokenService: PasswordResetTokenService;
+    private magicLinkTokenService: MagicLinkTokenService;
 
     constructor(
         private db: NodePgDatabase,
@@ -707,6 +771,7 @@ export class PostgresTokenRepository implements TokenRepository {
     ) {
         this.refreshTokenService = new RefreshTokenService(db, tableOrTables);
         this.passwordResetTokenService = new PasswordResetTokenService(db, tableOrTables);
+        this.magicLinkTokenService = new MagicLinkTokenService(db, tableOrTables);
     }
 
     // Refresh token operations
@@ -756,6 +821,20 @@ export class PostgresTokenRepository implements TokenRepository {
     async deleteExpiredTokens(): Promise<void> {
         await this.passwordResetTokenService.deleteExpired();
     }
+
+    // Magic link token operations
+
+    async createMagicLinkToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void> {
+        await this.magicLinkTokenService.createToken(userId, tokenHash, expiresAt);
+    }
+
+    async findValidMagicLinkToken(tokenHash: string): Promise<MagicLinkTokenInfo | null> {
+        return this.magicLinkTokenService.findValidByHash(tokenHash);
+    }
+
+    async markMagicLinkTokenUsed(tokenHash: string): Promise<void> {
+        await this.magicLinkTokenService.markAsUsed(tokenHash);
+    }
 }
 
 /**
@@ -955,6 +1034,20 @@ collectionPermissions: null }
         await this.tokenRepository.deleteExpiredTokens();
     }
 
+    // Magic link token operations
+
+    async createMagicLinkToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void> {
+        await this.tokenRepository.createMagicLinkToken(userId, tokenHash, expiresAt);
+    }
+
+    async findValidMagicLinkToken(tokenHash: string): Promise<MagicLinkTokenInfo | null> {
+        return this.tokenRepository.findValidMagicLinkToken(tokenHash);
+    }
+
+    async markMagicLinkTokenUsed(tokenHash: string): Promise<void> {
+        await this.tokenRepository.markMagicLinkTokenUsed(tokenHash);
+    }
+
     // MFA operations (delegate to MfaService)
 
     private _mfaService: MfaService | null = null;

package/src/cli-errors.ts

@@ -0,0 +1,162 @@
+import chalk from "chalk";
+import { logger } from "@rebasepro/server-core";
+
+/**
+ * Detect whether an error (or AggregateError wrapping multiple attempts)
+ * represents an ECONNREFUSED — i.e. the database is simply not running.
+ *
+ * Handles:
+ * - Direct `{ code: "ECONNREFUSED" }` errors from Node `net`
+ * - `AggregateError` from dual-stack IPv4+IPv6 connection attempts
+ * - Drizzle's `cause`-wrapped pg errors
+ */
+export function isEconnrefused(err: unknown): boolean {
+    if (!err || typeof err !== "object") return false;
+    const e = err as { code?: string; cause?: unknown; errors?: unknown[] };
+    if (e.code === "ECONNREFUSED") return true;
+    // AggregateError from Node net (dual-stack IPv4 + IPv6)
+    if (Array.isArray(e.errors)) {
+        return e.errors.some(inner =>
+            inner && typeof inner === "object" && (inner as { code?: string }).code === "ECONNREFUSED"
+        );
+    }
+    // Drizzle wraps the pg error in `cause`
+    if (e.cause && typeof e.cause === "object") {
+        return isEconnrefused(e.cause);
+    }
+    return false;
+}
+
+/**
+ * Detect PostgreSQL authentication failures.
+ * PG error codes: 28P01 (invalid_password), 28000 (invalid_authorization_specification)
+ */
+export function isAuthFailure(err: unknown): boolean {
+    if (!err || typeof err !== "object") return false;
+    const e = err as { code?: string; cause?: unknown };
+    if (e.code === "28P01" || e.code === "28000") return true;
+    if (e.cause && typeof e.cause === "object") {
+        return isAuthFailure(e.cause);
+    }
+    // Also check the message for common pg auth failure text
+    if ("message" in e && typeof (e as { message?: string }).message === "string") {
+        const msg = (e as { message: string }).message.toLowerCase();
+        if (msg.includes("password authentication failed") || msg.includes("no pg_hba.conf entry")) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Parse host:port from a DATABASE_URL for display purposes.
+ */
+function parseHostInfo(databaseUrl: string): string {
+    try {
+        const parsed = new URL(databaseUrl);
+        return `${parsed.hostname}:${parsed.port || 5432}`;
+    } catch {
+        return "unknown";
+    }
+}
+
+/**
+ * Format a diagnostic banner for ECONNREFUSED errors.
+ */
+function formatConnectionRefusedBanner(databaseUrl: string): string {
+    const hostInfo = parseHostInfo(databaseUrl);
+    return (
+        `\n` +
+        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+        `  ❌  Cannot connect to PostgreSQL at ${hostInfo}\n` +
+        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+        `\n` +
+        `  The database server is not running or is not accepting\n` +
+        `  connections. Common fixes:\n` +
+        `\n` +
+        `    • brew services start postgresql@18\n` +
+        `    • docker compose up -d postgres\n` +
+        `    • Verify DATABASE_URL in your .env file\n` +
+        `\n` +
+        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`
+    );
+}
+
+/**
+ * Format a diagnostic banner for authentication failures.
+ */
+function formatAuthFailureBanner(databaseUrl: string): string {
+    const hostInfo = parseHostInfo(databaseUrl);
+    let username = "unknown";
+    try {
+        username = new URL(databaseUrl).username || "unknown";
+    } catch { /* ignore */ }
+
+    return (
+        `\n` +
+        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+        `  ❌  Authentication failed for user "${username}" at ${hostInfo}\n` +
+        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+        `\n` +
+        `  PostgreSQL rejected the credentials. Common fixes:\n` +
+        `\n` +
+        `    • Check the username and password in DATABASE_URL\n` +
+        `    • Verify the user exists:  psql -c "\\du"\n` +
+        `    • Reset the password:  ALTER USER ${username} PASSWORD 'new_password';\n` +
+        `\n` +
+        `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`
+    );
+}
+
+/**
+ * Pre-flight check: verify that the database is reachable before running
+ * a heavy subprocess (Atlas, migrations, etc.).
+ *
+ * Exits with code 1 and a friendly banner on known failure modes.
+ * On unknown errors, logs a warning and allows the caller to proceed.
+ */
+export async function checkDatabaseConnectivity(databaseUrl: string): Promise<void> {
+    let client: import("pg").Client | undefined;
+    try {
+        const { Client } = await import("pg");
+        client = new Client({
+            connectionString: databaseUrl,
+            connectionTimeoutMillis: 5000
+        });
+        await client.connect();
+        await client.query("SELECT 1");
+    } catch (err: unknown) {
+        if (isEconnrefused(err)) {
+            logger.error(formatConnectionRefusedBanner(databaseUrl));
+            process.exit(1);
+        }
+        if (isAuthFailure(err)) {
+            logger.error(formatAuthFailureBanner(databaseUrl));
+            process.exit(1);
+        }
+        // Unknown error — warn but don't block; let the downstream tool surface details
+        logger.warn(chalk.yellow(`  ⚠  Could not verify database connectivity: ${err instanceof Error ? err.message : String(err)}`));
+        logger.warn(chalk.gray("    Proceeding anyway — the command may fail if the database is unreachable."));
+    } finally {
+        try {
+            await client?.end();
+        } catch {
+            // ignore cleanup errors
+        }
+    }
+}
+
+/**
+ * Post-hoc error diagnosis for direct database operations (e.g. applyPolicies).
+ * Returns a formatted diagnostic string if the error matches a known pattern,
+ * or null if unrecognized.
+ */
+export function diagnoseDbError(err: unknown, databaseUrl?: string): string | null {
+    if (isEconnrefused(err)) {
+        return formatConnectionRefusedBanner(databaseUrl || "");
+    }
+    if (isAuthFailure(err)) {
+        return formatAuthFailureBanner(databaseUrl || "");
+    }
+    return null;
+}