An association is a logical relationship between two entities.

As of the current version, Hanami supports associations as an experimental feature only for the SQL adapter.


Because the association is made of data linked together in a database, we define associations in repositories.

Explicit Interface

When we declare an association, that repository does NOT get any extra method to its public interface. This because Hanami wants to prevent to bloat in repositories by adding methods that are often never used.

When we define an association, the repository doesn't get any extra public methods.

If we need to create an author, contextually with a few books, we need to explicitly define a method to perform that operation.

Explicit Loading

The same principle applies to read operations: if we want to eager load an author with the associated books, we need an explicit method to do so.

If we don't explicitly load that books, then the resulting data will be nil.

No Proxy Loader

Please remember that operations on associations are made via explicit repository methods. Hanami does NOT support by design, the following use cases:

Please remember that author.books is just an array, its mutation won't be reflected in the database.

Types Of Associations

Looking for Lotus? We renamed the project and it's now called Hanami. Read the announcement.