@voltro/database 0.23.0 → 0.25.0

package/dist/sql.d.ts

@@ -143,6 +143,25 @@ export declare const applySchema: (tables: ReadonlyArray<AnyTable>, dialect?: Di
  *  raised nothing. */
 cdcChannel?: string) => Effect.Effect<void, never, SqlClient.SqlClient>;
 
+/**
+ * The OPT-IN refuse gate over the advisory. By default (`VOLTRO_ROLLING_DEPLOY`
+ * unset) this never fires — the classifier stays a `db plan` advisory, because
+ * the framework can't know the deploy strategy and a maintenance-window /
+ * scale-to-zero deploy has no overlap window. An operator who DOES rolling
+ * deploys opts in with `VOLTRO_ROLLING_DEPLOY=1`, turning an unsafe `db apply`
+ * into a hard refusal they must split (expand/contract) or explicitly `--force`.
+ *
+ * Pure — the caller supplies the resolved flags + the unsafe-op count (the ⚠
+ * detail is already printed by the plan renderer), so the decision is testable
+ * without a CLI or a DB, and the cloud managed-hosting migration wall can reuse
+ * exactly this verdict.
+ */
+export declare const assessRollingDeployGate: (input: {
+    readonly enabled: boolean;
+    readonly forced: boolean;
+    readonly unsafeCount: number;
+}) => RollingDeployGateVerdict;
+
 /** Per-row backfill body executed by the migration runner. */
 declare type BackfillFunction<TsType = unknown> = (row: Readonly<Record<string, unknown>>) => TsType | Promise<TsType>;
 
@@ -190,6 +209,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;
@@ -358,6 +399,23 @@ declare interface ColumnDefinition<TsType, Type extends ColumnType = ColumnType,
      * COSTS is per command — see `serverOnly()` below for the matrix.
      */
     readonly serverOnly?: boolean;
+    /**
+     * Optimistic-concurrency marker, set by `.version()`.
+     *
+     * The column the store INCREMENTS on every update, and the one an update may
+     * carry an expectation of. Two clients that read the same row and both write
+     * it are the normal case, not an exotic one — and without this the second
+     * write silently wins, which is the shape of every "my change disappeared"
+     * report ever filed.
+     *
+     * A TIMESTAMP cannot do this job. Two writes in the same millisecond are
+     * indistinguishable, and across replicas the clocks disagree; this repo has
+     * already lost rows to exactly that (an analytics sink dropped 7 of 40 events
+     * written in the same millisecond as the query bounding them). A monotonic
+     * integer has neither problem, and it also answers the other half of the
+     * question — which of two copies is NEWER — without consulting a clock.
+     */
+    readonly versionColumn?: boolean;
     /**
      * Data-sensitivity classification, set by `.sensitive(class)`. Declares that
      * this column holds personal / sensitive data of a given CLASS (`'email'`,
@@ -712,10 +770,7 @@ 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. Exported so
- *  the store and the DDL cannot drift: they must agree, and before this they
- *  did not — the store read `options.cdcChannel` while the trigger hardcoded
- *  the default, so any custom channel listened to silence. */
+/** The NOTIFY channel a schema emits on when none is configured. */
 export declare const DEFAULT_CDC_CHANNEL = "framework_changes";
 
 /**
@@ -769,7 +824,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';
@@ -938,6 +997,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;
@@ -1565,7 +1639,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 {
@@ -1576,6 +1650,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;
@@ -1600,6 +1707,36 @@ export declare const rollbackFileBasedMigration: (sql: SqlClient.SqlClient, ctx:
     durationMs: number;
 }, unknown>;
 
+export declare interface RollingDeployGateVerdict {
+    /** The apply MUST NOT proceed (opt-in gate tripped, not forced). */
+    readonly refuse: boolean;
+    /** The gate tripped but `--force` waved it through — surface a warning. */
+    readonly warnForced: boolean;
+    /** Empty unless refuse or warnForced. */
+    readonly message: string;
+}
+
+/** 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 {