crystal-mysql v0.10.0

MySQL connector for Crystal

crystal-mysql Build Status

MySQL driver implement natively in Crystal, without relying on external libraries.

Check crystal-db for general db driver documentation. crystal-mysql driver is registered under mysql:// uri.


Using a natively implemented library has a significant performance improvement over working with an external library, since there is no need to copy data to and from the Crystal space and the native code. Initial tests with the library have shown a 2x-3x performance boost, though additional testing is required.

Also, going through the MySQL external library blocks the Crystal thread using it, thus imposing a significant penalty to concurrent database accesses, such as those in web servers. We aim to overcome this issue through a full Crystal implementation of the MySQL driver that plays nice with non-blocking IO.


This driver is a work in progress. It implements mysql's binary protocol to create prepared statements. Contributions are most welcome.


Add this to your application's shard.yml:

    github: crystal-lang/crystal-mysql


require "mysql"

# connect to localhost mysql test db "mysql://root@localhost/test" do |db|
  db.exec "drop table if exists contacts"
  db.exec "create table contacts (name varchar(30), age int)"
  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)

When running this example, if you get the following exception:

Unhandled exception: Client does not support authentication protocol requested by server; consider upgrading MySQL client (Exception)

You have two options, set a password for root, or (most recommended option) create another user with access to test database.

CREATE USER 'test'@'localhost' IDENTIFIED WITH mysql_native_password BY 'yourpassword';

Then use the example above changing the line to "mysql://test:yourpassword@localhost/test" do |db|

v0.10.0 (2019-12-11)

  • Update to crystal-db ~> 0.8.0. (#85)

v0.9.0 (2019-09-20)

This release requires Crystal >= 0.30.0

  • Update to crystal-db ~> 0.7.0

v0.8.0 (2019-08-02)

  • Fix compatibility issues for Crystal 0.30.0. (#80, thanks @bcardiff)

v0.7.0 (2019-07-03)

  • Support implicit conversion from integer types to Bool (#78, thanks @Blacksmoke16)
  • Improve docs. (#71, thanks @fernandes)

v0.6.0 (2019-04-18)

  • Fix compatibility issues for crystal 0.28.0 (#73)
  • Fix connection to IPv6 hosts (#69, thanks @j8r)

v0.5.1 (2018-11-06)

  • Fix read_lenenc_int return UInt64.
  • Add missing IO#read_fully when reading slice. (#45, thanks @pacuum).

v0.5.0 (2018-06-15)

  • Fix compatibility issues for crystal 0.25.0 (#60)
    • All the time instances are translated to UTC before saving them in the db
  • Send quit packet before closing connection (#61, thanks @liuyang1204)

v0.4.0 (2017-12-29)

  • Update to crystal-db ~> 0.5.0
  • Fix compatibility issues for crystal 0.24.1 (thanks @lipanski)
    • Drop support for zero dates

v0.3.3 (2017-11-08)

  • Fix release connection. (see #35 and #38, thanks @benoist)
  • Fix unprepared queries creation. (#37, thanks @benoist)
  • Fix use read_fully when reading slice. (see #25)
  • Add support for Date, Time and Mediumint. (see #31 and #41, thanks @crisward)

v0.3.2 (2017-03-21)

  • Update to crystal-db ~> 0.4.0

v0.3.1 (2016-12-24)

  • Update to crystal-db ~> 0.3.3
  • Fix compatibility issues for crystal 0.20.3
  • Add support for Timestamp

v0.3.0 (2016-12-15)

  • Update to crystal-db ~> 0.3.1
  • Add support for unprepared statements using TextProtocol. This means only argless commands/query can be executed in unprepared fashion.
  • Add support for Bool (stored as BOOL/TINYINT(1))

v0.2.2 (2016-12-07)

  • Remove restriction to use only DB::Any in some cases

v0.2.1 (2016-12-07)

  • Add support for TinyInt as Int8 and SmallInt as Int16. (thanks @crisward)
  • Update to crystal 0.20.0 (thanks @tbrand)

v0.2.0 (2016-10-20)

Github statistic:
  • 76
  • 174
  • 30
  • 11
  • 20
  • 6 days ago


MIT License