create-repository

Use this skill when creating ROM Repositories that encapsulate domain-level persistence logic in Hanami 2.x.

---

Quick Reference

---

Essentials

1. Create the Repository file: Place repositories under app/repos/:

   # app/repos/user_repo.rb
   module MyApp
     module Repos
       class UserRepo < Hanami::DB::Repo[:users]
       end
     end
   end

2. Verify container registration: After creating the repository, confirm it is correctly registered in the Hanami container before wiring it into actions. Run in the console:

   MyApp::App["repos.user_repo"]
   # => #<MyApp::Repos::UserRepo ...>

   If this raises a key error, check the file path and module namespace match the expected container key.

3. Inject into Actions: Inject repositories using the container dependency injection (Deps):

   # app/actions/users/index.rb
   class Index < MyApp::Action
     include Deps["repos.user_repo"]
   
     def handle(request, response)
       response.render(view, users: user_repo.all)
     end
   end

4. Add domain methods: Write specific read and write methods to isolate your actions from raw relation access:

   def active
     users.active.to_a
   end
   
   def find_by_email(email)
     users.by_email(email).one
   end

---

Advanced Topics

5. Use transactions for multi-step writes: Wrap mutations in transaction blocks. If the block raises an error, the transaction is automatically rolled back and the error is re-raised.

   transaction do
     accounts.update(from_id, balance: from_account.balance - amount)
     accounts.update(to_id,   balance: to_account.balance + amount)
   end

6. Map to custom Entities: Configure the struct_namespace to automatically map SQL relation rows to custom Entity domain models.

   class UserRepo < Hanami::DB::Repo[:users]
     struct_namespace MyApp::Entities
     auto_struct true
   end

7. Do not expose Relations directly: Actions must fetch and modify data via Repositories. Bypassing repositories to query relations directly in actions/views is an anti-pattern.

---

For detailed repository pattern examples, see REPOSITORIES.md.

Integration