kern-migrations 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilya Semenov
+
+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

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# kern-migrations
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Migrations of PostgreSQL schemas for [kern-orm](https://github.com/IlyaSemenov/kern-orm) and its database layer `kern-db`: write each change of the database with helpers, SQL, or code, and apply the pending ones to a schema, such as the schema of each tenant.
+
+## Install
+
+Install it beside `kern-orm` or `kern-db`:
+
+```sh
+npm install kern-migrations
+```
+
+## Usage
+
+```ts
+// src/migrations/0001_create_form.ts
+import { createIndex, createTable, defineMigration } from "kern-migrations"
+
+export default defineMigration([
+  createTable("form", {
+    id: "uuid PRIMARY KEY DEFAULT gen_random_uuid()",
+    name: "text NOT NULL",
+  }),
+  createIndex("form", ["name"]),
+])
+```
+
+```ts
+import { defineMigrations, migrate } from "kern-migrations"
+
+const migrations = defineMigrations({
+  "0001_create_form": () => import("./migrations/0001_create_form.ts"),
+})
+
+await migrate(db, migrations)
+```
+
+See [Migrations](https://ilyasemenov.github.io/kern-orm/migrations/) for the helpers, steps of SQL and code, listing migrations, tenants, rolling back, the command line, and testing migrations.

package/dist/cli.d.mts

@@ -0,0 +1,27 @@
+import { i as MigrationHistory, t as MigrationTarget } from "./target-iyJah0hO.mjs";
+/** Options of the list module that the command `new` writes. */
+interface MigrationListModuleOptions {
+  /** Path of the module, absolute or relative to the working directory, or its `file:` URL. */
+  readonly path: string | URL;
+  /** Whether import specifiers keep the extension of the migration modules, such as `./0001_create_form.ts`; `true` by default. */
+  readonly extensions?: boolean;
+}
+/** Options of `runMigrationCli`. */
+interface MigrationCliOptions {
+  /** Directory of the migration modules, where the command `new` creates one: a path, absolute or relative to the working directory, or a `file:` URL. */
+  readonly directory?: string | URL;
+  /** Module that the command `new` writes with the loaders of the migration modules of `directory`, for runtimes without `import.meta.glob`: its path or URL, or its options. */
+  readonly listModule?: string | URL | MigrationListModuleOptions;
+  /** Returns the text of a new migration module by its key, such as `0003_add_form_slug`. */
+  readonly template?: (key: string) => string;
+  /** Arguments of the command, `process.argv.slice(2)` by default. */
+  readonly args?: readonly string[];
+}
+/**
+ * Runs the command of the arguments of the process on `target` with the migrations of `history`, such as `migrate` or `rollback 2`, and prints its result.
+ *
+ * It never rejects: it prints an error to stderr and sets `process.exitCode` to 1, so that the script closes the database after it.
+ * It does not close the database, which belongs to the script.
+ */
+export declare function runMigrationCli(target: MigrationTarget, history: MigrationHistory, options?: MigrationCliOptions): Promise<void>;
+export type { MigrationCliOptions, MigrationListModuleOptions };

package/dist/cli.mjs

@@ -0,0 +1,369 @@
+import { d as moduleExtensions, i as isMigrationTargetDb, l as getMigrationNumber, s as compareMigrationNumbers, w as getErrorMessage } from "./target-BHaRgZJG.mjs";
+import { i as rollback, n as migrate, r as redo, t as getMigrationStatus } from "./migrate-CxWPJJmr.mjs";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+// src/cli/args.ts
+/** Error of the arguments of the command line, which the command line reports with a hint to `--help`. */
+var CliUsageError = class extends Error {
+	name = "CliUsageError";
+};
+/** Text of `--help`. */
+const usage = `Usage: <script> <command> [options]
+
+Commands:
+  migrate [count]         Apply the pending migrations, or the first count of them
+  rollback [count | all]  Roll back the last applied migration, the last count of them, or all
+  redo [count]            Roll back the last applied migration, or the last count of them, and apply them again
+  status                  List the applied and the pending migrations
+  new <name>              Create the module of the next migration
+
+Options:
+  -s, --schema <name>     PostgreSQL schema to migrate instead of that of the database
+  -h, --help              Show this help`;
+/**
+* Parses the arguments of the command line, such as `["rollback", "2", "--schema", "tenant_acme"]`.
+*
+* It returns `help` for `--help` and for arguments without a command, and throws a `CliUsageError` for arguments of another form.
+*/
+function parseCliArgs(args) {
+	const { values, positionals } = parseOptions(args);
+	if (values.help) return {
+		name: "help",
+		requested: true
+	};
+	const command = positionals[0];
+	const commandArgs = positionals.slice(1);
+	const schemaName = values.schema;
+	if (schemaName === "") throw new CliUsageError("--schema requires the name of a PostgreSQL schema");
+	switch (command) {
+		case void 0: return {
+			name: "help",
+			requested: false
+		};
+		case "migrate":
+		case "redo": {
+			const arg = getCountArg(command, commandArgs);
+			return {
+				name: command,
+				count: arg === void 0 ? void 0 : parseCount(command, arg, false),
+				schemaName
+			};
+		}
+		case "rollback": {
+			const arg = getCountArg(command, commandArgs);
+			return {
+				name: command,
+				count: arg === void 0 || arg === "all" ? arg : parseCount(command, arg, true),
+				schemaName
+			};
+		}
+		case "status":
+			if (commandArgs.length > 0) throw new CliUsageError("status takes no arguments");
+			return {
+				name: command,
+				schemaName
+			};
+		case "new":
+			if (schemaName !== void 0) throw new CliUsageError("new takes no --schema");
+			return {
+				name: command,
+				migrationName: parseMigrationName(commandArgs)
+			};
+		default: throw new CliUsageError(`Unknown command ${command}`);
+	}
+}
+/** Parses the options and the positional arguments, throwing a `CliUsageError` for an unknown option or an option without its value. */
+function parseOptions(args) {
+	try {
+		return parseArgs({
+			args: [...args],
+			options: {
+				schema: {
+					type: "string",
+					short: "s"
+				},
+				help: {
+					type: "boolean",
+					short: "h"
+				}
+			},
+			allowPositionals: true
+		});
+	} catch (error) {
+		if (error instanceof TypeError && String(Reflect.get(error, "code")).startsWith("ERR_PARSE_ARGS_")) throw new CliUsageError(error.message);
+		throw error;
+	}
+}
+/** Returns the optional count argument of `command`, rejecting more arguments. */
+function getCountArg(command, args) {
+	if (args.length > 1) throw new CliUsageError(`${command} takes one count at most`);
+	return args[0];
+}
+/** Parses the count argument of `command`: decimal digits of a positive safe integer, so that `0x10`, `1e3`, and `02` are not counts. */
+function parseCount(command, arg, allowsAll) {
+	const count = Number(arg);
+	if (!/^[1-9]\d*$/.test(arg) || !Number.isSafeInteger(count)) throw new CliUsageError(`The count of ${command} must be a positive integer${allowsAll ? " or all" : ""}, not ${arg}`);
+	return count;
+}
+/** Parses the name of a new migration, the `<name>` of its key `<number>_<name>`. */
+function parseMigrationName(args) {
+	const name = args[0];
+	if (name === void 0 || args.length > 1) throw new CliUsageError("new takes the name of the migration, such as new add_form_slug");
+	if (!/^[\p{L}\p{N}_-]+$/u.test(name)) throw new CliUsageError(`The name of a migration must have only letters, digits, _, and -, such as add_form_slug, not ${name}`);
+	return name;
+}
+// src/cli/new.ts
+/** First line of the list module, by which `new` recognizes a module that it may write. */
+const listModuleHeader = "// Written by the new command of kern-migrations";
+/**
+* Text of a new migration module: `createTable` for the first migration and `addColumn` for a later one.
+*
+* Their names are blank, with comments that name them, and fail to load until they are filled in, so that a migration left as created never applies.
+*/
+function getDefaultTemplate(_key, isFirst) {
+	return isFirst ? `import { createTable, defineMigration } from "kern-migrations"
+
+export default defineMigration([
+  createTable(/* table */ "", {
+    id: "uuid PRIMARY KEY DEFAULT gen_random_uuid()",
+  }),
+])
+` : `import { addColumn, defineMigration } from "kern-migrations"
+
+export default defineMigration([
+  addColumn(/* table */ "", /* column */ "", "text"),
+])
+`;
+}
+/**
+* Creates the module of the next migration named `name` in the directory, and then writes the list module, if any; returns the paths that it wrote.
+*
+* The number of the migration follows the greatest number of `keys` and of the modules of the directory, with as many digits as the key of that number.
+* It checks the list module and builds its text before it creates the migration, so that a list module written by hand or a module that the list cannot import fails without writing anything.
+* It writes the list from the modules of the directory listed again after it creates the migration, so that the list keeps a migration that another `new` has created meanwhile, and two migrations of one number fail.
+*/
+async function createMigration(keys, name, options) {
+	const { directory, listModule } = options;
+	if (listModule !== void 0) await checkListModule(listModule.path);
+	const modules = await listMigrationModules(directory);
+	const existingKeys = [...keys, ...modules.map((module) => module.key)];
+	const key = getNextKey(existingKeys, name);
+	const fileName = `${key}.ts`;
+	if (listModule !== void 0) formatListModule([...modules, {
+		key,
+		number: getMigrationNumber(key),
+		fileName
+	}], directory, listModule);
+	await mkdir(directory, { recursive: true });
+	const path = join(directory, fileName);
+	await writeFile(path, options.template(key, existingKeys.length === 0), { flag: "wx" });
+	if (listModule === void 0) return [path];
+	const text = formatListModule(await listMigrationModules(directory), directory, listModule);
+	await mkdir(dirname(listModule.path), { recursive: true });
+	await writeFile(listModule.path, text);
+	return [path, listModule.path];
+}
+/**
+* Lists the migration modules of `directory` in the order of their numbers, and none of a missing directory.
+*
+* A module is a file with the extension of a module whose name without the extension is a key, such as `0001_create_form.ts`; other files, such as `index.ts` and migration tests `*.migration-test.ts`, are not.
+* It rejects two modules of one key or one number, such as of two branches that took one number.
+*/
+async function listMigrationModules(directory) {
+	let entries;
+	try {
+		entries = await readdir(directory, { withFileTypes: true });
+	} catch (error) {
+		if (Reflect.get(Object(error), "code") === "ENOENT") return [];
+		throw error;
+	}
+	const modules = [];
+	for (const entry of entries) {
+		const extension = extname(entry.name);
+		if (!entry.isFile() || !moduleExtensions.has(extension)) continue;
+		const key = entry.name.slice(0, -extension.length);
+		const number = getMigrationNumber(key);
+		if (number !== void 0) modules.push({
+			key,
+			number,
+			fileName: entry.name
+		});
+	}
+	modules.sort((left, right) => compareMigrationNumbers(left.number, right.number) || (left.fileName < right.fileName ? -1 : left.fileName > right.fileName ? 1 : 0));
+	for (let index = 1; index < modules.length; index++) {
+		const previous = modules[index - 1];
+		const module = modules[index];
+		if (previous.number === module.number) throw new Error(`Migrations ${previous.fileName} and ${module.fileName} have the same number: give each migration its own number`);
+	}
+	return modules;
+}
+/** Returns the key of the migration named `name` that follows the greatest number of `keys`, such as `0010_add_form_slug` after `0009_create_tag`, or `0001_…` without keys. */
+function getNextKey(keys, name) {
+	let last;
+	for (const key of keys) {
+		const number = getMigrationNumber(key);
+		if (number !== void 0 && (last === void 0 || number > last.number)) last = {
+			key,
+			number
+		};
+	}
+	if (last === void 0) return `0001_${name}`;
+	const digits = last.key.indexOf("_");
+	return `${String(last.number + 1n).padStart(digits, "0")}_${name}`;
+}
+/**
+* Rejects a list module that `new` must not write: one named as a migration module, which would replace the migration of its key, and one that exists without the header line, so that `new` never overwrites a module written by hand.
+*
+* It reads the header line without the `\r` of a line ending converted to CRLF, such as by a checkout on Windows.
+*/
+async function checkListModule(path) {
+	const fileName = basename(path);
+	if (getMigrationNumber(fileName.slice(0, fileName.length - extname(fileName).length)) !== void 0) throw new Error(`Cannot write the list of migrations to ${path}: name it other than a migration, such as index.ts`);
+	let text;
+	try {
+		text = await readFile(path, "utf8");
+	} catch (error) {
+		if (Reflect.get(Object(error), "code") === "ENOENT") return;
+		throw error;
+	}
+	if (text.split("\n", 1)[0].replace(/\r$/, "") !== listModuleHeader) throw new Error(`Cannot write the list of migrations to ${path}: the new command writes only a module that starts with the line "${listModuleHeader}"; add the line at the top of the module to let the command write it`);
+}
+/**
+* Formats the list module: the default export of the loaders of `modules` by key, with import specifiers relative to the list module.
+*
+* It rejects a specifier with `#`, `?`, or `%` rather than escaping it, since Node.js reads a specifier as a URL, and Bun and bundlers read it as a path.
+* It rejects a module that has no relative path from the list module, such as on a different Windows drive.
+*/
+function formatListModule(modules, directory, listModule) {
+	const lines = [listModuleHeader, "export default {"];
+	for (const module of modules) {
+		const fileName = listModule.extensions ? module.fileName : module.fileName.slice(0, -extname(module.fileName).length);
+		const relativePath = relative(dirname(listModule.path), join(directory, fileName));
+		if (isAbsolute(relativePath)) throw new Error(`Cannot import ${relativePath} from the list of migrations at ${listModule.path}: put the list module on the drive of the migrations`);
+		const path = relativePath.split(sep).join("/");
+		const specifier = path.startsWith("../") ? path : `./${path}`;
+		if (/[#?%]/.test(specifier)) throw new Error(`Cannot import ${specifier} from the list of migrations: an import specifier must not have #, ?, or %`);
+		lines.push(`  ${JSON.stringify(module.key)}: () => import(${JSON.stringify(specifier)}),`);
+	}
+	lines.push("}", "");
+	return lines.join("\n");
+}
+// src/cli/run.ts
+/**
+* Runs the command of the arguments of the process on `target` with the migrations of `history`, such as `migrate` or `rollback 2`, and prints its result.
+*
+* It never rejects: it prints an error to stderr and sets `process.exitCode` to 1, so that the script closes the database after it.
+* It does not close the database, which belongs to the script.
+*/
+async function runMigrationCli(target, history, options = {}) {
+	const exitCode = await runCli(target, history, options, {
+		log: (text) => console.log(text),
+		error: (value) => console.error(value)
+	});
+	if (exitCode !== 0) process.exitCode = exitCode;
+}
+/** Runs the command of `options.args` and prints its result to `output`; resolves to the exit code. */
+async function runCli(target, history, options, output) {
+	try {
+		const command = parseCliArgs(options.args ?? process.argv.slice(2));
+		switch (command.name) {
+			case "help":
+				if (!command.requested) {
+					output.error(usage);
+					return 1;
+				}
+				output.log(usage);
+				return 0;
+			case "migrate": {
+				const { database, schemaName } = resolveTarget(target, command.schemaName);
+				logKeys(output, "Applied", await migrate(database, history, {
+					count: command.count,
+					schemaName
+				}), "No pending migrations");
+				return 0;
+			}
+			case "rollback": {
+				const { database, schemaName } = resolveTarget(target, command.schemaName);
+				logKeys(output, "Rolled back", await rollback(database, history, {
+					count: command.count,
+					schemaName
+				}), "No applied migrations");
+				return 0;
+			}
+			case "redo": {
+				const { database, schemaName } = resolveTarget(target, command.schemaName);
+				const keys = await redo(database, history, {
+					count: command.count,
+					schemaName
+				});
+				logKeys(output, "Rolled back", keys.toReversed(), "No applied migrations");
+				logKeys(output, "Applied", keys);
+				return 0;
+			}
+			case "status": {
+				const { database, schemaName } = resolveTarget(target, command.schemaName);
+				const status = await getMigrationStatus(database, history, { schemaName });
+				const applied = new Set(status.applied);
+				output.log(`Migrations of schema "${status.schemaName}":`);
+				for (const key of history.keys) output.log(`  ${applied.has(key) ? "applied" : "pending"}  ${key}`);
+				for (const key of status.unknown) output.log(`  unknown  ${key}`);
+				return 0;
+			}
+			case "new": {
+				if (options.directory === void 0) throw new Error("The command new requires the directory option of runMigrationCli");
+				const listModule = typeof options.listModule === "string" || options.listModule instanceof URL ? { path: options.listModule } : options.listModule;
+				const paths = await createMigration(history.keys, command.migrationName, {
+					directory: resolvePath(options.directory),
+					listModule: listModule === void 0 ? void 0 : {
+						path: resolvePath(listModule.path),
+						extensions: listModule.extensions ?? true
+					},
+					template: options.template ?? getDefaultTemplate
+				});
+				output.log(`Created ${relative(process.cwd(), paths[0])}`);
+				if (paths[1] !== void 0) output.log(`Wrote ${relative(process.cwd(), paths[1])}`);
+				return 0;
+			}
+		}
+	} catch (error) {
+		output.error(error instanceof CliUsageError ? `${error.message}\nRun with --help to list the commands.` : error);
+		return 1;
+	}
+}
+/**
+* Resolves the database and the PostgreSQL schema of a command: the schema of `--schema`, otherwise that of a `Db`, or `undefined` for `current_schema()`.
+*
+* It reads `$schemaName` of a `Db` once, and the command passes the calls the database with that schema, so that no call reads it again.
+* When the function of the schema throws, such as of the current tenant, which a command line has no context for, the error names `--schema`.
+*/
+function resolveTarget(target, schemaName) {
+	if (!isMigrationTargetDb(target)) return {
+		database: target,
+		schemaName
+	};
+	const database = target.$database;
+	if (schemaName !== void 0) return {
+		database,
+		schemaName
+	};
+	try {
+		return {
+			database,
+			schemaName: target.$schemaName
+		};
+	} catch (error) {
+		throw new Error(`Cannot resolve the PostgreSQL schema of the target: ${getErrorMessage(error)}; pass --schema`, { cause: error });
+	}
+}
+/** Prints a line of `verb` for each key, or `empty` without keys. */
+function logKeys(output, verb, keys, empty) {
+	if (keys.length === 0 && empty !== void 0) output.log(empty);
+	for (const key of keys) output.log(`${verb} ${key}`);
+}
+/** Resolves a path of an option, absolute or relative to the working directory, or a `file:` URL. */
+function resolvePath(path) {
+	return resolve(path instanceof URL ? fileURLToPath(path) : path);
+}
+export { runMigrationCli };

package/dist/error-BOZbdvKf.d.mts

@@ -0,0 +1,19 @@
+/** Direction of a migration: `up` applies it, and `down` rolls it back. */
+type MigrationDirection = "up" | "down";
+/** Error of a migration: of loading its module, or of a step that failed, with the original error in `cause`. */
+declare class MigrationError extends Error {
+  readonly name = "MigrationError";
+  /** Key of the migration. */
+  readonly key: string;
+  /** Number of the step, from 1, or `undefined` for an error of the migration as a whole, such as of loading its module. */
+  readonly step: number | undefined;
+  /** Direction of the step that failed, or `undefined` for an error of the migration as a whole or of a step that is not valid. */
+  readonly direction: MigrationDirection | undefined;
+  constructor(message: string, details: {
+    key: string;
+    step?: number;
+    direction?: MigrationDirection;
+    cause?: unknown;
+  });
+}
+export { MigrationError as n, MigrationDirection as t };

package/dist/index.d.mts

@@ -0,0 +1,185 @@
+import { n as MigrationError, t as MigrationDirection } from "./error-BOZbdvKf.mjs";
+import { a as MigrationHistoryOptions, c as Migration, d as MigrationStep, f as defineMigration, i as MigrationHistory, l as MigrationChange, n as MigrationTargetDb, o as MigrationLoader, r as MigrationTargetOptions, s as defineMigrations, t as MigrationTarget, u as MigrationDatabase } from "./target-iyJah0hO.mjs";
+/** Builds a step that adds a column of a SQL definition, such as `"text NOT NULL DEFAULT ''"`, to a table, and drops it on rollback. */
+export declare function addColumn(table: string, column: string, definition: string): MigrationStep;
+/**
+ * Builds a step that drops a column of a table, and adds it again on rollback as `addColumn` of the same arguments does.
+ *
+ * Rollback restores neither the values of the column nor the indexes and constraints on it that its definition does not describe.
+ */
+export declare function dropColumn(table: string, column: string, definition: string): MigrationStep;
+/** Builds a step that renames a column of a table, and renames it back on rollback. */
+export declare function renameColumn(table: string, from: string, to: string): MigrationStep;
+/** State of a column that `changeColumn` changes from or to: the properties that change, each given in both states. */
+interface ColumnState {
+  /** SQL type, such as `"integer"`. */
+  type?: string;
+  /** SQL expression that converts the values of the column to `type`, such as `"position::integer"`, for a change to this state. */
+  using?: string;
+  notNull?: boolean;
+  /** SQL expression of the default, such as `"0"`, or `null` for no default. */
+  default?: string | null;
+}
+/**
+ * Builds a step that changes the type, the nullability, or the default of a column from state `from` to state `to`, and changes it back on rollback.
+ *
+ * A property that changes must be in both states, and `using` of a state requires a change of type: `up` converts the values with `using` of `to`, and `down` with that of `from`.
+ * It throws when the states change nothing.
+ */
+export declare function changeColumn(table: string, column: string, from: ColumnState, to: ColumnState): MigrationStep;
+/** Builds a step that adds a constraint of a SQL definition, such as `"CHECK (price > 0)"`, to a table, and drops it on rollback. */
+export declare function addConstraint(table: string, name: string, definition: string): MigrationStep;
+/** Builds a step that drops a constraint of a table, and adds it again on rollback as `addConstraint` of the same arguments does. */
+export declare function dropConstraint(table: string, name: string, definition: string): MigrationStep;
+/** Builds a step that replaces the definition of a constraint of a table, keeping its name, and restores it on rollback. */
+export declare function changeConstraint(table: string, name: string, from: string, to: string): MigrationStep;
+/** Options of `createExtension`. */
+interface ExtensionOptions {
+  /** PostgreSQL schema of the objects of the extension, such as `"extensions"`, which the step creates when it is missing; without it, the first schema of the search path, which is the target schema of the migration. */
+  schema?: string;
+}
+/**
+ * Builds a step that creates a PostgreSQL extension unless it exists, with its schema when the schema is missing, and does nothing on rollback, since an extension and its schema belong to the whole database, such as to every tenant.
+ *
+ * It sends no notice for an existing extension, unlike `CREATE EXTENSION IF NOT EXISTS`, which postgres.js would log at every target.
+ * Migrations of different targets that create a missing extension at once wait for each other instead of failing on the duplicate.
+ */
+export declare function createExtension(name: string, options?: ExtensionOptions): MigrationStep;
+/** Options of `createIndex` and `dropIndex`. */
+interface IndexOptions {
+  /**
+   * Name of the index.
+   *
+   * Without it, the name is the one that PostgreSQL gives an index without a name, `<table>_<columns>_idx` of the columns and the `include` columns, such as `form_field_form_id_idx`.
+   * The name is required when an element is not a lowercase column name, with an optional ordering such as `DESC`, when a column repeats, or when the name would be longer than 63 bytes.
+   */
+  name?: string;
+  unique?: boolean;
+  /** Treats `NULL` values as equal when a unique index compares keys. */
+  nullsNotDistinct?: boolean;
+  /** Index method, such as `"gin"`. */
+  using?: string;
+  /** Columns that the index stores without searching by them, each a SQL reference to a column, such as `"label"`. */
+  include?: readonly string[];
+  /** SQL condition of a partial index, such as `"deleted_at IS NULL"`. */
+  where?: string;
+  /**
+   * Builds and drops the index without blocking writes to the table, with `CREATE INDEX CONCURRENTLY` and `DROP INDEX CONCURRENTLY`, when `migrate`, `rollback`, or `redo` runs outside a transaction; inside a transaction, the step builds and drops the index as without this option.
+   *
+   * A build after a failed one first drops the index that the failed build left not valid; a valid index of the name on the table counts as built.
+   * PostgreSQL rejects it for a partitioned table.
+   */
+  concurrently?: boolean;
+}
+/**
+ * Builds a step that creates an index of a table, and drops it on rollback.
+ *
+ * `columns` are the SQL elements of the index: columns or expressions, with their ordering, such as `["form_id", "position DESC"]`, `["lower(email)"]`, or `["(true)"]`.
+ */
+export declare function createIndex(table: string, columns: readonly string[], options?: IndexOptions): MigrationStep;
+/**
+ * Builds a step that drops an index of a table, and creates it again on rollback as `createIndex` of the same arguments does.
+ *
+ * It drops the index of the name that `createIndex` gives it, and with `concurrently`, drops and builds it as `createIndex` does.
+ */
+export declare function dropIndex(table: string, columns: readonly string[], options?: IndexOptions): MigrationStep;
+/**
+ * Inverts a step: its `down` becomes `up`, and its `up` becomes `down`, also of its changes outside a transaction, such as to build a helper that drops what another helper creates.
+ *
+ * It throws for a step without `down`, which gives nothing to apply, and for a value that is not a step, such as one with a misspelled `down`, which the inverted step would hide.
+ */
+export declare function invertStep(step: MigrationStep): MigrationStep;
+/**
+ * Combines steps into one step: its `up` runs the `up` of the steps in order, and its `down` runs the `down` of those that have one in reverse order.
+ *
+ * A direction whose changes are all SQL scripts is one script of them; otherwise, it is a function that runs them in order.
+ * The step has no `down` when no step has one.
+ * It throws for a value that is not a step, such as one with a misspelled `down`, which the combined step would hide, and for a step with changes outside a transaction, which runs alone in its migration.
+ */
+export declare function combineSteps(...steps: readonly MigrationStep[]): MigrationStep;
+/** Options of `createTable` and `dropTable`. */
+interface TableOptions {
+  /** Constraints of the table by name, each a SQL definition, such as `{ form_field_position_key: "UNIQUE (form_id, position)" }`. */
+  constraints?: Readonly<Record<string, string>>;
+}
+/**
+ * Builds a step that creates a table, and drops it on rollback.
+ *
+ * `columns` gives the SQL definition of each column by its name, such as `{ name: "text NOT NULL" }`.
+ */
+export declare function createTable(table: string, columns: Readonly<Record<string, string>>, options?: TableOptions): MigrationStep;
+/**
+ * Builds a step that drops a table, and creates it again on rollback as `createTable` of the same arguments does.
+ *
+ * Rollback restores neither the rows of the table nor its indexes and constraints that the arguments do not describe.
+ */
+export declare function dropTable(table: string, columns: Readonly<Record<string, string>>, options?: TableOptions): MigrationStep;
+/** Builds a step that renames a table, and renames it back on rollback. */
+export declare function renameTable(from: string, to: string): MigrationStep;
+/** Options of `migrate`. */
+interface MigrateOptions extends MigrationTargetOptions {
+  /** Number of the first pending migrations to apply; all by default. */
+  count?: number;
+}
+/** Options of `rollback`. */
+interface RollbackOptions extends MigrationTargetOptions {
+  /** Number of the last applied migrations to roll back, or `"all"`; one by default. */
+  count?: number | "all";
+}
+/** Options of `redo`. */
+interface RedoOptions extends MigrationTargetOptions {
+  /** Number of the last applied migrations to roll back and apply again; one by default. */
+  count?: number;
+}
+/** Migrations of a history as a target has applied them. */
+interface MigrationStatus {
+  /** PostgreSQL schema of the target that the call resolved, such as `current_schema()` of a `Database`. */
+  readonly schemaName: string;
+  /** Keys of the applied migrations of the history, in order. */
+  readonly applied: readonly string[];
+  /** Keys of the migrations of the history that the target has not applied, in order. */
+  readonly pending: readonly string[];
+  /** Applied keys that the history lacks, such as of migrations that a newer version of the application has applied. */
+  readonly unknown: readonly string[];
+}
+/**
+ * Applies the pending migrations of `history` to `target`, or the first `count` of them, and resolves to their keys.
+ *
+ * It applies them in one transaction, unless a migration runs outside a transaction: that migration runs alone, after the migrations before it commit, and the migrations after it run in a transaction of their own.
+ * Inside a transaction, it runs in a nested transaction, so that the migrations commit or roll back with the enclosing one, and every migration runs in it.
+ * A target that is up to date costs two statements outside a transaction; otherwise, it locks the target, so that processes that migrate it at once apply each migration once.
+ * It rejects when the target has applied a migration that the history lacks before its last migration, or a migration after a pending one; applied migrations after the last one, such as of a newer version of the application, are allowed.
+ * In a transaction at `repeatable read` or `serializable`, it rejects when it has migrations to apply, before it locks the target, since the snapshot of the transaction misses the migrations that another process applies meanwhile.
+ */
+export declare function migrate(target: MigrationTarget, history: MigrationHistory, options?: MigrateOptions): Promise<string[]>;
+/**
+ * Rolls back the last applied migrations of `target`, one by default, and resolves to their keys in the order of rolling back.
+ *
+ * It rolls them back in one transaction, unless a migration runs outside a transaction, as `migrate` applies them.
+ * It rejects when the target has applied a migration that the history lacks, since it cannot roll it back.
+ * In a transaction at `repeatable read` or `serializable`, it rejects when the target has applied migrations, before it locks the target.
+ */
+export declare function rollback(target: MigrationTarget, history: MigrationHistory, options?: RollbackOptions): Promise<string[]>;
+/**
+ * Rolls back the last applied migrations of `target` and applies them again, one by default, and resolves to their keys in order.
+ *
+ * It runs them in one transaction, unless a migration runs outside a transaction, as `migrate` applies them.
+ * It rejects when the target has applied a migration that the history lacks, since it cannot roll it back.
+ * In a transaction at `repeatable read` or `serializable`, it rejects when the target has applied migrations, before it locks the target.
+ */
+export declare function redo(target: MigrationTarget, history: MigrationHistory, options?: RedoOptions): Promise<string[]>;
+/** Lists the applied and the pending migrations of `history` on `target`, and the applied migrations that the history lacks. */
+export declare function getMigrationStatus(target: MigrationTarget, history: MigrationHistory, options?: MigrationTargetOptions): Promise<MigrationStatus>;
+/**
+ * Quotes a PostgreSQL identifier, such as the name of a schema or a table, so that it keeps its case and characters.
+ *
+ * It throws for an empty name, which PostgreSQL rejects, so that a helper with a name left blank fails when its migration loads rather than when it runs.
+ */
+export declare function quoteIdentifier(name: string): string;
+/**
+ * Quotes a string as a PostgreSQL string literal, as `quote_literal` of PostgreSQL does.
+ *
+ * It doubles quotes and backslashes, and prefixes `E` to a literal with a backslash, so that the literal keeps its value whatever `standard_conforming_strings` is.
+ */
+export declare function quoteLiteral(value: string): string;
+export { type ColumnState, type ExtensionOptions, type IndexOptions, type MigrateOptions, type Migration, type MigrationChange, type MigrationDatabase, type MigrationDirection, MigrationError, type MigrationHistory, type MigrationHistoryOptions, type MigrationLoader, type MigrationStatus, type MigrationStep, type MigrationTarget, type MigrationTargetDb, type MigrationTargetOptions, type RedoOptions, type RollbackOptions, type TableOptions, defineMigration, defineMigrations };