@rebasepro/server-postgresql 0.6.1 → 0.8.0

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`.
@@ -123,6 +133,7 @@ export class PostgresBackendDriver implements DataDriver {
         if (!collection && !path) return {
             collection: undefined,
             callbacks: undefined,
+            globalCallbacks: undefined,
             propertyCallbacks: undefined
         };
         const registryCollection = this.registry?.getCollectionByPath(path);
@@ -134,6 +145,7 @@ export class PostgresBackendDriver implements DataDriver {
             : collection as EntityCollection<M>;
 
         const callbacks = resolvedCollection?.callbacks;
+        const globalCallbacks = this.registry?.getGlobalCallbacks();
         const properties = resolvedCollection?.properties;
         let propertyCallbacks;
         if (properties) {
@@ -142,6 +154,7 @@ export class PostgresBackendDriver implements DataDriver {
         return {
             collection: resolvedCollection,
             callbacks,
+            globalCallbacks,
             propertyCallbacks
         };
     }
@@ -174,13 +187,24 @@ export class PostgresBackendDriver implements DataDriver {
         const {
             collection: resolvedCollection,
             callbacks,
+            globalCallbacks,
             propertyCallbacks
         } = this.resolveCollectionCallbacks(collection, path);
 
-        if (callbacks?.afterRead || propertyCallbacks?.afterRead) {
+        if (globalCallbacks?.afterRead || callbacks?.afterRead || propertyCallbacks?.afterRead) {
             const contextForCallback = this.buildCallContext();
             return Promise.all(entities.map(async (entity) => {
                 let fetched = entity;
+                // 1. Global callbacks first
+                if (globalCallbacks?.afterRead) {
+                    fetched = await globalCallbacks.afterRead({
+                        collection: resolvedCollection as unknown as EntityCollection,
+                        path,
+                        entity: fetched as unknown as Entity<Record<string, unknown>>,
+                        context: contextForCallback
+                    }) as unknown as Entity<M>;
+                }
+                // 2. Collection callbacks second
                 if (callbacks?.afterRead) {
                     fetched = await callbacks.afterRead({
                         collection: resolvedCollection as EntityCollection<M>,
@@ -189,13 +213,14 @@ export class PostgresBackendDriver implements DataDriver {
                         context: contextForCallback
                     }) ?? fetched;
                 }
+                // 3. Property callbacks third
                 if (propertyCallbacks?.afterRead) {
                     fetched = await propertyCallbacks.afterRead({
-                        collection: resolvedCollection as EntityCollection<M>,
+                        collection: resolvedCollection as unknown as EntityCollection,
                         path,
-                        entity: fetched,
+                        entity: fetched as unknown as Entity<Record<string, unknown>>,
                         context: contextForCallback
-                    }) as Entity<M> ?? fetched;
+                    }) as unknown as Entity<M>;
                 }
                 return fetched;
             }));
@@ -283,26 +308,38 @@ export class PostgresBackendDriver implements DataDriver {
         const {
             collection: resolvedCollection,
             callbacks,
+            globalCallbacks,
             propertyCallbacks
         } = this.resolveCollectionCallbacks(collection, path);
 
-        if (entity && (callbacks?.afterRead || propertyCallbacks?.afterRead)) {
+        if (entity && (globalCallbacks?.afterRead || callbacks?.afterRead || propertyCallbacks?.afterRead)) {
             const contextForCallback = this.buildCallContext();
+            // 1. Global callbacks first
+            if (globalCallbacks?.afterRead) {
+                entity = await globalCallbacks.afterRead({
+                    collection: resolvedCollection as unknown as EntityCollection,
+                    path,
+                    entity: entity as unknown as Entity<Record<string, unknown>>,
+                    context: contextForCallback
+                }) as unknown as Entity<M>;
+            }
+            // 2. Collection callbacks second
             if (callbacks?.afterRead) {
                 entity = await callbacks.afterRead({
                     collection: resolvedCollection as EntityCollection<M>,
                     path,
-                    entity,
+                    entity: entity!,
                     context: contextForCallback
-                }) ?? entity;
+                });
             }
+            // 3. Property callbacks third
             if (propertyCallbacks?.afterRead) {
                 entity = await propertyCallbacks.afterRead({
-                    collection: resolvedCollection as EntityCollection<M>,
+                    collection: resolvedCollection as unknown as EntityCollection,
                     path,
-                    entity,
+                    entity: entity as unknown as Entity<Record<string, unknown>>,
                     context: contextForCallback
-                }) as Entity<M> ?? entity;
+                }) as unknown as Entity<M>;
             }
         }
 
@@ -365,6 +402,7 @@ export class PostgresBackendDriver implements DataDriver {
         const {
             collection: resolvedCollection,
             callbacks,
+            globalCallbacks,
             propertyCallbacks
         } = this.resolveCollectionCallbacks(collection, path);
 
@@ -380,7 +418,22 @@ export class PostgresBackendDriver implements DataDriver {
             }
         }
 
-        if (callbacks?.beforeSave || propertyCallbacks?.beforeSave) {
+        if (globalCallbacks?.beforeSave || callbacks?.beforeSave || propertyCallbacks?.beforeSave) {
+            // 1. Global callbacks first
+            if (globalCallbacks?.beforeSave) {
+                const result = await globalCallbacks.beforeSave({
+                    collection: resolvedCollection as unknown as EntityCollection,
+                    path,
+                    entityId,
+                    values: updatedValues,
+                    previousValues: previousValuesForHistory,
+                    status,
+                    context: contextForCallback
+                });
+                if (result) updatedValues = mergeDeep(updatedValues, result);
+            }
+
+            // 2. Collection callbacks second
             if (callbacks?.beforeSave) {
                 const result = await callbacks.beforeSave({
                     collection: resolvedCollection as EntityCollection<M>,
@@ -394,9 +447,10 @@ export class PostgresBackendDriver implements DataDriver {
                 if (result) updatedValues = mergeDeep(updatedValues, result);
             }
 
+            // 3. Property callbacks third
             if (propertyCallbacks?.beforeSave) {
                 const result = await propertyCallbacks.beforeSave({
-                    collection: resolvedCollection as EntityCollection<M>,
+                    collection: resolvedCollection as unknown as EntityCollection,
                     path,
                     entityId,
                     values: updatedValues,
@@ -428,7 +482,17 @@ export class PostgresBackendDriver implements DataDriver {
                 resolvedCollection?.databaseId
             );
 
-            if (savedEntity && (callbacks?.afterRead || propertyCallbacks?.afterRead)) {
+            if (savedEntity && (globalCallbacks?.afterRead || callbacks?.afterRead || propertyCallbacks?.afterRead)) {
+                // 1. Global callbacks first
+                if (globalCallbacks?.afterRead) {
+                    savedEntity = await globalCallbacks.afterRead({
+                        collection: resolvedCollection as unknown as EntityCollection,
+                        path,
+                        entity: savedEntity as unknown as Entity<Record<string, unknown>>,
+                        context: contextForCallback
+                    }) as unknown as Entity<M>;
+                }
+                // 2. Collection callbacks second
                 if (callbacks?.afterRead) {
                     savedEntity = await callbacks.afterRead({
                         collection: resolvedCollection as EntityCollection<M>,
@@ -437,17 +501,31 @@ export class PostgresBackendDriver implements DataDriver {
                         context: contextForCallback
                     }) ?? savedEntity;
                 }
+                // 3. Property callbacks third
                 if (propertyCallbacks?.afterRead) {
                     savedEntity = await propertyCallbacks.afterRead({
-                        collection: resolvedCollection as EntityCollection<M>,
+                        collection: resolvedCollection as unknown as EntityCollection,
                         path,
-                        entity: savedEntity,
+                        entity: savedEntity as unknown as Entity<Record<string, unknown>>,
                         context: contextForCallback
-                    }) as Entity<M> ?? savedEntity;
+                    }) as unknown as Entity<M>;
                 }
             }
 
-            if (callbacks?.afterSave || propertyCallbacks?.afterSave) {
+            if (globalCallbacks?.afterSave || callbacks?.afterSave || propertyCallbacks?.afterSave) {
+                // 1. Global callbacks first
+                if (globalCallbacks?.afterSave) {
+                    await globalCallbacks.afterSave({
+                        collection: resolvedCollection as unknown as EntityCollection,
+                        path,
+                        entityId: savedEntity.id,
+                        values: savedEntity.values,
+                        previousValues: previousValuesForHistory,
+                        status,
+                        context: contextForCallback
+                    });
+                }
+                // 2. Collection callbacks second
                 if (callbacks?.afterSave) {
                     await callbacks.afterSave({
                         collection: resolvedCollection as EntityCollection<M>,
@@ -459,9 +537,10 @@ export class PostgresBackendDriver implements DataDriver {
                         context: contextForCallback
                     });
                 }
+                // 3. Property callbacks third
                 if (propertyCallbacks?.afterSave) {
                     await propertyCallbacks.afterSave({
-                        collection: resolvedCollection as EntityCollection<M>,
+                        collection: resolvedCollection as unknown as EntityCollection,
                         path,
                         entityId: savedEntity.id,
                         values: savedEntity.values,
@@ -503,7 +582,20 @@ export class PostgresBackendDriver implements DataDriver {
 
             return savedEntity;
         } catch (error) {
-            if (callbacks?.afterSaveError || propertyCallbacks?.afterSaveError) {
+            if (globalCallbacks?.afterSaveError || callbacks?.afterSaveError || propertyCallbacks?.afterSaveError) {
+                // 1. Global callbacks first
+                if (globalCallbacks?.afterSaveError) {
+                    await globalCallbacks.afterSaveError({
+                        collection: resolvedCollection as unknown as EntityCollection,
+                        path,
+                        entityId: entityId || "unknown",
+                        values: updatedValues,
+                        previousValues: undefined,
+                        status,
+                        context: contextForCallback
+                    });
+                }
+                // 2. Collection callbacks second
                 if (callbacks?.afterSaveError) {
                     await callbacks.afterSaveError({
                         collection: resolvedCollection as EntityCollection<M>,
@@ -515,9 +607,10 @@ export class PostgresBackendDriver implements DataDriver {
                         context: contextForCallback
                     });
                 }
+                // 3. Property callbacks third
                 if (propertyCallbacks?.afterSaveError) {
                     await propertyCallbacks.afterSaveError({
-                        collection: resolvedCollection as EntityCollection<M>,
+                        collection: resolvedCollection as unknown as EntityCollection,
                         path,
                         entityId: entityId || "unknown",
                         values: updatedValues,
@@ -540,13 +633,28 @@ export class PostgresBackendDriver implements DataDriver {
         const {
             collection: resolvedCollection,
             callbacks,
+            globalCallbacks,
             propertyCallbacks
         } = this.resolveCollectionCallbacks(collection, entity.path);
 
         const contextForCallback = this.buildCallContext();
 
-        if (callbacks?.beforeDelete || propertyCallbacks?.beforeDelete) {
+        if (globalCallbacks?.beforeDelete || callbacks?.beforeDelete || propertyCallbacks?.beforeDelete) {
             let preventDefault = false;
+            // 1. Global callbacks first
+            if (globalCallbacks?.beforeDelete) {
+                const result = await globalCallbacks.beforeDelete({
+                    collection: resolvedCollection as unknown as EntityCollection,
+                    path: entity.path,
+                    entityId: entity.id,
+                    entity,
+                    context: contextForCallback
+                });
+                if (result === false) {
+                    preventDefault = true;
+                }
+            }
+            // 2. Collection callbacks second
             if (callbacks?.beforeDelete) {
                 const result = await callbacks.beforeDelete({
                     collection: resolvedCollection as EntityCollection<M>,
@@ -559,9 +667,10 @@ export class PostgresBackendDriver implements DataDriver {
                     preventDefault = true;
                 }
             }
+            // 3. Property callbacks third
             if (propertyCallbacks?.beforeDelete) {
                 const result = await propertyCallbacks.beforeDelete({
-                    collection: resolvedCollection as EntityCollection<M>,
+                    collection: resolvedCollection as unknown as EntityCollection,
                     path: entity.path,
                     entityId: entity.id,
                     entity,
@@ -582,7 +691,18 @@ export class PostgresBackendDriver implements DataDriver {
             entity.databaseId || resolvedCollection?.databaseId
         );
 
-        if (callbacks?.afterDelete || propertyCallbacks?.afterDelete) {
+        if (globalCallbacks?.afterDelete || callbacks?.afterDelete || propertyCallbacks?.afterDelete) {
+            // 1. Global callbacks first
+            if (globalCallbacks?.afterDelete) {
+                await globalCallbacks.afterDelete({
+                    collection: resolvedCollection as unknown as EntityCollection,
+                    path: entity.path,
+                    entityId: entity.id,
+                    entity,
+                    context: contextForCallback
+                });
+            }
+            // 2. Collection callbacks second
             if (callbacks?.afterDelete) {
                 await callbacks.afterDelete({
                     collection: resolvedCollection as EntityCollection<M>,
@@ -592,9 +712,10 @@ export class PostgresBackendDriver implements DataDriver {
                     context: contextForCallback
                 });
             }
+            // 3. Property callbacks third
             if (propertyCallbacks?.afterDelete) {
                 await propertyCallbacks.afterDelete({
-                    collection: resolvedCollection as EntityCollection<M>,
+                    collection: resolvedCollection as unknown as EntityCollection,
                     path: entity.path,
                     entityId: entity.id,
                     entity,
@@ -684,10 +805,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 +820,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 +833,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 +945,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)} (