@voltro/database 0.13.0 → 0.14.0

package/dist/sql.d.ts

@@ -702,6 +702,18 @@ export declare const defaultJsonClause: (value: object, dialect: DialectId) => s
 
 export declare const describeOutcome: (outcome: BootMigrationOutcome, dialectId: string) => string;
 
+/**
+ * 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 +891,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 +1384,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 +1509,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 +1544,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 +1682,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 +1994,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>;
 }
 
 /**