write-migration

Use this skill when writing or running Sequel database migrations in Hanami 2.x.

Core principle: Sequel migration DSL is provided by jeremyevans/sequel — not ActiveRecord. Never use ActiveRecord syntax here.

Quick Reference

Core Rules

1. Generate the migration file using the Hanami CLI:

   hanami generate migration <migration_name>

   This creates db/migrate/<timestamp>_<migration_name>.rb.

2. Open the generated file and write the migration body inside the Sequel.migration block. Prefer change { } for reversible operations.

3. Define the schema change using the Sequel DSL. Always specify column types explicitly — do not rely on inference.

4. Run the migration:

   hanami db migrate

5. Verify the schema change in the database or via hanami console:

   Hanami.app["db.rom"].relations[:users].schema.to_h

6. Update the ROM Relation (define-relation) to reflect any new or removed columns. The Relation schema must stay in sync with the database.

7. Update Entities and Structs (define-entity) if attribute lists change.

8. Run the test suite to confirm nothing is broken.

Common Mistakes & Red Flags

Integration

Reference Files

• RAILS_MAPPING.md — Side-by-side Rails (ActiveRecord) → Hanami 2.x (Sequel) syntax reference.
• COLUMN_TYPES.md — Sequel generic column types and database mappings.

Examples

Create a table with a primary key and columns

# db/migrate/20240601120000_create_users.rb

Sequel.migration do
  change do
    # create_table takes a symbol matching the intended table name
    create_table(:users) do
      # primary_key generates an auto-incrementing integer PK named :id
      primary_key :id

      # column :name, :type — always specify type explicitly
      column :email,      :text,    null: false
      column :first_name, :text,    null: false
      column :last_name,  :text,    null: false
      column :role,       :text,    null: false, default: "member"
      column :created_at, :timestamptz, null: false
      column :updated_at, :timestamptz, null: false

      # unique constraint on a single column
      unique [:email]
    end
  end
end

Add a column to an existing table (reversible)

# db/migrate/20240602090000_add_bio_to_users.rb

Sequel.migration do
  change do
    # alter_table wraps all modifications to an existing table
    alter_table(:users) do
      # add_column :name, :type, options
      add_column :bio, :text, null: true
    end
  end
end

Drop a column (irreversible — use up/down)

# db/migrate/20240603100000_remove_legacy_token_from_users.rb

Sequel.migration do
  up do
    alter_table(:users) do
      drop_column :legacy_token
    end
  end

  down do
    alter_table(:users) do
      add_column :legacy_token, :text, null: true
    end
  end
end