@voltro/database 0.76.0 → 0.77.0

package/dist/sql.d.ts

@@ -611,6 +611,14 @@ export declare const chunkTables: <T>(xs: ReadonlyArray<T>, n: number) => T[][];
 /**
  * Classify a single DDL operation for rolling-deploy safety.
  *
+ * Every UNSAFE verdict rests on one premise, and its `reason` says so: an
+ * instance on the PREVIOUS release keeps serving against the new schema. A
+ * deployment with no such instance — first deploy, scale-to-zero, maintenance
+ * window — can read the premise and set the advisory aside.
+ *
+ * SAFE regardless of kind: any operation on a table the same plan creates
+ * (`context.createdTables`) — no previous release ever touched it.
+ *
  * 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.
@@ -628,7 +636,7 @@ export declare const chunkTables: <T>(xs: ReadonlyArray<T>, n: number) => T[][];
  *     removing enforcement never makes an old query ERROR.
  *   - `alter-column-nullability` → nullable, `alter-column-default` — relaxing.
  */
-export declare const classifyRollingDeploySafety: (op: MigrationOperation) => RollingDeploySafety;
+export declare const classifyRollingDeploySafety: (op: MigrationOperation, context?: RollingDeployContext) => RollingDeploySafety;
 
 /**
  * Every resume-ledger row, gone — for a caller that has just UNDONE the run
@@ -1720,6 +1728,9 @@ declare type ColumnType = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigi
 
 declare type ColumnType_2 = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigint' | 'boolean' | 'timestamp' | 'date' | 'json' | 'bytes' | 'reference' | 'vector' | 'enum' | 'array' | 'interval' | 'raw';
 
+/** The tables a plan CREATEs — the set every same-plan operation is checked against. */
+export declare const createdTablesOf: (operations: ReadonlyArray<PlannedOperation>) => ReadonlySet<string>;
+
 declare interface DataStore {
     /**
      * Execute a typed query descriptor and return matching rows.
@@ -2629,6 +2640,22 @@ export declare const ensureLedgerTable: (sql: SqlClient.SqlClient, dialect: Dial
  */
 export declare const ensurePlanLedgerTable: (sql: SqlClient.SqlClient, dialect: DialectId) => Effect.Effect<void, SqlError_2>;
 
+/**
+ * The in-progress marker (`_voltro_replace_in_progress`) — same bootstrap,
+ * for a caller `db apply` cannot precede: a native `voltro data restore` into
+ * an EMPTY database writes the marker before its first destructive statement,
+ * and applying the declared schema there first would install the very state
+ * the artefact is about to replace.
+ *
+ * Trigger-free as well as index-free, and that half is load-bearing on
+ * postgres: `applySchema` would add the reactive NOTIFY trigger, whose function
+ * the dump then fails to `DROP` (a dependent object the dump does not know)
+ * and fails to `CREATE` (it already exists) — two errors, and `pg_restore`
+ * exits 1 over a database that is otherwise fine. The planner emits no trigger
+ * for this table either, so the shape converges on the next apply.
+ */
+export declare const ensureReplaceMarkerTable: (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;
@@ -2848,14 +2875,36 @@ export declare interface FileMigrationContext {
     }) => Promise<T> | Effect.Effect<T, unknown, SqlClient.SqlClient>) => Effect.Effect<T, unknown>;
 }
 
-export declare interface FileMigrationContextInput {
-    readonly sql: SqlClient.SqlClient;
-    readonly store: DataStore;
+/**
+ * A body driven over a store that has no SQL underneath — the in-memory
+ * store a unit test uses. No client: `each`, `rewrite`, `expect`,
+ * `skipUnless`, `store`, `log` and a Promise body under `transactional` run
+ * against the store; `raw()`, every `schema` operation and an Effect body
+ * under `transactional` fail with `MigrationNeedsSqlClient`. A store that
+ * CAN run SQL (`run` present) is not accepted here: its migration context
+ * needs the client, and the type says so before the runtime check does.
+ */
+export declare interface FileMigrationContextInMemoryInput extends FileMigrationContextInputBase {
+    readonly sql?: undefined;
+    readonly store: DataStore & {
+        readonly run?: undefined;
+    };
+}
+
+export declare type FileMigrationContextInput = FileMigrationContextLiveInput | FileMigrationContextInMemoryInput;
+
+declare interface FileMigrationContextInputBase {
     readonly dialect: DialectId;
     readonly migrationId: string;
     readonly appliedAt: string;
 }
 
+/** The runner's shape: a SQL-backed store and the client it executes on. */
+export declare interface FileMigrationContextLiveInput extends FileMigrationContextInputBase {
+    readonly sql: SqlClient.SqlClient;
+    readonly store: DataStore;
+}
+
 /**
  * A migration whose `up()` SUCCEEDED and whose ledger row could not be written.
  *
@@ -3351,6 +3400,25 @@ export declare interface MigrationLockScope {
     readonly schema?: string | undefined;
 }
 
+/**
+ * A migration context was built without a SQL client — over the in-memory
+ * store, the shape a unit test uses — and the body reached a surface that
+ * needs a live connection: `raw()`, every `ctx.schema` operation, or an
+ * Effect body under `ctx.transactional` (which runs ON the connection).
+ * `each`, `rewrite`, `expect`, `skipUnless`, `store` and `log` work without
+ * one. Also raised at construction when what was handed in as `sql` is not
+ * an `@effect/sql` client, or when a SQL-backed store arrives without the
+ * client it executes on — both are refused before a body can run rather
+ * than surfacing as a TypeError from inside the first helper that touches
+ * the client.
+ */
+export declare class MigrationNeedsSqlClient extends Error {
+    readonly migrationId: string;
+    readonly operation: string;
+    readonly _tag = "MigrationNeedsSqlClient";
+    constructor(migrationId: string, operation: string, detail: string);
+}
+
 /**
  * Discriminated union for the concrete DDL operations the planner
  * emits. Every variant carries the `table` (most ops act on one
@@ -4906,6 +4974,15 @@ export declare const rollbackFileBasedMigration: (sql: SqlClient.SqlClient, ctx:
     durationMs: number;
 }, unknown>;
 
+/**
+ * What the plan already knows that a single operation does not: the tables it
+ * creates. Optional — without it nothing is known to be new and every verdict
+ * stays conservative.
+ */
+export declare interface RollingDeployContext {
+    readonly createdTables: ReadonlySet<string>;
+}
+
 export declare interface RollingDeployGateVerdict {
     /** The apply MUST NOT proceed (opt-in gate tripped, not forced). */
     readonly refuse: boolean;