@voltro/database 0.73.0 → 0.75.0

package/dist/sql.d.ts

@@ -9,6 +9,48 @@ import { Statement } from '@effect/sql';
 
 export declare const acquireMigrationLock: (sql: SqlClient.SqlClient, scope?: MigrationLockScope) => Effect.Effect<HeldMigrationLock, SqlError_2>;
 
+export declare const addColumnDdl: (op: Extract<MigrationOperation, {
+    kind: "add-column";
+}>, planned: PlannedOperation, backfillFromTable: (table: string, column: string) => {
+    sql?: Statement.Fragment;
+    js?: (row: Record<string, unknown>) => unknown | Promise<unknown>;
+    batchSize?: number;
+    sleepMs?: number;
+} | undefined, dialect: "mariadb" | "postgres" | "sqlite" | "mssql") => {
+    pre: ReadonlyArray<string>;
+    backfillKind?: "sql" | "js";
+    backfillSql?: Statement.Fragment;
+    backfillJs?: (row: Record<string, unknown>) => unknown | Promise<unknown>;
+    batchSize?: number;
+    sleepMs?: number;
+    post: ReadonlyArray<string>;
+    /**
+     * The column declares `.unique()` and THIS emitter did not satisfy it.
+     *
+     * A column-level `.unique()` is a COLUMN FLAG, not a snapshot index — the
+     * planner says so itself, which is why `classifyColumnChange` has to catch a
+     * unique that appears on an EXISTING column. For a column the same plan
+     * CREATES there is no live side to compare against, so no `add-unique` op is
+     * ever emitted and this emitter is the only thing that can carry the flag.
+     *
+     * It carried it on exactly one of its three branches. `safe` (a nullable add)
+     * renders `UNIQUE` inline; `needs-default` and `needs-backfill` dropped it
+     * silently, so a new NOT NULL unique column arrived without its constraint,
+     * the re-plan then saw `declared.unique !== live.unique` and proposed
+     * `add-unique` — and `applyPlan` failed its own convergence proof on a plan
+     * that had executed without error. Reported from a MariaDB deploy where the
+     * first apply after an upgrade aborted and the second succeeded, because by
+     * then the column existed and the comparison branch could run.
+     *
+     * The flag rather than the DDL, because the statement is dialect-specific
+     * (mysql needs the key-prefix resolution, mssql bounds the text column first,
+     * sqlite rebuilds) and those emitters already exist at the call site, where
+     * `ctx.declared` is in scope. A second spelling here would be a second
+     * decision to keep in step.
+     */
+    uniquePending?: true;
+};
+
 declare interface AggregateColumn<TResult = number | Date | null> {
     readonly op: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'count-distinct' | 'window-row-number' | 'window-rank' | 'window-dense-rank' | 'window-lag' | 'window-lead' | 'window-sum-over' | 'window-avg-over' | 'column';
     readonly column?: string;
@@ -119,13 +161,21 @@ declare type AnyView = View<string, Record<string, ColumnDefinition<unknown>>>;
  */
 export declare const appliedAtValue: (sql: SqlClient.SqlClient, iso: string) => Effect.Effect<string>;
 
+export declare const appliedFileMigrationIds: (sql: SqlClient.SqlClient) => Effect.Effect<ReadonlyArray<string>, SqlError_2>;
+
 /**
- * The ids recorded as applied file migrations on THIS database — exported for
- * the deploy compensation, which compares the set before a run with the set
- * after it to know which `down`s to run. An absent ledger table reads as an
- * empty set: a virgin database has applied nothing.
+ * The applied file migrations WITH the body hash recorded at the time.
+ *
+ * An empty `hash` means the row predates hash recording — the answer there is
+ * "cannot compare", never "the body changed". Getting that backwards would
+ * report drift for every migration an existing database has ever applied, on
+ * the first run after upgrading, which is the loudest possible way to make a
+ * true warning ignorable.
  */
-export declare const appliedFileMigrationIds: (sql: SqlClient.SqlClient) => Effect.Effect<ReadonlyArray<string>, never>;
+export declare const appliedFileMigrations: (sql: SqlClient.SqlClient) => Effect.Effect<ReadonlyArray<{
+    readonly id: string;
+    readonly hash: string;
+}>, SqlError_2>;
 
 /**
  * The operations the resume ledger says RAN — `started`, `added` or `applied` —
@@ -2564,6 +2614,21 @@ export declare const ensureDeployLedgerTable: (sql: SqlClient.SqlClient, dialect
  */
 export declare const ensureLedgerTable: (sql: SqlClient.SqlClient, dialect: DialectId) => Effect.Effect<void, SqlError_2>;
 
+/**
+ * The PLAN ledger (`_voltro_migration_plans`) — same bootstrap, one caller.
+ *
+ * A file migration records itself here, and the file pass runs BEFORE the
+ * planner that would otherwise create this table. On a database that does not
+ * have it yet, `up()` therefore succeeded and the recording INSERT failed —
+ * `FileMigrationLedgerError`, the one outcome whose whole message is "do not
+ * re-run this". Same reason the resume ledger above is created by the applier
+ * rather than planned: a run needs it before any DDL of its own has happened.
+ *
+ * Index-free like the others, so the planner still owns the table's shape and a
+ * re-plan converges by adding the indexes it declares.
+ */
+export declare const ensurePlanLedgerTable: (sql: SqlClient.SqlClient, dialect: DialectId) => Effect.Effect<void, SqlError_2>;
+
 /** Exported for the same reason as {@link enumTypeBlocks}, and it MUST run
  *  before it — see that function's note on ordering. */
 export declare const enumRenameBlocks: (tables: ReadonlyArray<AnyTable>, dialect: DialectId) => string;
@@ -2797,6 +2862,9 @@ export declare interface FileMigrationContextInput {
  * 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.
+ * Unless the write failed because the row is ALREADY there — another process
+ * recorded the same migration — and then the message says the opposite: the
+ * record is correct and the body ran twice.
  */
 export declare class FileMigrationLedgerError extends Error {
     readonly migrationId: string;
@@ -2814,6 +2882,27 @@ export declare interface FileMigrationRunResult {
     readonly skipped: ReadonlyArray<string>;
 }
 
+/**
+ * Applied and pending file migrations, for a caller that wants to REPORT rather
+ * than apply.
+ *
+ * `voltro db status` had no way to ask: it walks `*.migration.ts` and reads the
+ * other ledger, so against a project using `migrations/<timestamp>_<slug>.ts` it
+ * answered "no migrations found" while `voltro db files` listed four. Two
+ * commands that both say "migrations" and mean different files is a contradiction
+ * a user is right to report as a bug, whichever one they read first.
+ */
+export declare const fileMigrationStatus: (sql: SqlClient.SqlClient, projectRoot: string) => Effect.Effect<ReadonlyArray<FileMigrationStatusRow>, unknown>;
+
+/** One row of `voltro db status` for a `migrations/<timestamp>_<slug>.ts` file. */
+export declare interface FileMigrationStatusRow {
+    readonly id: string;
+    readonly applied: boolean;
+    /** The file no longer hashes to what was recorded when it ran. Always false
+     *  for a row applied before hashes were recorded — see `appliedFileMigrations`. */
+    readonly bodyChanged: boolean;
+}
+
 /**
  * Stable-hash a SchemaSnapshot. Returns the hex-encoded sha256 of the
  * canonicalised JSON representation. Truncated identifiers are NOT
@@ -3204,6 +3293,22 @@ export declare type MigrationAtomicity = 'plan-transactional' | 'per-operation';
 
 export declare const migrationAtomicityFor: (dialect: DialectId) => MigrationAtomicity;
 
+/**
+ * The hash of a migration file's SOURCE, recorded beside its ledger row.
+ *
+ * A migration is looked up by id alone, so without this a body could be
+ * rewritten after it was applied and nothing would say so — the file then reads
+ * like something that ran, and is not. That is the check Liquibase and Flyway
+ * make, for the same reason.
+ *
+ * Shared with the `.migration.ts` runner rather than spelled twice: it has
+ * recorded a hash and warned on drift since it shipped, and two definitions of
+ * "the hash of this file" would be two answers to one question the moment one
+ * of them changed. Same algorithm, same truncation — a hash is only comparable
+ * to one computed identically.
+ */
+export declare const migrationBodyHash: (source: string) => string;
+
 /** One or more `ctx.expect` post-conditions did not hold after `up`. */
 export declare class MigrationExpectationFailed extends Error {
     readonly migrationId: string;
@@ -3510,8 +3615,17 @@ export declare interface MigrationSchemaOps {
         readonly onDelete?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
         readonly onUpdate?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
     }) => Effect.Effect<SchemaOpOutcome, unknown>;
-    /** Remove every row. `DELETE FROM` where the dialect has no TRUNCATE inside a unit. */
-    readonly truncate: (table: string) => Effect.Effect<void, unknown>;
+    /**
+     * Remove every row. `DELETE FROM` rather than TRUNCATE: it is a data
+     * statement on every dialect, so it stays inside a transactional migration
+     * where TRUNCATE (DDL on the MySQL family and SQL Server) would commit it.
+     *
+     * Answers `already-absent` for a table that is not there, like every
+     * operation above — and deliberately does NOT go through the store, whose
+     * set-based delete returns the deleted rows in order to fan out one change
+     * event per row.
+     */
+    readonly truncate: (table: string) => Effect.Effect<SchemaOpOutcome, unknown>;
     /**
      * The Voltro way to change a table's shape in a migration: DECLARE the
      * table as it should be from here on, and the same planner that drives