@rebasepro/server-postgres 0.0.1-canary.4829d6e

package/src/databasePoolManager.ts

@@ -0,0 +1,87 @@
+import { Pool } from "pg";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { logger } from "@rebasepro/server";
+
+export class DatabasePoolManager {
+    private pools: Map<string, Pool> = new Map();
+    private drizzleInstances: Map<string, NodePgDatabase> = new Map();
+    public readonly defaultDatabaseName: string;
+    private readonly rootConnectionString: string;
+
+    constructor(adminConnectionString: string) {
+        this.rootConnectionString = adminConnectionString;
+        try {
+            const url = new URL(adminConnectionString);
+            this.defaultDatabaseName = url.pathname.slice(1);
+        } catch (e) {
+            throw new Error(`Invalid adminConnectionString provided: ${e}`);
+        }
+    }
+
+    public getDrizzle(databaseName: string): NodePgDatabase<Record<string, never>> {
+        const existing = this.drizzleInstances.get(databaseName);
+        if (existing) {
+            return existing;
+        }
+
+        const pool = this.getPool(databaseName);
+        const db = drizzle(pool);
+        this.drizzleInstances.set(databaseName, db);
+        return db;
+    }
+
+    public getPool(databaseName: string): Pool {
+        if (this.pools.has(databaseName)) {
+            return this.pools.get(databaseName)!;
+        }
+
+        const url = new URL(this.rootConnectionString);
+        url.pathname = `/${databaseName}`;
+
+        const pool = new Pool({
+            connectionString: url.toString(),
+            max: 10, // Default sensible limit, can be tuned later
+            idleTimeoutMillis: 10000, // Reduced from 30000 for aggressive cleanup
+            allowExitOnIdle: true // Prevent idle clients from hanging the Node.js process
+        });
+
+        // Prevent idle client errors from crashing the Node.js process
+        pool.on("error", (err) => {
+            logger.error(`[DatabasePoolManager] Unexpected error on idle client for db ${databaseName}`, { error: err });
+        });
+
+        this.pools.set(databaseName, pool);
+        return pool;
+    }
+
+    /**
+     * Disconnect and remove the pool for a specific database.
+     * Required before `CREATE DATABASE ... TEMPLATE` or `DROP DATABASE`,
+     * which need exclusive access to the target database.
+     */
+    public async disconnectDatabase(databaseName: string): Promise<void> {
+        const pool = this.pools.get(databaseName);
+        if (pool) {
+            await pool.end();
+            this.pools.delete(databaseName);
+            this.drizzleInstances.delete(databaseName);
+        }
+    }
+
+    /** Check if a pool exists for a given database name. */
+    public hasPool(databaseName: string): boolean {
+        return this.pools.has(databaseName);
+    }
+
+    public async shutdown(): Promise<void> {
+        const promises = [];
+        for (const [dbName, pool] of this.pools.entries()) {
+            logger.info(`[DatabasePoolManager] Shutting down pool for ${dbName}`);
+            promises.push(pool.end());
+        }
+        await Promise.all(promises);
+        this.pools.clear();
+        this.drizzleInstances.clear();
+    }
+}

package/src/history/HistoryService.ts

@@ -0,0 +1,272 @@
+import { sql } from "drizzle-orm";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { logger } from "@rebasepro/server";
+
+export interface HistoryEntry {
+    id: string;
+    table_name: string;
+    entity_id: string;
+    action: "create" | "update" | "delete";
+    changed_fields: string[] | null;
+    values: Record<string, unknown> | null;
+    previous_values: Record<string, unknown> | null;
+    updated_by: string | null;
+    updated_at: string;
+}
+
+export interface RecordHistoryParams {
+    tableName: string;
+    id: string;
+    action: "create" | "update" | "delete";
+    values?: Record<string, unknown> | null;
+    previousValues?: Record<string, unknown> | null;
+    updatedBy?: string | null;
+}
+
+export interface FetchHistoryOptions {
+    limit?: number;
+    offset?: number;
+}
+
+export interface HistoryRetentionConfig {
+    /** Max entries per row. Oldest pruned first. Default 200. */
+    maxEntries: number;
+    /** Entries older than this many days are pruned. Default 90. */
+    ttlDays: number;
+}
+
+const DEFAULT_RETENTION: HistoryRetentionConfig = {
+    maxEntries: 200,
+    ttlDays: 90
+};
+
+/**
+ * Service for recording and querying row change history.
+ * Stores history entries in the `rebase.entity_history` table.
+ */
+export class HistoryService {
+    public retention: HistoryRetentionConfig;
+
+    constructor(
+        private db: NodePgDatabase,
+        retention?: Partial<HistoryRetentionConfig>
+    ) {
+        this.retention = { ...DEFAULT_RETENTION,
+...retention };
+    }
+
+    /**
+     * Record a history entry for an row change.
+     * This is intentionally fire-and-forget safe — errors are logged but never
+     * bubble up to block the main save/delete operation.
+     *
+     * After inserting, kicks off a non-blocking pruning pass for this row.
+     */
+    async recordHistory(params: RecordHistoryParams): Promise<void> {
+        const {
+            tableName,
+            id,
+            action,
+            values,
+            previousValues,
+            updatedBy
+        } = params;
+
+        const changedFields = previousValues && values
+            ? findChangedFields(previousValues, values)
+            : null;
+
+
+        // Skip recording if this is an update with zero actual changes
+
+        if (action === "update" && (!changedFields || changedFields.length === 0)) {
+            return;
+        }
+
+        try {
+            await this.db.execute(sql`
+                INSERT INTO rebase.entity_history 
+                    (table_name, entity_id, action, changed_fields, "values", previous_values, updated_by)
+                VALUES (
+                    ${tableName},
+                    ${String(id)},
+                    ${action},
+                    ${changedFields ? sql`ARRAY[${sql.join(changedFields.map(f => sql`${f}`), sql`, `)}]::text[]` : sql`NULL`},
+                    ${values ? sql`${JSON.stringify(values)}::jsonb` : sql`NULL`},
+                    ${previousValues ? sql`${JSON.stringify(previousValues)}::jsonb` : sql`NULL`},
+                    ${updatedBy ?? null}
+                )
+            `);
+
+            // Non-blocking prune for this specific row
+            this.pruneEntity(tableName, id).catch(err =>
+                logger.error("History prune failed", { error: err })
+            );
+        } catch (error) {
+            logger.error("Failed to record row history", { error: error });
+        }
+    }
+
+    /**
+     * Fetch history entries for an row, ordered by most recent first.
+     */
+    async fetchHistory(
+        tableName: string,
+        id: string,
+        options: FetchHistoryOptions = {}
+    ): Promise<{ data: HistoryEntry[]; total: number }> {
+        const limit = options.limit ?? 20;
+        const offset = options.offset ?? 0;
+
+        const [countResult, dataResult] = await Promise.all([
+            this.db.execute(sql`
+                SELECT COUNT(*) as count
+                FROM rebase.entity_history
+                WHERE table_name = ${tableName}
+                  AND entity_id = ${String(id)}
+            `),
+            this.db.execute(sql`
+                SELECT id, table_name, entity_id, action, changed_fields,
+                       "values", previous_values, updated_by, updated_at
+                FROM rebase.entity_history
+                WHERE table_name = ${tableName}
+                  AND entity_id = ${String(id)}
+                ORDER BY updated_at DESC
+                LIMIT ${limit}
+                OFFSET ${offset}
+            `)
+        ]);
+
+        const total = parseInt(
+            (countResult.rows[0] as Record<string, string>)?.count ?? "0",
+            10
+        );
+
+        return {
+            data: dataResult.rows as unknown as HistoryEntry[],
+            total
+        };
+    }
+
+    /**
+     * Fetch a single history entry by ID.
+     */
+    async fetchHistoryEntry(historyId: string): Promise<HistoryEntry | null> {
+        const result = await this.db.execute(sql`
+            SELECT id, table_name, entity_id, action, changed_fields,
+                   "values", previous_values, updated_by, updated_at
+            FROM rebase.entity_history
+            WHERE id = ${historyId}
+        `);
+
+        if (result.rows.length === 0) return null;
+        return result.rows[0] as unknown as HistoryEntry;
+    }
+
+    // ───────── Retention / Pruning ─────────
+
+    /**
+     * Prune history for a single row: enforce maxEntries and TTL.
+     */
+    async pruneEntity(tableName: string, id: string): Promise<number> {
+        let deleted = 0;
+
+        // 1. TTL — delete entries older than ttlDays
+        const ttlResult = await this.db.execute(sql`
+            DELETE FROM rebase.entity_history
+            WHERE table_name = ${tableName}
+              AND entity_id = ${String(id)}
+              AND updated_at < NOW() - MAKE_INTERVAL(days => ${this.retention.ttlDays})
+        `);
+        deleted += ttlResult.rowCount ?? 0;
+
+        // 2. Max entries — keep the newest maxEntries, delete the rest
+        const maxResult = await this.db.execute(sql`
+            DELETE FROM rebase.entity_history
+            WHERE id IN (
+                SELECT id FROM rebase.entity_history
+                WHERE table_name = ${tableName}
+                  AND entity_id = ${String(id)}
+                ORDER BY updated_at DESC
+                OFFSET ${this.retention.maxEntries}
+            )
+        `);
+        deleted += maxResult.rowCount ?? 0;
+
+        return deleted;
+    }
+
+    /**
+     * Global prune: enforce TTL across ALL rows in a single sweep.
+     * Intended to be called periodically (e.g. once per hour or daily).
+     */
+    async pruneExpired(): Promise<number> {
+        const result = await this.db.execute(sql`
+            DELETE FROM rebase.entity_history
+            WHERE updated_at < NOW() - MAKE_INTERVAL(days => ${this.retention.ttlDays})
+        `);
+        return result.rowCount ?? 0;
+    }
+}
+
+
+/**
+ * Deep equality without JSON.stringify.
+ * Handles primitives, arrays, Dates, and plain objects recursively.
+ */
+function deepEqual(a: unknown, b: unknown): boolean {
+    if (a === b) return true;
+    if (a == null || b == null) return false;
+    if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length) return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const aObj = a as Record<string, unknown>;
+        const bObj = b as Record<string, unknown>;
+        const aKeys = Object.keys(aObj);
+        const bKeys = Object.keys(bObj);
+        if (aKeys.length !== bKeys.length) return false;
+        return aKeys.every(k => deepEqual(aObj[k], bObj[k]));
+    }
+    return false;
+}
+
+/**
+ * Shallow comparison to find top-level keys that changed between two objects.
+ */
+export function findChangedFields(
+    oldValues: Record<string, unknown>,
+    newValues: Record<string, unknown>
+): string[] | null {
+    const changed: string[] = [];
+    const allKeys = new Set([
+        ...Object.keys(oldValues),
+        ...Object.keys(newValues)
+    ]);
+
+    for (const key of allKeys) {
+        const oldVal = oldValues[key];
+        const newVal = newValues[key];
+
+        // Skip internal metadata
+        if (key.startsWith("__")) continue;
+
+        if (oldVal !== newVal) {
+            // For objects/arrays, use structural comparison
+            if (
+                typeof oldVal === "object" && oldVal !== null &&
+                typeof newVal === "object" && newVal !== null
+            ) {
+                if (!deepEqual(oldVal, newVal)) {
+                    changed.push(key);
+                }
+            } else {
+                changed.push(key);
+            }
+        }
+    }
+
+    return changed.length > 0 ? changed : null;
+}

package/src/history/ensure-history-table.ts

@@ -0,0 +1,46 @@
+import { sql } from "drizzle-orm";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { logger } from "@rebasepro/server";
+
+/**
+ * Auto-create the row history table if it doesn't exist.
+ * This runs on startup when history is enabled, following the same
+ * pattern as `ensureAuthTablesExist`.
+ */
+export async function ensureHistoryTableExists(db: NodePgDatabase): Promise<void> {
+    logger.info("🔍 Checking row history table...");
+
+    try {
+        // Create the rebase schema (idempotent — may already exist from auth init)
+        await db.execute(sql`CREATE SCHEMA IF NOT EXISTS rebase`);
+
+        await db.execute(sql`
+            CREATE TABLE IF NOT EXISTS rebase.entity_history (
+                id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+                table_name TEXT NOT NULL,
+                entity_id TEXT NOT NULL,
+                action TEXT NOT NULL,
+                changed_fields TEXT[],
+                "values" JSONB,
+                previous_values JSONB,
+                updated_by TEXT,
+                updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+        `);
+
+        await db.execute(sql`
+            CREATE INDEX IF NOT EXISTS idx_history_entity
+            ON rebase.entity_history(table_name, entity_id)
+        `);
+
+        await db.execute(sql`
+            CREATE INDEX IF NOT EXISTS idx_history_time
+            ON rebase.entity_history(table_name, entity_id, updated_at DESC)
+        `);
+
+        logger.info("✅ Entity history table ready");
+    } catch (error) {
+        logger.error("❌ Failed to create row history table", { error: error });
+        logger.warn("⚠️ Continuing without creating history table.");
+    }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from "./connection";
+export * from "./interfaces";
+export * from "./PostgresBackendDriver";
+export * from "./databasePoolManager";
+export * from "./schema/auth-schema";
+export * from "./schema/generate-drizzle-schema-logic";
+export * from "./schema/generate-drizzle-schema";
+export * from "./utils/drizzle-conditions";
+export * from "./services/realtimeService";
+export * from "./websocket";
+export * from "./collections/PostgresCollectionRegistry";
+export * from "./services/BranchService";
+export * from "./backup";
+export * from "./PostgresBootstrapper";
+export * from "./PostgresAdapter";

package/src/interfaces.ts

@@ -0,0 +1,60 @@
+/**
+ * Database Abstraction Interfaces
+ *
+ * These interfaces define the contracts that any database backend must implement
+ * to be used with Rebase. This allows for pluggable database backends like
+ * PostgreSQL, MongoDB, MySQL, etc.
+ */
+
+import {
+    Entity,
+    CollectionConfig,
+    FilterValues,
+    WhereFilterOp,
+    DatabaseConnection,
+    QueryFilter,
+    FetchCollectionOptions,
+    SearchOptions,
+    CountOptions,
+    ConditionBuilder,
+    ConditionBuilderStatic,
+    DataRepository,
+    CollectionSubscriptionConfig,
+    SingleSubscriptionConfig,
+    RealtimeProvider,
+    CollectionRegistryInterface,
+    DataTransformer,
+    BackendConfig,
+    BackendInstance,
+    BackendFactory
+} from "@rebasepro/types";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { PgTransaction } from "drizzle-orm/pg-core";
+
+/**
+ * Type representing either a direct database connection or a transaction.
+ * Used to allow services to operate within a transaction context.
+ * Note: `any` is intentional here — it represents a Drizzle client with
+ * a dynamic schema, enabling `db.query[tableName]` access without casts.
+ */
+
+export type DrizzleClient = NodePgDatabase<any> | PgTransaction<any, any, any>;
+
+export type {
+    DatabaseConnection,
+    QueryFilter,
+    FetchCollectionOptions,
+    SearchOptions,
+    CountOptions,
+    ConditionBuilder,
+    ConditionBuilderStatic,
+    DataRepository,
+    CollectionSubscriptionConfig,
+    SingleSubscriptionConfig,
+    RealtimeProvider,
+    CollectionRegistryInterface,
+    DataTransformer,
+    BackendConfig,
+    BackendInstance,
+    BackendFactory
+};

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

@@ -0,0 +1,41 @@
+/**
+ * Canonical SQL bootstrap for the `auth` schema and its RLS helper functions.
+ *
+ * Generated RLS policies reference `auth.uid()` / `auth.roles()` /
+ * `auth.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 auth.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.
+ *
+ * Deliberately does NOT create the `rebase` schema: that is runtime plumbing
+ * (Atlas revision table, auth tables) created directly against the target
+ * database. Creating it here would leak it into Atlas's replayed migration
+ * state — absent from the desired `schema.sql`, Atlas would then plan
+ * `DROP SCHEMA "rebase" CASCADE` on the next diff. The `auth` schema is safe
+ * because the generated schema.sql declares it.
+ */
+export const AUTH_BOOTSTRAP_SQL = `-- Auth schema + RLS helper functions (required by the policies below)
+CREATE SCHEMA IF NOT EXISTS auth;
+
+CREATE OR REPLACE FUNCTION auth.uid() RETURNS text AS $$
+    SELECT NULLIF(current_setting('app.user_id', true), '');
+$$ LANGUAGE sql STABLE;
+
+CREATE OR REPLACE FUNCTION auth.jwt() RETURNS jsonb AS $$
+    SELECT COALESCE(
+        NULLIF(current_setting('app.jwt', true), ''),
+        '{}'
+    )::jsonb;
+$$ LANGUAGE sql STABLE;
+
+CREATE OR REPLACE FUNCTION auth.roles() RETURNS text AS $$
+    SELECT COALESCE(NULLIF(current_setting('app.user_roles', true), ''), '');
+$$ LANGUAGE sql STABLE;
+`;

package/src/schema/auth-default-policies.ts

@@ -0,0 +1,125 @@
+import { CollectionConfig, SecurityRule, SecurityOperation, AuthCollectionConfig, PolicyExpression, isPostgresCollectionConfig, policy } from "@rebasepro/types";
+import { getTableName } from "@rebasepro/common";
+
+/**
+ * Default RLS policies injected by the schema generator.
+ *
+ * Rebase's enforcement model is unified: authenticated (user-context) requests
+ * run under the restricted `rebase_user` role, so Postgres RLS binds *every*
+ * statement — reads and writes. A collection's `securityRules` are the whole
+ * authorization model. The server context (auth flows, migrations,
+ * `dataAsAdmin`) runs as the owner and bypasses RLS.
+ *
+ * Because RLS default-denies, every collection is **locked by default**: with
+ * no rules, only the server context and admins can touch it. The generator
+ * injects that safe baseline:
+ *
+ * **For every collection**
+ *  1. A permissive **server-or-admin SELECT** grant.
+ *  2. A permissive **server-or-admin write** grant (insert/update/delete).
+ *
+ * Author `securityRules` are permissive and OR together, so explicit rules only
+ * *broaden* access from this locked baseline (e.g. "users read/write their own
+ * rows").
+ *
+ * **For auth collections additionally**
+ *  3. A permissive **self SELECT** grant (`id = auth.uid()`), so users can read
+ *     their own row (profile, session bootstrap) without every app re-declaring
+ *     it.
+ *  4. A **restrictive** admin write gate. Restrictive policies are AND'd with
+ *     every other policy, so a write is rejected unless the caller is an admin
+ *     (or the server context) — even if the author also wrote a permissive rule
+ *     such as "a user may edit their own row". Without this, a permissive owner
+ *     rule would let a user change their own `roles`.
+ *
+ * The server context is recognised as `auth.uid() IS NULL` — the built-in flows
+ * that run without a user (signup, migrations) set no user GUC — which also
+ * lets the owner connection satisfy these policies even under FORCE RLS.
+ *
+ * Opt out with `disableDefaultPolicies: true` to take full responsibility for
+ * the collection's RLS.
+ */
+// Expressed structurally (not as raw SQL) so the admin UI can evaluate it
+// exactly — the framework's most security-critical policies must be reflected
+// precisely, not left as un-evaluable raw clauses. Compiles to
+// `auth.uid() IS NULL OR (string_to_array(auth.roles(), ',') && ARRAY['admin'])`.
+const SERVER_OR_ADMIN_EXPR: PolicyExpression = policy.or(
+    policy.not(policy.authenticated()),
+    policy.rolesOverlap(["admin"])
+);
+
+/** Write operations that must be admin-gated by default on auth collections. */
+const DEFAULT_GUARDED_OPS: SecurityOperation[] = ["insert", "update", "delete"];
+
+/** Whether a collection is flagged as an authentication collection. */
+function isAuthCollection(collection: CollectionConfig): boolean {
+    const auth = collection.auth;
+    return auth === true || (typeof auth === "object" && (auth as AuthCollectionConfig)?.enabled === true);
+}
+
+/** The property marked as the row id (falls back to `id`). */
+function getIdPropertyName(collection: CollectionConfig): string {
+    for (const [name, prop] of Object.entries(collection.properties ?? {})) {
+        if (prop && typeof prop === "object" && "isId" in prop && (prop as { isId?: unknown }).isId) {
+            return name;
+        }
+    }
+    return "id";
+}
+
+/**
+ * Returns the security rules that should be applied to a collection: the
+ * author's explicit `securityRules` plus the framework defaults described in
+ * the module doc (baseline server/admin read for all collections; self-read
+ * and the admin write gate for auth collections).
+ *
+ * Collections that opt out via `disableDefaultPolicies` are returned unchanged.
+ */
+export function getEffectiveSecurityRules(collection: CollectionConfig): SecurityRule[] {
+    const explicit = [...((isPostgresCollectionConfig(collection) ? collection.securityRules : undefined) ?? [])];
+
+    if (collection.disableDefaultPolicies) {
+        return explicit;
+    }
+
+    const tableName = getTableName(collection);
+    const injected: SecurityRule[] = [];
+
+    // Baseline read + write: the server context and admins can always operate.
+    // RLS default-denies under the user role, so without these a rule-less
+    // collection would be locked to everyone — including the admin studio.
+    // Author rules are permissive and broaden access from here.
+    injected.push({
+        name: `${tableName}_default_admin_read`,
+        operations: ["select"],
+        condition: SERVER_OR_ADMIN_EXPR
+    });
+    injected.push({
+        name: `${tableName}_default_admin_write`,
+        operations: [...DEFAULT_GUARDED_OPS],
+        condition: SERVER_OR_ADMIN_EXPR,
+        check: SERVER_OR_ADMIN_EXPR
+    });
+
+    if (isAuthCollection(collection)) {
+        // Self-read: a user can always read their own row.
+        injected.push({
+            name: `${tableName}_default_self_read`,
+            operations: ["select"],
+            condition: policy.compare(policy.field(getIdPropertyName(collection)), "eq", policy.authUid())
+        });
+
+        // Restrictive gate: AND'd with all other policies, so no permissive rule
+        // (e.g. an owner "edit your own row" rule) can let a non-admin change
+        // privileged columns like `roles`.
+        injected.push({
+            name: `${tableName}_require_admin_write`,
+            mode: "restrictive",
+            operations: [...DEFAULT_GUARDED_OPS],
+            condition: SERVER_OR_ADMIN_EXPR,
+            check: SERVER_OR_ADMIN_EXPR
+        });
+    }
+
+    return [...explicit, ...injected];
+}