@rebasepro/server-postgresql 0.0.1-canary.09e5ec5

package/src/databasePoolManager.ts

@@ -0,0 +1,85 @@
+import { Pool } from "pg";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+
+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<any> {
+        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) => {
+            console.error(`[DatabasePoolManager] Unexpected error on idle client for db ${databaseName}`, 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()) {
+            console.log(`[DatabasePoolManager] Shutting down pool for ${dbName}`);
+            promises.push(pool.end());
+        }
+        await Promise.all(promises);
+        this.pools.clear();
+    }
+}

package/src/history/HistoryService.ts

@@ -0,0 +1,248 @@
+import { sql } from "drizzle-orm";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+
+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;
+    entityId: 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 entity. 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 entity change history.
+ * Stores snapshots 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 entity 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 entity.
+     */
+    async recordHistory(params: RecordHistoryParams): Promise<void> {
+        const {
+            tableName,
+            entityId,
+            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(entityId)},
+                    ${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 entity
+            this.pruneEntity(tableName, entityId).catch(err =>
+                console.error("History prune failed:", err)
+            );
+        } catch (error) {
+            console.error("Failed to record entity history:", error);
+        }
+    }
+
+    /**
+     * Fetch history entries for an entity, ordered by most recent first.
+     */
+    async fetchHistory(
+        tableName: string,
+        entityId: 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(entityId)}
+            `),
+            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(entityId)}
+                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 entity: enforce maxEntries and TTL.
+     */
+    async pruneEntity(tableName: string, entityId: 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(entityId)}
+              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(entityId)}
+                ORDER BY updated_at DESC
+                OFFSET ${this.retention.maxEntries}
+            )
+        `);
+        deleted += maxResult.rowCount ?? 0;
+
+        return deleted;
+    }
+
+    /**
+     * Global prune: enforce TTL across ALL entities 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;
+    }
+}
+
+
+/**
+ * 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 JSON comparison
+            if (
+                typeof oldVal === "object" && oldVal !== null &&
+                typeof newVal === "object" && newVal !== null
+            ) {
+                if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+                    changed.push(key);
+                }
+            } else {
+                changed.push(key);
+            }
+        }
+    }
+
+    return changed.length > 0 ? changed : null;
+}

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

@@ -0,0 +1,45 @@
+import { sql } from "drizzle-orm";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+
+/**
+ * Auto-create the entity 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> {
+    console.log("🔍 Checking entity 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)
+        `);
+
+        console.log("✅ Entity history table ready");
+    } catch (error) {
+        console.error("❌ Failed to create entity history table:", error);
+        console.warn("⚠️ Continuing without creating history table.");
+    }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+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 "./PostgresBootstrapper";

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,
+    EntityCollection,
+    FilterValues,
+    WhereFilterOp,
+    DatabaseConnection,
+    QueryFilter,
+    FetchCollectionOptions,
+    SearchOptions,
+    CountOptions,
+    ConditionBuilder,
+    ConditionBuilderStatic,
+    EntityRepository,
+    CollectionSubscriptionConfig,
+    EntitySubscriptionConfig,
+    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,
+    EntityRepository,
+    CollectionSubscriptionConfig,
+    EntitySubscriptionConfig,
+    RealtimeProvider,
+    CollectionRegistryInterface,
+    DataTransformer,
+    BackendConfig,
+    BackendInstance,
+    BackendFactory
+};

package/src/schema/auth-schema.ts

@@ -0,0 +1,169 @@
+import { pgSchema, varchar, uuid, timestamp, boolean, jsonb, primaryKey, unique } from "drizzle-orm/pg-core";
+import { relations } from "drizzle-orm";
+
+/**
+ * Dedicated PostgreSQL schema for all Rebase internal tables.
+ * Keeps the user's `public` schema clean.
+ */
+export const rebaseSchema = pgSchema("rebase");
+
+/**
+ * Users table - stores both email/password and OAuth users
+ */
+export const users = rebaseSchema.table("users", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    email: varchar("email", { length: 255 }).notNull().unique(),
+    passwordHash: varchar("password_hash", { length: 255 }), // NULL for OAuth-only users
+    displayName: varchar("display_name", { length: 255 }),
+    photoUrl: varchar("photo_url", { length: 500 }),
+    emailVerified: boolean("email_verified").default(false).notNull(),
+    emailVerificationToken: varchar("email_verification_token", { length: 255 }),
+    emailVerificationSentAt: timestamp("email_verification_sent_at"),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at").defaultNow().notNull()
+});
+
+/**
+ * Roles table - defines permission sets
+ */
+export const roles = rebaseSchema.table("roles", {
+    id: varchar("id", { length: 50 }).primaryKey(), // 'admin', 'editor', 'viewer'
+    name: varchar("name", { length: 100 }).notNull(),
+    isAdmin: boolean("is_admin").default(false).notNull(),
+    defaultPermissions: jsonb("default_permissions").$type<{
+        read?: boolean;
+        create?: boolean;
+        edit?: boolean;
+        delete?: boolean;
+    }>(),
+    collectionPermissions: jsonb("collection_permissions").$type<
+        Record<string, {
+            read?: boolean;
+            create?: boolean;
+            edit?: boolean;
+            delete?: boolean;
+        }>
+    >(),
+    config: jsonb("config").$type<{
+        createCollections?: boolean;
+        editCollections?: "own" | "all" | boolean;
+        deleteCollections?: "own" | "all" | boolean;
+    }>()
+});
+
+/**
+ * User-Role junction table
+ */
+export const userRoles = rebaseSchema.table("user_roles", {
+    userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+    roleId: varchar("role_id", { length: 50 }).notNull().references(() => roles.id, { onDelete: "cascade" })
+}, (table) => ({
+    pk: primaryKey({ columns: [table.userId, table.roleId] })
+}));
+
+/**
+ * Refresh tokens for long-lived sessions
+ */
+export const refreshTokens = rebaseSchema.table("refresh_tokens", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+    tokenHash: varchar("token_hash", { length: 255 }).notNull().unique(),
+    expiresAt: timestamp("expires_at").notNull(),
+    userAgent: varchar("user_agent", { length: 500 }),
+    ipAddress: varchar("ip_address", { length: 45 }),
+    createdAt: timestamp("created_at").defaultNow().notNull()
+}, (table) => ({
+    uniqueDeviceSession: unique("unique_device_session").on(table.userId, table.userAgent, table.ipAddress)
+}));
+
+/**
+ * Password reset tokens for forgot password flow
+ */
+export const passwordResetTokens = rebaseSchema.table("password_reset_tokens", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+    tokenHash: varchar("token_hash", { length: 255 }).notNull().unique(),
+    expiresAt: timestamp("expires_at").notNull(),
+    usedAt: timestamp("used_at"),
+    createdAt: timestamp("created_at").defaultNow().notNull()
+});
+
+/**
+ * App config - key/value store for custom settings
+ */
+export const appConfig = rebaseSchema.table("app_config", {
+    key: varchar("key", { length: 100 }).primaryKey(),
+    value: jsonb("value").notNull(),
+    updatedAt: timestamp("updated_at").defaultNow().notNull()
+});
+
+/**
+ * User identities - maps external OAuth profiles back to local users
+ */
+export const userIdentities = rebaseSchema.table("user_identities", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    userId: uuid("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+    provider: varchar("provider", { length: 50 }).notNull(), // e.g. 'google', 'linkedin'
+    providerId: varchar("provider_id", { length: 255 }).notNull(),
+    profileData: jsonb("profile_data"),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at").defaultNow().notNull()
+}, (table) => ({
+    uniqueProviderId: unique("unique_provider_id").on(table.provider, table.providerId)
+}));
+
+// Relations
+export const usersRelations = relations(users, ({ many }) => ({
+    userRoles: many(userRoles),
+    refreshTokens: many(refreshTokens),
+    passwordResetTokens: many(passwordResetTokens),
+    userIdentities: many(userIdentities)
+}));
+
+export const rolesRelations = relations(roles, ({ many }) => ({
+    userRoles: many(userRoles)
+}));
+
+export const userRolesRelations = relations(userRoles, ({ one }) => ({
+    user: one(users, {
+        fields: [userRoles.userId],
+        references: [users.id]
+    }),
+    role: one(roles, {
+        fields: [userRoles.roleId],
+        references: [roles.id]
+    })
+}));
+
+export const refreshTokensRelations = relations(refreshTokens, ({ one }) => ({
+    user: one(users, {
+        fields: [refreshTokens.userId],
+        references: [users.id]
+    })
+}));
+
+export const passwordResetTokensRelations = relations(passwordResetTokens, ({ one }) => ({
+    user: one(users, {
+        fields: [passwordResetTokens.userId],
+        references: [users.id]
+    })
+}));
+
+export const userIdentitiesRelations = relations(userIdentities, ({ one }) => ({
+    user: one(users, {
+        fields: [userIdentities.userId],
+        references: [users.id]
+    })
+}));
+
+// Type exports
+export type User = typeof users.$inferSelect;
+export type NewUser = typeof users.$inferInsert;
+export type Role = typeof roles.$inferSelect;
+export type NewRole = typeof roles.$inferInsert;
+export type UserRole = typeof userRoles.$inferSelect;
+export type RefreshToken = typeof refreshTokens.$inferSelect;
+export type PasswordResetToken = typeof passwordResetTokens.$inferSelect;
+export type AppConfig = typeof appConfig.$inferSelect;
+export type UserIdentity = typeof userIdentities.$inferSelect;
+export type NewUserIdentity = typeof userIdentities.$inferInsert;

package/src/schema/doctor-cli.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for `rebase doctor`.
+ * Invoked via tsx by the server-postgresql CLI plugin.
+ */
+import path from "path";
+import chalk from "chalk";
+import { runDoctor } from "./doctor";
+
+async function main() {
+    const collectionsArg = process.argv.find((a) => a.startsWith("--collections="));
+    const schemaArg = process.argv.find((a) => a.startsWith("--schema="));
+
+    const collectionsPath = collectionsArg?.split("=")[1] ?? path.join("..", "shared", "collections");
+    const schemaPath = schemaArg?.split("=")[1] ?? path.join("src", "schema.generated.ts");
+
+    // Load .env
+    try {
+        const dotenv = await import("dotenv");
+        const envPath = process.env.DOTENV_CONFIG_PATH;
+        if (envPath) {
+            dotenv.config({ path: envPath });
+        } else {
+            dotenv.config();
+        }
+    } catch {
+        // dotenv may not be installed
+    }
+
+    const databaseUrl = process.env.DATABASE_URL || process.env.ADMIN_CONNECTION_STRING;
+
+    const report = await runDoctor({
+        collectionsPath: path.resolve(process.cwd(), collectionsPath),
+        schemaPath: path.resolve(process.cwd(), schemaPath),
+        databaseUrl: databaseUrl ?? undefined
+    });
+
+    // Exit with non-zero code if there are errors
+    if (report.summary.errors > 0) {
+        process.exit(1);
+    }
+}
+
+main().catch((err) => {
+    console.error(chalk.red("  ✗ Doctor failed:"), err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});