Migration

Database migration framework with transaction support, rollback capabilities, and multi-engine support.

Installation

entries:
  - name: migration
    kind: ns.dependency
    component: wippy/migration
    version: "*"

Creating Migrations

Create a migration file in your migrations/ folder:

-- migrations/01_create_users_table.lua
return require("migration").define(function()
    migration("Create users table", function()
        database("postgres", function()
            up(function(db)
                local _, err = db:execute([[
                    CREATE TABLE users (
                        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
                        email VARCHAR(255) NOT NULL UNIQUE,
                        created_at TIMESTAMP NOT NULL DEFAULT NOW()
                    )
                ]])
                if err then error(err) end
            end)

            down(function(db)
                local _, err = db:execute("DROP TABLE IF EXISTS users")
                if err then error(err) end
            end)
        end)

        database("sqlite", function()
            up(function(db)
                local _, err = db:execute([[
                    CREATE TABLE users (
                        id TEXT PRIMARY KEY,
                        email TEXT NOT NULL UNIQUE,
                        created_at TEXT NOT NULL DEFAULT (datetime('now'))
                    )
                ]])
                if err then error(err) end
            end)

            down(function(db)
                local _, err = db:execute("DROP TABLE IF EXISTS users")
                if err then error(err) end
            end)
        end)
    end)
end)

Registering Migrations

Add migration entries to your _index.yaml:

entries:
  - name: 01_create_users_table
    kind: function.lua
    meta:
      type: migration
      target_db: app:db
    source: file://migrations/01_create_users_table.lua
    method: run
    imports:
      migration: wippy.migration:migration

DSL Reference

• migration(description, fn) - Define a migration with description
• database(type, fn) - Database-specific implementation ("postgres", "sqlite", etc.)
• up(fn) - Forward migration logic, receives db transaction
• down(fn) - Rollback logic, receives db transaction
• after(fn) - Optional post-migration hook

Running Migrations

Migrations run automatically via the bootloader when your application starts. The bootloader:

• Discovers all migrations targeting configured databases
• Applies pending migrations in order
• Tracks applied migrations in a _migrations table

Manual Execution

local runner = require("runner")

local r = runner.setup("app:db")

-- Find migrations
local result = r:find_migrations()
-- result.pending - migrations to apply
-- result.applied - already applied

-- Run pending migrations
local run_result = r:run()

Transaction Safety

Each migration runs in a transaction:

• up() executes within transaction
• On success, migration is recorded and committed
• On failure, transaction rolls back automatically