@rebasepro/server-postgres 0.0.1-canary.fc811d7 → 0.9.1-canary.0de22e0

package/README.md

@@ -76,6 +76,27 @@ process.on("SIGTERM", async () => {
 | `statementTimeout` | 30,000 |
 | `keepAlive` | true |
 
+## Testing
+
+This package runs **two test runners**, split by directory. This is deliberate — check which half you are in before running anything.
+
+| Tests | Runner | Config | Command |
+|-------|--------|--------|---------|
+| `test/*.ts` (unit) | jest | [`jest.config.cjs`](./jest.config.cjs) | `pnpm test` |
+| `test/e2e/**` (integration) | vitest | [`vitest.e2e.config.ts`](./vitest.e2e.config.ts) | `pnpm test:e2e` |
+
+The unit tests use jest's injected globals (`describe`/`it`/`expect`) and `jest.mock`. The e2e tests import explicitly from `vitest` and need Docker (testcontainers spins up a real Postgres).
+
+**Running a single unit test:**
+
+```bash
+npx jest test/auth-services.test.ts
+```
+
+Pointing `vitest` at a unit test is the easy mistake here — it produces a bare `ReferenceError: jest is not defined` and a "no tests" result, which looks exactly like a dead or broken test file rather than the wrong runner. [`vitest.config.ts`](./vitest.config.ts) exists solely to intercept that and print the command you actually wanted.
+
+`pnpm test` runs jest **without** `--passWithNoTests`: if the unit suite ever stops being collected, CI fails instead of going quietly green.
+
 ## Related Packages
 
 | Package | Role |

package/dist/PostgresBackendDriver.d.ts

@@ -3,7 +3,7 @@ import { BranchService } from "./services/BranchService";
 import { RealtimeService } from "./services/realtimeService";
 import { DatabasePoolManager } from "./databasePoolManager";
 import { DrizzleClient } from "./interfaces";
-import { DatabaseAdmin, DataDriver, DeleteProps, CollectionConfig, FetchCollectionProps, FetchOneProps, ListenCollectionProps, ListenOneProps, RebaseClient, RebaseSdkData, RestFetchService, SaveProps, TableMetadata, User } from "@rebasepro/types";
+import { DatabaseAdmin, DataDriver, DeleteProps, CollectionConfig, FetchCollectionProps, FetchOneProps, ListenCollectionProps, ListenOneProps, RebaseClient, RebaseSdkData, RestFetchService, SaveManyProps, SaveProps, TableMetadata, User } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "./collections/PostgresCollectionRegistry";
 import { HistoryService } from "./history/HistoryService";
 export declare class PostgresBackendDriver implements DataDriver {
@@ -88,7 +88,20 @@ export declare class PostgresBackendDriver implements DataDriver {
     listenCollection<M extends Record<string, unknown>>({ path, collection, filter, limit, offset, startAfter, orderBy, searchString, order, onUpdate, onError }: ListenCollectionProps<M>): () => void;
     fetchOne<M extends Record<string, unknown>>({ path, id, databaseId, collection }: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;
     listenOne<M extends Record<string, unknown>>({ path, id, collection, onUpdate, onError }: ListenOneProps<M>): () => void;
-    save<M extends Record<string, unknown>>({ path, id, values, collection, status }: SaveProps<M>): Promise<Record<string, unknown>>;
+    save<M extends Record<string, unknown>>({ path, id, values, collection, status, upsert }: SaveProps<M>): Promise<Record<string, unknown>>;
+    /**
+     * Write many rows through the same pipeline as {@link save}.
+     *
+     * The batch runs in one transaction of its own, so a failure part-way leaves
+     * nothing behind — the point of a batch is that a re-run starts from a known
+     * state. When this driver is already inside a transaction (the authenticated
+     * path, via `withTransaction`) the nested call becomes a savepoint, which is
+     * still atomic and still commits once.
+     *
+     * Rows are applied in order, so a batch that touches the same key twice ends
+     * with the last write winning, exactly as separate calls would.
+     */
+    saveMany<M extends Record<string, unknown>>({ path, rows, collection, upsert }: SaveManyProps<M>): Promise<Record<string, unknown>[]>;
     delete<M extends Record<string, unknown>>({ row, collection }: DeleteProps<M>): Promise<void>;
     deleteAll(path: string): Promise<void>;
     checkUniqueField(path: string, name: string, value: unknown, id?: string, collection?: CollectionConfig): Promise<boolean>;
@@ -101,6 +114,24 @@ export declare class PostgresBackendDriver implements DataDriver {
     }): Promise<Record<string, unknown>[]>;
     fetchAvailableDatabases(): Promise<string[]>;
     fetchAvailableRoles(): Promise<string[]>;
+    /**
+     * Application-level roles actually in use in this project.
+     *
+     * Distinct from {@link fetchAvailableRoles}, which returns native
+     * PostgreSQL roles from `pg_roles` (`postgres`, `rebase_user`, …). Those
+     * are the roles the SQL editor can `SET ROLE` to. *These* are the strings
+     * held in the users table's `roles` column, injected per-transaction as
+     * `auth.roles()` and matched by `SecurityRule.roles`. Feeding the pg roles
+     * into a `SecurityRule.roles` field produces a condition no user can ever
+     * satisfy, so the two must not be conflated.
+     *
+     * Roles have no registry table — they were migrated out of
+     * `rebase.user_roles` onto an inline `roles TEXT[]` column — so the live
+     * set is derived from what is assigned. A role that is declared in a policy
+     * but held by nobody yet cannot be discovered here; callers that need it
+     * should union in the roles they already know about.
+     */
+    fetchApplicationRoles(): Promise<string[]>;
     fetchCurrentDatabase(): Promise<string | undefined>;
     /**
      * Fetch public tables that are not yet mapped to a collection.
@@ -143,6 +174,16 @@ export declare class AuthenticatedPostgresBackendDriver implements DataDriver {
     fetchOne<M extends Record<string, unknown>>(props: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;
     listenOne<M extends Record<string, unknown>>(props: ListenOneProps<M>): () => void;
     save<M extends Record<string, unknown>>(props: SaveProps<M>): Promise<Record<string, unknown>>;
+    /**
+     * One transaction for the whole batch, rather than one per row.
+     *
+     * This is the point of the method: `save` opens a transaction per call, so
+     * importing 10k rows through it means 10k transactions (and, over HTTP, 10k
+     * round trips). Here the RLS context is established once and every row lands
+     * or none does. Realtime notifications are already deferred to commit by
+     * `withTransaction`, so a batch does not flood subscribers mid-flight.
+     */
+    saveMany<M extends Record<string, unknown>>(props: SaveManyProps<M>): Promise<Record<string, unknown>[]>;
     delete<M extends Record<string, unknown>>(props: DeleteProps<M>): Promise<void>;
     deleteAll(path: string): Promise<void>;
     checkUniqueField(path: string, name: string, value: unknown, id?: string, collection?: CollectionConfig): Promise<boolean>;

package/dist/PostgresBootstrapper.d.ts

@@ -4,11 +4,12 @@
  * Implements the `BackendBootstrapper` interface for PostgreSQL.
  */
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { BackendBootstrapper } from "@rebasepro/types";
+import { BackendBootstrapper, type RealtimeChannelsConfig } from "@rebasepro/types";
 import { PostgresBackendDriver } from "./PostgresBackendDriver";
 import { RealtimeService } from "./services/realtimeService";
 import { DatabasePoolManager } from "./databasePoolManager";
 import { PostgresCollectionRegistry } from "./collections/PostgresCollectionRegistry";
+import { type CdcTableRef } from "./services/cdc/trigger-cdc";
 export interface PostgresDriverConfig {
     connectionString?: string;
     adminConnectionString?: string;
@@ -24,6 +25,12 @@ export interface PostgresDriverConfig {
      * (BaaS mode). Defaults to `public`.
      */
     introspectionSchema?: string;
+    /**
+     * Realtime options. Currently only channel retention, which is opt-in:
+     * without rules here no channel keeps any history and broadcast stays
+     * fire-and-forget. See {@link ChannelRetentionRule}.
+     */
+    realtime?: RealtimeChannelsConfig;
 }
 /**
  * Opaque internals bag that PostgresBootstrapper stores during `initializeDriver()`
@@ -36,6 +43,15 @@ export interface PostgresDriverInternals {
     realtimeService: RealtimeService;
     driver: PostgresBackendDriver;
     poolManager?: DatabasePoolManager;
+    /**
+     * Attach CDC triggers to tables that did not exist when the driver
+     * bootstrapped. Only set when database-level capture is actually active.
+     *
+     * Auth owns its own tables and creates them later in boot, so at driver
+     * bootstrap they are legitimately missing and get skipped; without this
+     * they would stay uninstrumented until the next restart.
+     */
+    provisionCdcForTables?: (tables: CdcTableRef[]) => Promise<void>;
 }
 /**
  * Default PostgreSQL bootstrapper.

package/dist/auth/services.d.ts

@@ -19,6 +19,22 @@ export declare class UserService implements UserRepository {
     private userIdentitiesTable;
     constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
     private getQualifiedUsersTableName;
+    /**
+     * Run a privileged auth write with an explicitly cleared RLS context.
+     *
+     * The auth services run on the base/owner connection, which by design
+     * carries a NULL `app.user_id` so the `auth.uid() IS NULL` server-escape
+     * in the default policies applies. That NULL is normally guaranteed by
+     * `set_config(..., is_local = true)` resetting at transaction end — but a
+     * GUC that survives on a pooled connection (or a connection role that
+     * doesn't bypass RLS: FORCE ROW LEVEL SECURITY, or a non-owner role)
+     * turns the trusted write into an RLS-scoped one and denies it with
+     * SQLSTATE 42501. Clearing the GUCs here, transaction-locally at the
+     * single chokepoint, makes the server context deterministic instead of
+     * trusting whatever state the pool hands us. `auth.uid()` reads '' as
+     * NULL via NULLIF, so '' is the server context.
+     */
+    private withServerContext;
     private mapRowToUser;
     private mapPayload;
     createUser(data: CreateUserData): Promise<UserData>;

package/dist/collections/buildRegistry.d.ts

@@ -0,0 +1,27 @@
+import { Relations } from "drizzle-orm";
+import { PgEnum } from "drizzle-orm/pg-core";
+import { CollectionConfig } from "@rebasepro/types";
+import { PostgresCollectionRegistry } from "./PostgresCollectionRegistry";
+/**
+ * Everything a registry is built from: the collections, and the drizzle schema
+ * they are backed by. In BaaS mode all of it is introspected from the live
+ * database; in CMS mode it comes from the config and the generated schema.
+ */
+export interface RegistrySchema {
+    collections?: CollectionConfig[];
+    tables?: Record<string, unknown>;
+    enums?: Record<string, PgEnum<[string, ...string[]]>>;
+    relations?: Record<string, Relations>;
+}
+/**
+ * Build the collection registry for a driver.
+ *
+ * The order matters and is the reason this is one function rather than a run of
+ * statements in the bootstrapper. Keys are resolved from the drizzle schema, so
+ * anything that inspects them has to run *after* the tables are registered —
+ * and `warnOnKeysTheAdminCannotResolve` fails open if it does not, because a
+ * collection whose table it cannot look up is one it has nothing to say about.
+ * Warned too early, it would skip every collection and report nothing, which
+ * reads exactly like having nothing to report.
+ */
+export declare function buildCollectionRegistry(schema: RegistrySchema): PostgresCollectionRegistry;

package/dist/connection.d.ts

@@ -19,6 +19,27 @@ export interface PostgresPoolConfig {
     /** Enable TCP keep-alive (default: true) */
     keepAlive?: boolean;
 }
+/**
+ * Destroy pool clients that are released while still inside a transaction.
+ *
+ * pg-pool returns a client to the idle list whenever `release()` is called
+ * without an error — even if the connection is still mid-transaction (status
+ * `T`/`E`). That happens in practice: drizzle's pool transaction releases in
+ * a `finally` after attempting ROLLBACK, and if the ROLLBACK itself fails
+ * (e.g. it was queued behind a statement that hit the client-side
+ * query_timeout), the client goes back dirty. The next checkout then runs
+ * its statements inside the zombie transaction — with the previous request's
+ * `app.*` RLS GUCs still applied, which turns unrelated queries into
+ * RLS-scoped ones (observed in production as registration failing with
+ * SQLSTATE 42501 under a leaked anonymous context).
+ *
+ * pg-pool emits `release` before it consults its private `_expired` set, so
+ * marking the client expired here makes `_release()` destroy it instead of
+ * pooling it. Both `client._txStatus` (pg ≥ 8.16) and `pool._expired` are
+ * private APIs — feature-detect and fall back to loud logging so an upstream
+ * change degrades to observability, never to silent corruption.
+ */
+export declare function guardPoolAgainstDirtyRelease(pool: Pool, label: string): void;
 /**
  * Create a Drizzle-backed Postgres connection with a production-grade
  * connection pool.

package/dist/data-transformer.d.ts

@@ -12,12 +12,19 @@ import { PostgresCollectionRegistry } from "./collections/PostgresCollectionRegi
 export interface SerializedEntityData {
     /** Scalar column values ready for INSERT/UPDATE. */
     scalarData: Record<string, unknown>;
-    /** Inverse relation updates that must be applied to target tables. */
+    /**
+     * Inverse relation updates that must be applied to target tables.
+     *
+     * No address here: the row being written does not know its own. These are
+     * applied by `PersistService`, which addresses them with the id it holds —
+     * the one it was given for an update, or the one the INSERT returned — and
+     * that is the authority. This item used to carry a `currentId` derived from
+     * the *input* values, which nothing ever read.
+     */
     inverseRelationUpdates: Array<{
         relationKey: string;
         relation: Relation;
         newValue: unknown;
-        currentId?: string | number;
     }>;
     /** JoinPath relation updates that require multi-hop writes. */
     joinPathRelationUpdates: Array<{