define-relation

Use this skill when defining ROM Relations that map to database tables in Hanami 2.x.

Core principle: The Relation is the query layer. It defines how to read and filter data, not business logic.

---

Quick Reference

---

Core Rules

1. Create the Relation file in the app or slice:

   # app/relations/users.rb
   # frozen_string_literal: true
   
   module MyApp
     module Relations
       class Users < Hanami::DB::Relation
         schema :users, infer: true
       end
     end
   end

2. Use infer: true for new tables where the database schema is the source of truth. ROM will introspect the table at boot.

3. Define explicit schema when you need custom type coercion or virtual attributes:

   schema :users do
     attribute :id, Types::Integer
     attribute :email, Types::String
     attribute :created_at, Types::Time
   end

4. Add query methods for reusable filters. Encapsulate all query filters inside public relation methods — keep business logic, validations, and side effects out of Relations:

   def active
     where(status: "active")
   end
   
   def by_email(email)
     where(email: email)
   end

5. Define associations: Use the association DSL macros for basic and advanced linkage between tables:

   associations do
     # Basic cases
     many_to_one :users, as: :author
     one_to_many :posts, as: :posts
   
     # Aliased foreign key
     many_to_one :users, foreign_key: :author_id, as: :author
   
     # Nested / through association
     one_to_many :comments, through: :posts
   end

   Loading strategies: use combine to eagerly load associations in a single composed query, or load to issue a separate query:

   # In a repository or relation method:
   users.combine(:posts)           # eager-load posts into each user struct
   users.combine(posts: :comments) # nested eager-load

6. Keep Relations in sync with migrations: If not using infer: true, manually sync explicit schema declarations when migrations alter the database. Verify using the console:

   bundle exec hanami console
   # check app["relations.users"].schema

   If schema mismatch or boot failure: check migration status → run pending migrations (bundle exec hanami db migrate) → restart the console → re-verify the schema. If infer: true fails at boot, confirm the table exists in the database and that the connection configuration is correct.

---

Common Mistakes

---

For detailed relation pattern examples, see RELATIONS.md.

Integration