Onyx::SQL is a delightful SQL ORM. It provides tools to map models from an SQL database to your Crystal applications. It also has a convenient and type-safe SQL query builder. It currently does not include tools for migration or somehow else manipulating your databases. You can you migrate.cr, for example.
The ORM is designed to be as much database-agnotic as possible. It should work with any database shard implementing the crystal-db interface. Currently these are crystal-sqlite3, crystal-mysql, crystal-pg and crystal-cassandra.
However, different databases handle types differently and all have their edges. For example, SQLite3 doesn't have arrays, but PostgreSQL has native support for them. To handle such situations, the concept of converters exists. Currently common converters for these shards only are included into the ORM: crystal-sqlite3, crystal-pg. But it is quite simple to implement custom converters for a database you want.
To add the Onyx::SQL functionality into your application, you must explicitly add the
onyx-sql dependency into your
shard.yml file along with
onyx and the database shard you're planning to work with (for example, crystal-pg):
dependencies: onyx: github: onyxframework/onyx version: ~> 0.3.0 onyx-sql: github: onyxframework/sql version: ~> 0.7.0 pg: github: will/crystal-pg version: ~> 0.15.0
Then in your Crystal code you should require both
onyx-sql and the database shard requiring the database shard before the ORM:
require "pg" require "onyx/sql"
From now on, your application requires
DATABASE_URL environment variable to be set. See more about loading environment variables in the Onyx Helpers section.
The Onyx::SQL docs are split to these sections: