createSqliteMigrator

FunctionExperimental

Signature

function createSqliteMigrator<TStateProvider>(options): Migrator<ProviderMode<TStateProvider>>;

sqlite/src/migration-store/migration-store.sqlite.ts:311

Create a migrator for your application's own migrations, kept in SQLite through the state provider you pass to the state adapter. The migrator follows the provider's mode.

The migrator creates its history and lock tables on the first run, if they are missing. Each migration transaction writes to the lock table first, so it takes SQLite's write lock before it reads the history. Set the driver's busy timeout longer than your longest migration transaction, or a waiting process fails with SQLITE_BUSY instead of waiting its turn.

  • Over a SqliteStateProvider it returns a Migrator. Every run claims a lease row in the lock table first, so processes migrating at once take turns: one migrates and extends the lease while it works, the others wait and then skip what it applied.
  • Over a SqliteStateProvider with sync: true it takes synchronous migrations and returns a Migrator<"sync">, whose migrateToLatest and migrateTo return their results directly. It takes no lease: each transactional migration still takes SQLite's write lock before it reads the history, so processes migrating at once apply it once, but a non-transactional migration can run in two of them. Migrate from one process when you have those.

Inside a transactional migration, run queries only through the txCtx that up and down receive. An asynchronous provider holds its write lock for the whole transaction, so a query through the outer client, or taking the provider's lock again, waits forever.

Type Parameters

Parameters

  • options
    SqliteMigratorOptions<TStateProvider>
    Migrator configuration.

Returns

Migrator<ProviderMode<TStateProvider>>

Throws

  • Error if a table name is not a plain SQL identifier, or if two migrations share a name or a name is empty.
  • TypeError if a lock timing is not a positive finite number, or heartbeatIntervalMs is not below a third of ttlMs.

Example

TypeScript

const migrator = createSqliteMigrator({
  stateProvider,
  migrations: [
    {
      name: "create_invoices",
      up: ({ db }) => {
        db.exec("CREATE TABLE invoices (id TEXT PRIMARY KEY, total_cents INTEGER NOT NULL)");
      },
      down: ({ db }) => {
        db.exec("DROP TABLE invoices");
      },
    },
  ],
});
migrator.migrateToLatest();

Used in guides

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open