@voltro/database 0.22.1 → 0.24.0

package/dist/sql.d.ts

@@ -135,7 +135,13 @@ export declare interface ApplyPlanCtx {
  * Caller passes the dialect explicitly. Defaults to `'postgres'` for
  * call-sites that haven't migrated yet.
  */
-export declare const applySchema: (tables: ReadonlyArray<AnyTable>, dialect?: DialectId) => Effect.Effect<void, never, SqlClient.SqlClient>;
+export declare const applySchema: (tables: ReadonlyArray<AnyTable>, dialect?: DialectId, 
+/** NOTIFY channel for the reactive triggers. Pass the SAME value the store
+ *  was built with. They are two halves of one contract and used to be able to
+ *  disagree silently: the store listened on its `cdcChannel` while the DDL
+ *  always emitted on the default, so a custom channel received nothing and
+ *  raised nothing. */
+cdcChannel?: string) => Effect.Effect<void, never, SqlClient.SqlClient>;
 
 /** Per-row backfill body executed by the migration runner. */
 declare type BackfillFunction<TsType = unknown> = (row: Readonly<Record<string, unknown>>) => TsType | Promise<TsType>;
@@ -184,6 +190,28 @@ export declare type BootMigrationOutcome = {
  *  producing a complete, non-overlapping partition of the table list. */
 export declare const chunkTables: <T>(xs: ReadonlyArray<T>, n: number) => T[][];
 
+/**
+ * Classify a single DDL operation for rolling-deploy safety.
+ *
+ * UNSAFE (breaks old code during the overlap window):
+ *   - `drop-column` / `drop-table` — old code reads it → error.
+ *   - `rename-column` / `rename-table` — to old code the old name vanished.
+ *   - `alter-column-type` — old reads may fail to decode, old writes may be
+ *     rejected by the new type; even a "widening" is risky to assume.
+ *   - `alter-column-nullability` → NOT NULL — old code that inserts without the
+ *     column (or with NULL) is now rejected.
+ *   - `add-unique` / `add-unique-composite` / `add-check` / `add-foreign-key`
+ *     — a constraint old writes may violate the instant it exists.
+ *
+ * SAFE (old code keeps working):
+ *   - `create-table` / `add-column` (nullable or defaulted) / `add-index` —
+ *     additive; old code doesn't see it.
+ *   - `drop-index` / `drop-unique*` / `drop-check` / `drop-foreign-key` —
+ *     removing enforcement never makes an old query ERROR.
+ *   - `alter-column-nullability` → nullable, `alter-column-default` — relaxing.
+ */
+export declare const classifyRollingDeploySafety: (op: MigrationOperation) => RollingDeploySafety;
+
 declare interface ColumnDefinition<TsType, Type extends ColumnType = ColumnType, HasDefault extends boolean = boolean> {
     readonly type: Type;
     readonly nullable: boolean;
@@ -706,6 +734,9 @@ declare type ColumnType = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigi
  */
 export declare const declaredSnapshot: (tables: ReadonlyArray<TableLike>, dialect?: DialectId) => SchemaSnapshot;
 
+/** The NOTIFY channel a schema emits on when none is configured. */
+export declare const DEFAULT_CDC_CHANNEL = "framework_changes";
+
 /**
  * `DEFAULT <expr>` for an array-valued default.
  *
@@ -757,7 +788,11 @@ export declare const destructiveScope: (raw: string | undefined) => {
 export declare const detectReactiveTriggerDrift: (sql: SqlClient.SqlClient, tables: ReadonlyArray<{
     readonly tableName: string;
     readonly isReactive?: boolean;
-}>) => Effect.Effect<ReactiveTriggerDrift, SqlError_2>;
+}>, 
+/** The app's `cdcChannel`. Part of the trigger NAME on any non-default
+ *  channel, so omitting it here reported every table as missing on a database
+ *  where every trigger was present. */
+channel?: string) => Effect.Effect<ReactiveTriggerDrift, SqlError_2>;
 
 /** Dialect IDs the framework supports. */
 declare type DialectId = 'postgres' | 'mysql' | 'mariadb' | 'mssql' | 'sqlite' | 'turso';
@@ -815,7 +850,9 @@ export declare const emitDropColumnDdlMysql: (op: Extract<MigrationOperation, {
  * Dialect-uniform now, because there is nothing left in it that only one dialect
  * can express.
  */
-export declare const emitFrameworkBootstrapSql: (tables: ReadonlyArray<AnyTable>, dialect: DialectId) => string;
+export declare const emitFrameworkBootstrapSql: (tables: ReadonlyArray<AnyTable>, dialect: DialectId, 
+/** NOTIFY channel for the reactive triggers — see `applySchema`. */
+cdcChannel?: string) => string;
 
 /**
  * Emit the full schema DDL SCOPED to a tenant namespace. The container is
@@ -856,7 +893,10 @@ export declare const emitNamespacedSchemaSql: (tables: ReadonlyArray<AnyTable>,
  */
 export declare const emitNamespaceProvisionDdl: (namespace: string, dialect: DialectId, sqliteFile?: string) => string;
 
-export declare const emitSchemaSql: (entities: ReadonlyArray<AnyTable | AnyView>, dialect: DialectId) => string;
+export declare const emitSchemaSql: (entities: ReadonlyArray<AnyTable | AnyView>, dialect: DialectId, 
+/** NOTIFY channel for the reactive triggers. Must match the store's
+ *  `cdcChannel`, or writes emit where nothing is listening. */
+cdcChannel?: string) => string;
 
 declare type EmptyMerge = unknown;
 
@@ -921,6 +961,21 @@ export declare interface FileMigrationContext {
     readonly appliedAt: string;
 }
 
+/**
+ * A migration whose `up()` SUCCEEDED and whose ledger row could not be written.
+ *
+ * Its own error type because the recovery is the opposite of the ordinary one:
+ * do NOT re-run. The change has landed; what is missing is the record that says
+ * so, and every future invocation will apply it again until that row exists.
+ */
+export declare class FileMigrationLedgerError extends Error {
+    readonly migrationId: string;
+    readonly file: string;
+    readonly cause: unknown;
+    readonly _tag = "FileMigrationLedgerError";
+    constructor(migrationId: string, file: string, cause: unknown);
+}
+
 export declare interface FileMigrationRunResult {
     readonly applied: ReadonlyArray<{
         id: string;
@@ -1548,7 +1603,7 @@ export declare interface RawSqlFragment {
     readonly dependsOn?: ReadonlyArray<string>;
 }
 
-/** Prefix `reactiveTableTriggerSql` names its triggers with. */
+/** Prefix every reactive trigger name starts with, whatever the channel. */
 export declare const REACTIVE_TRIGGER_PREFIX = "framework_changes_";
 
 export declare interface ReactiveTriggerDrift {
@@ -1559,6 +1614,39 @@ export declare interface ReactiveTriggerDrift {
     readonly stale: ReadonlyArray<string>;
 }
 
+/**
+ * The statements that bring the DATABASE's change triggers back in line with
+ * what the schema declares.
+ *
+ * This exists because the diff could not do it and said it could. Reactive
+ * triggers are emitted only by the two full-schema emitters — the CREATE-
+ * everything path for a fresh database, and the framework bootstrap — so a
+ * table that arrived through the PLANNER (every table an existing app has
+ * added since it was created) never got one. The planner has no trigger
+ * dimension at all, so `db plan` reports 0 operations and `db apply` reports
+ * "schema is up to date" while the drift detector is simultaneously telling
+ * you 500 tables have no trigger, and pointing at `voltro db apply` as the
+ * remedy. Reported by a consumer with 525 tables and 27 triggers, all 27 on
+ * framework tables.
+ *
+ * A single instance is unaffected — its own writes reach its own subscribers
+ * through the in-process path — so this is invisible until you scale out, which
+ * is the worst possible time to find it.
+ *
+ * Postgres only: it is the one dialect where reactivity is carried by DDL. The
+ * binlog / Change Tracking readers are configured at runtime from the same
+ * in-memory table list, so they cannot drift from it.
+ */
+export declare const reactiveTriggerRepairSql: (input: {
+    readonly tables: ReadonlyArray<AnyTable>;
+    readonly dialect: DialectId;
+    /** Table names the detector found reactive-but-untriggered. */
+    readonly missing: ReadonlyArray<string>;
+    /** Table names the detector found triggered-but-declared-nonReactive. */
+    readonly stale: ReadonlyArray<string>;
+    readonly channel?: string;
+}) => ReadonlyArray<string>;
+
 export declare const releaseMigrationLock: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError_2>;
 
 export declare const renderColumnMysql: (col: ColumnSnapshot) => string;
@@ -1583,6 +1671,27 @@ export declare const rollbackFileBasedMigration: (sql: SqlClient.SqlClient, ctx:
     durationMs: number;
 }, unknown>;
 
+/** Verdict for one operation under a rolling deploy. */
+export declare type RollingDeploySafety = {
+    readonly safe: true;
+} | {
+    readonly safe: false;
+    /** Why an instance on the OLD code breaks against the new schema. */
+    readonly reason: string;
+    /** The expand/contract move that keeps both code versions working. */
+    readonly remedy: string;
+};
+
+/**
+ * The rolling-deploy-unsafe operations in a plan, each paired with its verdict.
+ * Empty ⇒ the whole plan is safe to apply while an old deploy is still live.
+ */
+export declare const rollingDeployUnsafeOps: (operations: ReadonlyArray<PlannedOperation>) => ReadonlyArray<{
+    readonly op: PlannedOperation;
+    readonly reason: string;
+    readonly remedy: string;
+}>;
+
 export declare const runFileBasedMigrations: (sql: SqlClient.SqlClient, ctx: RunFileBasedMigrationsCtx) => Effect.Effect<FileMigrationRunResult, unknown>;
 
 export declare interface RunFileBasedMigrationsCtx {