Versioning

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:

all bugfixes, new minor features or (sometimes) ones that don't break the existing API will be added as a patch number (e.g. 0.3.4);

all breaking changes and new important features (as well as reaching a milestone) will be added by bumping the minor digit (0.4.0);

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
Jennifer::Adapter.adapter.begin_transaction
end
Spec.after_each do
Jennifer::Adapter.adapter.rollback_transaction
end

to your spec_helper.cr. 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.

Development

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

To setup dev environment run ./examples/setup.sh - it creates ./examples/database.yml configuration file. You can override there any values specific to your environment (like db user of password).

To create the databases:

# Postgres
$ make sam db:setup
# Mysql
$ DB=mysql make same db:setup

Running tests

All unit tests are written using core spec. Also in spec/spec_helper.cr 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/run_docker_mysql.sh docker boot script.

Documentation

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

$ ./generate-docs.sh

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

Similar shards

crecto - based on Phoenix's Ecto lib and follows the repository pattern

0.4.0 (30-09-2017)

now #eager_load behaves as old variant of #includes - via joining relations and adding them to the SELECT statement (breaking changes)

added #preload method which allows to load all listed relations after execution of main request

new behavior of #includes is same as #preload (breaking changes)

added Jennifer::QueryBuilder::QueryObject which designed to be as a abstract class for query objects for Model::Base scopes (will be renamed in futher releases)

all query related objects are clonable

now GROUP clause is placed right after the WHERE clause

aggregation methods is moved to Jennifer::QueryBuilder::Aggregations module which is included in the Query class

Query#select now accepts Criteria object, Symbol (which now will be transformed to corresponding Criteria), 'String' (which will be transformed to RawSql), string and symbol tuples, array of criterion and could raise a block with ExpressionBuilder as a current context (Array(Criteria) is expected to be returned)

Query#group got same behavior as Query#select

Query#order realize same idea as with Query#select but with hashes

added Criteria#alias method which allows to alias field in the SELECT clause