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::Date
• time maps to Cassandra::Time
• uuid maps to Cassandra::Uuid
• timeuuid maps to Cassandra::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::Any which performs a similar function to
JSON::Any. You can pass
collection parameters to queries wrapped with Cassandra::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