@voltro/database 0.13.0 → 0.15.0

package/dist/sql.d.ts

@@ -702,6 +702,37 @@ export declare const defaultJsonClause: (value: object, dialect: DialectId) => s
 
 export declare const describeOutcome: (outcome: BootMigrationOutcome, dialectId: string) => string;
 
+/**
+ * Parse `VOLTRO_DESTRUCTIVE_OK`.
+ *
+ * `1` / `true` acknowledges every lossy op in the run. A comma-separated list
+ * acknowledges only those TABLES — which is the form somebody wants far more
+ * often, and its absence was a real complaint: a plan carrying one intended drop
+ * plus three other lossy ops had no way to say yes to the one. `1` said yes to
+ * all four, and the alternative was a hand-written DROP migration, which the
+ * framework's own upgrade note warns against.
+ *
+ * `undefined` = not set at all.
+ */
+export declare const destructiveScope: (raw: string | undefined) => {
+    readonly kind: "all";
+} | {
+    readonly kind: "tables";
+    readonly tables: ReadonlySet<string>;
+} | undefined;
+
+/**
+ * Compare declared reactivity against the triggers actually installed.
+ *
+ * Postgres only — it is the one dialect where reactivity is carried by DDL. The
+ * binlog and Change Tracking readers are configured at runtime from the same
+ * in-memory table list the schema produced, so they cannot drift from it.
+ */
+export declare const detectReactiveTriggerDrift: (sql: SqlClient.SqlClient, tables: ReadonlyArray<{
+    readonly tableName: string;
+    readonly isReactive?: boolean;
+}>) => Effect.Effect<ReactiveTriggerDrift, SqlError_2>;
+
 /** Dialect IDs the framework supports. */
 declare type DialectId = 'postgres' | 'mysql' | 'mariadb' | 'mssql' | 'sqlite' | 'turso';
 
@@ -879,6 +910,9 @@ export declare interface FileMigrationRunResult {
  */
 export declare const fingerprintSchema: (snapshot: SchemaSnapshot) => string;
 
+/** Human report, or `undefined` when the database and the schema agree. */
+export declare const formatReactiveTriggerDrift: (drift: ReactiveTriggerDrift) => string | undefined;
+
 /**
  * Fully-resolved scheme stored on the `id` column definition AFTER
  * `table()` walks the fields. For `typeid`, the prefix is always
@@ -1369,6 +1403,17 @@ export declare const parseEnumCheck: (clause: string) => {
     readonly values: ReadonlyArray<string>;
 } | null;
 
+/**
+ * The ids of migration files present on disk but NOT yet recorded against THIS
+ * database — i.e. exactly what `runFileBasedMigrations` would execute next.
+ *
+ * Exists so a caller can decide WHETHER to apply before applying. `voltro dev`
+ * uses it to refuse unattended file migrations against a remote database: that
+ * decision needs the list (to name it in the refusal) and must not have run
+ * anything to get it.
+ */
+export declare const pendingFileMigrationIds: (sql: SqlClient.SqlClient, projectRoot: string) => Effect.Effect<ReadonlyArray<string>, unknown>;
+
 export declare interface PlanInput {
     readonly declared: ReadonlyArray<TableLike>;
     readonly live: SchemaSnapshot;
@@ -1483,6 +1528,17 @@ export declare interface RawSqlFragment {
     readonly dependsOn?: ReadonlyArray<string>;
 }
 
+/** Prefix `reactiveTableTriggerSql` names its triggers with. */
+export declare const REACTIVE_TRIGGER_PREFIX = "framework_changes_";
+
+export declare interface ReactiveTriggerDrift {
+    /** Tables the schema says are reactive that carry no trigger in the DB. */
+    readonly missing: ReadonlyArray<string>;
+    /** Tables that carry a trigger but are declared `.nonReactive()` — their
+     *  writes still hit the NOTIFY channel and cost WAL for nothing. */
+    readonly stale: ReadonlyArray<string>;
+}
+
 export declare const releaseMigrationLock: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError_2>;
 
 export declare const renderColumnMysql: (col: ColumnSnapshot) => string;
@@ -1507,16 +1563,6 @@ export declare const rollbackFileBasedMigration: (sql: SqlClient.SqlClient, ctx:
     durationMs: number;
 }, unknown>;
 
-/**
- * Discover + apply every pending file-based migration under
- * `projectRoot/migrations/`. Runs under the same advisory lock as
- * the planner-based applier, so concurrent invocations serialise.
- *
- * - Returns `applied` (newly-run ids + durations) + `skipped`
- *   (ids that were already applied) for the caller's log line.
- * - Failures abort the run + propagate as the Effect's error
- *   channel; the caller (dev.ts boot) is expected to refuse-to-boot.
- */
 export declare const runFileBasedMigrations: (sql: SqlClient.SqlClient, ctx: RunFileBasedMigrationsCtx) => Effect.Effect<FileMigrationRunResult, unknown>;
 
 export declare interface RunFileBasedMigrationsCtx {
@@ -1655,7 +1701,7 @@ export declare interface SquashResult {
     readonly snapshotId: string;
 }
 
-declare interface Table<Name extends string, Fields extends Record<string, ColumnDefinition<unknown>>, Reactive extends boolean = false, IxNames extends string = never> extends TableLike {
+declare interface Table<Name extends string, Fields extends Record<string, ColumnDefinition<unknown>>, Reactive extends boolean = true, IxNames extends string = never> extends TableLike {
     readonly tableName: Name;
     readonly fields: Fields;
     readonly isReactive: Reactive;
@@ -1967,11 +2013,39 @@ declare interface Table<Name extends string, Fields extends Record<string, Colum
      */
     primaryKey: <const F extends readonly [keyof Fields & string, keyof Fields & string, ...Array<keyof Fields & string>]>(fields: F) => Table<Name, Fields, Reactive, IxNames>;
     /**
-     * Opt the table into the reactive engine. Applies
-     * `alter table <name> replica identity full` at migration time so the WAL
-     * stream carries full pre-images on UPDATE/DELETE. See the schema-DSL plan.
+     * Turn reactivity OFF for this table.
+     *
+     * Not "off across instances" — off. The table emits no change events at all:
+     * no local subscriber fires, no cross-instance transport carries it. That is
+     * what the name says, and a version of this that only silenced the
+     * cross-instance half would leave every in-process subscription live on a
+     * table declared non-reactive.
+     *
+     * Reactivity is the default because that is what this framework is for. The
+     * inverse (`.reactive()`) was the API for a long time and failed in both
+     * directions silently: written on mariadb it did nothing at all, omitted on
+     * postgres+cdc it meant a write on one instance never reached another
+     * instance's subscribers.
+     *
+     * Implemented in EVERY dialect, at the store's emit:
+     *
+     *   memory      the store's single emit point drops the event
+     *   sqlite /    same, and turso reuses that store
+     *   turso
+     *   postgres    also: no `REPLICA IDENTITY FULL`, no `pg_notify` trigger
+     *   mysql /     also: excluded from the binlog reader's table filter
+     *   mariadb
+     *   mssql       also: excluded from the Change Tracking table set
+     *
+     * The WRITE is unaffected — this is about notification, never persistence.
+     *
+     * Worth using for a genuinely hot table nobody subscribes to: an append-only
+     * event log, a metrics sink. On postgres it also drops `REPLICA IDENTITY
+     * FULL`, which widens every UPDATE/DELETE in the WAL. Do NOT use it on a
+     * table a query reads — that subscription simply never fires. `voltro dev`
+     * says so at boot.
      */
-    reactive: () => Table<Name, Fields, true, IxNames>;
+    nonReactive: () => Table<Name, Fields, false, IxNames>;
 }
 
 /**
@@ -2105,23 +2179,7 @@ declare interface TableUnique {
     };
 }
 
-/**
- * Clear the `blocked` flag on every LOSSY operation in a plan.
- *
- * Called only after the destructive opt-in has been established, and it is not
- * cosmetic. `applyPlan` carries its OWN unconditional refusal on any blocked
- * operation, with no override parameter. So a plan that the boot gate has
- * decided may proceed, but which still arrives marked blocked, is refused a
- * second time by the applier — which meant `VOLTRO_DESTRUCTIVE_OK=1` could
- * never actually drop a table. The planner's fix hint names that exact
- * variable, so the documented escape hatch pointed at a wall.
- *
- * Only `lossy` ops are unblocked, and callers must have already established
- * that no other class is blocked. A rename-without-marker or a NOT NULL
- * without backfill stays blocked even in destructive-OK mode: those lose data
- * regardless of intent, so intent is not the question being asked.
- */
-export declare const unblockLossy: (plan: MigrationPlan) => MigrationPlan;
+export declare const unblockLossy: (plan: MigrationPlan, scope?: ReturnType<typeof destructiveScope>) => MigrationPlan;
 
 /**
  * Unique-constraint metadata. Set by `.unique()` (or `.unique({ dedup })`).