Skip to main content

​
Overview

The Migrator class provides methods for managing database migrations. It handles migration execution, rollback, and tracking of migration state.

​
Constructor

new Migrator(props: MigratorProps)
Creates a new Migrator instance.

​
Example

import { promises as fs } from 'node:fs'
import path from 'node:path'
import * as Sqlite from 'better-sqlite3'
import {
  FileMigrationProvider,
  Kysely,
  Migrator,
  SqliteDialect
} from 'kysely'

const db = new Kysely<any>({
  dialect: new SqliteDialect({
    database: Sqlite(':memory:')
  })
})

const migrator = new Migrator({
  db,
  provider: new FileMigrationProvider({
    fs,
    path,
    migrationFolder: 'some/path/to/migrations',
  })
})

​
Configuration

​
MigratorProps

​
db
Kysely<any>
required
The Kysely database instance to run migrations against.
​
provider
MigrationProvider
required
A migration provider that supplies migrations to execute. Use FileMigrationProvider to load migrations from a folder.
​
migrationTableName
string
default:"kysely_migration"
The name of the internal migration table.Warning: If you specify this, you must ALWAYS use the same value. Changing it after migrations have run will cause Kysely to create a new empty migration table and attempt to re-run migrations.
​
migrationLockTableName
string
default:"kysely_migration_lock"
The name of the internal migration lock table.Warning: If you specify this, you must ALWAYS use the same value from the beginning of the project.
​
migrationTableSchema
string
The schema of the internal migration tables. Defaults to the default schema on dialects that support schemas.Only works on PostgreSQL and MSSQL.Warning: If you specify this, you must ALWAYS use the same value. Changing it will create new migration tables in the new schema.
​
allowUnorderedMigrations
boolean
default:false
Enforces whether or not migrations must be run in alpha-numeric order.
  • When false (default): migrations must be run in exact alpha-numeric order, checked against already-run migrations in the database. This is the safest option.
  • When true: migrations are still run in alpha-numeric order, but the order is not validated against the database. Kysely will simply run all pending migrations in alpha-numeric order.
​
nameComparator
(name0: string, name1: string) => number
A function that compares migration names when sorting migrations in ascending order.Default is name0.localeCompare(name1).
​
disableTransactions
boolean
default:false
When true, don’t run migrations in transactions even if the dialect supports transactional DDL.Useful when some migrations include queries that would fail in a transaction.

​
Methods

​
getMigrations()

getMigrations(): Promise<ReadonlyArray<MigrationInfo>>
Returns a MigrationInfo object for each migration. The returned array is sorted by migration name.
​
name
string
Name of the migration.
​
migration
Migration
The actual migration object.
​
executedAt
Date | undefined
When the migration was executed. undefined if the migration hasn’t been executed yet.

​
migrateToLatest()

migrateToLatest(): Promise<MigrationResultSet>
Runs all migrations that have not yet been run. This method returns a MigrationResultSet instance and never throws. MigrationResultSet.error holds the error if something went wrong. MigrationResultSet.results contains information about which migrations were executed and which failed. This method goes through all possible migrations provided by the provider and runs the ones whose names come alphabetically after the last migration that has been run.

​
Example

const { error, results } = await migrator.migrateToLatest()

results?.forEach((it) => {
  if (it.status === 'Success') {
    console.log(`migration "${it.migrationName}" was executed successfully`)
  } else if (it.status === 'Error') {
    console.error(`failed to execute migration "${it.migrationName}"`)
  }
})

if (error) {
  console.error('failed to run `migrateToLatest`')
  console.error(error)
}

​
migrateTo()

migrateTo(targetMigrationName: string | NoMigrations): Promise<MigrationResultSet>
Migrate up or down to a specific migration. This method returns a MigrationResultSet instance and never throws.

​
Parameters

​
targetMigrationName
string | NoMigrations
required
The name of the target migration, or NO_MIGRATIONS to migrate all the way down.

​
Examples

Migrate to a specific migration: 
await migrator.migrateTo('some_migration')
Migrate all the way down: If you specify the name of the first migration, this method migrates down to the first migration, but doesn’t run the down method of the first migration. To migrate all the way down, use the NO_MIGRATIONS constant: 
import { NO_MIGRATIONS } from 'kysely'

await migrator.migrateTo(NO_MIGRATIONS)

​
migrateUp()

migrateUp(): Promise<MigrationResultSet>
Migrate one step up. This method returns a MigrationResultSet instance and never throws.

​
Example

await migrator.migrateUp()

​
migrateDown()

migrateDown(): Promise<MigrationResultSet>
Migrate one step down. This method returns a MigrationResultSet instance and never throws.

​
Example

await migrator.migrateDown()

​
Types

​
MigrationResultSet

All migration methods return this object instead of throwing errors.
​
error
unknown
Defined if something went wrong. An error may have occurred in one of the migrations (check results for which one) or before Kysely could determine which migrations to execute (in which case results is undefined).
​
results
MigrationResult[]
MigrationResult for each individual migration that was supposed to be executed.
  • If all went well, each result’s status is Success
  • If a migration failed, the failed migration’s result has status of Error and all subsequent results have status of NotExecuted
  • Can be undefined if an error occurred before determining which migrations to execute
  • Empty array if there were no migrations to execute

​
MigrationResult

​
migrationName
string
The name of the migration.
​
direction
'Up' | 'Down'
The direction in which this migration was executed.
​
status
'Success' | 'Error' | 'NotExecuted'
The execution status:
  • Success: migration was successfully executed (note: may be rolled back if a later migration failed and dialect supports transactional DDL)
  • Error: migration failed (see MigrationResultSet.error for details)
  • NotExecuted: migration was supposed to be executed but wasn’t because an earlier migration failed

​
Migration

Interface that all migrations must implement. 
interface Migration {
  up(db: Kysely<any>): Promise<void>
  down?(db: Kysely<any>): Promise<void>
}
​
up
(db: Kysely<any>) => Promise<void>
required
Method to run when migrating up.
​
down
(db: Kysely<any>) => Promise<void>
Optional method to run when migrating down. If not provided, the migration is skipped when migrating down.

​
MigrationInfo

Information about a migration returned by getMigrations().
​
name
string
Name of the migration.
​
migration
Migration
The actual migration object.
​
executedAt
Date | undefined
When the migration was executed. undefined if not yet executed.

​
Constants

​
NO_MIGRATIONS

const NO_MIGRATIONS: NoMigrations
Special constant used with migrateTo() to migrate all the way down (rolling back all migrations).

​
DEFAULT_MIGRATION_TABLE

const DEFAULT_MIGRATION_TABLE = 'kysely_migration'
The default name for the migration tracking table.

​
DEFAULT_MIGRATION_LOCK_TABLE

const DEFAULT_MIGRATION_LOCK_TABLE = 'kysely_migration_lock'
The default name for the migration lock table.

​
DEFAULT_ALLOW_UNORDERED_MIGRATIONS

const DEFAULT_ALLOW_UNORDERED_MIGRATIONS = false
The default value for the allowUnorderedMigrations option.

Build docs developers (and LLMs) love

Get started for freeTalk to us