migration

SQLite schema migrations for the Mule adapter — the SQLite twin of mule/engines/postgres/migration. Mirrors Oban.Migrations.SQLite’s schema (adapted to this port’s conventions) while keeping the Postgres module’s versioned-step machinery, so future schema evolution sequences the same way on both engines.

Differences from the Postgres module, forced by SQLite:

No schema prefixes: SQLite has no schemas, so there are no Prefix/CreateSchema options and no _with variants.
Timestamps are INTEGER epoch microseconds (SQLite has no timestamptz); the engine reads and writes the same representation.
args/meta/tags/errors/attempted_by are TEXT holding JSON (SQLite has no jsonb or arrays); the JSON1 functions query them.
The version ledger is a single-row mule_migrations table rather than a table comment (COMMENT ON does not exist). PRAGMA user_version was rejected because it is database-global and the host application may already use it for its own migrations.

Coexisting with Elixir Oban (`Oban.Engines.Lite`)

Mule’s tables are deliberately named mule_* where Elixir’s are oban_*, so both can live in one database file without collision, with no options required.

The ownership probe remains as a defensive check: before touching anything, migrate/rollback/verify_migrated probe the inserted_at column’s declared type — INTEGER is ours, anything else marks a mule_jobs these migrations did not create, and every entry point refuses with ForeignSchema instead of corrupting it. SQLite has no schema-prefix escape hatch — drop or rename such a table, or give this install its own database file.

Types

MigrationError

</>

Everything migrate/rollback/verify_migrated can report beyond success. MigrationFailed and ForeignSchema come from any entry point; the remaining variants are verify_migrated findings. describe renders each as the message the boot guard prints.

pub type MigrationError {
  MigrationFailed(sqlight.Error)
  ForeignSchema(inserted_at_column_type: String)
  NotMigrated
  MissingLedger
  OutdatedVersion(migrated: Int, target: Int)
}

Constructors

```
MigrationFailed(sqlight.Error)
```
A statement failed; wraps the sqlight error. The walk runs in one transaction, so nothing was applied.
```
ForeignSchema(inserted_at_column_type: String)
```
mule_jobs exists but was not created by these migrations: its inserted_at column is not INTEGER. Refused rather than managed — SQLite has no schema prefixes, so drop or rename the table, or give this port its own database file.
```
NotMigrated
```
verify: the mule_jobs table does not exist — migrations never ran.
```
MissingLedger
```
verify: mule_jobs exists (and is ours) but the mule_migrations ledger is missing — a schema applied by an external runner. Running migrate once converges the guarded steps and stamps the ledger.
```
OutdatedVersion(migrated: Int, target: Int)
```
verify: the ledger is behind this library’s target.

Step

</>

One schema version: its forward and backward SQL as a list of individual statements (one per element), the same shape as the Postgres module’s Step so a future SQLite gen_migration can reuse it.

pub type Step {
  Step(
    version: Int,
    name: String,
    up: List(String),
    down: List(String),
  )
}

Constructors

Step(
  version: Int,
  name: String,
  up: List(String),
  down: List(String),
)

Values

describe

</>

pub fn describe(error error: MigrationError) -> String

Render an error as the human-facing message the boot guard raises with.

migrate

</>

pub fn migrate(
  connection connection: sqlight.Connection,
) -> Result(Int, MigrationError)

Apply every step newer than the recorded version, then stamp the reached version into the ledger. The whole walk runs in one transaction so a failed step rolls back cleanly. Returns the ledger version after the walk: the highest step applied, or the current version untouched when nothing was pending (a ledger ahead of this build is never overwritten backwards).

rollback

</>

pub fn rollback(
  connection connection: sqlight.Connection,
  to target: Int,
) -> Result(Int, MigrationError)

Reverse the schema down to target by running each applied step’s down, newest-first. Rolling back to 0 drops the tables and the ledger; a partial rollback re-stamps the ledger with the new target. A to at or above the current version reverts nothing — rollback never moves the stamp forward.

steps

</>

pub fn steps() -> List(Step)

The ordered schema history. Every statement is guarded (if not exists / if exists) so a re-run against a partially-applied schema converges instead of erroring — the same idempotence property the Postgres steps hold.

target_version

</>

pub fn target_version() -> Int

Highest version known to this build — the target a fresh migrate reaches.

verify_migrated

</>

pub fn verify_migrated(
  connection connection: sqlight.Connection,
) -> Result(Nil, MigrationError)

Check that the database is migrated to this library’s target version — the port of Oban.Migration.verify_migrated!, minus the raise: each finding is a MigrationError variant and describe renders its message. The engine’s verify_migrated hook delegates here.

Coexisting with Elixir Oban (Oban.Engines.Lite)

Constructors

Constructors

Coexisting with Elixir Oban (`Oban.Engines.Lite`)