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):

    github: onyxframework/onyx
    version: ~> 0.3.0
    github: onyxframework/sql
    version: ~> 0.7.0
    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:

  • Schema describes the mapping
  • Query introduces to the SQL Queries builder