@cipherstash/migrate 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# @cipherstash/migrate
+
+## 0.2.0
+
+### Minor Changes
+
+- add4357: Add `stash encrypt` command group and `@cipherstash/migrate` library for plaintext → encrypted column migrations.
+
+  New CLI commands:
+
+  - `stash encrypt status` — per-column migration status (phase, backfill progress, drift between intent and state, EQL registration).
+  - `stash encrypt plan` — diff `.cipherstash/migrations.json` (intent) vs observed state.
+  - `stash encrypt backfill --table <t> --column <c>` — resumable, idempotent, chunked encryption of plaintext into `<col>_encrypted`. Uses the user's encryption client (Protect/Stack). SIGINT-safe; re-run to resume. The first run on a column prompts to confirm dual-writes are deployed (or accept `--confirm-dual-writes-deployed` for non-interactive contexts), records the `dual_writing` transition in `cs_migrations`, then runs the chunked encryption loop. `--force` re-encrypts every plaintext row regardless of current state — recovery path for drift caused by an earlier backfill running before dual-writes were actually live.
+  - `stash encrypt cutover --table <t> --column <c>` — runs `eql_v2.rename_encrypted_columns()` inside a transaction; optionally forces Proxy config refresh via `CIPHERSTASH_PROXY_URL`. After cutover, apps reading `<col>` transparently receive the encrypted column.
+  - `stash encrypt drop --table <t> --column <c>` — generates a migration file that drops the old plaintext column.
+
+  `stash db install` now also installs a `cipherstash.cs_migrations` table used to track per-column migration runtime state (current phase, backfill cursor, rows processed). The table is append-only (event-log shape) and kept separate from `eql_v2_configuration` which remains the authoritative EQL intent store used by Proxy.
+
+  The new `@cipherstash/migrate` package exposes the same primitives as a library for users who want to embed backfill in their own workers or cron jobs — all commands are thin wrappers around its exports (`runBackfill`, `appendEvent`, `latestByColumn`, `progress`, `renameEncryptedColumns`, `reloadConfig`, `readManifest`, `writeManifest`).

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CipherStash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @cipherstash/migrate
+
+Primitives for migrating existing plaintext columns to CipherStash's `eql_v2_encrypted` in production Postgres databases, safely and resumably.
+
+Backs the `stash encrypt` CLI command group, but also exported for direct use — embed `runBackfill()` in your own worker or cron job when you'd rather not pipe gigabytes through a CLI process.
+
+## Lifecycle
+
+Each column walks through these phases:
+
+```
+schema-added → dual-writing → backfilling → backfilled → cut-over → dropped
+```
+
+State is tracked in an append-only `cipherstash.cs_migrations` table installed by `stash db install`. The EQL intent (which indexes, which cast_as) continues to live in `eql_v2_configuration` so Proxy continues to work against the same database.
+
+## API
+
+```ts
+import {
+  installMigrationsSchema,
+  appendEvent,
+  latestByColumn,
+  progress,
+  runBackfill,
+  renameEncryptedColumns,
+  reloadConfig,
+  readManifest,
+  writeManifest,
+} from '@cipherstash/migrate'
+```
+
+### `installMigrationsSchema(client)`
+
+Creates `cipherstash.cs_migrations` idempotently. Normally called by `stash db install`.
+
+### `runBackfill({ db, encryptionClient, tableSchema, tableName, plaintextColumn, encryptedColumn, pkColumn, schemaColumnKey, chunkSize?, signal?, onProgress? })`
+
+Chunked, resumable, idempotent backfill of plaintext → encrypted. Per chunk, in a single transaction: select next page → encrypt via `client.bulkEncryptModels` → `UPDATE … FROM (VALUES …)` → `INSERT` a `backfill_checkpoint` event. Guards with `encrypted IS NULL` so re-runs never double-write.
+
+- `db`: a `pg.PoolClient` (the runner drives transactions on it).
+- `encryptionClient`: your initialised `@cipherstash/stack` `EncryptionClient` (or anything that exposes `bulkEncryptModels(models, table)` returning `{ data } | { failure }`).
+- `tableSchema`: the `EncryptedTable` for the target table from your encryption client file.
+- `signal`: optional `AbortSignal`. If aborted between chunks, the backfill exits cleanly and leaves a resumable checkpoint.
+
+Returns `{ resumed, rowsProcessed, rowsTotal, completed }`.
+
+### `appendEvent(client, { tableName, columnName, event, phase, … })` / `progress(client, table, column)` / `latestByColumn(client)`
+
+Direct access to the `cs_migrations` event log. Use these if you're building your own migration UI or orchestration on top.
+
+### `renameEncryptedColumns(client)` / `reloadConfig(client)`
+
+Thin wrappers around `eql_v2.rename_encrypted_columns()` (the cut-over primitive) and `eql_v2.reload_config()` (Proxy refresh hint — no-op when connected directly to Postgres).
+
+### `readManifest(cwd)` / `writeManifest(manifest, cwd)`
+
+Read/write `.cipherstash/migrations.json` — the repo-side intent declaration. Zod-validated. The manifest is optional; commands work without it but you lose the `plan` diff.
+
+## Drop-in usage in a BullMQ/Inngest worker
+
+```ts
+import pg from 'pg'
+import { runBackfill } from '@cipherstash/migrate'
+import { encryptionClient, usersTable } from './src/encryption/index.js'
+
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
+
+export async function handler({ signal }: { signal: AbortSignal }) {
+  const db = await pool.connect()
+  try {
+    return await runBackfill({
+      db,
+      encryptionClient,
+      tableSchema: usersTable,
+      tableName: 'users',
+      schemaColumnKey: 'email',
+      plaintextColumn: 'email',
+      encryptedColumn: 'email_encrypted',
+      pkColumn: 'id',
+      chunkSize: 2000,
+      signal,
+      onProgress: (p) => console.log(`${p.rowsProcessed}/${p.rowsTotal}`),
+    })
+  } finally {
+    db.release()
+  }
+}
+```

package/dist/index.cjs

@@ -0,0 +1,524 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MIGRATIONS_SCHEMA_SQL: () => MIGRATIONS_SCHEMA_SQL,
+  activateConfig: () => activateConfig,
+  appendEvent: () => appendEvent,
+  countEncryptedWithActiveConfig: () => countEncryptedWithActiveConfig,
+  countUnencrypted: () => countUnencrypted,
+  discardPendingConfig: () => discardPendingConfig,
+  fetchUnencryptedPage: () => fetchUnencryptedPage,
+  installMigrationsSchema: () => installMigrationsSchema,
+  latestByColumn: () => latestByColumn,
+  manifestPath: () => manifestPath,
+  migrateConfig: () => migrateConfig,
+  progress: () => progress,
+  qualifyTable: () => qualifyTable,
+  quoteIdent: () => quoteIdent,
+  readManifest: () => readManifest,
+  readyForEncryption: () => readyForEncryption,
+  reloadConfig: () => reloadConfig,
+  renameEncryptedColumns: () => renameEncryptedColumns,
+  runBackfill: () => runBackfill,
+  selectPendingColumns: () => selectPendingColumns,
+  setManifestTargetPhase: () => setManifestTargetPhase,
+  upsertManifestColumn: () => upsertManifestColumn,
+  writeManifest: () => writeManifest
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/install.ts
+var MIGRATIONS_SCHEMA_SQL = `
+CREATE SCHEMA IF NOT EXISTS cipherstash;
+
+CREATE TABLE IF NOT EXISTS cipherstash.cs_migrations (
+  id             bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  table_name     text NOT NULL,
+  column_name    text NOT NULL,
+  event          text NOT NULL,
+  phase          text NOT NULL,
+  cursor_value   text,
+  rows_processed bigint,
+  rows_total     bigint,
+  details        jsonb,
+  created_at     timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS cs_migrations_column_id_desc
+  ON cipherstash.cs_migrations (table_name, column_name, id DESC);
+`;
+async function installMigrationsSchema(client) {
+  await client.query(MIGRATIONS_SCHEMA_SQL);
+}
+
+// src/state.ts
+async function appendEvent(client, input) {
+  const result = await client.query(
+    `INSERT INTO cipherstash.cs_migrations
+      (table_name, column_name, event, phase, cursor_value, rows_processed, rows_total, details)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+     RETURNING id, table_name, column_name, event, phase, cursor_value, rows_processed, rows_total, details, created_at`,
+    [
+      input.tableName,
+      input.columnName,
+      input.event,
+      input.phase,
+      input.cursorValue ?? null,
+      input.rowsProcessed ?? null,
+      input.rowsTotal ?? null,
+      input.details ?? null
+    ]
+  );
+  return rowToState(result.rows[0]);
+}
+async function latestByColumn(client) {
+  const result = await client.query(
+    `SELECT DISTINCT ON (table_name, column_name)
+       id, table_name, column_name, event, phase, cursor_value, rows_processed, rows_total, details, created_at
+     FROM cipherstash.cs_migrations
+     ORDER BY table_name, column_name, id DESC`
+  );
+  const map = /* @__PURE__ */ new Map();
+  for (const row of result.rows) {
+    const state = rowToState(row);
+    map.set(`${state.tableName}.${state.columnName}`, state);
+  }
+  return map;
+}
+async function progress(client, tableName, columnName) {
+  const result = await client.query(
+    `SELECT id, table_name, column_name, event, phase, cursor_value, rows_processed, rows_total, details, created_at
+     FROM cipherstash.cs_migrations
+     WHERE table_name = $1 AND column_name = $2
+     ORDER BY id DESC
+     LIMIT 1`,
+    [tableName, columnName]
+  );
+  if (result.rows.length === 0) return null;
+  return rowToState(result.rows[0]);
+}
+function rowToState(row) {
+  return {
+    id: String(row.id),
+    tableName: row.table_name,
+    columnName: row.column_name,
+    event: row.event,
+    phase: row.phase,
+    cursorValue: row.cursor_value,
+    rowsProcessed: row.rows_processed === null ? null : Number(row.rows_processed),
+    rowsTotal: row.rows_total === null ? null : Number(row.rows_total),
+    details: row.details,
+    createdAt: row.created_at
+  };
+}
+
+// src/eql.ts
+async function selectPendingColumns(client) {
+  const result = await client.query("SELECT table_name, column_name FROM eql_v2.select_pending_columns()");
+  return result.rows.map((row) => ({
+    tableName: row.table_name,
+    columnName: row.column_name
+  }));
+}
+async function readyForEncryption(client) {
+  const result = await client.query(
+    "SELECT eql_v2.ready_for_encryption() AS ready"
+  );
+  return result.rows[0]?.ready === true;
+}
+async function renameEncryptedColumns(client) {
+  await client.query("SELECT eql_v2.rename_encrypted_columns()");
+}
+async function migrateConfig(client) {
+  await client.query("SELECT eql_v2.migrate_config()");
+}
+async function activateConfig(client) {
+  await client.query("SELECT eql_v2.activate_config()");
+}
+async function discardPendingConfig(client) {
+  await client.query(
+    "DELETE FROM public.eql_v2_configuration WHERE state = 'pending'"
+  );
+}
+async function reloadConfig(client) {
+  await client.query("SELECT eql_v2.reload_config()");
+}
+async function countEncryptedWithActiveConfig(client, tableName, columnName) {
+  const result = await client.query(
+    "SELECT eql_v2.count_encrypted_with_active_config($1, $2) AS count",
+    [tableName, columnName]
+  );
+  return BigInt(result.rows[0]?.count ?? "0");
+}
+
+// src/sql.ts
+function quoteIdent(identifier) {
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+
+// src/cursor.ts
+async function fetchUnencryptedPage(client, opts) {
+  const pk = quoteIdent(opts.pkColumn);
+  const plain = quoteIdent(opts.plaintextColumn);
+  const enc = quoteIdent(opts.encryptedColumn);
+  const table = qualifyTable(opts.tableName);
+  const params = [];
+  let where = opts.force ? `${plain} IS NOT NULL` : `${plain} IS NOT NULL AND ${enc} IS NULL`;
+  if (opts.after !== null) {
+    params.push(opts.after);
+    where += ` AND ${pk} > $${params.length}`;
+  }
+  params.push(opts.limit);
+  const limitParam = `$${params.length}`;
+  const sql = `
+    SELECT ${pk}::text AS pk, ${plain} AS plaintext
+    FROM ${table}
+    WHERE ${where}
+    ORDER BY ${pk} ASC
+    LIMIT ${limitParam}
+  `;
+  const result = await client.query(
+    sql,
+    params
+  );
+  const rows = result.rows;
+  const lastPk = rows.length > 0 ? rows[rows.length - 1]?.pk : null;
+  return { rows, lastPk };
+}
+async function countUnencrypted(client, tableName, plaintextColumn, encryptedColumn, force = false) {
+  const plain = quoteIdent(plaintextColumn);
+  const enc = quoteIdent(encryptedColumn);
+  const table = qualifyTable(tableName);
+  const where = force ? `${plain} IS NOT NULL` : `${plain} IS NOT NULL AND ${enc} IS NULL`;
+  const result = await client.query(
+    `SELECT count(*)::text AS count FROM ${table} WHERE ${where}`
+  );
+  return Number(result.rows[0]?.count ?? 0);
+}
+function qualifyTable(tableName) {
+  if (tableName.includes(".")) {
+    const parts = tableName.split(".");
+    return parts.map(quoteIdent).join(".");
+  }
+  return quoteIdent(tableName);
+}
+
+// src/backfill.ts
+var import_stack = require("@cipherstash/stack");
+async function runBackfill(options) {
+  const chunkSize = options.chunkSize ?? 1e3;
+  const { db, tableName, pkColumn, plaintextColumn, encryptedColumn } = options;
+  const force = options.force ?? false;
+  const rowsTotal = await countUnencrypted(
+    db,
+    tableName,
+    plaintextColumn,
+    encryptedColumn,
+    force
+  );
+  const last = await progress(db, tableName, plaintextColumn);
+  const resumeCursor = last?.event === "backfill_checkpoint" ? last.cursorValue : null;
+  const resumed = resumeCursor !== null;
+  const priorProcessed = last?.event === "backfill_checkpoint" ? last.rowsProcessed ?? 0 : 0;
+  await appendEvent(db, {
+    tableName,
+    columnName: plaintextColumn,
+    event: "backfill_started",
+    phase: "backfilling",
+    cursorValue: resumeCursor,
+    rowsProcessed: priorProcessed,
+    rowsTotal: priorProcessed + rowsTotal,
+    details: { chunkSize, resumed, ...force ? { force: true } : {} }
+  });
+  let cursor = resumeCursor;
+  let rowsProcessed = priorProcessed;
+  const rowsTotalWithResumed = priorProcessed + rowsTotal;
+  let chunkIndex = 0;
+  let completed = false;
+  try {
+    while (true) {
+      if (options.signal?.aborted) break;
+      const page = await fetchUnencryptedPage(db, {
+        tableName,
+        pkColumn,
+        plaintextColumn,
+        encryptedColumn,
+        after: cursor,
+        limit: chunkSize,
+        force
+      });
+      if (page.rows.length === 0) {
+        completed = true;
+        break;
+      }
+      const coerce = options.transformPlaintext ?? ((v) => v);
+      const models = page.rows.map((row) => ({
+        __pk: row.pk,
+        [options.schemaColumnKey]: coerce(row.plaintext)
+      }));
+      const encryptResult = await options.encryptionClient.bulkEncryptModels(
+        models,
+        options.tableSchema
+      );
+      if (encryptResult.failure) {
+        throw new Error(
+          `bulkEncryptModels failed: ${encryptResult.failure.message}`
+        );
+      }
+      for (const [i, row] of encryptResult.data.entries()) {
+        const value = row[options.schemaColumnKey];
+        if (!(0, import_stack.isEncryptedPayload)(value)) {
+          const pk = row.__pk ?? page.rows[i]?.pk;
+          const valueType = value === null ? "null" : typeof value;
+          throw new Error(
+            `Encryption client returned a non-ciphertext value (type: ${valueType}) at model key "${options.schemaColumnKey}" for pk=${pk}. This usually means the schema column key does not match your EncryptedTable. Verify that your schema declares a column keyed "${options.schemaColumnKey}", or pass --schema-column-key <name> to override.`
+          );
+        }
+      }
+      await db.query("BEGIN");
+      try {
+        await writeEncryptedChunk(db, {
+          tableName,
+          pkColumn,
+          encryptedColumn,
+          schemaColumnKey: options.schemaColumnKey,
+          encryptedRows: encryptResult.data,
+          force
+        });
+        rowsProcessed += page.rows.length;
+        cursor = page.lastPk;
+        await appendEvent(db, {
+          tableName,
+          columnName: plaintextColumn,
+          event: "backfill_checkpoint",
+          phase: "backfilling",
+          cursorValue: cursor,
+          rowsProcessed,
+          rowsTotal: rowsTotalWithResumed,
+          details: { chunkIndex, chunkRows: page.rows.length }
+        });
+        await db.query("COMMIT");
+      } catch (err) {
+        await db.query("ROLLBACK").catch(() => {
+        });
+        throw err;
+      }
+      options.onProgress?.({
+        rowsProcessed,
+        rowsTotal: rowsTotalWithResumed,
+        lastPk: cursor,
+        chunkSize,
+        chunkIndex
+      });
+      chunkIndex += 1;
+    }
+    if (completed) {
+      await appendEvent(db, {
+        tableName,
+        columnName: plaintextColumn,
+        event: "backfilled",
+        phase: "backfilled",
+        cursorValue: cursor,
+        rowsProcessed,
+        rowsTotal: rowsTotalWithResumed,
+        details: { chunkCount: chunkIndex }
+      });
+    }
+  } catch (err) {
+    await appendEvent(db, {
+      tableName,
+      columnName: plaintextColumn,
+      event: "error",
+      phase: "backfilling",
+      cursorValue: cursor,
+      rowsProcessed,
+      rowsTotal: rowsTotalWithResumed,
+      details: {
+        message: err instanceof Error ? err.message : String(err),
+        chunkIndex
+      }
+    });
+    throw err;
+  }
+  return {
+    resumed,
+    rowsProcessed,
+    rowsTotal: rowsTotalWithResumed,
+    completed
+  };
+}
+async function writeEncryptedChunk(db, opts) {
+  if (opts.encryptedRows.length === 0) return;
+  const table = qualifyTable(opts.tableName);
+  const pk = quoteIdent(opts.pkColumn);
+  const enc = quoteIdent(opts.encryptedColumn);
+  const params = [];
+  const valuesSql = opts.encryptedRows.map((row) => {
+    const pkValue = row.__pk;
+    const encryptedValue = row[opts.schemaColumnKey];
+    params.push(pkValue);
+    const pkParam = `$${params.length}`;
+    params.push(encryptedValue);
+    const encParam = `$${params.length}::jsonb`;
+    return `(${pkParam}, ${encParam})`;
+  }).join(", ");
+  const where = opts.force ? `t.${pk}::text = v.pk::text` : `t.${pk}::text = v.pk::text AND t.${enc} IS NULL`;
+  const sql = `
+    UPDATE ${table} AS t
+    SET ${enc} = v.enc
+    FROM (VALUES ${valuesSql}) AS v(pk, enc)
+    WHERE ${where}
+  `;
+  await db.query(sql, params);
+}
+
+// src/manifest.ts
+var fs = __toESM(require("fs/promises"), 1);
+var path = __toESM(require("path"), 1);
+var import_zod = require("zod");
+var IndexKind = import_zod.z.enum(["unique", "match", "ore", "ste_vec"]);
+var CastAs = import_zod.z.enum([
+  "text",
+  "int",
+  "small_int",
+  "big_int",
+  "real",
+  "double",
+  "boolean",
+  "date",
+  "jsonb",
+  "json",
+  "float",
+  "decimal",
+  "timestamp"
+]);
+var ManifestColumnSchema = import_zod.z.object({
+  /** Physical column name, e.g. `email`. */
+  column: import_zod.z.string(),
+  /**
+   * EQL cast type. Text by default. See the EQL docs for the full list
+   * (`text | int | small_int | big_int | real | double | boolean | date |
+   * jsonb | json | float | decimal | timestamp`).
+   */
+  castAs: CastAs.default("text"),
+  /** Desired EQL index set. Driver of the `indexes: {…}` block in EQL config. */
+  indexes: import_zod.z.array(IndexKind).default([]),
+  /**
+   * The phase the user wants this column to reach. `cut-over` is the
+   * typical end state (reads transparently decrypted); advance to
+   * `dropped` only once you're confident the plaintext column is no
+   * longer needed.
+   */
+  targetPhase: import_zod.z.enum(["schema-added", "dual-writing", "backfilled", "cut-over", "dropped"]).default("cut-over"),
+  /**
+   * Override for primary-key detection during backfill. Omit to let the
+   * CLI auto-detect via `information_schema`.
+   */
+  pkColumn: import_zod.z.string().optional()
+});
+var ManifestSchema = import_zod.z.object({
+  version: import_zod.z.literal(1).default(1),
+  /** Map of table name → array of column intents for that table. */
+  tables: import_zod.z.record(import_zod.z.array(ManifestColumnSchema))
+});
+function manifestPath(cwd = process.cwd()) {
+  return path.join(cwd, ".cipherstash", "migrations.json");
+}
+async function readManifest(cwd = process.cwd()) {
+  const filePath = manifestPath(cwd);
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+  const parsed = ManifestSchema.parse(JSON.parse(raw));
+  return parsed;
+}
+async function writeManifest(manifest, cwd = process.cwd()) {
+  const filePath = manifestPath(cwd);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const validated = ManifestSchema.parse(manifest);
+  await fs.writeFile(
+    filePath,
+    `${JSON.stringify(validated, null, 2)}
+`,
+    "utf-8"
+  );
+}
+async function upsertManifestColumn(table, column, cwd = process.cwd()) {
+  const existing = await readManifest(cwd) ?? { version: 1, tables: {} };
+  const tableColumns = existing.tables[table] ?? [];
+  const remaining = tableColumns.filter((c) => c.column !== column.column);
+  existing.tables[table] = [...remaining, column];
+  await writeManifest(existing, cwd);
+}
+async function setManifestTargetPhase(table, columnName, targetPhase, cwd = process.cwd()) {
+  const existing = await readManifest(cwd);
+  if (!existing) return;
+  const tableColumns = existing.tables[table];
+  if (!tableColumns) return;
+  const current = tableColumns.find((c) => c.column === columnName);
+  if (!current) return;
+  existing.tables[table] = tableColumns.map(
+    (c) => c.column === columnName ? { ...c, targetPhase } : c
+  );
+  await writeManifest(existing, cwd);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MIGRATIONS_SCHEMA_SQL,
+  activateConfig,
+  appendEvent,
+  countEncryptedWithActiveConfig,
+  countUnencrypted,
+  discardPendingConfig,
+  fetchUnencryptedPage,
+  installMigrationsSchema,
+  latestByColumn,
+  manifestPath,
+  migrateConfig,
+  progress,
+  qualifyTable,
+  quoteIdent,
+  readManifest,
+  readyForEncryption,
+  reloadConfig,
+  renameEncryptedColumns,
+  runBackfill,
+  selectPendingColumns,
+  setManifestTargetPhase,
+  upsertManifestColumn,
+  writeManifest
+});
+//# sourceMappingURL=index.cjs.map