@rebasepro/server-postgres 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/services/cdc/trigger-cdc.d.ts

@@ -6,9 +6,13 @@ import type { RawSqlRunner } from "../../security/rls-enforcement.js";
  * — like Supabase Realtime — sees *every* commit regardless of how it was made.
  * When logical replication is unavailable (managed Postgres without
  * `wal_level=logical`, no replication privilege, no `REPLICA IDENTITY`), this
- * trigger-based fallback provides the same guarantee at the row level:
+ * trigger-based fallback provides the same guarantee:
  *
- *   AFTER INSERT/UPDATE/DELETE trigger  →  pg_notify('rebase_cdc', payload)
+ *   AFTER INSERT/UPDATE/DELETE/TRUNCATE statement trigger  →  pg_notify('rebase_cdc', payload)
+ *
+ * once per statement, naming the changed rows by key in batches of about a
+ * thousand — a 1M-row UPDATE is ~1,000 notifications, where a row trigger sent
+ * a million into Postgres's shared notification queue, to every instance.
  *
  * A single dedicated LISTEN client per backend instance consumes the channel
  * (see {@link CdcListener}) and feeds the change into the existing
@@ -21,24 +25,88 @@ import type { RawSqlRunner } from "../../security/rls-enforcement.js";
  */
 /** Postgres NOTIFY channel carrying database-level change events. */
 export declare const CDC_CHANNEL = "rebase_cdc";
-/** Schema-qualified name of the generic trigger function. */
+/**
+ * Schema-qualified name of the row-level trigger function: one notification
+ * per changed row. What every version before statement-level capture attached
+ * everywhere, and still what a partitioned or foreign table gets — see
+ * {@link levelForRelkind}.
+ */
 export declare const CDC_TRIGGER_FUNCTION = "rebase.rebase_cdc_notify";
-/** Name of the per-table trigger (unqualified — triggers are namespaced by table). */
+/**
+ * Schema-qualified name of the statement-level trigger function: one
+ * notification per ~1,000 changed rows. See {@link buildCdcFunctionSql}.
+ *
+ * A function of its own rather than a new body for the row function, because
+ * an instance of an older version replaces the row function's body every time
+ * it boots: a statement trigger calling it would then run a row trigger's body,
+ * for every write, until the next boot of this version.
+ */
+export declare const CDC_STATEMENT_FUNCTION = "rebase.rebase_cdc_notify_statement";
+/** Name of the per-table row-level trigger (unqualified — triggers are namespaced by table). */
 export declare const CDC_TRIGGER_NAME = "rebase_cdc_trigger";
+/** How a table is instrumented: one notification per statement's ~1,000 rows, or one per row. */
+export type CdcTriggerLevel = "statement" | "row";
+/** One trigger this module creates, as `pg_trigger` describes it. */
+interface CdcTriggerSpec {
+    name: string;
+    /** The function it calls. */
+    fn: "row" | "statement";
+    /** `CREATE TRIGGER` between the name and `ON`. */
+    timing: string;
+    /** `CREATE TRIGGER` between the table and `EXECUTE`. */
+    forEach: string;
+    /** `tgtype`: ROW (1), BEFORE (2), INSERT (4), DELETE (8), UPDATE (16), TRUNCATE (32), INSTEAD (64). */
+    type: number;
+    /** `tgnewtable` / `tgoldtable`: the transition tables it captures. */
+    newTable: string | null;
+    oldTable: string | null;
+}
+/**
+ * The statement-level triggers a plain table gets. One per event, because
+ * Postgres refuses transition tables on a trigger with more than one event.
+ * The TRUNCATE one is new with them: a row trigger never fires on `TRUNCATE`,
+ * so a truncated table used to be announced to nobody.
+ */
+export declare const CDC_STATEMENT_TRIGGERS: readonly CdcTriggerSpec[];
+/**
+ * The level a table is instrumented at, by `pg_class.relkind`.
+ *
+ * A plain table gets statement triggers. A partitioned table keeps the row
+ * trigger: Postgres clones a row trigger onto every partition, so a write made
+ * straight to a partition is still captured, while a statement trigger on the
+ * parent fires only for statements against the parent. A foreign table
+ * cannot have transition tables at all.
+ */
+export declare const levelForRelkind: (relkind: string | null | undefined) => CdcTriggerLevel;
+/**
+ * How long after a boot first converts a table from the row trigger, the
+ * statement triggers still announce every change one row per notification.
+ *
+ * The triggers are the database's, and an instance of the previous version
+ * still running beside this one — a rolling deploy, a rollback — reads the
+ * same channel with a parser that knows one row per notification: given a
+ * batch it sees no key, so its lists refetch but its single-row and
+ * many-to-many subscribers hear nothing. While any such instance may be up,
+ * the statement triggers speak its protocol; after this window they batch.
+ * Every version that batches reads both. A boot of the older version re-attaches its row trigger (it
+ * creates a missing one), and the next boot of this one converts it back and
+ * re-opens the window, so a rollback is covered the same way.
+ */
+export declare const CDC_ROW_COMPAT_MS: number;
 /**
- * SQL that (re)creates the generic CDC trigger function. Safe to run repeatedly:
+ * SQL that (re)creates both CDC trigger functions. Safe to run repeatedly:
  * `CREATE OR REPLACE` updates in place without dropping dependent triggers —
- * which is also how a database instrumented by an older version gets this body
- * on its next boot, for every table at once, re-attached or not.
- *
- * The function emits `{ schema, table, op, row }`, and `row` is an **identity,
- * never the tuple**. Postgres puts no privilege on `LISTEN`: any role that can
- * connect can listen on this channel, whatever it may `SELECT`. When `row` was
- * `to_jsonb(NEW)`, a login with no grant on anything received every changed row
- * of every instrumented table — `password_hash` and verification tokens from
- * the auth table included — past RLS and column grants. The consumer never
- * read anything but the key: every subscriber re-reads the row under its own
- * scope.
+ * which is also how a database instrumented by an older version gets these
+ * bodies on its next boot, for every table at once, re-attached or not.
+ *
+ * Both functions emit `{ schema, table, op, ... }`, and the rows are named by
+ * **identity, never the tuple**. Postgres puts no privilege on `LISTEN`: any
+ * role that can connect can listen on this channel, whatever it may `SELECT`.
+ * When `row` was `to_jsonb(NEW)`, a login with no grant on anything received
+ * every changed row of every instrumented table — `password_hash` and
+ * verification tokens from the auth table included — past RLS and column
+ * grants. The consumer never read anything but the key: every subscriber
+ * re-reads the row under its own scope.
  *
  * The identity is, in order:
  *  - the columns the trigger was attached with (`TG_ARGV`) — the key the
@@ -49,18 +117,26 @@ export declare const CDC_TRIGGER_NAME = "rebase_cdc_trigger";
  *    maps any more;
  *  - otherwise `id`, if the table has one, and else nothing: a change the
  *    consumer can only treat as collection-wide.
+ *
+ * `compatUntil` is the end of the window in which the statement function
+ * still sends one row per notification — see {@link CDC_ROW_COMPAT_MS}. A
+ * timestamp, or `-infinity` for none.
  */
-export declare function buildCdcFunctionSql(): string;
+export declare function buildCdcFunctionSql(options?: {
+    compatUntil?: string;
+}): string;
 /**
- * SQL that (re)attaches the CDC trigger to a single table. `DROP ... IF EXISTS`
- * before `CREATE` keeps it idempotent and picks up any function signature change.
+ * SQL that (re)attaches the CDC triggers to a single table, at `level`.
+ * Every trigger this module owns is dropped first, whichever level it was
+ * created at, so a table moves between levels — a row trigger left by an
+ * older version becomes the statement triggers — in one transaction, with no
+ * moment at which a write is announced by neither.
  *
- * `identityColumns` are what the payload names the changed row by — see
+ * `identityColumns` are what the payload names the changed rows by — see
  * {@link buildCdcFunctionSql}. Passed as trigger arguments, so one shared
- * function serves every table without a catalogue read per row. Empty means
- * "the primary key".
+ * function serves every table. Empty means "the primary key".
  */
-export declare function buildCdcTriggerSql(schema: string, table: string, identityColumns?: readonly string[]): string;
+export declare function buildCdcTriggerSql(schema: string, table: string, identityColumns?: readonly string[], level?: CdcTriggerLevel): string;
 export interface CdcTableRef {
     schema: string;
     table: string;
@@ -80,7 +156,7 @@ export interface ProvisionResult {
     }>;
 }
 /**
- * Replace an already-installed trigger function with the current body, and
+ * Replace the already-installed trigger functions with the current bodies, and
  * install nothing where there is none.
  *
  * For a process that owns the schema but is not provisioning capture on this
@@ -88,15 +164,63 @@ export interface ProvisionResult {
  * earlier boot attached keep firing whether anything consumes them or not, so
  * a database instrumented by a version whose function put whole rows on the
  * channel kept doing so, for every login that cares to `LISTEN`, until capture
- * was switched back on. Returns whether a function was there to replace.
+ * was switched back on. The statement function keeps its compatibility
+ * window. Returns whether a function was there to replace.
  */
 export declare function refreshInstalledCdcFunction(run: RawSqlRunner): Promise<boolean>;
 /**
- * Idempotently install the CDC trigger function and per-table triggers.
+ * Take change capture off the database: detach every capture trigger and drop
+ * both functions. Returns how many triggers were attached.
+ *
+ * For `REALTIME_CDC=off`. Capture switched off used to leave the triggers in
+ * place, so every write to every instrumented table still ran one and sent a
+ * notification on a channel nothing listened to. Nothing depends on them once
+ * capture is off: a process without capture announces its own writes on the
+ * cross-instance channel, and the instances that serve realtime listen there.
+ *
+ * `DROP FUNCTION … CASCADE` takes the triggers with it in one statement. It
+ * waits for each table's lock like any trigger DDL, so it runs with the boot's
+ * lock budget and is retried on a lock timeout; a database still contended
+ * after that keeps its triggers and the caller reports it.
+ */
+export declare function removeTriggerCdc(run: RawSqlRunner): Promise<number>;
+/**
+ * What a boot that does not provision capture does with capture an earlier
+ * boot installed.
+ *
+ *  - `capture: "off"` — `REALTIME_CDC=off` — removes it ({@link removeTriggerCdc}).
+ *  - `capture: "not-provisioned"` — capture is wanted but this boot could not
+ *    install it (no direct URL, `auto` fell back) — leaves the triggers and
+ *    brings the functions up to date ({@link refreshInstalledCdcFunction}),
+ *    since they keep firing.
+ */
+export declare function settleInstalledCapture(run: RawSqlRunner, options: {
+    capture: "off" | "not-provisioned";
+}): Promise<{
+    removed: number;
+} | {
+    refreshed: boolean;
+}>;
+/**
+ * Idempotently install the CDC trigger functions and per-table triggers.
+ *
+ * A plain table gets the statement-level triggers, a partitioned or foreign
+ * one the row trigger ({@link levelForRelkind}). A table whose triggers are
+ * already exactly the ones this would create — same function, same events,
+ * enabled, same identity arguments — is left alone; one with a trigger
+ * missing, disabled, attached with different arguments or at the other level
+ * is (re-)attached, all of it in one transaction.
+ *
+ * Converting a table from a row trigger an older version attached opens the
+ * statement function's compatibility window ({@link CDC_ROW_COMPAT_MS}): the
+ * instances that attached it may still be listening.
  *
  * Runs as the owner (server) connection at bootstrap. A table that does not yet
  * exist in the database (schema drift) is skipped with a warning rather than
  * aborting the whole install, so one un-migrated collection cannot disable CDC
  * for the rest.
  */
-export declare function provisionTriggerCdc(run: RawSqlRunner, tables: CdcTableRef[]): Promise<ProvisionResult>;
+export declare function provisionTriggerCdc(run: RawSqlRunner, tables: CdcTableRef[], options?: {
+    now?: number;
+}): Promise<ProvisionResult>;
+export {};

package/dist/services/channel-bus/index.d.ts

@@ -36,7 +36,7 @@ export interface ChannelBusDeps {
  * transports this package knows how to construct, so honouring it there would
  * mean silently discarding the object the application handed us.
  */
-export declare function resolveChannelBusSetting(configured?: ChannelBusSetting): ChannelBusSetting;
+export declare function resolveChannelBusSetting(configured?: ChannelBusSetting, env?: NodeJS.ProcessEnv): ChannelBusSetting;
 /**
  * Produce the bus a setting asks for.
  *

package/dist/services/channel-history.d.ts

@@ -79,10 +79,21 @@ export interface RetainedAnnouncement {
 export declare class ChannelHistoryStore {
     private db;
     private rules;
-    /** Resolved rule per channel name, so the match runs once per channel. */
-    private resolved;
-    /** Channel → timestamp of its last prune, for {@link PRUNE_THROTTLE_MS}. */
+    /**
+     * Each rule with its retention resolved, once. Matched per call rather
+     * than cached per channel name: a cache keyed by the names clients invent
+     * grew by every one of them for the life of the process, and matching a
+     * handful of prefixes costs less than the hashing a lookup does.
+     */
+    private resolvedRules;
+    /**
+     * Channel → timestamp of its last prune, for {@link PRUNE_THROTTLE_MS}.
+     * An entry older than the window throttles nothing, so they are swept once
+     * a window: the map holds the channels pruned recently, not every channel
+     * ever pruned.
+     */
     private lastPruned;
+    private nextPruneSweepAt;
     private tablesReady;
     constructor(db: NodePgDatabase<Record<string, unknown>>, rules?: ChannelRetentionRule[]);
     /** Whether any channel retains anything at all. */
@@ -140,6 +151,6 @@ export declare class ChannelHistoryStore {
      * volume, which is what makes retention affordable on a hot channel.
      */
     prune(channel: string, retention: ResolvedRetention): Promise<number>;
-    /** Forget throttle and match caches. Called on shutdown. */
+    /** Forget the prune throttle. Called on shutdown. */
     clear(): void;
 }

package/dist/services/collection-helpers.d.ts

@@ -143,6 +143,21 @@ export declare function requirePrimaryKeys(collection: CollectionConfig, registr
  * @param collectionPath named in the error.
  */
 export declare function primaryKeyColumns(table: PgTable, primaryKeys: PrimaryKeyInfo[], collectionPath: string): AnyPgColumn[];
+/**
+ * The column a `joinPath` step names, on a table that may key it either way.
+ *
+ * A `JoinStep` is written in database terms — `on: { from: "author_id" }` —
+ * because there is no collection to translate through: the step names a raw
+ * table. A table the boot reads back out of the catalogue is keyed by the
+ * *wire* name, `authorId`, while a hand-written Drizzle schema may key it by
+ * the column name. Looking the step's name up as a key therefore found
+ * nothing on every booted table, and a `via` relation loaded nothing at all.
+ *
+ * The key first, as the step may already name one; then the column whose SQL
+ * name it is. `undefined` when the table has neither, which the caller turns
+ * into an error naming the step.
+ */
+export declare function columnNamed(table: PgTable, name: string): AnyPgColumn | undefined;
 /**
  * The column on the *source* table that a `hasOne`/`hasMany` link points at.
  *

package/dist/services/field-viewer.d.ts

@@ -1,4 +1,5 @@
-import type { FieldViewer } from "@rebasepro/common";
+import { type FieldViewer } from "@rebasepro/common";
+import type { CollectionConfig } from "@rebasepro/types";
 /**
  * Run `fn` with `viewer` as the caller every row strip judges against.
  *
@@ -17,3 +18,16 @@ export declare function withFieldViewer<T>(viewer: FieldViewer | undefined, fn:
  * that is what establishes the viewer.
  */
 export declare function currentFieldViewer(): FieldViewer | undefined;
+/**
+ * The names an API caller's query may not see on `collection`: its
+ * `excludeFromApi` fields, in every spelling. Empty on the trusted server plane
+ * (no viewer), which may filter and sort on those columns — the auth adapter
+ * looks rows up by them — and empty with no collection in hand.
+ *
+ * A query naming one of these is answered exactly as a query naming a column
+ * the table does not have. The REST check passes such a name through to this
+ * driver rather than refusing it itself, so the two answers come from one throw
+ * and cannot drift: a "not readable" there would confirm a column OpenAPI and
+ * `list_collections` hide.
+ */
+export declare function namesHiddenFromCaller(collection: CollectionConfig | undefined): ReadonlySet<string>;

package/dist/services/pg-notify-listener.d.ts

@@ -46,6 +46,13 @@ export interface PgNotifyListenerOptions {
      * rejects, so a caller with a fallback can take it.
      */
     retryInitialConnect?: boolean;
+    /**
+     * The `application_name` the connection reports in `pg_stat_activity`.
+     * Visible to every role, which is what lets one instance count the others
+     * (see `RealtimeService.warnIfMemoryBusOnMultiplePods`). A connection
+     * string that sets its own `application_name` wins.
+     */
+    applicationName?: string;
 }
 /**
  * What a listener can say about itself — read by `/health`.