@talosjs/migrations package is a database migration runner for Bun’s native SQL client. A migration is a class implementing IMigration with up and down methods, a timestamp-based version, and an optional dependency list. Migrations are registered with a decorator, sorted by version, and run inside a transaction. Applied versions are tracked in a database table so each one runs exactly once.
How migrations behave
Every migration carries a timestamp version (YYYYMMDDHHMMSSMMM), and the runner sorts by version before applying migrations in order. The up() method applies a change and down() reverses it, which keeps schema changes symmetric and reviewable. Each migration runs inside sql.begin(), so a failure rolls back the whole migration and stops the run. Applied versions are recorded in a tracking table (default migrations), and anything already applied is skipped on the next run.
A migration can also declare other migrations as dependencies, and those run first regardless of timestamp. As with the rest of the framework, you register a migration class with a decorator and the runner resolves it from the container.
The IMigration contract
A migration is a class that satisfies IMigration from @talosjs/migrations:
The tracking table
The runner records one row per applied version in a tracking table (defaultmigrations, id VARCHAR(20) PRIMARY KEY), creating it if it is missing. Before running a migration, the runner checks the table for its id; if it is already there, the migration is skipped. Rolling a migration back deletes its row, so a later migration:up re-applies it.
Environment variables
Next steps
- Writing migrations: scaffold a migration and implement
up(),down(), and dependency ordering. - Running migrations: apply pending migrations across every module with
talos migration:up. - Rolling back: reverse an applied migration with
talos migration:down. - Caching: how the per-version run cache skips unchanged migrations.
@talosjs/migrationscomponent: the full package reference.