turbine-orm 0.77.1 → 0.78.0

package/dist/cli/migrate.js

@@ -16,8 +16,9 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { join } from 'node:path';
 import pg from 'pg';
 import { postgresql } from '../adapters/index.js';
+import { isPlainSchemaIdentifier, parseSearchPathValue, withSearchPathOption } from '../connection-url.js';
 import { postgresDialect } from '../dialect.js';
-import { MigrationError } from '../errors.js';
+import { MigrationError, ValidationError } from '../errors.js';
 import { DESTRUCTIVE_KIND_LABEL, scanDestructiveSql } from './destructive.js';
 import { splitSqlStatements, tokenizeSql } from './sql-statements.js';
 /**
@@ -155,6 +156,39 @@ async function getAppliedMigrations(client, dialect = postgresDialect) {
     const result = await client.query(dialect.buildMigrationSelectApplied(quotedTrackingTable(dialect)));
     return result.rows;
 }
+/**
+ * The applied rows for a READ-ONLY caller: existence is TESTED, never created.
+ *
+ * `migrate status` used to reach the tracking table through
+ * {@link ensureTrackingTable}, which issues `CREATE TABLE IF NOT EXISTS`
+ * unconditionally. PostgreSQL checks the CREATE privilege on the schema BEFORE
+ * the `IF NOT EXISTS` short-circuit, so a read-only role got `permission denied
+ * for schema public` and a CI "is production up to date?" check could not run
+ * as one. A report must not need write rights to say what it can see: an
+ * absent table means "no migration has been applied here", which is the honest
+ * answer and the one `up` will act on.
+ *
+ * @internal exported for tests.
+ */
+export async function readAppliedMigrations(client, dialect = postgresDialect) {
+    // Asked of the schema the tracking table would be CREATED in, not of the
+    // whole search_path. Since a pin EXTENDS the caller's path
+    // (`connectionStringForSchema`), a bare `to_regclass('_turbine_migrations')`
+    // matches the FIRST such table anywhere on it, so a project moving to
+    // `schema: 'app'` with an old `public._turbine_migrations` still around read
+    // public's rows and reported them as app's. `ensureTrackingTable` has no such
+    // ambiguity: `CREATE TABLE IF NOT EXISTS` tests the CREATION target, which is
+    // `current_schema()`, and creates there even when the name is visible further
+    // down the path (measured). So this asks the writer's question. When it says
+    // present, the unqualified SELECT below resolves to that same table:
+    // `current_schema()` is the first EXISTING entry, and a table there shadows
+    // any later one.
+    const present = await client.query(`SELECT to_regclass(quote_ident(current_schema()) || '.' || quote_ident(${dialect.paramPlaceholder(1)})) IS NOT NULL AS present`, [TRACKING_TABLE]);
+    if (present.rows[0]?.present !== true)
+        return { applied: [], trackingTableExists: false };
+    const result = await client.query(dialect.buildMigrationSelectApplied(quotedTrackingTable(dialect)));
+    return { applied: result.rows, trackingTableExists: true };
+}
 // ---------------------------------------------------------------------------
 // File operations
 // ---------------------------------------------------------------------------
@@ -244,6 +278,21 @@ export function listMigrationFiles(migrationsDir) {
     }
     return files;
 }
+/**
+ * `.sql` files in `migrationsDir` that the runner NEVER sees, because their
+ * name lacks the `YYYYMMDDHHMMSS_<name>.sql` shape {@link listMigrationFiles}
+ * requires (a hand-written `add_thing.sql`, a 13-digit prefix). Such a file
+ * used to be skipped in silence by `status`, `up` and `deploy` alike, so a
+ * misnamed migration simply never ran and nothing said so. The CLI prints one
+ * warning per entry.
+ */
+export function listIgnoredSqlFiles(migrationsDir) {
+    if (!existsSync(migrationsDir))
+        return [];
+    return readdirSync(migrationsDir)
+        .filter((f) => f.endsWith('.sql') && parseMigrationFilename(f) === null)
+        .sort();
+}
 /**
  * The `-- turbine:no-transaction` directive: when present in a migration's
  * header (before `-- UP`), the runner applies the file WITHOUT wrapping it in
@@ -664,11 +713,156 @@ export function deriveLockId(databaseName) {
  * Fetch the current database name from the connected client. Used to derive
  * the advisory lock ID so concurrent migrations in sibling databases do not
  * contend on one another.
+ *
+ * Asked of `current_database()` and NOT parsed out of the connection string:
+ * the string may carry no path at all (a `PGDATABASE` environment default, a
+ * service file, a `.pgpass` entry), and a lock id derived from an empty name
+ * would put every such database on ONE lock. The empty-string fallback is the
+ * same hazard one step further in, so it is here to be seen rather than to be
+ * relied on.
+ *
+ * @internal exported for tests. `deriveLockId` is tested for stability and for
+ * staying inside the positive int4 range; this is the value it is given, and an
+ * untested input to a tested function is an untested pair.
  */
-async function getCurrentDatabaseName(client) {
+export async function getCurrentDatabaseName(client) {
     const result = await client.query(`SELECT current_database()`);
     return result.rows[0]?.current_database ?? '';
 }
+/**
+ * The connection string the migration runner (and `turbine seed`) connects
+ * with for a configured schema: unchanged for the default, pinned otherwise.
+ *
+ * "Not configured" emits NOTHING: with no `schema` at all the role's own
+ * search_path decides, as it always has. A CONFIGURED schema is applied as the
+ * `options=-c search_path=...` startup parameter through
+ * {@link withSearchPathOption}, never as a `SET`, so the migration's own DDL,
+ * its `_turbine_migrations` tracking table, and the lock connection all resolve
+ * unqualified names in the schema the rest of the CLI (`push`, `generate`,
+ * `doctor`, Studio) already reads. Before this the runner had no schema at all,
+ * and a code-first project on `schema: 'app'` pushed its tables into `app`,
+ * diffed against `app`, and then applied the resulting migration into `public`.
+ *
+ * `public` is pinned like any other name, and used to be exempted on the
+ * reasoning that it is the default anyway. It is not: `search_path` is a
+ * role/database/connection-string setting, so on a role whose path is
+ * `app, public` a project configured `schema: 'public'` had `push` creating in
+ * `public` (its own pin is unconditional) while `migrate up` created in `app`.
+ * That is the same split this function exists to close, reintroduced for the
+ * one schema most projects actually use. `schema-sql.ts`'s `pinSearchPath` is
+ * the other half of the rule and the two now answer identically: pin
+ * unconditionally, and EXTEND the caller's path rather than replace it. The
+ * extension is why `inheritedSchemas` exists, since a startup parameter cannot
+ * read the path it is about to override; {@link connectMigrationClient} probes
+ * for it. Left empty, the emitted parameter is byte-identical to before.
+ *
+ * The helper is a pure leaf and returns `null` for a name it cannot emit safely
+ * or a string it cannot rewrite; here each becomes the E003 the rest of the CLI
+ * raises for a bad configured value, because a connection parameter is a
+ * literal and a name that can carry a space can carry a second `-c`.
+ *
+ * @internal exported for the seed runner and tests.
+ */
+/**
+ * Refuse a configured schema NAME the CLI cannot emit into a connection
+ * parameter, before anything opens a connection with it.
+ *
+ * Separate from {@link assertSchemaExists}, and it has to run FIRST: they answer
+ * different questions and only one of them has a useful answer for a name like
+ * `bad name`. Asking the catalog first reports "schema does not exist" and
+ * suggests `CREATE SCHEMA "bad name"`, which is true and useless; the real
+ * problem is that a value carrying whitespace cannot go into `options=-c` at
+ * all, because libpq splits that parameter on spaces and a second `-c` would
+ * set any GUC it liked.
+ *
+ * @internal exported for tests.
+ */
+export function assertPinnableSchema(schema) {
+    if (isPlainSchemaIdentifier(schema))
+        return;
+    throw new ValidationError(`Cannot pin search_path to "${schema}": a schema name used as a connection parameter must be a plain ` +
+        `identifier (letters, digits, "_" and "$", not starting with a digit).`);
+}
+export function connectionStringForSchema(connectionString, schema, inheritedSchemas = []) {
+    if (schema === undefined || schema === '')
+        return connectionString;
+    assertPinnableSchema(schema);
+    const pinned = withSearchPathOption(connectionString, schema, inheritedSchemas);
+    if (pinned === null) {
+        throw new ValidationError('Cannot pin search_path on a connection string that is not a URL (expected postgres://... or postgresql://...).');
+    }
+    return pinned;
+}
+/**
+ * Refuse a configured schema that does not exist in this database.
+ *
+ * Postgres does not validate `search_path`: pinning it to a namespace that does
+ * not exist succeeds, and the first unqualified statement then fails with
+ * `relation "..." does not exist` or "no schema has been selected to create in",
+ * neither of which names the schema or the setting that caused it. This is the
+ * ONE place that question is asked, and it is asked of the CATALOG
+ * (`to_regnamespace`, bound as a parameter) rather than of the connection's own
+ * resolved `current_schema()`, so it gives the same answer whether the client
+ * calling it is pinned or not. That is what lets `turbine seed` use it: the seed
+ * runs its callback in a child process and could not have been checked through
+ * the pin at all.
+ *
+ * @internal exported for the seed runner and tests.
+ */
+export async function assertSchemaExists(client, schema) {
+    const present = await client.query('SELECT to_regnamespace($1) IS NOT NULL AS present', [
+        schema,
+    ]);
+    if (present.rows[0]?.present === true)
+        return;
+    throw new MigrationError(`Schema "${schema}" does not exist in this database. ` +
+        `Postgres accepts a missing namespace in search_path without complaint, so running anyway would ` +
+        `fail on the first unqualified statement with a message that names neither. ` +
+        `Create the schema first (CREATE SCHEMA "${schema}"), or correct the schema name in turbine.config.ts ` +
+        `(or the --schema flag).`);
+}
+/**
+ * Open the runner's primary connection for `schema`, and hand back the string
+ * the second (lock-only) connection must use too.
+ *
+ * TWO connections are opened when a schema is configured, and the first one is
+ * not an accident. A `search_path` startup parameter is in force before the
+ * connection's first statement, which is exactly what makes it safe (it cannot
+ * leak onto a pooled backend the way a `SET` does) and exactly what stops it
+ * reading the path it is about to override. So the probe connects with the
+ * caller's string untouched, asks the two questions that need the caller's own
+ * view (does the schema exist, and what does this connection resolve through),
+ * and closes; the real connection is then pinned to the target FOLLOWED BY what
+ * the probe saw. Without the second half, pinning breaks any migration that
+ * names an extension type unqualified, because `citext` / `vector` / `postgis`
+ * live in a schema the pin had discarded.
+ */
+async function connectMigrationClient(connectionString, schema) {
+    const inherited = schema === undefined || schema === '' ? [] : await probeConnectionSchemas(connectionString, schema);
+    const pinned = connectionStringForSchema(connectionString, schema, inherited);
+    const client = new pg.Client({ connectionString: pinned });
+    await client.connect();
+    return { client, connectionString: pinned };
+}
+/**
+ * Ask an UNPINNED connection the two questions a pin cannot answer for itself,
+ * and close it again.
+ */
+async function probeConnectionSchemas(connectionString, schema) {
+    // Before the connection, not after: a name that cannot be pinned has to say
+    // so in those terms, see assertPinnableSchema.
+    assertPinnableSchema(schema);
+    const probe = new pg.Client({ connectionString });
+    await probe.connect();
+    try {
+        await assertSchemaExists(probe, schema);
+        const shown = await probe.query('SHOW search_path');
+        return parseSearchPathValue(shown.rows[0]?.search_path ?? '');
+    }
+    finally {
+        await probe.end();
+    }
+}
 /** Open the second, lock-only connection. Separated so tests can fake it. */
 async function openLockConnection(connectionString) {
     const client = new pg.Client({ connectionString });
@@ -768,6 +962,24 @@ export async function runMigrationInTransaction(client, body, tracking) {
         return err instanceof Error ? err.message : String(err);
     }
 }
+/**
+ * Which of `pending` would be applied out of timestamp order, given `applied`.
+ *
+ * The rule `migrateUp` applies, extracted so the dry run cannot drift from it.
+ *
+ * @internal exported for tests.
+ */
+export function predictOutOfOrder(applied, pending) {
+    const newestPrior = applied
+        .map((m) => ({ ts: migrationTimestamp(m.name), name: m.name }))
+        .filter((m) => m.ts !== null)
+        .sort((a, b) => (a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : 0))[0];
+    if (!newestPrior)
+        return [];
+    return pending
+        .filter((file) => file.timestamp && file.timestamp < newestPrior.ts)
+        .map((file) => ({ applied: file.filename, newestPrior: `${newestPrior.name}.sql` }));
+}
 /**
  * Validate that applied migration files have not been modified or deleted since they were run.
  * Returns an array of mismatched migrations (empty if all are clean).
@@ -776,9 +988,33 @@ export async function runMigrationInTransaction(client, body, tracking) {
  */
 export async function validateChecksums(client, migrationsDir, dialect = postgresDialect) {
     const applied = await getAppliedMigrations(client, dialect);
+    const { mismatches, legacyUpgrades } = compareAppliedChecksums(applied, migrationsDir);
+    for (const upgrade of legacyUpgrades) {
+        await client.query(dialect.buildMigrationUpdateChecksum(quotedTrackingTable(dialect)), [
+            upgrade.checksum,
+            upgrade.name,
+        ]);
+    }
+    return mismatches;
+}
+/**
+ * THE drift comparison, over rows already read: which applied migrations no
+ * longer match their file, and which are merely carrying a pre-v0.6 hash.
+ *
+ * Split out of {@link validateChecksums} so a DRY RUN can ask the same question
+ * without answering it in the database. `validateChecksums` reads through
+ * `getAppliedMigrations`, which CREATES the tracking table, and then WRITES the
+ * legacy-hash upgrades; a preview must do neither. A dry run that re-derived
+ * drift its own way is how `migrate down --dry-run` came to green-light a batch
+ * the real command refuses, so the rule lives here once and both paths call it.
+ *
+ * @internal exported for tests.
+ */
+export function compareAppliedChecksums(applied, migrationsDir) {
     const allFiles = listMigrationFiles(migrationsDir);
     const fileMap = new Map(allFiles.map((f) => [f.name, f]));
     const mismatches = [];
+    const legacyUpgrades = [];
     for (const migration of applied) {
         const file = fileMap.get(migration.name);
         if (!file) {
@@ -798,10 +1034,7 @@ export async function validateChecksums(client, migrationsDir, dialect = postgre
             // matches what was stored. A legacy row whose file HAS changed falls
             // through to the mismatch path below (bypassable with --allow-drift).
             if (canUpgradeLegacyChecksum(migration.checksum, content)) {
-                await client.query(dialect.buildMigrationUpdateChecksum(quotedTrackingTable(dialect)), [
-                    currentHash,
-                    migration.name,
-                ]);
+                legacyUpgrades.push({ name: migration.name, checksum: currentHash });
                 continue;
             }
             mismatches.push({
@@ -812,13 +1045,49 @@ export async function validateChecksums(client, migrationsDir, dialect = postgre
             });
         }
     }
-    return mismatches;
+    return { mismatches, legacyUpgrades };
 }
-export function formatChecksumMismatchError(mismatches) {
+/**
+ * Rewrite the stored checksum of each MODIFIED migration to its file's current
+ * hash, and report what changed.
+ *
+ * This is what `--allow-drift` was always documented to mean ("when
+ * intentionally rewriting history") and never did. The flag let the run
+ * proceed and left the stored hash alone, so the very next `up` was blocked
+ * again, forever: the only ways out were reverting the file byte-for-byte or
+ * editing `_turbine_migrations` by hand. Recording the new hash is what makes
+ * the flag a one-time decision instead of a permanent one.
+ *
+ * DELETED files are deliberately not touched. There is no content to hash, and
+ * the row is the only remaining record that the migration ran; rewriting or
+ * removing it would erase history rather than re-baseline it.
+ *
+ * @internal exported for tests.
+ */
+export async function rebaselineChecksums(client, migrationsDir, mismatches, dialect = postgresDialect) {
+    const fileMap = new Map(listMigrationFiles(migrationsDir).map((f) => [f.name, f]));
+    const done = [];
+    for (const mismatch of mismatches) {
+        if (mismatch.type !== 'modified')
+            continue;
+        const file = fileMap.get(mismatch.name);
+        if (!file)
+            continue;
+        const current = checksum(readFileSync(file.path, 'utf-8'));
+        await client.query(dialect.buildMigrationUpdateChecksum(quotedTrackingTable(dialect)), [current, mismatch.name]);
+        done.push({ name: mismatch.name, from: mismatch.expected, to: current });
+    }
+    return done;
+}
+export function formatChecksumMismatchError(mismatches, 
+// `down` reuses this report, and a rollback refusal that says it is
+// "refusing to apply pending migrations" sends the reader after the wrong
+// command. Default keeps `up` / `deploy` byte-identical.
+action = 'apply pending migrations') {
     const modified = mismatches.filter((m) => m.type === 'modified');
     const missing = mismatches.filter((m) => m.type === 'missing');
     const lines = [
-        'Migration drift detected, refusing to apply pending migrations.',
+        `Migration drift detected, refusing to ${action}.`,
         '',
         'Applied migrations should be immutable. The following files no longer match their applied state:',
         '',
@@ -831,18 +1100,55 @@ export function formatChecksumMismatchError(mismatches) {
     }
     lines.push('');
     lines.push('Fix one of these:');
-    lines.push('  1. Restore the file(s) to their original content, OR');
-    if (modified.length > 0) {
-        // `migrate down` needs the file on disk to read its DOWN section, so it is
-        // only a remedy for MODIFIED files, never for deleted ones.
-        lines.push('  2. Roll back the affected migrations with `npx turbine migrate down` (modified files only), OR');
+    const remedies = ['Restore the file(s) to their original content'];
+    // `migrate down` needs the file on disk to read its DOWN section, so it is
+    // only a remedy for MODIFIED files, never for deleted ones. It is also not a
+    // remedy for `down` ITSELF: offering the command that just refused sends the
+    // reader in a circle.
+    if (modified.length > 0 && action === 'apply pending migrations') {
+        remedies.push('Roll back the affected migrations with `npx turbine migrate down` (modified files only)');
     }
     if (missing.length > 0) {
-        lines.push('     (deleted files cannot be rolled back: restore the file, then run `migrate down` if needed), OR');
+        remedies.push('Restore each deleted file (a deleted migration cannot be rolled back: its DOWN is gone)');
+    }
+    // The flag no longer skips the check, it RE-BASELINES: validation still runs
+    // and its result is written back to `_turbine_migrations`. Said three
+    // different ways in one release ("disabled", "bypass", "re-baseline"), only
+    // the last of which was true, so every copy of it now says the same thing.
+    remedies.push('Pass `--allow-drift` to record the on-disk content as the applied state ' +
+        '(advanced: it REWRITES migration history, and the SQL that already ran is not re-run)');
+    for (const [index, remedy] of remedies.entries()) {
+        lines.push(`  ${index + 1}. ${remedy}${index === remedies.length - 1 ? '.' : ', OR'}`);
     }
-    lines.push('  3. Pass `--allow-drift` to bypass this check (advanced, make sure you know what you are doing).');
     return lines.join('\n');
 }
+/**
+ * Refuse a batch containing a migration whose UP section runs NOTHING.
+ *
+ * The untouched `migrate create` scaffold is exactly this: a `-- UP` marker
+ * followed by `-- Write your migration SQL here`. It used to be applied and
+ * recorded, and the developer who then filled the file in was refused as
+ * drift; with `--allow-drift` the file was "already applied" and its SQL never
+ * ran, and the only exit was editing `_turbine_migrations` by hand. The runner
+ * already refuses a file with no marker on the grounds that "nothing would run,
+ * and the migration would still be recorded as applied": a marker over zero
+ * executable statements records the same thing. Same rule for a
+ * `-- turbine:no-transaction` file. Pre-flight over the whole batch, alongside
+ * {@link assertNoEmbeddedTransactions}, so nothing is applied first.
+ *
+ * @internal exported for tests.
+ */
+export function assertUpHasStatements(files) {
+    for (const file of files) {
+        const { up } = parseMigrationSQL(file.path);
+        const executable = tokenizeSql(up).filter((s) => !s.commentOnly && s.stripped.trim() !== '');
+        if (executable.length > 0)
+            continue;
+        throw new MigrationError(`Migration ${file.filename} has an UP section with no executable statement (comments only). ` +
+            `Applying it would record the migration as applied while running nothing, and filling the file in ` +
+            `afterwards would then be refused as drift. Write the UP section or delete the file.`);
+    }
+}
 /**
  * Build a deploy plan from local migration files and applied migration rows.
  * This is pure file-system planning; callers with a database connection should
@@ -877,27 +1183,22 @@ export function planMigrationDeploy(migrationsDir, applied) {
             });
         }
     }
-    return {
-        pending: allFiles.filter((f) => !appliedNames.has(f.name)),
-        mismatches,
-    };
+    const pending = allFiles.filter((f) => !appliedNames.has(f.name));
+    return { pending, mismatches, outOfOrder: predictOutOfOrder(applied, pending) };
 }
 /**
  * Inspect deploy status without applying migrations.
  */
-export async function inspectMigrationDeploy(connectionString, migrationsDir) {
-    const client = new pg.Client({ connectionString });
-    await client.connect();
+export async function inspectMigrationDeploy(connectionString, migrationsDir, options) {
+    const { client } = await connectMigrationClient(connectionString, options?.schema);
     const dialect = migrationDialect();
     try {
         await ensureTrackingTable(client, dialect);
         const mismatches = await validateChecksums(client, migrationsDir, dialect);
         const applied = await getAppliedMigrations(client, dialect);
         const appliedNames = new Set(applied.map((m) => m.name));
-        return {
-            pending: listMigrationFiles(migrationsDir).filter((f) => !appliedNames.has(f.name)),
-            mismatches,
-        };
+        const pending = listMigrationFiles(migrationsDir).filter((f) => !appliedNames.has(f.name));
+        return { pending, mismatches, outOfOrder: predictOutOfOrder(applied, pending) };
     }
     finally {
         await client.end();
@@ -918,11 +1219,11 @@ export async function inspectMigrationDeploy(connectionString, migrationsDir) {
  * this check (the CLI exposes this as `--allow-drift`).
  */
 export async function migrateUp(connectionString, migrationsDir, options) {
-    const client = new pg.Client({ connectionString });
-    await client.connect();
+    const { client, connectionString: url } = await connectMigrationClient(connectionString, options?.schema);
     // Treat `force` as an alias for `allowDrift` for backwards compatibility.
     const allowDrift = options?.allowDrift === true || options?.force === true;
     const dialect = migrationDialect();
+    const rebaselined = [];
     try {
         // Derive an advisory lock ID per-database so concurrent migrations in
         // sibling databases on the same Postgres cluster do not contend.
@@ -933,7 +1234,7 @@ export async function migrateUp(connectionString, migrationsDir, options) {
         // table-lock adapter gets its OWN connection so the per-migration
         // BEGIN/COMMIT below cannot end the transaction the lock lives in.
         const adapter = options?.adapter;
-        const lock = await acquireMigrationLock(client, lockId, adapter, () => openLockConnection(connectionString));
+        const lock = await acquireMigrationLock(client, lockId, adapter, () => openLockConnection(url));
         if (!lock.acquired) {
             throw new MigrationError('Could not acquire migration lock, another migration is already running');
         }
@@ -945,11 +1246,14 @@ export async function migrateUp(connectionString, migrationsDir, options) {
             // migration history no longer agree, so we BLOCK the run by default.
             // Users can pass `allowDrift: true` (CLI: `--allow-drift`) to force past
             // the block when they are intentionally rewriting history.
-            if (!allowDrift) {
-                const mismatches = await validateChecksums(client, migrationsDir, dialect);
-                if (mismatches.length > 0) {
+            // Computed on BOTH paths. Without the flag a mismatch blocks the run;
+            // with it, the drifted files are re-baselined so the decision is made
+            // once rather than on every future run (see rebaselineChecksums).
+            const mismatches = await validateChecksums(client, migrationsDir, dialect);
+            if (mismatches.length > 0) {
+                if (!allowDrift)
                     throw new MigrationError(formatChecksumMismatchError(mismatches));
-                }
+                rebaselined.push(...(await rebaselineChecksums(client, migrationsDir, mismatches, dialect)));
             }
             const applied = await getAppliedMigrations(client, dialect);
             const appliedNames = new Set(applied.map((m) => m.name));
@@ -969,6 +1273,7 @@ export async function migrateUp(connectionString, migrationsDir, options) {
             // transactions cannot be run safely at all, so it is refused for everyone,
             // deploy included. Pre-flight over the whole batch, so nothing is applied.
             assertNoEmbeddedTransactions(pending, 'up');
+            assertUpHasStatements(pending);
             // Destructive statements in the pending batch, computed once. Returned in
             // the result regardless of the gate so `deploy` can print a notice even
             // though it proceeds by design.
@@ -1051,7 +1356,7 @@ export async function migrateUp(connectionString, migrationsDir, options) {
                 results.push(file);
                 flagOutOfOrder(file);
             }
-            return { applied: results, errors, destructive, outOfOrder, noTransaction: noTransactionApplied };
+            return { applied: results, errors, destructive, outOfOrder, noTransaction: noTransactionApplied, rebaselined };
         }
         finally {
             await releaseMigrationLock(lock, client);
@@ -1072,6 +1377,7 @@ export async function migrateDeploy(connectionString, migrationsDir, options) {
         allowDrift: options?.allowDrift === true,
         allowDestructive: true,
         adapter: options?.adapter,
+        schema: options?.schema,
     });
 }
 /**
@@ -1139,6 +1445,59 @@ export async function rollbackMigrations(client, toRollback, fileMap, deleteAppl
     }
     return { rolledBack: results, errors };
 }
+/**
+ * What `migrateDown` WOULD roll back, computed by the same rule it uses, and
+ * where it would stop.
+ *
+ * `migrate down --dry-run` used to build its list from `migrateStatus`, which
+ * sorts by filename and drops applied migrations whose file is missing. The
+ * real run walks the tracking table newest-APPLIED first and STOPS at the first
+ * migration it cannot read, so with a deleted file the two named different
+ * migrations: the dry run reported the one after the gap. A dry run that names
+ * the wrong migration is not a dry run, so both now read the same function.
+ *
+ * `stoppedAt` is the migration the real run would fail on (a missing file, or a
+ * missing DOWN section) together with the message it would print; `toRollback`
+ * is what it would get through first.
+ */
+export async function planMigrationRollback(connectionString, migrationsDir, options) {
+    const { client } = await connectMigrationClient(connectionString, options?.schema);
+    const dialect = migrationDialect();
+    try {
+        const { applied } = await readAppliedMigrations(client, dialect);
+        // The drift gate the real rollback runs, asked of the same rows by the same
+        // function. Without it the preview reported a batch `migrate down` refuses
+        // outright, which is the failure this whole function exists to prevent: a
+        // dry run that disagrees with the run is not a dry run. Read-only, so the
+        // legacy-hash upgrades `validateChecksums` would write are left for the
+        // real run; they are not drift and never reach the refusal.
+        if (options?.allowDrift !== true) {
+            const { mismatches } = compareAppliedChecksums(applied, migrationsDir);
+            if (mismatches.length > 0)
+                throw new MigrationError(formatChecksumMismatchError(mismatches, 'roll back'));
+        }
+        const fileMap = new Map(listMigrationFiles(migrationsDir).map((f) => [f.name, f]));
+        const batch = applied.reverse().slice(0, options?.step ?? 1);
+        const toRollback = [];
+        for (const migration of batch) {
+            const file = fileMap.get(migration.name);
+            if (!file) {
+                return {
+                    toRollback,
+                    stoppedAt: { name: migration.name, error: `Migration file not found for "${migration.name}"` },
+                };
+            }
+            if (!parseMigrationSQL(file.path).down) {
+                return { toRollback, stoppedAt: { name: migration.name, error: 'No DOWN section found in migration file' } };
+            }
+            toRollback.push(file);
+        }
+        return { toRollback, stoppedAt: null };
+    }
+    finally {
+        await client.end();
+    }
+}
 /**
  * Rollback the last N migrations (DOWN).
  *
@@ -1148,8 +1507,7 @@ export async function rollbackMigrations(client, toRollback, fileMap, deleteAppl
  * - Properly reverses changes in reverse application order
  */
 export async function migrateDown(connectionString, migrationsDir, options) {
-    const client = new pg.Client({ connectionString });
-    await client.connect();
+    const { client, connectionString: url } = await connectMigrationClient(connectionString, options?.schema);
     const dialect = migrationDialect();
     try {
         // Derive a per-database advisory lock ID so concurrent migrations in
@@ -1157,15 +1515,30 @@ export async function migrateDown(connectionString, migrationsDir, options) {
         const dbName = await getCurrentDatabaseName(client);
         const lockId = deriveLockId(dbName);
         const adapter = options?.adapter;
-        const lock = await acquireMigrationLock(client, lockId, adapter, () => openLockConnection(connectionString));
+        const lock = await acquireMigrationLock(client, lockId, adapter, () => openLockConnection(url));
         if (!lock.acquired) {
             throw new MigrationError('Could not acquire migration lock, another migration is already running');
         }
         try {
             await ensureTrackingTable(client, dialect);
+            // THE SAME DRIFT QUESTION `up` ASKS, and it matters more here: the DOWN
+            // that runs is read from the CURRENT file, so rolling back a drifted
+            // migration executes SQL that was never the applied file's DOWN. This
+            // used to happen with no check and no warning.
+            // VALIDATED here, REBASELINED further down. The two used to happen
+            // together, above every gate, so a rollback the destructive gate then
+            // refused had already rewritten `_turbine_migrations` by the time the CLI
+            // printed "nothing was rolled back and no data was touched". A refusal
+            // must touch nothing, which means the only write on this path happens
+            // after the last thing that can refuse.
+            const rebaselined = [];
+            const mismatches = await validateChecksums(client, migrationsDir, dialect);
+            if (mismatches.length > 0 && options?.allowDrift !== true) {
+                throw new MigrationError(formatChecksumMismatchError(mismatches, 'roll back'));
+            }
             const applied = await getAppliedMigrations(client, dialect);
             if (applied.length === 0) {
-                return { rolledBack: [], errors: [] };
+                return { rolledBack: [], errors: [], rebaselined };
             }
             const allFiles = listMigrationFiles(migrationsDir);
             const fileMap = new Map(allFiles.map((f) => [f.name, f]));
@@ -1204,7 +1577,13 @@ export async function migrateDown(connectionString, migrationsDir, options) {
                     throw new MigrationError(lines.join('\n'));
                 }
             }
-            return await rollbackMigrations(client, toRollback, fileMap, dialect.buildMigrationDeleteApplied(quotedTrackingTable(dialect)));
+            // Past every gate: nothing below this line can refuse, so the history
+            // rewrite `--allow-drift` asks for is finally safe to perform.
+            if (mismatches.length > 0) {
+                rebaselined.push(...(await rebaselineChecksums(client, migrationsDir, mismatches, dialect)));
+            }
+            const result = await rollbackMigrations(client, toRollback, fileMap, dialect.buildMigrationDeleteApplied(quotedTrackingTable(dialect)));
+            return { ...result, rebaselined };
         }
         finally {
             await releaseMigrationLock(lock, client);
@@ -1221,13 +1600,12 @@ export async function migrateDown(connectionString, migrationsDir, options) {
  * unchanged pre-v0.6 row reports the same way `migrate up` treats it (valid,
  * pending an in-place hash upgrade) rather than looking like drift.
  */
-export async function migrateStatus(connectionString, migrationsDir) {
-    const client = new pg.Client({ connectionString });
-    await client.connect();
+export async function migrateStatus(connectionString, migrationsDir, options) {
+    const { client } = await connectMigrationClient(connectionString, options?.schema);
     const dialect = migrationDialect();
     try {
-        await ensureTrackingTable(client, dialect);
-        const applied = await getAppliedMigrations(client, dialect);
+        // READ ONLY: never create the tracking table here, see readAppliedMigrations.
+        const { applied } = await readAppliedMigrations(client, dialect);
         const appliedMap = new Map(applied.map((m) => [m.name, m]));
         const allFiles = listMigrationFiles(migrationsDir);
         const fileNames = new Set(allFiles.map((f) => f.name));