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 toCassandra::DBApi::Date
time
maps toCassandra::DBApi::Time
uuid
maps toCassandra::DBApi::Uuid
timeuuid
maps toCassandra::DBApi::TimeUuid
Some of the collection types are also supported:
list
maps toArray
set
maps toSet
map
maps toHash
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
- Fork it (<https://github.com/kaukas/crystal-cassandra/fork>)
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Contributors
- kaukas Linas Juškevičius - creator, maintainer