igmarin add-table-column
Use this workflow when adding a column to an existing table in Hanami 2.x.
Core principle: Schema changes cascade through the data layer. Update the database, then Relations, Entities, Repositories, and tests.
Core Process
| Step | Skill | What to do | Handoff Condition |
|---|---|---|---|
| 1. Generate migration | write-migration |
hanami generate migration add_bio_to_users; write the migration body |
Migration file exists and is valid |
| 2. Run migration | manage-database |
hanami db migrate; verify schema change in database |
Schema updated in database |
| 3. Update Relation | define-relation |
If explicit schema, add new column; if infer: true, auto-updated at boot |
Relation includes new column |
| 4. Update Entity | define-entity |
Add attribute: attribute :bio, Types::String.optional |
Entity includes new attribute |
| 5. Update Repository | create-repository |
Update query/create/update methods if new column affects filtering or is required | Repository methods handle new column |
| 6. Write Tests | write-request-spec |
Update request specs to assert on new column; test persistence and return | All tests pass |
Complete Migration File Example
# db/migrate/20240601120000_add_bio_to_users.rb
Rom::SQL::Migration do
change do
alter_table(:users) do
add_column :bio, :text, null: true
end
end
end
For a NOT NULL column on a populated table, use a three-step approach:
# Step 1: Add as nullable with a default
alter_table(:users) do
add_column :bio, :text, null: true, default: ''
end
# Step 2: Backfill existing rows (separate migration or script)
# Step 3: Add NOT NULL constraint after backfill
alter_table(:users) do
set_column_not_null :bio
end
Pitfalls
| Mistake / Red Flag | Correct Approach |
|---|---|
| Entity updated before migration applied | The migration must be applied before the Entity can reference the new column. |
| Repository not updated for new column | If the new column affects queries or required fields, the Repository must be updated. |
| Tests not updated | Tests must assert on the new column. Update existing specs and add new ones. |
NOT NULL column added without a default on a populated table |
Adding NOT NULL without a default fails on existing rows. Add a default or make it nullable first, backfill, then add NOT NULL. |
| Missing backfill strategy for existing data | Plan a backfill step in a separate migration or script before enforcing constraints. |