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

package/dist/schema/doctor-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/schema/doctor.d.ts

@@ -0,0 +1,58 @@
+import { CollectionConfig, Property } from "@rebasepro/types";
+export type IssueSeverity = "error" | "warning" | "info";
+export interface DoctorIssue {
+    severity: IssueSeverity;
+    category: "missing_table" | "missing_column" | "type_mismatch" | "missing_constraint" | "schema_stale" | "missing_enum" | "enum_value_mismatch" | "missing_foreign_key" | "sdk_stale";
+    table?: string;
+    column?: string;
+    expected?: string;
+    actual?: string;
+    message: string;
+    fix: string;
+}
+export interface DoctorReport {
+    collectionsToSchema: {
+        passed: boolean;
+        issues: DoctorIssue[];
+    };
+    collectionsToSdk: {
+        passed: boolean;
+        issues: DoctorIssue[];
+    };
+    schemaToDatabase: {
+        passed: boolean;
+        issues: DoctorIssue[];
+    };
+    summary: {
+        passed: number;
+        warnings: number;
+        errors: number;
+    };
+}
+export declare function getExpectedColumnType(prop: Property): string | null;
+/**
+ * Re-exported so callers keep importing it from here, but the implementation is
+ * now shared with the runtime and the generators — a doctor that disagreed with
+ * the policy generator about which files are collections would compare the
+ * wrong thing.
+ */
+export declare function loadCollections(collectionsPath: string): Promise<CollectionConfig[]>;
+export declare function checkCollectionsVsSchema(collections: CollectionConfig[], schemaFilePath: string): Promise<{
+    passed: boolean;
+    issues: DoctorIssue[];
+}>;
+export declare function checkCollectionsVsSdk(collections: CollectionConfig[], sdkFilePath: string): Promise<{
+    passed: boolean;
+    issues: DoctorIssue[];
+}>;
+export declare function checkCollectionsVsDatabase(collections: CollectionConfig[], databaseUrl: string): Promise<{
+    passed: boolean;
+    issues: DoctorIssue[];
+}>;
+export declare function renderReport(report: DoctorReport): void;
+export declare function runDoctor(options: {
+    collectionsPath: string;
+    schemaPath: string;
+    sdkPath: string;
+    databaseUrl?: string;
+}): Promise<DoctorReport>;

package/dist/schema/dynamic-tables.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Build drizzle tables at runtime from an introspected schema.
+ *
+ * CMS mode gets its drizzle tables from a generated `schema.generated.ts` that
+ * the developer commits. BaaS mode has no such file — it points at a database
+ * and serves it — so the equivalent table objects are constructed here from
+ * `information_schema` metadata.
+ *
+ * These are handed to drizzle as its schema, which keeps the relational query
+ * path (`db.query.*`) working; without them FetchService would fall back to
+ * plain selects and lose relation loading.
+ */
+import { type PgTable } from "drizzle-orm/pg-core";
+import { type Relations } from "drizzle-orm";
+import type { TableMeta } from "./introspect-db-logic";
+/**
+ * Build one drizzle table per introspected table, keyed by table name.
+ */
+export declare function buildDrizzleTablesFromSchema(tablesMap: Map<string, TableMeta>, pgSchemaName?: string): Record<string, PgTable>;
+/**
+ * Build drizzle `relations()` for the foreign keys, so the relational query
+ * path can actually load them.
+ *
+ * FetchService asks drizzle for `with: { <key>: true }`, keyed by the relation
+ * property on the collection. Tables alone don't satisfy that — without these,
+ * `?include=author` silently returns the raw `author_id` and no author.
+ *
+ * The keys here must match `buildRelations` in introspect-runtime.ts, which is
+ * what names the collection's relation properties.
+ */
+export declare function buildDrizzleRelationsFromSchema(tablesMap: Map<string, TableMeta>, tables: Record<string, PgTable>): Record<string, Relations>;

package/dist/schema/generate-drizzle-schema-logic.d.ts

@@ -0,0 +1,2 @@
+import { CollectionConfig } from "@rebasepro/types";
+export declare const generateSchema: (collections: CollectionConfig[], stripPolicies?: boolean) => Promise<string>;

package/dist/schema/generate-drizzle-schema.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/schema/generate-postgres-ddl-logic.d.ts

@@ -0,0 +1,5 @@
+import { CollectionConfig } from "@rebasepro/types";
+export declare const generatePostgresDdl: (collections: CollectionConfig[], options?: {
+    includePolicies?: boolean;
+}) => Promise<string>;
+export declare const generatePostgresPoliciesDdl: (collections: CollectionConfig[]) => string;

package/dist/schema/generate-postgres-ddl.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/schema/introspect-db-inference.d.ts

@@ -0,0 +1,5 @@
+export interface InferenceResult {
+    propType?: string;
+    extra?: string;
+}
+export declare function inferPropertyFromData(columnName: string, pgDataType: string, currentPropType: string, sampleValues: unknown[], isPk: boolean): InferenceResult;

package/dist/schema/introspect-db-logic.d.ts

@@ -0,0 +1,118 @@
+export interface TableRow {
+    table_name: string;
+}
+export interface TableColumn {
+    table_name: string;
+    column_name: string;
+    data_type: string;
+    udt_name: string;
+    is_nullable: string;
+    column_default: string | null;
+    atttypmod: number | null;
+}
+export interface EnumValue {
+    enum_name: string;
+    enum_value: string;
+    sort_order: number;
+}
+export interface PrimaryKeyRow {
+    table_name: string;
+    column_name: string;
+}
+export interface ForeignKeyRow {
+    table_name: string;
+    column_name: string;
+    foreign_table_name: string;
+    foreign_column_name: string;
+}
+export interface TableMeta {
+    name: string;
+    columns: TableColumn[];
+    pks: string[];
+    fks: ForeignKeyRow[];
+}
+export declare function singularize(word: string): string;
+/**
+ * Convert a snake_case name to a human-readable Title Case label.
+ * e.g. "created_at" -> "Created At", "customer_id" -> "Customer Id"
+ */
+export declare function humanize(snakeName: string): string;
+/**
+ * Convert a snake_case table name to a camelCase + "Collection" variable name.
+ * e.g. "company_token" -> "companyTokenCollection"
+ */
+export declare function toCollectionVarName(tableName: string): string;
+export declare function getIconForTable(tableName: string): string;
+/**
+ * Map a PostgreSQL data type to a Rebase property type.
+ */
+export declare function mapPgType(dataType: string): string;
+export declare function buildEnumMap(enumValues: EnumValue[]): Map<string, string[]>;
+export declare function buildTablesMap(tables: TableRow[], columns: TableColumn[], pks: PrimaryKeyRow[], fks: ForeignKeyRow[]): Map<string, TableMeta>;
+export declare function identifyJoinTables(tablesMap: Map<string, TableMeta>): Set<string>;
+/**
+ * Property metadata used to compute display priority.
+ * Keeps computePropertyPriority free of any TableMeta coupling.
+ */
+export interface PropertyOrderingContext {
+    /** The resolved Rebase property type (e.g. "string", "number", "date", "relation"). */
+    propType: string;
+    /** Whether this column is a primary key. */
+    isPk: boolean;
+    /** Whether this column is an enum (USER-DEFINED with matching values). */
+    isEnum: boolean;
+    /** Whether this is a storage/file-upload field (detected from column name). */
+    isStorage: boolean;
+    /** The PostgreSQL data_type (e.g. "text", "character varying", "jsonb"). */
+    pgDataType: string;
+    /** The original column index in PostgreSQL (for stable tiebreaking). */
+    originalIndex: number;
+}
+/**
+ * Compute a numeric priority score for a property.
+ * Lower scores appear first in the generated `propertiesOrder` array.
+ *
+ * The system uses 14 tiers (0–139), with the original column index
+ * added as a fractional tiebreaker (originalIndex / 10000) to
+ * guarantee stable ordering within the same tier.
+ *
+ * Pure function — no side effects.
+ */
+export declare function computePropertyPriority(columnName: string, ctx: PropertyOrderingContext): number;
+/**
+ * Sort a `propertiesOrder` array using the priority heuristic.
+ * Returns a new sorted array; does not mutate the input.
+ *
+ * @param entries - Array of { key, columnName, propType, ... } objects
+ *                  carrying the information needed to compute priority.
+ */
+export interface PropertyOrderEntry {
+    /** The property key in the generated collection (may differ from columnName for relations). */
+    key: string;
+    /** The ordering context for this property. */
+    ctx: PropertyOrderingContext;
+}
+export declare function sortPropertiesOrder(entries: PropertyOrderEntry[]): string[];
+export interface GeneratedFile {
+    tableName: string;
+    fileName: string;
+    content: string;
+}
+/**
+ * Generate the full TypeScript file content for a single collection.
+ * Pure function — no I/O.
+ */
+export declare function generateCollectionFile(tableName: string, meta: TableMeta, allFks: ForeignKeyRow[], joinTables: Set<string>, tablesMap: Map<string, TableMeta>, enumMap: Map<string, string[]>, sampleData?: Record<string, unknown>[]): string;
+/**
+ * Generate the content for an index.ts file that re-exports all collections.
+ */
+export declare function generateIndexContent(fileNames: string[]): string;
+/**
+ * Merge new exports into existing index.ts content.
+ * Returns the merged content string.
+ */
+export declare function mergeIndexContent(existingContent: string, newFileNames: string[]): string;
+/**
+ * Safely extract the host portion of a database URL for logging.
+ */
+export declare function safeHostFromUrl(url: string): string;

package/dist/schema/introspect-db.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/schema/introspect-runtime.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Runtime introspection — builds collections in memory from the live database.
+ *
+ * This is what makes BaaS mode work with zero configuration: instead of loading
+ * collection files from disk, the server reads `information_schema` at boot and
+ * derives a collection per table, so any database is served over REST without a
+ * single config file.
+ *
+ * Distinct from `introspect-db.ts`, which runs the same queries but emits
+ * TypeScript *source* for a developer to edit and commit (CMS mode). The two
+ * share the mapping helpers in `introspect-db-logic.ts` so a table is described
+ * the same way whether it was generated or introspected.
+ */
+import type { PostgresCollectionConfig } from "@rebasepro/types";
+import { TableMeta } from "./introspect-db-logic";
+export interface IntrospectedSchema {
+    tablesMap: Map<string, TableMeta>;
+    enumMap: Map<string, string[]>;
+    joinTables: Set<string>;
+}
+/** Whether a table carries an authorization model of its own. */
+export interface TableRlsStatus {
+    table: string;
+    /** ALTER TABLE … ENABLE ROW LEVEL SECURITY has been run. */
+    rlsEnabled: boolean;
+    /** Policies attached to it. RLS enabled with none = nothing is visible. */
+    policyCount: number;
+}
+/**
+ * Read the RLS posture of each table in a schema.
+ *
+ * This is what decides whether baas mode may serve a table. A table with RLS
+ * disabled has no authorization model: since every authenticated request runs
+ * as `rebase_user`, and that role is granted DML on the schema, serving such a
+ * table hands every row to every logged-in user.
+ */
+export declare function readRlsStatus(client: Queryable, pgSchema: string): Promise<Map<string, TableRlsStatus>>;
+/** Minimal query surface — satisfied by pg.Client and pg.Pool alike. */
+export interface Queryable {
+    query<R>(text: string, values?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+}
+/**
+ * Read tables, columns, enums, primary keys and foreign keys for a schema.
+ * Mirrors the queries in introspect-db.ts.
+ */
+export declare function introspectSchema(client: Queryable, pgSchema: string): Promise<IntrospectedSchema>;
+/**
+ * Turn an introspected schema into collections.
+ *
+ * Join tables are skipped: they carry no identity of their own and exist to
+ * express a many-to-many edge between two other tables.
+ */
+export declare function buildCollectionsFromSchema({ tablesMap, enumMap, joinTables }: IntrospectedSchema, pgSchema: string): PostgresCollectionConfig[];
+/** Introspect the database and return ready-to-serve collections. */
+export declare function introspectCollections(client: Queryable, pgSchema: string): Promise<PostgresCollectionConfig[]>;

package/dist/schema/test-schema.d.ts

@@ -0,0 +1,24 @@
+export declare const testTable: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "test";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "test";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;

package/dist/security/policy-drift.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Compare the RLS policies a database actually has against the ones the
+ * collections describe.
+ *
+ * Policies live in Postgres; the collection config is only their *source*.
+ * Nothing reconciled the two, which is how the demo database served empty
+ * collections indefinitely: its policies granted `TO authenticated` (a Supabase
+ * role name) while requests run as `rebase_user`, so RLS filtered every row.
+ * The config was later corrected and the database never noticed — an empty
+ * table is indistinguishable from a table with no data.
+ *
+ * Expected policies are parsed from `generatePostgresPoliciesDdl`, the same
+ * function `db push` uses to write `drizzle/policies.sql`, so this compares
+ * against exactly what would be applied rather than a reimplementation.
+ */
+import type { CollectionConfig } from "@rebasepro/types";
+export interface PolicyRef {
+    schema: string;
+    table: string;
+    name: string;
+    /** Roles in the TO clause. */
+    roles: string[];
+    /** SELECT / INSERT / UPDATE / DELETE / ALL. */
+    command: string;
+}
+export interface PolicyDrift {
+    /** Described by the collections, absent from the database. */
+    missing: PolicyRef[];
+    /** In the database, described by no collection — stale pushes live here. */
+    orphaned: PolicyRef[];
+    /** Same policy name, different roles or command. */
+    diverged: {
+        expected: PolicyRef;
+        actual: PolicyRef;
+        differences: string[];
+    }[];
+}
+export interface Queryable {
+    query<R>(text: string, values?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+}
+/** Parse the generated DDL rather than rebuilding the shape by hand. */
+export declare function parseExpectedPolicies(ddl: string): PolicyRef[];
+/**
+ * Diff expected against live.
+ *
+ * Compares names, roles and command only — all exact values. Policy
+ * *expressions* are deliberately not compared: Postgres rewrites `qual`/
+ * `with_check` when storing them (parenthesising, casting, schema-qualifying),
+ * so text comparison reports drift that does not exist, and a check that cries
+ * wolf gets ignored. Roles alone catch the failure this exists for.
+ */
+export declare function checkPolicyDrift(client: Queryable, collections: CollectionConfig[]): Promise<PolicyDrift>;
+export declare const hasDrift: (d: PolicyDrift) => boolean;
+/** Human-readable report; empty string when the database matches the config. */
+export declare function formatPolicyDrift(drift: PolicyDrift): string;

package/dist/security/rls-enforcement.d.ts

@@ -0,0 +1,122 @@
+import { SQL } from "drizzle-orm";
+/**
+ * Unified RLS enforcement — the "user context vs server context" model.
+ *
+ * Every operation runs in one of two contexts:
+ *
+ *  - **User context** — a request authenticated (or anonymous) via
+ *    `driver.withAuth(user)`. Runs as the restricted `rebase_user` role: a
+ *    non-owner, NOSUPERUSER, NOBYPASSRLS role, so Postgres RLS binds *every*
+ *    statement (SELECT, INSERT, UPDATE, DELETE). The collection's
+ *    `securityRules` are the whole authorization model; app-layer callbacks
+ *    are validation/side-effects, not a security boundary.
+ *
+ *  - **Server context** — the base (owner) connection: auth flows, migrations,
+ *    background jobs, and the explicit `rebase.dataAsAdmin` accessor. As table
+ *    owner it bypasses RLS. This is the trusted plane, equivalent to
+ *    Supabase's `service_role`.
+ *
+ * This module provides the three pieces:
+ *
+ *  1. {@link detectConnectionPosture} — is the connection subject to RLS at
+ *     all? (superuser / BYPASSRLS / table owner ⇒ no)
+ *  2. {@link ensureAppRole} — idempotently provision `rebase_user` with
+ *     SELECT/INSERT/UPDATE/DELETE grants (+ default privileges so future
+ *     tables stay covered).
+ *  3. {@link applyAuthContext} — per-transaction: set the `app.*` GUCs the
+ *     policies read (`auth.uid()` etc.) and `SET LOCAL ROLE rebase_user` so
+ *     RLS binds. Transaction-scoped, so it composes with poolers.
+ *
+ * Provisioning runs from the framework's own bootstrap/migrate (which already
+ * self-creates the `auth` schema and functions) — enforcement is default-on,
+ * not an operator opt-in.
+ */
+/** The restricted role every authenticated (user-context) request runs as. */
+export declare const REBASE_USER_ROLE = "rebase_user";
+/** Minimal SQL runner so callers can adapt drizzle or pg.Client. */
+export type RawSqlRunner = (sqlText: string) => Promise<Record<string, unknown>[]>;
+/** Minimal transaction surface needed by {@link applyAuthContext}. */
+export interface SqlTx {
+    execute(query: SQL): Promise<unknown>;
+}
+export interface ConnectionPosture {
+    /** The connection's `current_user`. */
+    role: string;
+    superuser: boolean;
+    bypassRLS: boolean;
+    /** Owns at least one user table — owners bypass non-FORCE RLS. */
+    ownsTables: boolean;
+    /** True when RLS would NOT constrain this connection. */
+    privileged: boolean;
+}
+export interface AuthContext {
+    userId: string;
+    /** Raw roles as carried on the user (strings or `{ id }` objects). */
+    roles: unknown[];
+}
+export declare function detectConnectionPosture(run: RawSqlRunner): Promise<ConnectionPosture>;
+/**
+ * Human-actionable instructions for when the connection cannot provision the
+ * user role itself (no CREATEROLE and role not pre-created by the platform).
+ */
+export declare function appRoleSetupInstructions(connectionRole: string, schemas: string[]): string;
+/**
+ * Idempotently provision the `rebase_user` role, membership for the current
+ * connection role, and DML grants (+ default privileges for future tables)
+ * on every existing schema in `schemas`.
+ *
+ * Split into privilege tiers so it works both when the connection is a
+ * superuser (creates everything) and when the platform pre-created the role
+ * and membership (e.g. CNPG `postInitApplicationSQL`) and the connection is
+ * merely the table owner — owners can always run the grant tier themselves.
+ *
+ * RLS still filters every row: these grants only make the tables *reachable*
+ * by the role; the policies decide which rows/commands actually pass.
+ *
+ * Throws with precise setup instructions when the role is missing and the
+ * connection cannot create it.
+ */
+export declare function ensureAppRole(run: RawSqlRunner, schemas: string[]): Promise<void>;
+/**
+ * Apply the authenticated context to a transaction: the `app.*` GUCs that RLS
+ * policies read via `auth.uid()` / `auth.roles()` / `auth.jwt()`, and — when
+ * `userRole` is set — `SET LOCAL ROLE` so RLS binds every statement in this
+ * transaction (reads *and* writes).
+ *
+ * GUCs are set with `is_local = true` and the role switch is `LOCAL`: both
+ * reset at commit/rollback, so pooled connections are never polluted.
+ *
+ * Fails closed by construction: if the role switch errors, the transaction
+ * aborts instead of proceeding privileged.
+ *
+ * SECURITY: this function is only ever called on the **user** path (the server
+ * context uses the base/owner driver and never calls it). The default policies
+ * treat `auth.uid() IS NULL` as the trusted server context, and `auth.uid()`
+ * is `NULLIF(current_setting('app.user_id'), '')` — so an EMPTY user id would
+ * be read as NULL and silently escalate a user request to server privileges.
+ * Coerce empty/blank ids to a sentinel here, at the single chokepoint, rather
+ * than trusting every caller (e.g. realtime subscription auth) to do it.
+ */
+export declare function applyAuthContext(tx: SqlTx, auth: AuthContext, userRole?: string): Promise<void>;
+/**
+ * Reject `pgRoles` that this server can never satisfy.
+ *
+ * `pgRoles` sets the `TO` clause of a generated policy, so a policy naming a
+ * role the request never runs as simply never applies — and RLS then filters
+ * every row. The table reads as empty, which is indistinguishable from having
+ * no data, so the mistake survives review and ships.
+ *
+ * Requests run as `rebase_user`, so a policy is only reachable if it targets
+ * `public` or a role `rebase_user` holds. Anything else is a configuration
+ * error worth failing the boot for.
+ */
+export declare function validatePolicyPgRoles(run: RawSqlRunner, collections: {
+    slug?: string;
+    securityRules?: readonly {
+        name?: string;
+        pgRoles?: readonly string[];
+    }[];
+}[], 
+/** The role requests actually run as: `rebase_user` when the connection is
+ *  privileged enough to switch, otherwise the connection role itself. */
+requestRole?: string): Promise<void>;

package/dist/services/BranchService.d.ts

@@ -0,0 +1,47 @@
+/**
+ * BranchService
+ *
+ * Manages database branching by creating/deleting PostgreSQL databases
+ * using `CREATE DATABASE ... TEMPLATE`. Branch metadata is stored in the
+ * `rebase.branches` table in the default (main) database, following the
+ * same `rebase` schema convention used by entity_history, auth, etc.
+ */
+import { BranchInfo } from "@rebasepro/types";
+import { DrizzleClient } from "../interfaces";
+import { DatabasePoolManager } from "../databasePoolManager";
+export declare class BranchService {
+    private db;
+    private poolManager;
+    constructor(db: DrizzleClient, poolManager: DatabasePoolManager);
+    /**
+     * Ensure the `rebase.branches` metadata table exists in the default database.
+     * Idempotent — safe to call on every startup.
+     */
+    ensureBranchMetadataTable(): Promise<void>;
+    /**
+     * Create a new branch database by templating the source database.
+     *
+     * Uses `CREATE DATABASE ... TEMPLATE` for an instant, full-fidelity copy
+     * of both schema and data.
+     *
+     * @param name   User-facing branch name (e.g., "feature_auth")
+     * @param options.source  Source database to clone; defaults to the main database.
+     */
+    createBranch(name: string, options?: {
+        source?: string;
+    }): Promise<BranchInfo>;
+    /**
+     * Delete a branch database and remove its metadata.
+     * Cannot delete the main/default database.
+     */
+    deleteBranch(name: string): Promise<void>;
+    /**
+     * List all branches recorded in the metadata table.
+     * Optionally fetches database sizes from pg_database.
+     */
+    listBranches(): Promise<BranchInfo[]>;
+    /**
+     * Get info about a specific branch.
+     */
+    getBranchInfo(name: string): Promise<BranchInfo | undefined>;
+}