turbine-orm 0.77.1 → 0.78.0

package/dist/cjs/cli/migrate.d.ts

@@ -84,6 +84,19 @@ export interface MigrationRunResult {
      * unrecorded, so every statement in one of these must be idempotent.
      */
     noTransaction: MigrationFile[];
+    /**
+     * Applied migrations whose stored checksum was re-baselined to the file's
+     * current hash, because the run was given `allowDrift`. Empty otherwise.
+     */
+    rebaselined: RebaselinedChecksum[];
+}
+/** One applied migration whose stored checksum was rewritten to match its file. */
+export interface RebaselinedChecksum {
+    name: string;
+    /** The hash the tracking table held, i.e. the content that was actually applied. */
+    from: string;
+    /** The hash of the file as it stands now. */
+    to: string;
 }
 /** Extract the YYYYMMDDHHMMSS timestamp prefix from a migration name, or null. */
 export declare function migrationTimestamp(name: string): string | null;
@@ -106,6 +119,24 @@ export declare function collectUpDestructive(files: MigrationFile[]): Destructiv
  * a gate. This entry point lets the RULE be asserted directly, once per code.
  */
 export declare function ensureTrackingTable(client: MigrationQueryClient, dialect?: Dialect): Promise<void>;
+/**
+ * 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 declare function readAppliedMigrations(client: MigrationQueryClient, dialect?: Dialect): Promise<{
+    applied: AppliedMigration[];
+    trackingTableExists: boolean;
+}>;
 /**
  * Parse a migration filename into its components.
  * Expected format: YYYYMMDDHHMMSS_description.sql
@@ -147,6 +178,15 @@ export declare function getPendingMigrations(migrationsDir: string, applied: str
  * List all migration files in the migrations directory, sorted by name.
  */
 export declare function listMigrationFiles(migrationsDir: string): MigrationFile[];
+/**
+ * `.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 declare function listIgnoredSqlFiles(migrationsDir: string): string[];
 /** The parsed sections of a migration file plus its execution directives. */
 export interface ParsedMigration {
     up: string;
@@ -284,6 +324,96 @@ export declare function createMigration(migrationsDir: string, name: string, aut
  * without contending on a single hardcoded lock ID.
  */
 export declare function deriveLockId(databaseName: string): number;
+/**
+ * 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.
+ */
+export declare function getCurrentDatabaseName(client: {
+    query: (sql: string) => Promise<{
+        rows: {
+            current_database?: string;
+        }[];
+    }>;
+}): Promise<string>;
+/**
+ * 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 declare function assertPinnableSchema(schema: string): void;
+export declare function connectionStringForSchema(connectionString: string, schema?: string, inheritedSchemas?: readonly string[]): string;
+/**
+ * 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 declare function assertSchemaExists(client: MigrationQueryClient, schema: string): Promise<void>;
 /**
  * The connection surface the migration lock needs. `pg.Client` satisfies it;
  * tests substitute a fake so the dedicated-connection wiring can be exercised
@@ -389,7 +519,22 @@ export interface ChecksumMismatch {
 export interface MigrationDeployPlan {
     pending: MigrationFile[];
     mismatches: ChecksumMismatch[];
+    /**
+     * The out-of-order applies the real run WOULD flag (a pending migration whose
+     * timestamp is older than one already applied). Present so `deploy --dry-run`
+     * can print the same warning the real deploy prints instead of being quieter
+     * than the thing it previews.
+     */
+    outOfOrder: OutOfOrderApply[];
 }
+/**
+ * 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 declare function predictOutOfOrder(applied: AppliedMigration[], pending: MigrationFile[]): OutOfOrderApply[];
 /**
  * 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).
@@ -397,7 +542,62 @@ export interface MigrationDeployPlan {
  * @internal exported for tests; not part of the CLI's public surface.
  */
 export declare function validateChecksums(client: MigrationQueryClient, migrationsDir: string, dialect?: Dialect): Promise<ChecksumMismatch[]>;
-export declare function formatChecksumMismatchError(mismatches: ChecksumMismatch[]): string;
+/**
+ * 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 declare function compareAppliedChecksums(applied: readonly AppliedMigration[], migrationsDir: string): {
+    mismatches: ChecksumMismatch[];
+    legacyUpgrades: Array<{
+        name: string;
+        checksum: string;
+    }>;
+};
+/**
+ * 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 declare function rebaselineChecksums(client: MigrationQueryClient, migrationsDir: string, mismatches: ChecksumMismatch[], dialect?: Dialect): Promise<RebaselinedChecksum[]>;
+export declare function formatChecksumMismatchError(mismatches: ChecksumMismatch[], action?: 'apply pending migrations' | 'roll back'): string;
+/**
+ * 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 declare function assertUpHasStatements(files: MigrationFile[]): void;
 /**
  * Build a deploy plan from local migration files and applied migration rows.
  * This is pure file-system planning; callers with a database connection should
@@ -407,7 +607,9 @@ export declare function planMigrationDeploy(migrationsDir: string, applied: Appl
 /**
  * Inspect deploy status without applying migrations.
  */
-export declare function inspectMigrationDeploy(connectionString: string, migrationsDir: string): Promise<MigrationDeployPlan>;
+export declare function inspectMigrationDeploy(connectionString: string, migrationsDir: string, options?: {
+    schema?: string;
+}): Promise<MigrationDeployPlan>;
 /**
  * Apply all pending migrations (UP).
  *
@@ -435,6 +637,11 @@ export declare function migrateUp(connectionString: string, migrationsDir: strin
      * long time on other transactions and otherwise looks hung).
      */
     onNoTransaction?: (file: MigrationFile) => void;
+    /**
+     * The Postgres schema unqualified identifiers resolve in, for the migration
+     * SQL and the tracking table alike. See {@link connectionStringForSchema}.
+     */
+    schema?: string;
 }): Promise<MigrationRunResult>;
 /**
  * Production migration apply. This intentionally applies files as written and
@@ -443,6 +650,7 @@ export declare function migrateUp(connectionString: string, migrationsDir: strin
 export declare function migrateDeploy(connectionString: string, migrationsDir: string, options?: {
     adapter?: DatabaseAdapter;
     allowDrift?: boolean;
+    schema?: string;
 }): Promise<MigrationRunResult>;
 /**
  * Roll back a prepared LIFO batch, newest first, stopping at the first
@@ -471,6 +679,32 @@ export declare function rollbackMigrations(client: MigrationTxClient, toRollback
         error: string;
     }>;
 }>;
+/**
+ * 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 declare function planMigrationRollback(connectionString: string, migrationsDir: string, options?: {
+    step?: number;
+    schema?: string;
+    allowDrift?: boolean;
+}): Promise<{
+    toRollback: MigrationFile[];
+    stoppedAt: {
+        name: string;
+        error: string;
+    } | null;
+}>;
 /**
  * Rollback the last N migrations (DOWN).
  *
@@ -483,12 +717,16 @@ export declare function migrateDown(connectionString: string, migrationsDir: str
     step?: number;
     allowDestructive?: boolean;
     adapter?: DatabaseAdapter;
+    schema?: string;
+    /** Roll back anyway when an applied file has drifted, re-baselining as `up` does. */
+    allowDrift?: boolean;
 }): Promise<{
     rolledBack: MigrationFile[];
     errors: Array<{
         file: MigrationFile;
         error: string;
     }>;
+    rebaselined: RebaselinedChecksum[];
 }>;
 /**
  * Get the status of all migrations (applied vs pending).
@@ -497,4 +735,6 @@ export declare function migrateDown(connectionString: string, migrationsDir: str
  * 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 declare function migrateStatus(connectionString: string, migrationsDir: string): Promise<MigrationStatus[]>;
+export declare function migrateStatus(connectionString: string, migrationsDir: string, options?: {
+    schema?: string;
+}): Promise<MigrationStatus[]>;