Jennifer Build Status Latest Release Docs

ActiveRecord pattern implementation for Crystal with a powerful query DSL, validation, relationship definition, translation and migration mechanism.


Add this to your application's shard.yml:

    github: imdrasil/
    version: "~> 0.6.2"



Jennifer allows you to maintain everything for your models - from db migrations and field mapping to callbacks and building queries. For detailed information see the guide and API documentation.


To start using Jennifer you'll first need to generate a migration:

$ crystal -- generate:migration CreateContact

then fill the created migration file with content:

class CreateContact < Jennifer::Migration::Base
  def up
    # Postgres requires to create specific enum type
    create_enum(:gender_enum, ["male", "female"])
    create_table(:contacts) do |t|
      t.string :name, {:size => 30}
      t.integer :age
      t.integer :tags, {:array => true}
      t.field :gender, :gender_enum

  def down
    drop_table :contacts

and run

$ crystal -- db:setup

to create the database and run the newly created migration.

For command management Jennifer uses Sam.


Jennifer provides next features:

Hers is model example:

class Contact < Jennifer::Model::Base
    id: Primary32, # is an alias for Int32? primary key
    name: String,
    gender: { type: String?, default: "male" },
    age: { type: Int32, default: 10 },
    description: String?,
    created_at: Time?,
    updated_at: Time?

  has_many :facebook_profiles, FacebookProfile
  has_and_belongs_to_many :countries, Country
  has_and_belongs_to_many :facebook_many_profiles, FacebookProfile, join_foreign: :profile_id
  has_one :passport, Passport

  validates_inclusion :age, 13..75
  validates_length :name, minimum: 1, maximum: 15
  validates_with_method :name_check

  scope :older { |age| where { _age >= age } }
  scope :ordered { order(name: :asc) }

  def name_check
    return unless description && description.not_nil!.size > 10
    errors.add(:description, "Too large description")

More details you can find in the documentation.

Query DSL

Jennifer allows you to query the db using a flexible DSL:

Contact.all.left_join(Passport) { _contact_id == _contact__id }
            .order(id: :asc).order(Contact._name.asc.nulls_last)
Contact.all.eager_load(:countries).where { __countries {"%tan%") } }, PG::Numeric)

Much more about the query DSL can be found on the wiki page.

SQLite Support

SQLite3 has many limitations so adding its support isn't a very easy task, but it is still important to Jennifer.


Now that Jennifer is under heavy development, there could be many breaking changes. So please check the release notes to check if any of the changes may prevent you from using it. Also, until this library reaches a beta version, the next version rules will be followed:

So even a patch version change could bring a lot of new stuff.

If there is a branch for the next release - it will be removed 1 month after the release. So please use them only as a hotfix or for experiments or contribution.

Test tips

The fastest way to rollback all changes in the DB after test case is by using a transaction. So add:

Spec.before_each do

Spec.after_each do

to your NB. you could simply use regular deleting or truncation, but a transaction will provide a 15x speed up (at least for postgres; mysql gets less impact).

This functions can be safely used only under test environment.


Before developing any feature please create an issue where you describe your idea.

Before development create the db user (see /spec/ file) and database:

# Postgres
$ make sam db:setup

# Mysql
$ DB=mysql make same db:setup

Running tests

All unit tests are written using core spec component. Also in spec/ some custom unit test matchers are defined. All migrations are under the ./examples/migrations directory.

The common way to run tests is just use using regular crystal spec tool:

$ crystal spec

PostgreSQL is used by default, but MySql is also supported while running tests by specifying environment variable DB=mysql:

In case you need to set the database user or password, use:

$ DB_USER=user DB_PASSWORD=pass crystal spec

Integration tests

Except unit tests there are also several integration tests. These tests checks possibility to compile and invoke jennifer functionality in some special edge cases (e.g. without defined models, migrations, etc.).

To run integration test just use standard spec runner:

$ crystal spec spec/integration/<test_name>.cr

Each test file is required to be invoked separately as it may have own configuration.

To run docker-related tests (by the way, all of them run only with mysql) firstly you should run docker container and specify environment variable DOCKER=1. For more details take a look at spec/integration/sam/* application files and examples/ docker boot script.


Self documentation is not fully support yet but docs can be compiled using this shell script:

$ ./

NB. It also depends on then chosen adapter (postgres by default).

Similar shards


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Please ask me before starting work on smth.