Skip to main content

DbMigrator

Applies a versioned migration package to a database. Extends AsyncEventEmitter (from strict-typed-events), so every listener registered with on() may itself be async — execute() awaits each one in turn as it emits lifecycle events.

connection.dialect selects the migration adapter: PostgreSQL, Oracle, MySQL, MariaDB, SQL Server, and SQLite are all supported (since v6.0.8); for SQLite, connection.driver ('sqlite' or 'sqljs') tells the two SQLite adapters apart. See Running Migrations for what differs per dialect.

Constructor​

new DbMigrator()

Takes no arguments.

import { DbMigrator } from '@sqb/migrator';

const migrator = new DbMigrator();

Methods​

execute()​

Applies pending migrations from a migration package to the database described by options.connection, up to options.targetVersion (or the package's highest version, if omitted).

execute(options: DbMigratorOptions): Promise<boolean>

ArgumentTypeDefaultDescription
optionsDbMigratorOptionsConnection, migration package, and execution options
  • Returns Promise<boolean> — resolves to true once the target version has been reached.

Throws:

  • TypeError — connection.dialect is missing, or is a dialect with no migration adapter (anything other than 'postgres', 'oracle', 'mysql', 'mariadb', 'mssql', or 'sqlite'); or (since v6.3.0) options.transaction is a mode the adapter does not support, or options.dryRun is combined with a transaction mode other than 'run'.
  • Error — targetVersion is lower than the migration package's lowest version, or the database's current version is more than one version behind the package's lowest version; in a transactional run, a pending script holds a statement that cannot run inside a transaction block; or a migration is flagged backup: true (no adapter implements a backup — since v6.3.0).
  • Whatever error a task itself throws (a SQL error, a rejected custom fn, etc.), after writing an error event row to the migration_events table (after the rollback, in a transactional run; not at all in a dry run) and — if a backup was taken — emitting restore and calling the adapter's restoreDatabase().
import '@sqb/postgres';
import { DbMigrator } from '@sqb/migrator';
import { myMigrationPackage } from './migrations/index.js';

const migrator = new DbMigrator();
migrator.on('task-start', ({ task }) => console.log('Running', task.title));

await migrator.execute({
  connection: { dialect: 'postgres', database: 'my_database' },
  migrationPackage: myMigrationPackage,
  targetVersion: 14,
});

Events​

DbMigrator is an AsyncEventEmitter — register listeners with .on(event, handler), where handler may be async (it is awaited before the migration proceeds).

EventPayloadEmitted
start—Once, at the beginning of execute().
backup—Only if some migration in the package has backup: true, before the adapter's backupDatabase() runs.
migration-start{ migration: Migration; total: number; index: number }Before a migration's tasks run.
task-start{ migration: Migration; task: MigrationTask; total: number; index: number }Before a task runs.
task-finish{ migration: Migration; task: MigrationTask; total: number; index: number }After a task completes successfully.
migration-finish{ migration: Migration; total: number; index: number }After a migration's tasks all complete.
commit—A transaction of a transactional run was committed (since v6.3.0).
rollback—A transaction was rolled back, on failure or at the end of a dry run (since v6.3.0).
restore—Only on failure, and only if a backup was taken, before the adapter's restoreDatabase() runs.
finish—Once, after every targeted migration has been applied.

See Running Migrations for the full execution order and a usage example.

See also​