Module: database/migrationRunner

Versioned, dialect-aware database migration runner.

Implements a standard sequential migration pattern:

  1. A schema_migrations table tracks which migrations have been applied.
  2. Migration files live in migrations/ as numbered .sql files (001_, 002_, …).
  3. On startup, the runner scans for unapplied migrations and executes them in order inside a transaction.
  4. Each migration is recorded with its name and timestamp so the history is auditable.

Dialect awareness (INF-001)

The runner accepts a database adapter (not a raw better-sqlite3 instance). When the adapter's dialect is "postgres", the runner translates SQLite-specific SQL in migration files using the PostgreSQL adapter's translateSql() function before execution.

Adding a new migration

  1. Create backend/src/database/migrations/NNN_description.sql (NNN = zero-padded sequence number, e.g. 002_add_foo_column.sql).
  2. Write idempotent SQL (use IF NOT EXISTS, ALTER TABLE … ADD COLUMN guards).
  3. Restart the server — the migration runs automatically.

Exports

  • runMigrations — Apply all pending migrations.
Source:

Methods

(static) runMigrations(db, optsopt) → {Object}

Apply all pending migrations in order.

Each migration runs inside its own transaction. If a migration fails, that transaction is rolled back and the error is thrown — subsequent migrations are NOT attempted.

Parameters:
Name Type Attributes Description
db Object

— Database adapter instance (SQLite or PostgreSQL).
opts Object <optional>

— Optional overrides.

Properties
Name Type Attributes Description
translateSql function <optional>

— SQL translator for PostgreSQL dialect. When omitted and dialect is "postgres", loaded dynamically from postgres-adapter.
Source:
Returns:
Type
Object

(inner) checksum(sql) → {string}

Compute SHA-256 checksum of a migration file's contents.

Parameters:
Name Type Description
sql string
Source:
Returns:
Type
string

(inner) discoverMigrations() → {Array.<{version: string, filePath: string}>}

Discover all migration files sorted by filename.

Source:
Returns:
Type
Array.<{version: string, filePath: string}>

(inner) ensureMigrationsTable(db)

Ensure the schema_migrations tracking table exists.

Parameters:
Name Type Description
db Object

— Database adapter instance.
Source:

(inner) getAppliedMigrations(db) → {Map.<string, string>}

Get already-applied migrations as a Map of version → checksum.

Parameters:
Name Type Description
db Object

— Database adapter instance.
Source:
Returns:
Type
Map.<string, string>