Migrations

Database migrations are versioned changes to your database schema. Shiva uses a sequential migration system — each migration has an up and down function.

Creating a Migration

shiva make migration my-module create_my_table
# Creates: migrations/001_create_my_table.lua

Migration File Format

-- migrations/001_create_my_table.lua
return {
    up = function(db)
        db:execute([[
            CREATE TABLE my_table (
                id         INT AUTO_INCREMENT PRIMARY KEY,
                player_id  INT NOT NULL,
                value      VARCHAR(255) NOT NULL,
                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
                INDEX idx_player_id (player_id)
            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
        ]])
    end,
    down = function(db)
        db:execute('DROP TABLE IF EXISTS my_table')
    end,
}

Running Migrations

shiva migrate                  # run all pending
shiva migrate --module my-module   # run for one module only
shiva migrate --status         # show migration status
shiva migrate --rollback       # roll back last batch
shiva migrate --rollback --steps 3  # roll back last 3

Migration Rules

• Additive by default — up should only add tables/columns
• Destructive requires a flag — dropping columns runs only with shiva migrate --destructive
• Never edit a run migration — create a new one instead
• Always write down — rollbacks must work

Naming Conventions

Migration files are numbered sequentially. Names should describe what changed:

001_create_players.lua
002_add_character_id_to_players.lua
003_create_accounts.lua
004_add_index_to_accounts.lua

See Also

• CLI: shiva migrate →
• API: Database →