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:

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

5. Define associations: Link related tables using association DSL macros. For complete association setup and advanced configurations, see RELATIONS.md.

   associations do
     many_to_one :users, as: :author
     one_to_many :posts, as: :posts
   end

6. Filter queries via custom methods: Encapsulate query filters inside public relation methods:

   def active
     where(status: "active")
   end

7. 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

8. Never put business logic in Relations: Relations are the query construction layer. Do not place validations or side effects here; those belong in Operations, Repositories, or actions.

---

Common Mistakes

---

Integration