Hanami::Model
A Ruby persistence framework for Hanami 1.x applications, using entities and repositories to separate domain logic from storage details.
What is Hanami::Model?
Hanami::Model is a Ruby persistence framework that provides entities and repositories to handle data storage in Hanami 1.x applications. It separates domain logic from persistence details, allowing developers to focus on business behaviors while abstracting database interactions. The framework supports SQL adapters and includes features like automapping and automatic timestamp management.
Ruby developers building applications with the Hanami 1.x framework who need a structured, clean architecture for data persistence. It's suited for projects emphasizing Domain-Driven Design and separation of concerns.
Developers choose Hanami::Model for its strict separation between entities (domain logic) and repositories (persistence), which reduces coupling and improves testability. Its repository pattern provides a stable, storage-independent API, making it easier to switch databases or handle legacy schemas without affecting application code.
Overview
Ruby persistence framework with entities and repositories
Use Cases
Best For
- Building Hanami 1.x applications with clean architecture
- Implementing Domain-Driven Design patterns in Ruby
- Abstracting database interactions with storage-independent repositories
- Managing legacy database schemas with custom mapping
- Separating business logic from persistence concerns
- Creating testable data layers with intention-revealing APIs
Not Ideal For
- Starting new projects with Hanami 2.x or planning framework upgrades
- Applications requiring long-term maintenance, security patches, or active community support
- Teams using Ruby 3.x or later versions due to compatibility restrictions
- Projects preferring ActiveRecord's convention-over-configuration for rapid prototyping without explicit repository patterns
Pros & Cons
Pros
Strictly separates domain logic (entities) from persistence (repositories), aligning with Domain-Driven Design principles as emphasized in the philosophy section, reducing coupling and improving testability.
Repositories abstract database interactions, allowing easy adapter changes without affecting application code, which supports dependency inversion and postpones storage decisions, as described in the repository concepts.
Offers automapping for standard databases and manual mapping overrides for legacy schemas with mismatched column names, demonstrated in the mapping example for cases like :t_user_archive tables.
Automatically updates created_at and updated_at fields when entities are persisted, reducing boilerplate code, as shown in the timestamps feature example with UserRepository.
Cons
Explicitly marked as deprecated with no future updates, making it unsuitable for new projects or those needing ongoing support, as stated in the important notice.
Only compatible with Ruby 2.6 and 2.7, excluding modern Ruby versions, which restricts adoption in current development environments.
Requires mutex synchronization during loading to avoid issues in non-Hanami applications, adding setup overhead and potential for errors in multi-threaded contexts.
Forces developers to define explicit repository methods for all queries instead of allowing chainable methods, which can increase initial development time compared to more flexible ORMs.
Frequently Asked Questions
Related Projects
MongoidThe Official Ruby Object Mapper for MongoDB
ROMData mapping and persistence toolkit for Ruby
Redis-ObjectsMap Redis types directly to Ruby objects
OhmObject-Hash Mapping for Redis
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.