@voltro/database 0.68.0 → 0.69.0

package/dist/sql.d.ts

@@ -7,7 +7,7 @@ import { SqlError } from '@effect/sql';
 import { SqlError as SqlError_2 } from '@effect/sql/SqlError';
 import { Statement } from '@effect/sql';
 
-export declare const acquireMigrationLock: (sql: SqlClient.SqlClient, scope?: MigrationLockScope) => Effect.Effect<void, SqlError_2>;
+export declare const acquireMigrationLock: (sql: SqlClient.SqlClient, scope?: MigrationLockScope) => Effect.Effect<HeldMigrationLock, SqlError_2>;
 
 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';
@@ -126,6 +126,14 @@ export declare interface AppliedOp {
  */
 export declare const applyNamespacedSchema: (tables: ReadonlyArray<AnyTable>, namespace: string, dialect?: DialectId, options?: SchemaApplyOptions) => Effect.Effect<void, never, SqlClient.SqlClient>;
 
+/**
+ * Apply a plan, holding the migration lock for the whole of it.
+ *
+ * `acquireUseRelease` rather than a `try/finally` in the body: Effect's own
+ * bracket runs its release on success, on failure, on a defect AND on
+ * interruption, which is exactly the set a JS `finally` inside `Effect.gen`
+ * does not cover.
+ */
 export declare const applyPlan: (sql: SqlClient.SqlClient, plan: MigrationPlan, ctx: ApplyPlanCtx) => Effect.Effect<AppliedMigration, SqlError_2, SqlClient.SqlClient>;
 
 export declare interface ApplyPlanCtx {
@@ -1344,6 +1352,22 @@ export declare const formatBranchRehearsal: (report: BranchRehearsalReport) => s
 /** Human report, or `undefined` when the database and the schema agree. */
 export declare const formatReactiveTriggerDrift: (drift: ReactiveTriggerDrift) => string | undefined;
 
+/**
+ * A lock that is being HELD, and the only way to let it go.
+ *
+ * The reserved connection lives inside this handle: `release` gives the lock
+ * back and closes the reservation, in that order. Returning it as a value
+ * rather than exposing a free `releaseMigrationLock(sql, scope)` is deliberate
+ * — a free release cannot know WHICH connection took the lock, and on every
+ * session-scoped dialect a release on the wrong connection is a no-op that
+ * reports success.
+ */
+export declare interface HeldMigrationLock {
+    /** Release the lock and return its connection to the pool. Idempotent only
+     *  in the sense that the dialect statements are; call it once. */
+    readonly release: Effect.Effect<void, SqlError_2>;
+}
+
 /**
  * Fully-resolved scheme stored on the `id` column definition AFTER
  * `table()` walks the fields. For `typeid`, the prefix is always
@@ -2555,8 +2579,6 @@ export declare const rehearsedOperation: (planned: PlannedOperation) => Rehearse
  */
 export declare const rehearseMigrationOnBranch: (ops: BranchRehearsalOps) => Promise<BranchRehearsalReport>;
 
-export declare const releaseMigrationLock: (sql: SqlClient.SqlClient, scope?: MigrationLockScope) => Effect.Effect<void, SqlError_2>;
-
 export declare const renderColumnMysql: (col: ColumnSnapshot) => string;
 
 export declare const renderColumnPg: (col: ColumnSnapshot) => string;
@@ -3570,12 +3592,6 @@ declare interface WindowSpec {
     }>;
 }
 
-/**
- * Convenience wrapper: acquire → run `work` → release. Releases even
- * on failure via `Effect.ensuring`, but a process crash mid-work
- * leaves the postgres lock held until that connection closes (which
- * the pooled SqlClient does on Effect scope cleanup).
- */
 export declare const withMigrationLock: <A, E, R = never>(sql: SqlClient.SqlClient, work: Effect.Effect<A, E, R>, scope?: MigrationLockScope) => Effect.Effect<A, E | SqlError_2, R>;
 
 /** Tree of relations to eager-load. */