orez 0.4.71 → 0.5.0

package/README.md

@@ -186,7 +186,48 @@ All options are optional with sensible defaults.
 | on-db-ready | `--on-db-ready=CMD` | `onDbReady: 'CMD'` or `onDbReady: fn` | after db + proxy ready, before zero |
 | on-healthy  | `--on-healthy=CMD`  | `onHealthy: 'CMD'` or `onHealthy: fn` | after all services ready            |
 
-Shell commands receive env vars: `DATABASE_URL`, `OREZ_PG_PORT`, `OREZ_ZERO_PORT`. Change tracking triggers are re-installed after `onDbReady`.
+Shell commands receive env vars: `DATABASE_URL`, `OREZ_PG_PORT`, `OREZ_ZERO_PORT`.
+On the PGlite backend, change-tracking triggers are re-installed after
+`onDbReady`.
+
+#### Startup blocking and the callback context
+
+`onDbReady` runs before zero-cache. On the PGlite and DO proxy backends, shell
+hooks and context-aware callbacks hold every ordinary PG client at connection
+startup until `onDbReady` returns, so an early application `SELECT` can't race
+schema provisioning (or monopolize the shared DB mutex while a migration is
+still creating tables).
+
+- **Shell command:** receives the tagged connection strings via
+  `ZERO_UPSTREAM_DB` / `ZERO_CVR_DB` / `ZERO_CHANGE_DB` / `DATABASE_URL`, plus
+  `PGAPPNAME`. Connecting with any of these bypasses the barrier.
+- **Context-aware callback:** declare a context parameter to opt into the
+  barrier and receive its privileged connection strings:
+
+  ```typescript
+  onDbReady: async (ctx) => {
+    // ctx.upstreamConnectionString / cvrConnectionString / cdbConnectionString
+    // are tagged so they bypass the startup barrier; ctx.applicationName is the
+    // tag itself (for clients that set application_name separately), and
+    // ctx.pgPort is the proxy port.
+    const sql = postgres(ctx.upstreamConnectionString)
+    await sql`CREATE TABLE ...`
+    await sql.end()
+  }
+  ```
+
+  A context-aware callback **must** provision through one of these privileged
+  connections. An ordinary (untagged) connection is held by the same barrier;
+  if the hook does that accidentally, the connection fails after a bounded wait
+  with an error pointing back to `HookContext` instead of hanging forever. Both
+  the hook and barrier default to a 30-second deadline; set
+  `onDbReadyTimeoutMs` higher for a legitimately longer migration.
+
+- **Legacy callback:** a zero-argument callback (`onDbReady: async () => { ... }`)
+  does not opt into the barrier. It keeps the behavior from orez v0.4.73 and
+  earlier, including the ability to open its existing ordinary proxy connection.
+  Callback arity is the runtime contract, so callbacks that need the context
+  should declare `ctx` without a default value or rest-parameter wrapper.
 
 ## Vite Plugin
 

package/dist/cf-do/cdc.d.ts

@@ -0,0 +1,148 @@
+import type { DurableSqlStorage } from './watermark.js';
+/** Bump whenever the generated trigger bodies or buffer shape change. */
+export declare const CDC_SCHEMA_VERSION = 2;
+export interface CdcTableRegistration {
+    /** Physical, flattened SQLite table name. */
+    physicalTableName: string;
+    /** Schema-qualified identity exposed in `_zero_changes`. */
+    tableName: string;
+    /** Optional known column list. The live SQLite schema remains authoritative. */
+    columns?: string[];
+    /** False captures before/after images for transaction rollback only. */
+    publish?: boolean;
+}
+/**
+ * A row image in storage-journal form: one tagged string per column, carrying
+ * the value's SQLite storage class and an exact, lossless payload. This is the
+ * undo encoding, deliberately separate from the Zero wire encoding that
+ * `journalToWire` derives.
+ */
+export type JournalRecord = Record<string, string>;
+export interface CapturedRowChange {
+    physicalTableName: string;
+    tableName: string;
+    op: 'INSERT' | 'UPDATE' | 'DELETE';
+    /** Zero wire image (JSON-safe; blobs as postgres bytea text). */
+    rowData: Record<string, unknown> | null;
+    oldData: Record<string, unknown> | null;
+    /** Lossless storage-journal image used only for undo. */
+    rowJournal: JournalRecord | null;
+    oldJournal: JournalRecord | null;
+    /** Exact decimal rowid text, or null for WITHOUT ROWID tables. */
+    newRowid: string | null;
+    oldRowid: string | null;
+    /** Omitted for normal published changes; false means rollback-only. */
+    publish?: boolean;
+}
+export interface SuspendedCdcTable {
+    physicalTableName: string;
+    tableName: string;
+    publish?: boolean;
+}
+/** Stable-identity and writability metadata read from the live SQLite schema. */
+export interface TableIdentity {
+    /** rowid alias usable in SQL, or null for a WITHOUT ROWID table. */
+    rowidAlias: string | null;
+    /** The INTEGER PRIMARY KEY column, which *is* the rowid, when one exists. */
+    rowidColumn: string | null;
+    /** Declared primary-key columns in key order. */
+    keyColumns: string[];
+    /** Columns undo may write. Excludes generated columns. */
+    writableColumns: string[];
+    /** Every column captured in a row image, generated columns included. */
+    columns: string[];
+}
+/**
+ * Rebuild the exact SQLite value for an undo statement. Integers and reals go
+ * back through CAST so the full int64 range and every double survive without
+ * depending on the driver's numeric binding.
+ */
+export declare function journalValueSqlBinding(encoded: string): {
+    expr: string;
+    params: unknown[];
+};
+export declare function parseJournalRecord(value: unknown): JournalRecord | null;
+/**
+ * Read stable-identity metadata from the live schema. Returns null when the
+ * table cannot be undone row-by-row (no rowid and no primary key), which keeps
+ * capture off it entirely so the caller falls back to table snapshots.
+ */
+export declare function tableIdentity(sql: DurableSqlStorage, table: string): TableIdentity | null;
+export interface TriggerDefinition {
+    name: string;
+    sql: string;
+}
+/**
+ * Drop every trigger on these tables and return their definitions.
+ *
+ * A restore must not fire the table's own business triggers. Undoing an INSERT
+ * with a DELETE would run its AFTER DELETE trigger and write side effects the
+ * original transaction never made, and if that side effect lands on a captured
+ * table, its CDC trigger stages a phantom change on top. Dropping only the
+ * generated CDC triggers leaves both holes open, so every trigger goes.
+ */
+export declare function suspendTriggers(sql: DurableSqlStorage, tables: Iterable<string>): TriggerDefinition[];
+/** Recreate triggers suspended for a restore, verbatim. */
+export declare function restoreTriggers(sql: DurableSqlStorage, triggers: TriggerDefinition[]): void;
+/** The columns a restore is allowed to write. Empty when the table is gone. */
+export declare function writableColumns(sql: DurableSqlStorage, table: string): string[];
+/**
+ * Transactional logical-row capture for the authoritative SQLite database.
+ *
+ * Generated AFTER triggers write full before/after row images to a staging
+ * table in the same SQLite statement as the application write. The owner
+ * drains that staging table before its storage transaction returns and moves
+ * the rows to either `_zero_changes` or `_zero_pending_changes`. Consequently
+ * a failed statement or storage transaction cannot leave an orphaned change.
+ *
+ * Every mutator of the in-memory registration cache runs inside the owner's
+ * storage transaction, so the cache can outlive an abort that rolled its SQLite
+ * side back. `reload()` re-derives the whole cache from SQLite and MUST be
+ * called on any aborted transaction; see `atomically` in worker.ts.
+ */
+export declare class TransactionalCdc {
+    #private;
+    private readonly sql;
+    constructor(sql: DurableSqlStorage);
+    get active(): boolean;
+    /** Force the next per-table ensure to re-read SQLite's live schema. */
+    invalidateSchema(): void;
+    /**
+     * Re-derive every cached decision from SQLite. Called after an aborted
+     * storage transaction, where SQLite rolled back the trigger and metadata
+     * writes but this object still remembers making them. Without it a table can
+     * stay "registered and verified" in memory with no trigger on disk, and every
+     * later write to it is silently uncaptured.
+     */
+    reload(): void;
+    private loadRegistrations;
+    private ensureTables;
+    private tableExists;
+    private triggersExist;
+    private registered;
+    capturesTable(tableName: string): boolean;
+    /** True when a DDL statement must atomically suspend and rebuild CDC triggers. */
+    capturesSchemaChange(sql: string): boolean;
+    private dropTriggers;
+    /**
+     * Drop generated triggers before SQLite rewrites a captured table. SQLite
+     * refuses DROP/RENAME COLUMN while any trigger still references the old row
+     * shape. The caller must run this, the DDL, and finishSchemaChange in one
+     * storage transaction so capture is never observably disabled.
+     */
+    beginSchemaChange(sql: string): SuspendedCdcTable[];
+    /** Re-introspect changed tables and rebuild their triggers from the live shape. */
+    finishSchemaChange(suspended: SuspendedCdcTable[]): void;
+    private installTriggers;
+    /**
+     * Ensure one table is captured. Returns false when the table does not exist
+     * or cannot be undone row-by-row, which leaves the caller on its table
+     * snapshot path rather than capturing changes it could never roll back.
+     */
+    ensureTable(registration: CdcTableRegistration, refresh?: boolean): boolean;
+    /** Replace the captured-table set with the caller's authoritative list. */
+    syncTables(registrations: CdcTableRegistration[]): void;
+    /** Drain all changes captured by the just-completed SQLite statement. */
+    drain(): CapturedRowChange[];
+}
+//# sourceMappingURL=cdc.d.ts.map

package/dist/cf-do/cdc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdc.d.ts","sourceRoot":"","sources":["../../src/cf-do/cdc.ts"],"names":[],"mappings":"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"}