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

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.