@rebasepro/server-postgres 0.23.0 → 0.24.1-canary.g19596ef

package/dist/history/HistoryService.d.ts

@@ -2,12 +2,15 @@ import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type { EntityHistoryEntry } from "@rebasepro/types";
 export type { RecordHistoryParams, FetchHistoryOptions, HistoryRetentionConfig } from "@rebasepro/types";
 import type { RecordHistoryParams, FetchHistoryOptions, HistoryRetentionConfig } from "@rebasepro/types";
+import { type HistoryTableState } from "./ensure-history-table.js";
 /**
  * A Postgres history row is already the wire shape — `updated_at` comes back
  * from the driver as a string. Kept as an alias because the name is used
  * throughout this package and in `PostgresBackendDriver`.
  */
 export type HistoryEntry = EntityHistoryEntry;
+/** Entries one statement of {@link HistoryService.pruneExpired} deletes at most. */
+export declare const PRUNE_BATCH_SIZE = 5000;
 /**
  * Service for recording and querying row change history.
  * Stores history entries in the `rebase.entity_history` table.
@@ -21,9 +24,41 @@ export declare class HistoryService {
      * through the pool and commit on their own.
      */
     private readonly inTransaction;
-    constructor(db: NodePgDatabase, retention?: Partial<HistoryRetentionConfig>, options?: {
-        inTransaction?: boolean;
+    /**
+     * What new entries are stored as — see `EntityHistoryEntry.format`. `2`,
+     * the previous values of the changed fields only, needs the table's
+     * `format` column, so it is what `ensureHistoryTableExists` found; a
+     * service built without saying stores whole rows, as it always did.
+     */
+    private readonly entryFormat;
+    /**
+     * What the database lacks for history to be recorded, when it lacks
+     * something — `the rebase.entity_history table`. Set for a driver opened
+     * without provisioning on a database no boot with history has prepared:
+     * writes to a `history: true` collection are then refused before they
+     * start (see {@link assertRecordable}), rather than made without their
+     * audit entries.
+     */
+    private readonly unavailable?;
+    /**
+     * Whether recording an entry also prunes that row's history to
+     * {@link retention}. Off for a process that does not know the retention the
+     * project's server is configured with — `openRebase` — which would
+     * otherwise delete entries the server keeps. What it leaves is pruned by
+     * the server: the row's next write, and the hourly sweep.
+     */
+    private readonly pruneOnRecord;
+    constructor(db: NodePgDatabase, retention?: Partial<HistoryRetentionConfig>, options?: Partial<HistoryTableState> & {
+        unavailable?: string;
+        pruneOnRecord?: boolean;
     });
+    /**
+     * Refuse a write to `collection` (a `history: true` collection's slug)
+     * when its entry could not be recorded. Called by the driver before the
+     * write runs anything — hooks included — so a refused write has no side
+     * effects. Reads are never refused.
+     */
+    assertRecordable(collection: string): void;
     /**
      * Record a history entry for a row change.
      *
@@ -68,15 +103,39 @@ export declare class HistoryService {
      * Fetch a single history entry by ID.
      */
     fetchHistoryEntry(historyId: string): Promise<HistoryEntry | null>;
+    /**
+     * Each entry's `format`. A table without the column holds only entries
+     * that store the whole previous row, which is what `1` says.
+     */
+    private formatColumn;
     /**
      * Prune history for a single row: enforce maxEntries and TTL.
      */
     pruneEntity(tableName: string, id: string): Promise<number>;
     /**
-     * Global prune: enforce TTL across ALL rows in a single sweep.
-     * Intended to be called periodically (e.g. once per hour or daily).
+     * Delete every entry older than `ttlDays`, whichever row it belongs to.
+     *
+     * The inline prune above only ever visits a row that was just written,
+     * so a row nobody writes again — every deleted one — kept its history for
+     * good, whatever `ttlDays` said. This is the other half: the backend runs
+     * it once an hour, on one instance of the fleet (see
+     * `startHistoryRetentionSweep` in `@rebasepro/server`).
+     *
+     * In batches of {@link PRUNE_BATCH_SIZE}, each its own statement, repeated
+     * until one comes back short: a first sweep over a year of backlog is many
+     * short deletes, not one that holds millions of row locks and a pool
+     * connection for minutes. `SKIP LOCKED`, so two instances sweeping at once
+     * (or a sweep meeting an inline prune) split the work instead of waiting
+     * on each other. Each batch reads `idx_history_updated_at`, built in the
+     * background at boot (`ensureHistoryIndexes`).
+     *
+     * `signal` ends it after the batch in flight: a shutdown waits for the
+     * sweep, and a first sweep over a large backlog is hundreds of batches.
+     * What is left goes in the next sweep.
      */
-    pruneExpired(): Promise<number>;
+    pruneExpired(options?: {
+        signal?: AbortSignal;
+    }): Promise<number>;
 }
 /**
  * Shallow comparison to find top-level keys that changed between two objects.

package/dist/history/ensure-history-table.d.ts

@@ -1,13 +1,72 @@
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { DeferredIndexBuild } from "../schema/plan/diff-plan.js";
+import { type BootLockOptions } from "../schema/boot-ddl.js";
 /** How a history entry gets written from inside the write it records. */
 export declare const RECORD_HISTORY_FUNCTION = "rebase.record_history";
+/** What {@link ensureHistoryTableExists} left in place, for `HistoryService`. */
+export interface HistoryTableState {
+    /**
+     * {@link RECORD_HISTORY_FUNCTION} exists, so an entry inside a write goes
+     * on that write's transaction. Without it, entries go through the pool and
+     * commit on their own.
+     */
+    inTransaction: boolean;
+    /**
+     * What new entries are stored as. `2` — an update keeps the previous values
+     * of its changed fields only (`EntityHistoryEntry.format`) — once the table
+     * has its `format` column; `1`, the whole previous row, where the column
+     * could not be added this boot.
+     */
+    entryFormat: 1 | 2;
+}
+/** Entries by age alone, for the retention sweep (`HistoryService.pruneExpired`). */
+export declare const HISTORY_SWEEP_INDEX = "idx_history_updated_at";
 /**
  * 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`.
  *
- * Resolves `true` when {@link RECORD_HISTORY_FUNCTION} exists, so an entry can
- * be written on the write's own transaction; `false` sends entries through the
- * pool as before, committing on their own.
+ * Resolves to what the history service may rely on: see {@link HistoryTableState}.
  */
-export declare function ensureHistoryTableExists(db: NodePgDatabase): Promise<boolean>;
+export declare function ensureHistoryTableExists(db: NodePgDatabase, options?: BootLockOptions): Promise<HistoryTableState>;
+/**
+ * What an earlier boot left in place, read without changing anything — for a
+ * driver opened without provisioning. Entries go on the write's transaction
+ * when the function for the table's entry format is there, and the format is
+ * `2` when the table has its `format` column. `tableExists` is false on a
+ * database no boot with history has provisioned.
+ */
+export declare function readHistoryTableState(db: NodePgDatabase): Promise<HistoryTableState & {
+    tableExists: boolean;
+}>;
+/**
+ * Why history cannot be recorded on a database {@link readHistoryTableState}
+ * read, or `undefined` when it can. `requireTransaction` also counts a
+ * missing {@link RECORD_HISTORY_FUNCTION}: without it an entry would commit on
+ * its own instead of with its row.
+ */
+export declare function historyUnavailableReason(state: HistoryTableState & {
+    tableExists: boolean;
+}, options: {
+    requireTransaction: boolean;
+}): string | undefined;
+/**
+ * Bring the history table's indexes to what its reads need, and say which one
+ * is left to build in the background.
+ *
+ * - `idx_history_entity` is dropped: `idx_history_time` leads with the same two
+ *   columns, so it served nothing the other does not, and cost a btree insert
+ *   per recorded change. A `DROP INDEX` takes the table's `ACCESS EXCLUSIVE`
+ *   lock for an instant, so it runs under the boot's lock budget — one second
+ *   per attempt, a few attempts — and a table something holds the whole time
+ *   keeps the index until the next boot. Only once `idx_history_time` is there
+ *   and valid, so a per-row lookup never loses its index.
+ * - `idx_history_updated_at`, which the retention sweep reads, is returned for
+ *   `buildDeferredIndexes`: on a table that already holds years of history the
+ *   build takes seconds to minutes, so it is built `CONCURRENTLY` after the boot,
+ *   blocking no read or write. Nothing is returned when it is already valid.
+ *
+ * Never throws: an index that cannot be dropped or read about is logged, and
+ * the next boot asks again.
+ */
+export declare function ensureHistoryIndexes(db: NodePgDatabase, options?: BootLockOptions): Promise<DeferredIndexBuild[]>;

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from "./services/BranchService.js";
 export * from "./backup/index.js";
 export * from "./PostgresBootstrapper.js";
 export * from "./PostgresAdapter.js";
+export * from "./open-rebase.js";
 /**
  * The app-role provisioning boot performs, for callers that restore a database
  * outside a boot.