@rvoh/dream 2.13.0 → 2.14.0-beta.1

package/dist/cjs/src/dream/QueryDriver/Postgres.js

@@ -13,12 +13,35 @@ import { isPrimitiveDataType } from '../../db/dataTypes.js';
 import DreamApp from '../../dream-app/index.js';
 import camelize from '../../helpers/camelize.js';
 import { findCitextArrayOid, findCorrespondingArrayOid, findEnumArrayOids, parsePostgresBigint, parsePostgresDate, parsePostgresDatetime, parsePostgresDatetimeTz, parsePostgresDecimal, parsePostgresTime, parsePostgresTimeTz, } from '../../helpers/customPgParsers.js';
+import { testDatabasePoolSize } from '../../db/testDatabasePool.js';
 import EnvInternal from '../../helpers/EnvInternal.js';
 import createDb from './helpers/pg/createDb.js';
 import _dropDb from './helpers/pg/dropDb.js';
 import loadPgClient from './helpers/pg/loadPgClient.js';
 import KyselyQueryDriver from './Kysely.js';
 const pgTypes = pg.types;
+// Fixed dream-pool namespace constant for the advisory-lock `key1`. Chosen to
+// sit high in the int4 range and be recognizable in `pg_locks` (classid/objid)
+// when debugging. XORed with a per-namespace hash below so two apps sharing one
+// Postgres cluster reserve disjoint index spaces.
+const DREAM_TEST_POOL_LOCK_NAMESPACE = 0x44_52_4d_00 | 0; // "DRM\0"
+// Aggressive TCP keepalive on the dedicated lock-holding connection. Insurance
+// for remote / CI Postgres and abrupt kills where a FIN might be lost: it lets
+// Postgres reap the dead backend (and release the lock) even when the OS never
+// delivered a clean socket close. For a local kill the lock releases on EOF
+// regardless of this.
+const LOCK_CONNECTION_KEEPALIVE_INITIAL_DELAY_MS = 1_000;
+function int32Hash(value) {
+    let hash = 0;
+    for (let i = 0; i < value.length; i++) {
+        hash = (Math.imul(hash, 31) + value.charCodeAt(i)) | 0;
+    }
+    return hash;
+}
+function advisoryLockKey1(namespace) {
+    // Stays within int4 via the `| 0` coercions.
+    return (DREAM_TEST_POOL_LOCK_NAMESPACE ^ int32Hash(namespace)) | 0;
+}
 export default class PostgresQueryDriver extends KyselyQueryDriver {
     /**
      * create the database. Must respond to the NODE_ENV value.
@@ -161,7 +184,12 @@ export default class PostgresQueryDriver extends KyselyQueryDriver {
             await client.query(`DROP DATABASE IF EXISTS ${replicaTestWorkerDatabaseName};`);
             await client.query(`CREATE DATABASE ${replicaTestWorkerDatabaseName} TEMPLATE ${dbConf.name};`);
         }
-        for (let i = 2; i <= parallelTests; i++) {
+        // The pool spans `<base>` (the migration template, also claimable) plus
+        // `<base>_2 .. <base>_K`. Each live test worker claims one member for its
+        // lifetime via an advisory lock, so the pool must be wide enough to cover
+        // active + still-terminating workers — see src/db/testDatabasePool.ts.
+        const poolSize = testDatabasePoolSize(parallelTests);
+        for (let i = 2; i <= poolSize; i++) {
             const workerDatabaseName = `${dbConf.name}_${i}`;
             DreamCLI.logger.logContinueProgress(`creating duplicate test database ${workerDatabaseName} for concurrent tests...`, { logPrefix: '  ├ [db]', logPrefixColor: 'greenBright' });
             await client.query(`DROP DATABASE IF EXISTS ${workerDatabaseName};`);
@@ -170,4 +198,51 @@ export default class PostgresQueryDriver extends KyselyQueryDriver {
         await client.end();
         DreamCLI.logger.logEndProgress();
     }
+    static supportsParallelTestDatabases = true;
+    /**
+     * @internal
+     *
+     * Postgres implementation of the per-worker test-database claim seam (see
+     * {@link TestDatabaseLockSession} and `src/db/testDatabasePool.ts`).
+     *
+     * Postgres advisory locks are global to the cluster (not scoped to a single
+     * database), so one dedicated connection — to the `postgres` maintenance
+     * database — can reserve a pool index for the whole cluster. We use the
+     * two-`int4` form `pg_try_advisory_lock(key1, key2)`, whose lock space is
+     * distinct from the single-`bigint` form `pg_advisory_lock(bigint)` that
+     * application code typically uses, so a claim can never clash with an
+     * app-level advisory lock. `key1` folds a hash of the lock namespace (the
+     * base database name) into a fixed dream-pool constant; `key2` is the pool
+     * index. The lock auto-releases when the connection drops on process exit.
+     */
+    static async openTestDatabaseLockSession(connectionName) {
+        const dreamApp = DreamApp.getOrFail();
+        const creds = dreamApp.dbCredentialsFor(connectionName)?.primary ?? dreamApp.dbCredentialsFor(connectionName)?.replica;
+        if (!creds?.name)
+            throw new Error(`[dream] cannot open a test-database lock session: the "${connectionName}" connection has no resolvable primary db name`);
+        const client = new pg.Client({
+            host: creds.host || 'localhost',
+            port: creds.port,
+            // The maintenance database always exists and we never lock it —
+            // advisory locks are cluster-wide.
+            database: 'postgres',
+            user: creds.user,
+            password: creds.password,
+            keepAlive: true,
+            keepAliveInitialDelayMillis: LOCK_CONNECTION_KEEPALIVE_INITIAL_DELAY_MS,
+        });
+        await client.connect();
+        return {
+            async tryAcquire(namespace, index) {
+                const result = await client.query('SELECT pg_try_advisory_lock($1::int4, $2::int4) AS locked', [
+                    advisoryLockKey1(namespace),
+                    index,
+                ]);
+                return result.rows[0]?.locked === true;
+            },
+            async release() {
+                await client.end().catch(() => undefined);
+            },
+        };
+    }
 }

package/dist/cjs/src/dream/QueryDriver/helpers/pg/dropDb.js

@@ -1,4 +1,5 @@
 import DreamCLI from '../../../../cli/index.js';
+import { testDatabasePoolSize } from '../../../../db/testDatabasePool.js';
 import DreamApp from '../../../../dream-app/index.js';
 import EnvInternal from '../../../../helpers/EnvInternal.js';
 import loadPgClient from './loadPgClient.js';
@@ -25,7 +26,8 @@ async function maybeDropDuplicateDatabases(client, dbName) {
         DreamCLI.logger.logContinueProgress(`dropping fake replica test database ${replicaTestWorkerDatabaseName}`, { logPrefix: '  ├ [db]', logPrefixColor: 'greenBright' });
         await client.query(`DROP DATABASE IF EXISTS ${replicaTestWorkerDatabaseName};`);
     }
-    for (let i = 2; i <= parallelTests; i++) {
+    const poolSize = testDatabasePoolSize(parallelTests);
+    for (let i = 2; i <= poolSize; i++) {
         const workerDatabaseName = `${dbName}_${i}`;
         DreamCLI.logger.logContinueProgress(`dropping duplicate test database ${workerDatabaseName}`, {
             logPrefix: '  ├ [db]',

package/dist/cjs/src/dream-app/index.js

@@ -1,4 +1,5 @@
 import * as util from 'node:util';
+import { claimedTestDatabaseIndexOrNull, claimTestDatabase, testDatabaseNameForIndex, } from '../db/testDatabasePool.js';
 import validateTable from '../db/validators/validateTable.js';
 import Query from '../dream/Query.js';
 import PostgresQueryDriver from '../dream/QueryDriver/Postgres.js';
@@ -47,8 +48,12 @@ export default class DreamApp {
         if (!dreamApp.serializers)
             setCachedSerializers({});
         cacheDreamApp(dreamApp);
-        if (!opts.bypassDbConnectionsDuringInit)
+        if (!opts.bypassDbConnectionsDuringInit) {
+            // Claim this worker's pool database before any connection is built, so
+            // the synchronous dbName() always resolves to the claimed database.
+            await dreamApp.ensureTestDatabaseClaimed();
             await this.setDatabaseTypeParsers(dreamApp);
+        }
         await deferCb?.(dreamApp);
         for (const plugin of dreamApp.plugins) {
             await plugin(dreamApp);
@@ -289,9 +294,56 @@ A new key can also be generated from the CLI:
     get serializers() {
         return getSerializersOrFail();
     }
+    /**
+     * The database name to connect to for a given connection. In dev/prod this is
+     * simply the configured name. Under vitest (test env) it is the per-worker
+     * database claimed from the pool — see {@link testDatabaseClaimEnabled} and
+     * `src/db/testDatabasePool.ts`.
+     *
+     * This is synchronous because Kysely builds its `pg.Pool` synchronously. It
+     * reads the already-claimed pool index; the claim is awaited earlier in the
+     * worker — `DreamApp.init()` calls {@link claimTestDatabase} before the first
+     * connection is built, and `dream-spec-helpers`' `truncate` awaits
+     * {@link testDatabaseName} — so the index is always populated by the time any
+     * connection resolves its name.
+     */
     dbName(connectionName, connection) {
         const conf = this.dbConnectionConfig(connectionName, connection);
-        return this.parallelDatabasesEnabled ? `${conf.name}_${process.env.VITEST_POOL_ID}` : conf.name;
+        if (!this.runtimeNeedsTestDatabaseClaim)
+            return conf.name;
+        this.requireTestDatabaseClaimSupport();
+        const index = claimedTestDatabaseIndexOrNull();
+        if (index === null)
+            throw new Error(`[dream] dbName("${connectionName}", "${connection}") was resolved before this worker claimed ` +
+                `a test database. The pool claim must be awaited first (DreamApp.init / truncate do this). ` +
+                `This indicates a database connection was opened before app initialization completed.`);
+        return testDatabaseNameForIndex(conf.name, index);
+    }
+    /**
+     * Single source of truth for the claimed test-database name, used both by
+     * dream's connection resolution and by `dream-spec-helpers`' `truncate`
+     * (which opens its own `pg.Client` and so must read — not recompute — the
+     * claim). Awaits the pool claim if it has not happened yet in this worker.
+     */
+    async testDatabaseName(connectionName, connection) {
+        const conf = this.dbConnectionConfig(connectionName, connection);
+        if (!this.runtimeNeedsTestDatabaseClaim)
+            return conf.name;
+        this.requireTestDatabaseClaimSupport();
+        const index = await claimTestDatabase(this);
+        return testDatabaseNameForIndex(conf.name, index);
+    }
+    /**
+     * Claim this worker's pool database if it hasn't been claimed yet. Idempotent
+     * and a no-op outside the test-under-vitest path. Called by `DreamApp.init()`
+     * before any connection is built so the synchronous {@link dbName} always
+     * sees a populated index.
+     */
+    async ensureTestDatabaseClaimed() {
+        if (!this.runtimeNeedsTestDatabaseClaim)
+            return;
+        this.requireTestDatabaseClaimSupport();
+        await claimTestDatabase(this);
     }
     dbConnectionConfig(connectionName, connection) {
         const conf = this.dbCredentialsFor(connectionName)?.[connection] || this.dbCredentialsFor(connectionName)?.primary;
@@ -322,10 +374,57 @@ A new key can also be generated from the CLI:
     hasReplicaConfig(connectionName) {
         return !!this.dbCredentials[connectionName]?.replica;
     }
-    get parallelDatabasesEnabled() {
-        return (!!this.parallelTests &&
-            !Number.isNaN(Number(process.env.VITEST_POOL_ID)) &&
-            Number(process.env.VITEST_POOL_ID) > 1);
+    /**
+     * Whether the runtime *requires* a per-worker test-database claim. Gated on
+     * test env *under vitest* (not on `parallelTests > 1`): the slot-reuse
+     * collision reproduces even serially, because vitest respawns a process per
+     * file and the lingering process overlaps the new one on the same database.
+     * CLI db tasks (`db:migrate`, `db:reset`, …) do not run under vitest, so they
+     * keep the unsuffixed name and operate on the whole pool explicitly.
+     *
+     * This is independent of whether the default driver can actually claim — when
+     * the need is present but the capability is absent, the claim path fails loud
+     * (see {@link requireTestDatabaseClaimSupport}) rather than silently sharing
+     * one database.
+     */
+    get runtimeNeedsTestDatabaseClaim() {
+        return EnvInternal.isTest && runningUnderVitest();
+    }
+    /**
+     * Whether the default connection's query driver implements the per-worker
+     * test-database claim seam (`openTestDatabaseLockSession`). The claim is keyed
+     * off the **default** connection's capability so a Postgres-default app with a
+     * MySQL secondary keeps working (the secondary borrows the Postgres-claimed
+     * index for its database name).
+     */
+    get defaultConnectionSupportsParallelTestDatabases() {
+        return this.dbConnectionQueryDriverClass('default').supportsParallelTestDatabases;
+    }
+    /**
+     * Whether the per-worker test-database pool claim is active: needed by the
+     * runtime *and* supported by the default connection's driver. Consumers that
+     * key behavior off the claimed index (connection-cache suffixing) use this;
+     * the claim entry points additionally fail loud when the need is present but
+     * support is absent.
+     */
+    get testDatabaseClaimEnabled() {
+        return this.runtimeNeedsTestDatabaseClaim && this.defaultConnectionSupportsParallelTestDatabases;
+    }
+    /**
+     * Throw an actionable error when the runtime needs a per-worker test-database
+     * claim but the default connection's driver cannot provide one — rather than
+     * silently sharing a single database across overlapping vitest workers (which
+     * reintroduces the flake this whole mechanism exists to fix).
+     */
+    requireTestDatabaseClaimSupport() {
+        if (this.defaultConnectionSupportsParallelTestDatabases)
+            return;
+        const driverName = this.dbConnectionQueryDriverClass('default').name;
+        throw new Error(`[dream] running under vitest requires a per-worker test database, but the "default" connection's ` +
+            `query driver (${driverName}) does not support parallel test databases. Implement the claim seam ` +
+            `on that driver — set \`supportsParallelTestDatabases = true\` and override ` +
+            `\`openTestDatabaseLockSession\` (see PostgresQueryDriver / the test-app MysqlQueryDriver for ` +
+            `reference) — or do not run this adapter under vitest.`);
     }
     async load(resourceType, resourcePath, importCb) {
         switch (resourceType) {
@@ -436,6 +535,14 @@ function loggerArgToString(arg) {
     }
     return JSON.stringify(util.inspect(arg, { depth: 6 }));
 }
+/**
+ * Whether the current process is a vitest worker. vitest sets `VITEST=true` in
+ * every worker, and also exposes the per-worker `VITEST_POOL_ID` /
+ * `VITEST_WORKER_ID`. CLI db tasks run outside vitest, so this is false there.
+ */
+function runningUnderVitest() {
+    return process.env.VITEST === 'true' || process.env.VITEST_POOL_ID != null;
+}
 export const DreamAppAllowedPackageManagersEnumValues = ['pnpm', 'yarn', 'npm', 'bun', 'deno'];
 // GeneratorImportStyles are used by CLI generators to determine how
 // to style import suffixes. When integrating with other apps, this

package/dist/cjs/src/helpers/areEqual.js

@@ -4,7 +4,7 @@ import CalendarDate from '../utils/datetime/CalendarDate.js';
 import { DateTime } from '../utils/datetime/DateTime.js';
 /**
  * Performs a deep equality check between two values, supporting primitives, arrays,
- * Dream instances, CalendarDate, DateTime, and objects.
+ * Dream instances, CalendarDate, DateTime, ClockTime, ClockTimeTz, and objects.
  *
  * Examples:
  *   areEqual(undefined, undefined) // true

package/dist/cjs/src/helpers/loadRepl.js

@@ -2,6 +2,8 @@ import DreamApp from '../dream-app/index.js';
 import Encrypt from '../encrypt/index.js';
 import ops from '../ops/index.js';
 import CalendarDate from '../utils/datetime/CalendarDate.js';
+import ClockTime from '../utils/datetime/ClockTime.js';
+import ClockTimeTz from '../utils/datetime/ClockTimeTz.js';
 import { DateTime } from '../utils/datetime/DateTime.js';
 import camelize from './camelize.js';
 import capitalize from './capitalize.js';
@@ -19,6 +21,8 @@ import uniq from './uniq.js';
 export default async function loadRepl(context) {
     const dreamApp = DreamApp.getOrFail();
     context.CalendarDate = CalendarDate;
+    context.ClockTime = ClockTime;
+    context.ClockTimeTz = ClockTimeTz;
     context.DateTime = DateTime;
     context.Encrypt = Encrypt;
     context.camelize = camelize;

package/dist/cjs/src/helpers/range.js

@@ -9,7 +9,7 @@ export class Range {
         this.begin = begin;
         this.end = end;
         this.excludeEnd = excludeEnd;
-        if (!begin && !end)
+        if (begin == null && end == null)
             throw new Error('Must pass either begin or end to a range');
     }
 }

package/dist/esm/src/Dream.js

@@ -2020,10 +2020,10 @@ export default class Dream {
      * //       as: 'ratings',
      * //       polymorphic: true,
      * //       source: 'ratings',
-     * //       where: undefined,
-     * //       whereNot: undefined,
-     * //       selfWhere: undefined,
-     * //       selfWhereNot: undefined,
+     * //       and: undefined,
+     * //       andNot: undefined,
+     * //       selfAnd: undefined,
+     * //       selfAndNot: undefined,
      * //       primaryKeyOverride: null,
      * //       primaryKey: [Function: primaryKey],
      * //       primaryKeyValue: [Function: primaryKeyValue],

package/dist/esm/src/db/DreamDbConnection.js

@@ -8,6 +8,7 @@
 // @ts-ignore
 import { CamelCasePlugin, Kysely } from 'kysely';
 import DreamApp from '../dream-app/index.js';
+import { claimedTestDatabaseIndexOrNull } from './testDatabasePool.js';
 import protectAgainstPollutingAssignment from '../helpers/protectAgainstPollutingAssignment.js';
 import { installDbConnectionLeakDiagnosticsIfEnabled, reportLeakedDbConnections, } from './dbConnectionLeakDiagnostics.js';
 let connections = {};
@@ -39,9 +40,14 @@ export default class DreamDbConnection {
         return dbConn;
     }
     static getConnectionTypeName(connectionType) {
-        return DreamApp.getOrFail().parallelDatabasesEnabled
-            ? `${connectionType}_${process.env.VITEST_POOL_ID}`
-            : connectionType;
+        // The connection cache is per Node process (per vitest worker), and a worker
+        // only ever uses its single claimed pool index, so suffixing the cache key by
+        // that index keeps connections cached per claimed database without colliding
+        // across the (now process-scoped) registry.
+        if (!DreamApp.getOrFail().testDatabaseClaimEnabled)
+            return connectionType;
+        const index = claimedTestDatabaseIndexOrNull();
+        return index === null ? connectionType : `${connectionType}_${index}`;
     }
 }
 export function dreamDbConnections() {

package/dist/esm/src/db/dbConnectionLeakDiagnostics.js

@@ -41,21 +41,15 @@ function track(client, stack) {
     if (!client)
         return;
     checkedOutClients.set(client, { stack: stack ?? '(no stack captured)', since: Date.now() });
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const c = client;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     if (c.__dreamReleasePatched)
         return;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     const originalRelease = c.release;
     if (typeof originalRelease !== 'function')
         return;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     c.__dreamReleasePatched = true;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     c.release = function patchedRelease(...args) {
         checkedOutClients.delete(client);
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
         return originalRelease.apply(this, args);
     };
 }
@@ -67,34 +61,26 @@ export function installDbConnectionLeakDiagnosticsIfEnabled() {
     if (!dreamDebugEnabled)
         return;
     enabled = true;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
     const Pool = pg.Pool;
     if (!Pool?.prototype)
         return;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     if (Pool.prototype[INSTALLED])
         return;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     Pool.prototype[INSTALLED] = true;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment
     const originalConnect = Pool.prototype.connect;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     Pool.prototype.connect = function patchedConnect(cb) {
         const acquireStack = new Error('db connection acquired here').stack;
         if (typeof cb === 'function') {
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
             return originalConnect.call(this, (err, client, release) => {
                 track(client, acquireStack);
                 // `track()` replaces `client.release` with an untracking wrapper.
                 // Callback-style users call the 3rd `release` arg, which pg captured
                 // *before* that swap — so hand them the wrapped one instead, or a
                 // correctly-released client would be reported as a false leak.
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
                 const wrappedRelease = client ? client.release : release;
                 cb(err, client, wrappedRelease);
             });
         }
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
         return originalConnect.call(this).then((client) => {
             track(client, acquireStack);
             return client;

package/dist/esm/src/db/migration-helpers/DreamMigrationHelpers.js

@@ -1,4 +1,5 @@
 import { sql } from 'kysely';
+import InternalEncrypt from '../../encrypt/InternalEncrypt.js';
 export default class DreamMigrationHelpers {
     /**
      * Rename a table and its associated primary key index and sequence.
@@ -195,6 +196,136 @@ export default class DreamMigrationHelpers {
             }
         }
     }
+    /**
+     * Convert an existing plaintext column into the encrypted-backed form expected by
+     * the `@Encrypted` decorator.
+     *
+     * This renames `column` to `encrypted_<column>`, widens it to `text`, and rewrites
+     * every non-null value with the AES-GCM ciphertext produced by the exact same code
+     * path the decorator's setter uses (`InternalEncrypt.encryptColumn`). After it runs,
+     * the column holds real ciphertext that the decorator's getter can decrypt — which is
+     * what a bare column rename does **not** do (renaming a plaintext column to
+     * `encrypted_<column>` and decorating the property leaves plaintext in the column, so
+     * the getter throws `DecryptionError`).
+     *
+     * The encryption key and algorithm come from the application's encryption config
+     * (`DreamApp` `encryption.columns.current`); if encryption is not configured this
+     * throws `MissingColumnEncryptionOpts`. Null values are left null.
+     *
+     * Intended for text/string columns (the common case is text -> encrypted text). The
+     * column is widened to `text` before reading, so values are encrypted as their text
+     * form; the inverse `decryptColumn` can restore a non-text type via its `columnType`
+     * option.
+     *
+     * ```ts
+     * // plaintext `phone` column -> encrypted `encrypted_phone` text column
+     * await DreamMigrationHelpers.encryptColumn(db, { table: 'users', column: 'phone' })
+     * ```
+     *
+     * **Rewrites rows one at a time** (each value needs a fresh random IV computed in Node,
+     * so the rewrite cannot be a single SQL `UPDATE`), reading them in keyset batches of
+     * `batchSize` to bound memory. It still holds the table for the migration's duration; on
+     * very large tables do not use this helper — write your own batched / online migration.
+     *
+     * **Drop any index on the column first.** Per-row updates pay index-maintenance cost on
+     * every write, and an index over ciphertext is useless anyway (encrypted values are not
+     * queryable). Remove the index before this migration and do not re-add it.
+     *
+     * @param db - The Kysely database object passed into the migration up/down function
+     * @param options - Configuration options
+     * @param options.table - The name of the table
+     * @param options.column - The current (plaintext) column name
+     * @param options.encryptedColumnName - The target encrypted column name. Defaults to `encrypted_<column>`, matching the `@Encrypted` decorator's default; pass this when the decorator was given a custom encrypted column name.
+     * @param options.primaryKey - The primary key column used to keyset-paginate and target each row's update. Defaults to `id`.
+     * @param options.batchSize - How many rows to read per batch. Defaults to `1000`.
+     */
+    static async encryptColumn(db, { table, column, encryptedColumnName = `encrypted_${column}`, primaryKey = 'id', batchSize = 1000, }) {
+        await db.schema.alterTable(table).renameColumn(column, encryptedColumnName).execute();
+        await db.schema
+            .alterTable(table)
+            .alterColumn(encryptedColumnName, col => col.setDataType('text'))
+            .execute();
+        await this.transformColumnInBatches(db, { table, column: encryptedColumnName, primaryKey, batchSize }, value => InternalEncrypt.encryptColumn(value));
+    }
+    /**
+     * Inverse of {@link DreamMigrationHelpers.encryptColumn}: decrypt an
+     * `encrypted_<column>` column back to plaintext and rename it to `column`.
+     *
+     * Every non-null value is decrypted with the same path the decorator's getter uses
+     * (`InternalEncrypt.decryptColumn`, which honors both the `current` and `legacy`
+     * encryption keys), then the column is renamed back. Called with the same `table` and
+     * `column`, this exactly reverses `encryptColumn`.
+     *
+     * By default the column is left as `text`, because the original column type cannot be
+     * recovered from the encrypted state. Pass `columnType` to restore a specific type
+     * (e.g. `'integer'`); the conversion runs `ALTER COLUMN ... TYPE <columnType> USING
+     * <column>::<columnType>`.
+     *
+     * ```ts
+     * await DreamMigrationHelpers.decryptColumn(db, { table: 'users', column: 'phone' })
+     *
+     * // restore the original column type as part of the inverse
+     * await DreamMigrationHelpers.decryptColumn(db, { table: 'users', column: 'age', columnType: 'integer' })
+     * ```
+     *
+     * The same per-row, batched, table-locking caveat as `encryptColumn` applies.
+     *
+     * @param db - The Kysely database object passed into the migration up/down function
+     * @param options - Configuration options
+     * @param options.table - The name of the table
+     * @param options.column - The target (plaintext) column name to rename back to
+     * @param options.encryptedColumnName - The current encrypted column name. Defaults to `encrypted_<column>`.
+     * @param options.primaryKey - The primary key column used to keyset-paginate and target each row's update. Defaults to `id`.
+     * @param options.batchSize - How many rows to read per batch. Defaults to `1000`.
+     * @param options.columnType - When provided, the restored column is converted to this type. When omitted, the column is left as `text`.
+     */
+    static async decryptColumn(db, { table, column, encryptedColumnName = `encrypted_${column}`, primaryKey = 'id', batchSize = 1000, columnType, }) {
+        await this.transformColumnInBatches(db, { table, column: encryptedColumnName, primaryKey, batchSize }, value => InternalEncrypt.decryptColumn(value));
+        await db.schema.alterTable(table).renameColumn(encryptedColumnName, column).execute();
+        if (columnType !== undefined) {
+            await sql `
+        ALTER TABLE ${sql.table(table)}
+        ALTER COLUMN ${sql.ref(column)}
+        TYPE ${sql.raw(columnType)}
+        USING ${sql.ref(column)}::${sql.raw(columnType)};
+      `.execute(db);
+        }
+    }
+    /**
+     * Walk every non-null value of `column` in keyset batches of `batchSize`, applying
+     * `transform` in Node and writing the result back one row at a time. Keyset pagination
+     * on `primaryKey` (`WHERE pk > last ORDER BY pk`) bounds memory to a single batch and
+     * guarantees forward progress, so a row is never read — or transformed — twice (which
+     * matters because the transform is not idempotent: re-encrypting ciphertext would
+     * double-encrypt, and re-decrypting plaintext would throw).
+     *
+     * Reads alias the selected columns to fixed keys via `sql.ref(...).as(...)` so a
+     * `CamelCasePlugin` on the connection cannot rename the result keys.
+     */
+    static async transformColumnInBatches(db, { table, column, primaryKey, batchSize, }, transform) {
+        let lastPrimaryKey;
+        for (;;) {
+            let query = db
+                .selectFrom(table)
+                .select([sql.ref(primaryKey).as('pk'), sql.ref(column).as('val')])
+                .where(column, 'is not', null)
+                .orderBy(primaryKey)
+                .limit(batchSize);
+            if (lastPrimaryKey !== undefined)
+                query = query.where(primaryKey, '>', lastPrimaryKey);
+            const rows = await query.execute();
+            if (rows.length === 0)
+                break;
+            for (const row of rows) {
+                await db
+                    .updateTable(table)
+                    .set({ [column]: transform(row.val) })
+                    .where(primaryKey, '=', row.pk)
+                    .execute();
+                lastPrimaryKey = row.pk;
+            }
+        }
+    }
 }
 async function getEnumValues(db, enumName) {
     const response = await sql `SELECT unnest(enum_range(NULL::${sql.raw(enumName)}))`.execute(db);