migrate

Migration Runner

Manages database schema migrations for Glimr applications. Migrations are SQL files stored in src/data/_migrations/ with timestamped filenames: (e.g., 20251217120000_create_users.sql).

Tracks applied migrations in the _glimr_migrations table to ensure each migration runs only once.

Types

Migration

</>

Migration Type

Represents a database migration loaded from a SQL file. The version is extracted from the filename prefix (timestamp), the name from the remainder of the filename, and sql contains the migration statements to execute.

pub type Migration {
  Migration(version: String, name: String, sql: String)
}

Constructors

Migration(version: String, name: String, sql: String)

MigrationStatus

</>

Migration Status Type

Represents the status of a migration - whether it has been applied to the database or is still pending.

pub type MigrationStatus {
  MigrationStatus(version: String, name: String, applied: Bool)
}

Constructors

MigrationStatus(version: String, name: String, applied: Bool)

Values

main

</>

pub fn main() -> Nil

Main

Entry point for the migration CLI. Run with: gleam run -m glimr/db/migrate

migrate

</>

pub fn migrate(
  conn: connection.Connection,
) -> Result(List(String), connection.DbError)

Migrate

Applies all pending migrations to the database. Creates the migrations tracking table if it doesn’t exist, then runs any migrations that haven’t been applied yet in version order.

Returns a list of version strings for successfully applied migrations, or an error if any migration fails.

Example:

use conn <- pool.get_connection_or(pool)
case migrate.migrate(conn) {
  Ok(applied) -> io.println("Applied " <> int.to_string(list.length(applied)))
  Error(err) -> io.println("Migration failed")
}

rollback

</>

pub fn rollback(
  conn: connection.Connection,
  steps: Int,
) -> Result(List(String), connection.DbError)

Rollback

Removes the last N migrations from the tracking table. Note that this only removes the migration record - it does not reverse the SQL changes. Actual rollback SQL would need to be stored separately or generated.

Returns a list of version strings for rolled-back migrations.

run_fresh

</>

pub fn run_fresh() -> Nil

Run Fresh

CLI command that drops all tables and re-runs all migrations from scratch. For SQLite, deletes the database file. For PostgreSQL, drops all tables in the public schema.

Use this during development to reset the database to a clean state. Do not use in production.

run_migrate

</>

pub fn run_migrate() -> Nil

Run Migrate

CLI command that applies all pending migrations. Loads database configuration from environment variables, connects to the database, and runs pending migrations.

Prints progress to stdout and exits cleanly.

status

</>

pub fn status(
  conn: connection.Connection,
) -> Result(List(MigrationStatus), connection.DbError)

Status

Returns the status of all migrations - both applied and pending. Useful for displaying migration status in CLI tools or admin interfaces.