Crystal DB API for Cassandra

A Crystal wrapper around the DataStax C/C++ Driver. It conforms to the crystal-db API.

Status

This is a personal project to create something meaningful while learning Crystal. There are no guarantees about future development, maintenance, or support. That said, if you need to use Crystal to query Cassandra this library could be a good starting point. YMMV.

Installation

Please make sure you have installed the DataStax C/C++ Driver. You can use "development" packages if they are available or build from source.

Then add this to your application's shard.yml:

dependencies:
  cassandra:
    github: kaukas/crystal-cassandra

Documentation

The latest Crystal Cassandra API documentation can be found here.

Usage

From the basic example:

require "cassandra/dbapi"

DB.open("cassandra://127.0.0.1/test") do |db|
  db.exec(<<-CQL)
    create table posts (
      id timeuuid primary key,
      title text,
      body text,
      created_at timestamp
    )
  CQL
  db.exec("insert into posts (id, title, body, created_at) values (now(), ?, ?, ?)",
          "Hello World",
          "Hello, World. I have a story to tell.",
          Time.now)
  db.query("select title, body, created_at from posts") do |rs|
    rs.each do
      title = rs.read(String)
      body = rs.read(String)
      created_at = rs.read(Time)
      puts title
      puts "(#{created_at})"
      puts body
    end
  end
end

Please refer to crystal-db for further usage instructions.

Types

crystal-cassandra supports all the DB::Any primitive types plus Int8 and Int16 and some additional value types:

• date maps to Cassandra::DBApi::Date
• time maps to Cassandra::DBApi::Time
• uuid maps to Cassandra::DBApi::Uuid
• timeuuid maps to Cassandra::DBApi::TimeUuid

Some of the collection types are also supported:

• list maps to Array
• set maps to Set
• map maps to Hash

Casting

Cassandra supports nested collection types (lists, sets, maps, etc.). Since Crystal deprecated recursive aliases they can be represented with recursive structs. crystal-cassandra has Cassandra::DBApi::Any which performs a similar function to JSON::Any. You can pass collection parameters to queries wrapped with Cassandra::DBApi::Any (taken from the collections example):

alias Any = Cassandra::DBApi::Any

# Assuming `authors` is `list<text>`
db.exec("insert into posts (id, authors) values (now(), ?)",
        Any.new([Any.new("John Doe"), Any.new("Ben Roe")]))

db.query("select authors from posts") do |rs|
  rs.each do
    authors = rs.read(Array(Any))
    puts "Authors: #{authors.map { |author| author.as_s }.join(", ")}"
  end
end

You could do the same for the primitive values as well:

db.exec("insert into posts (id, title) values (now(), ?)",
        Any.new("Hello World"))

db.query("select title from posts") do |rs|
  rs.each do
    title = rs.read(Any)
    puts title.as_s
  end
end

but shortcuts are defined for them so Any can be skipped (see the basic example).

Development

Install the C/C++ Driver. The Makefile commands work on MacOS:

make build-cppdriver

Start a Docker container with an instance of Cassandra:

make start-cassandra

Run the tests:

crystal spec

Stop Cassandra when finished:

make stop-cassandra

Contributing

1. Fork it (https://github.com/kaukas/crystal-cassandra/fork)
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

Contributors

• kaukas Linas Juškevičius - creator, maintainer