crystal-db v0.8.0

Common db api for crystal

Build Status


Common db api for crystal. You will need to have a specific driver to access a database.


If you are creating a shard that will work with any driver, then add crystal-db as a dependency in shard.yml:

    github: crystal-lang/crystal-db

If you are creating an application that will work with some specific driver(s), then add them in shard.yml:

    github: crystal-lang/crystal-sqlite3

crystal-db itself will be a nested dependency if drivers are included.

Note: Multiple drivers can be included in the same application.



This shard only provides an abstract database API. In order to use it, a specific driver for the intended database has to be required as well:

The following example uses SQLite where ? indicates the arguments. If PostgreSQL is used $1, $2, etc. should be used. crystal-db does not interpret the statements.

require "db"
require "sqlite3" "sqlite3:./file.db" do |db|
  # When using the pg driver, use $1, $2, etc. instead of ?
  db.exec "create table contacts (name text, age integer)"
  db.exec "insert into contacts values (?, ?)", "John Doe", 30

  args = [] of DB::Any
  args << "Sarah"
  args << 33
  db.exec "insert into contacts values (?, ?)", args: args

  puts "max age:"
  puts db.scalar "select max(age) from contacts" # => 33

  puts "contacts:"
  db.query "select name, age from contacts order by age desc" do |rs|
    puts "#{rs.column_name(0)} (#{rs.column_name(1)})"
    # => name (age)
    rs.each do
      puts "#{} (#{})"
      # => Sarah (33)
      # => John Doe (30)


Issues not yet addressed:

  • Support non prepared statements. #25
  • Time data type. (implementation details depends on actual drivers)
  • Data type extensibility. Allow each driver to extend the data types allowed.
  • Transactions & nested transactions. #27
  • Connection pool.
  • Logging
  • Direct access to IO to avoid memory allocation for blobs.


  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


  • bcardiff Brian J. Cardiff - creator, maintainer

v0.8.0 (2019-12-11)

  • Add DB::Serializable. (#115, thanks @nickbclifford)

This release requires Crystal 0.25.0 or later.

v0.7.0 (2019-09-20)

  • (breaking-change) #exec, #query, #scalar methods require named argument for array values (#110, thanks @straight-shoota)
  • Fix pool issues when creating simultaneous connections. (#109, thanks @bcardiff)
  • Fix compatibility issues for upcoming Crystal 0.31.0. (#111, thanks @bcardiff)
  • Added DB::Pool#stats. (#109, thanks @bcardiff)

v0.6.0 (2019-08-02)

  • Fix compatibility issues for Crystal 0.30.0. (#108, thanks @bcardiff)
  • Fix BeginTransaction#transaction rollback due to protocol error. (#101, thanks @straight-shoota)
  • CI includes Crystal nightly. (#106, thanks @bcardiff)
  • Add the Cassandra driver. (#94, thanks @kaukas)
  • Several docs improvements. (#99, #96, #107, thanks @nickelghost, @greenbigfrog, @MatthiasWinkelmann)

v0.5.1 (2018-11-07)

  • Fix QueryMethods#query_one? handling no rows. (#86, thanks @robdavid)
  • Documentation improvements. (#87, #82, #76, thanks @wontruefree, @Heaven31415, @vtambourine)

v0.5.0 (2017-12-29)

  • Fix compatibility issues for crystal 0.24.0. No changes in the api.

v0.4.4 (2017-12-29)

  • Allow query results to be read as named tuples directly (see #56, thanks @Nephos)
  • Fix sqlite samples in documentation (see #71, thanks @hinrik)

v0.4.3 (2017-11-07)

  • Fix connections were not released when building invalid statements. (see #65, thanks @crisward)
  • Fix some exceptions were not deriving from DB::Error. (see #70, thanks @exts)

v0.4.2 (2017-04-21)

  • Fix compatibility issues for crystal 0.22.0

v0.4.1 (2017-04-10)

  • Add spec helper for drivers. #48
  • Add #query_each. #18
  • Fix #read(T.class) to deal better with unhandled types.

v0.4.0 (2017-03-20)

  • Add DB.connect to create non pooled connections
  • Add Database#checkout to allow explicit checkout/release connection (see #38)
  • Fix Mapping.from_rs closes the result_set
  • Fix Mapping works with nilable types (see #40, thanks @RX14)

v0.3.3 (2016-12-24)

  • Fix compatibility issues for crystal 0.20.3

v0.3.2 (2016-12-16)

  • Allow connection pool retry logic in #scalar queries.

v0.3.1 (2016-12-15)

  • Add ConnectionRefused exception to flag issues when opening new connections.

v0.3.0 (2016-12-14)

  • Add support for non prepared statements. #25

  • Add support for transactions & nested transactions. #27

  • Add Bool and Time to DB::Any.

v0.2.2 (2016-12-06)

This release requires crystal 0.20.1

  • Changed default connection pool size limit is now 0 (unlimited).

  • Fixed allow new connections right away if pool can be increased.

v0.2.1 (2016-12-06) [YANKED]

v0.2.0 (2016-10-20)

  • Fixed release DB connection if an exception occurs during execution of a query (thanks @ggiraldez)

v0.1.1 (2016-09-28) [YANKED]

This release requires crystal 0.19.2

Note: v0.1.1 is yanked since is incompatible with v0.1.0 more.

  • Added connection pool. works with a underlying connection pool. Use Database#using_connection to ensure the same connection is been used across multiple statements. more

  • Added mappings. JSON/YAML-like mapping macros (thanks @spalladino) more

  • Changed require ResultSet implementors to just implement read, optionally implementing read(T.class).

v0.1.0 (2016-06-24)

  • Initial release
Github statistic:
  • 170
  • 156
  • 34
  • 20
  • 24
  • 6 days ago


MIT License