Project

ilios

0.0
The project is in a healthy, maintained state
Cassandra driver written by C language
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Runtime

 Project Readme

Ilios

Gem Version CI Ask DeepWiki

Ilios that Cassandra driver written by C language for Ruby using DataStax C/C++ Driver.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add ilios

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install ilios

This gem's installer will install the DataStax C/C++ Driver to the appropriate location automatically. However, if you prefer to install the DataStax C/C++ Driver manually, you can do so by executing:

$ bundle config set --local build.ilios --with-libuv-dir=/path/to/libuv-installed-dir
$ bundle config set --local build.ilios --with-cassandra-driver-dir=/path/to/cassandra-cpp-driver-installed-dir
$ bundle add ilios

or

$ gem install ilios -- --with-libuv-dir=/path/to/libuv-installed-dir --with-cassandra-driver-dir=/path/to/cassandra-cpp-driver-installed-dir

Requirements

  • cmake (in order to build the DataStax C/C++ Driver and libuv)
  • C/C++ compiler
  • install_name_tool (macOS only)

Supported

  • Ruby 3.4 or later
  • Cassandra 3.0 or later
  • Linux and macOS platform

Example

Basic usage

Create the keyspace in advance using the cqlsh command.

CREATE KEYSPACE IF NOT EXISTS ilios
WITH REPLICATION = {
  'class' : 'SimpleStrategy',
  'replication_factor' : 1
};

Then, you can run the following code.

require 'ilios'

cluster = Ilios::Cassandra::Cluster.new
cluster.keyspace('ilios')
cluster.hosts(['127.0.0.1'])
session = cluster.connect

# Create the table
statement = session.prepare(<<~CQL)
  CREATE TABLE IF NOT EXISTS ilios.example (
    id bigint,
    message text,
    created_at timestamp,
    PRIMARY KEY (id)
  ) WITH compaction = { 'class' : 'LeveledCompactionStrategy' }
  AND gc_grace_seconds = 691200;
CQL
session.execute(statement)

# Insert the records
statement = session.prepare(<<~CQL)
  INSERT INTO ilios.example (
    id,
    message,
    created_at
  ) VALUES (?, ?, ?)
CQL

100.times do |i|
  statement.bind({
    id: i,
    message: 'Hello World',
    created_at: Time.now,
  })
  session.execute(statement)
end

# Select the records
statement = session.prepare(<<~CQL)
  SELECT * FROM ilios.example
CQL
statement.idempotent = true
statement.page_size = 25
result = session.execute(statement)
result.each do |row|
  p row
end

while(result.next_page)
  result.each do |row|
    p row
  end
end

Collection types

list, set and map columns (including nested collections such as list<frozen<list<int>>>) are supported.

statement = session.prepare(<<~CQL)
  CREATE TABLE IF NOT EXISTS ilios.collection_example (
    id bigint,
    tags set<text>,
    scores list<int>,
    attributes map<text, bigint>,
    PRIMARY KEY (id)
  );
CQL
session.execute(statement)

statement = session.prepare(<<~CQL)
  INSERT INTO ilios.collection_example (
    id,
    tags,
    scores,
    attributes
  ) VALUES (?, ?, ?, ?)
CQL
statement.bind({
  id: 1,
  tags: Set['ruby', 'cassandra'],  # or an Array
  scores: [85, 92],
  attributes: { 'height' => 180 },
})
session.execute(statement)

statement = session.prepare(<<~CQL)
  SELECT * FROM ilios.collection_example
CQL
session.execute(statement).each do |row|
  row['tags']       # => Set["cassandra", "ruby"]
  row['scores']     # => [85, 92]
  row['attributes'] # => {"height" => 180}
end

Notes:

  • A set column accepts both Set and Array on bind, and is always returned as a Set.
  • A list column also accepts both Array and Set on bind, but is always returned as an Array. Binding a Set to a list column keeps the order Set#to_a returns.
  • Cassandra stores an empty non-frozen collection as null, so inserting [], Set.new or {} returns nil on select. This is Cassandra's data model, not an Ilios limitation.
  • nil is not allowed as a collection element (Cassandra collections cannot contain null).
  • Symbol is accepted for text (as well as ascii and varchar) columns and collection elements, and is stored (and returned) as a String.
  • Because a Symbol map key is stored as its String equivalent, binding a map that contains both (for example { k1: 1, 'k1' => 2 }) ends up as a single key on the server; the entry bound last wins.
  • Binding a String containing a NUL character (\0) to a text (or ascii / varchar) column raises ArgumentError (known limitation).

Authentication and cluster options

Username/password authentication (Cassandra's PasswordAuthenticator) and common cluster options are configured on Cluster before connect:

cluster = Ilios::Cassandra::Cluster.new
cluster.hosts(['127.0.0.1'])
cluster.credentials('username', 'password')
cluster.consistency(:quorum) # or Ilios::Cassandra::Cluster::CONSISTENCY_QUORUM
cluster.num_threads_io(4)
cluster.exponential_reconnect(2_000, 60_000)
cluster.tcp_keepalive(true, 60)
cluster.load_balance_dc_aware('dc1')
session = cluster.connect

See the RBS signatures in sig/ilios.rbs for the full list of options.

Synchronous API

Ilios::Cassandra::Session#prepare and Ilios::Cassandra::Session#execute are provided as synchronous API.

statement = session.prepare(<<~CQL)
  SELECT * FROM ilios.example
CQL
result = session.execute(statement)

Asynchronous API

Ilios::Cassandra::Session#prepare_async and Ilios::Cassandra::Session#execute_async are provided as asynchronous API.

prepare_future = session.prepare_async(<<~CQL)
  INSERT INTO ilios.example (
    id,
    message,
    created_at
  ) VALUES (?, ?, ?)
CQL

prepare_future.on_success { |statement|
  futures = []

  10.times do |i|
    statement.bind({
      id: i,
      message: 'Hello World',
      created_at: Time.now,
    })
    result_future = session.execute_async(statement)
    result_future.on_success { |result|
      p result
      p "success"
    }
    # `error` is an `Ilios::Cassandra::ExecutionError` (a StandardError with
    # a #code Integer attribute); the block is optional-arity, so `{ p "fail" }`
    # still works without it.
    result_future.on_failure { |error|
      p error.message
      p error.code
    }

    futures << result_future
  end
  futures.each(&:await)
}

prepare_future.await

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Watson1978/ilios.