Basic mysql bindings for crystal.
Crystal Shell
Latest commit 94e0bf2 Sep 21, 2016 @waterlink committed on GitHub Merge pull request #47 from waterlink/0.4.4-bump
Bump version to 0.4.4
Failed to load latest commit information.
libs Make it Projectfile compatible; Remove strange error handling from My… Mar 9, 2015
script cover #connect Mar 15, 2015
spec allow blob types Mar 18, 2016
src Fixed pseudo-method Sep 21, 2016
.gitignore Support shards package manager Sep 26, 2015
LICENSE Add MIT Mar 9, 2015 Release 0.4.2 Apr 2, 2016


Build Status

Fork of

Basic MySQL bindings for Crystal.

CAUTION: Pre-alpha quality. Don't use for anything serious. Any bug reports and feedback are warmly welcome!


Add it to your shard.yml

    github: waterlink/crystal-mysql
    version: ~> 0.4


require "mysql"

Connecting to mysql

# MySQL.connect(host, user, password, database, port, socket, flags = 0)
conn = MySQL.connect("", "crystal_mysql", "", "crystal_mysql_test", 3306_u16, nil)

Making a query

conn.query(%{SELECT 1})  #=> [[1]]

conn.query(%{CREATE TABLE user (id INT, email VARCHAR(255), name VARCHAR(255))})

conn.query(%{INSERT INTO user(id, email, name) values(1, "", "John Smith")})
conn.query(%{INSERT INTO user(id, email, name) values(2, "", "Sarah Smith")})

conn.query(%{SELECT * FROM user}) #=> [[1, "", "John Smith"], [2, "", "Sarah Smith"]]

conn.query(%{DROP TABLE user})

Using higher level Query api

  .new(%{SELECT * FROM user WHERE created_at > :from_filter},
       { "from_filter" => 14.days.ago })

You can reference parameters in query with symbol-like syntax: :some_symbol_like_syntax or :someSymbolLikeSyntax. And then you can resolve these references with passing a hash as a second argument, which specifies values for these parameters.

By the way all strings get properly escaped, so no SQL injections should be possible (if something is not escaped properly, then it is a bug, and you should probably report it here on github).

You can reference the same symbol multiple times in one query, as well you can use as much symbols as you want.

Making a transaction

other_conn = MySQL.connect("", "crystal_mysql", "", "crystal_mysql_test", 3306_u16, nil)

conn.transaction do
  conn.query(%{SELECT COUNT(id) FROM user})  #=> 2
  conn.query(%{INSERT INTO user(id, email, name) values(1, "", "James Smith")})

  conn.query(%{SELECT COUNT(id) FROM user})  #=> 3
  other_conn.query(%{SELECT COUNT(id) FROM user})  #=> 2

conn.query(%{SELECT COUNT(id) FROM user})  #=> 3
other_conn.query(%{SELECT COUNT(id) FROM user})  #=> 3

If block provided for #transaction raises exception, then it will rollback transaction automatically.

You can use #start_transaction, #commit_transaction and #rollback_transaction manually:

  # .. do stuff with conn ..

Nested transactions are possible.

Closing connection



  • This library assumes tinyint is used as boolean type.

High-level API roadmap

High level method Implemented?
MySQL.connect Yes
Connection#initialize Yes
Connection#client_info Yes
Connection#error Yes
Support#escape_string Yes
Connection#connect Yes
Connection#host_info No
Connection#query 72% (usable)
Connection#start_transaction Yes
Connection#commit_transaction Yes
Connection#rollback_transaction Yes
Connection#transaction Yes
Connection#close Yes
Query#to_mysql Yes
Query#run Yes


  • Support more types: Enum, Set, Geometry, Binary strings
  • Figure out utf-8 (and other collations) support
  • Set up CI for different versions of mysql, ie: 5.5, 5.6, 5.7
  • Set up CI for mac os x
  • Figure out 32bit support?


  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