Crystal driver using Neo4j's Bolt protocol
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Join the chat at

Crystal implementation of a Neo4j driver using the Bolt protocol.


Add this to your application's shard.yml:

    github: jgaskins/


First you need to set up a connection:

require "neo4j"

# The `ssl` option defaults to `true` so you don't accidentally send the
# password to your production DB in cleartext.
connection =
  ssl: false,

The connection has two public methods:

  • execute(query : String, params = ({} of String => Neo4j::Type)) : Neo4j::Result
  • transaction(&block)
  • reset

execute(query : String, params = ({} of String => Neo4j::Type))

Executes the given Cypher query. Takes a hash of params for sanitization and query caching.

result = connection.execute("
  MATCH (order:Order)-[:ORDERS]->(product:Product)
  RETURN order, collect(product)
  LIMIT 10

This method returns a Neo4j::Result. You can iterate over it with Enumerable methods. Each iteration of the block will return an array of the values passed to the query's RETURN clause:

result = connection.execute(<<-CYPHER, { "email" => "" })
  MATCH (self:User)<-[:SENT_TO]-(message:Message)-[:SENT_BY]->(author:User)
  WHERE == $email
  RETURN author, message
CYPHER do |(author, message)| # Using () to destructure the array into block args

Note that we cast the values returned from the query into Neo4j::Node. Each value returned from a query can be any Neo4j data type and cannot be known at compile time, so we have to cast the values into the types we know them to be — in this case, we are returning nodes.


Executes the block within the context of a Neo4j transaction. At the end of the block, the transaction is committed. If an exception is raised, the transaction will be rolled back and the connection will be reset to a clean state.


connection.transaction do
  query = <<-CYPHER
    CREATE (user:User {
      uuid: $uuid,
      name: $name,
      email: $email,

  connection.execute(query, params.merge({ "uuid" => UUID.random.to_s }))


Resets a connection to a clean state. A connection will automatically call reset if an exception is raised within a transaction, so you shouldn't have to call this explicitly, but it's provided just in case.


  • type : (Neo4j::Success | Neo4j::Ignored)
    • If you get an Ignored result, it probably means an error occurred. Call connection#reset to get it back to working order.
    • If a query results in a Neo4j::Failure, an exception is raised rather than wrapping it in a Result.
  • data : Array(Array(Neo4j::Type))
    • This is the list of result values. For example, if you RETURN a, b, c from your query, then this will be an array of [a, b, c].

The Result object itself is an Enumerable. Calling Result#each will iterate over the data for you.


These have a 1:1 mapping to nodes in your graph.

  • id : Int32: the node's internal id
    • WARNING: Do not store this id anywhere. These ids can be reused by the database. If you need an application-level unique id, store a UUID on the node. It is useful in querying nodes connected to this one when you already have it in memory, but not beyond that.
  • labels : Array(String): the labels stored on your node
  • properties : Hash(String, Neo4j::Type): the properties assigned to this node


  • id: Int32: the relationship's internal id
  • type : String: the type of relationship
  • start : Int32: the internal id for the node on the starting end of this relationship
  • end : Int32: the internal id of the node this relationship points to
  • properties : Hash(String, Neo4j::Type): the properties assigned to this relationship


Represents any data type that can be stored in a Neo4j database and communicated via the Bolt protocol. It's a shorthand for this union type:

Nil |
Bool |
String |
Int8 |
Int16 |
Int32 |
Int64 |
Float64 |
Array(Neo4j::Type) |
Hash(String, Neo4j::Type) |
Neo4j::Node |
Neo4j::Relationship |
Neo4j::UnboundRelationship |
Neo4j::Path |
Neo4j::Success |
Neo4j::Failure |

Mapping to Domain Objects

Similar to JSON.mapping in the Crystal standard library, you can map nodes and relationships to domain objects. For example:

require "uuid"

class User
    uuid: UUID,
    email: String,
    name: String
    registered_at: Time,

class Product
    uuid: UUID,
    name: String,
    description: String,
    price: Int32,
    created_at: Time,

class CartItem
    quantity: Int32,
    price: Int32,

With these in place, you can build them from your nodes and relationships:

result = connection.execute(<<-CYPHER, { "uuid" => params["uuid"] })
  MATCH (product:Product)-[cart_item:IN_CART]->(user:User { uuid: $uuid })
  RETURN product, cart_item

cart = { |(product, cart_item)|


  • Certain types like Point, Time, DateTime, LocalTime, LocalDateTime are not available in Bolt yet
    • They will be added when the Bolt spec is updated to include them
  • This is still relatively early development, so while it supports a lot of functionality, some APIs might change as improvements are discovered
    • For example, transaction doesn't yield a transaction and everything is just called on the connection, which is not ideal, so this is pretty likely to change

Future development

  • I'd like to support query pipelining
    • Send multiple queries, commands, etc, before reading the result from any of them. This could be useful for transactions where we don't try to consume the results until the end of the transaction.
    • The idea is that we don't spend time waiting on a response from a query if we can just pick it up later
    • If a query error occurs, the server will send Ignored results back to us until we acknowledge the failure, so there is no special processing needed for this occurrence
  • Streaming results, letting us send a query and consume its result lazily
    • For example, if we query 1000 results, we could defer deserializing them until the application needs them, potentially saving on processing
    • I don't know if this would be the default
  • bolt+routing
    • I'm checking out the Java driver to see how they handle routing between core servers in Enterprise clusters


This implementation is heavily based on @benoist's implementation of MessagePack. I had never built a binary protocol parser in a statically typed language before, so it really helped jump-start the development of this project.


  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


  • jgaskins Jamie Gaskins - creator, maintainer