• Stars
    star
    227
  • Rank 175,900 (Top 4 %)
  • Language
    Ruby
  • License
    Other
  • Created about 10 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

[MAINTENANCE ONLY] DataStax Ruby Driver for Apache Cassandra

⚠️ The Ruby driver is in maintenance mode. We are still accepting pull-requests and we will occasionally release critical bug fixes, but no ongoing active development is being done currently.

Datastax Ruby Driver for Apache Cassandra

If you're reading this on GitHub, please note that this is the readme for the development version and that some features described here might not yet have been released. You can view the documentation for the latest released version here.

Build Status

A Ruby client driver for Apache Cassandra. This driver works exclusively with the Cassandra Query Language version 3 (CQL3) and Cassandra's native protocol.

Use the Ruby DSE driver for better compatibility and support for DataStax Enterprise.

This driver is based on the cql-rb gem by Theo Hultberg and we added support for:

Check out the slides from Ruby Driver Explained for a detailed overview of the Ruby Driver architecture.

Compatibility

This driver works exclusively with the Cassandra Query Language v3 (CQL3) and Cassandra's native protocol. The current version works with:

  • Apache Cassandra versions 2.1, 2.2, 3.0+, and 4.0.x
  • DataStax Enterprise 4.8 and above. However, the Ruby DSE driver provides more features and is recommended for use with DataStax Enterprise.
  • Ruby (MRI) 2.2, 2.3, 2.4
  • JRuby 9k

Note: Rubinius is not supported.

Note: Big-endian systems are not supported.

Quick start

require 'cassandra'

cluster = Cassandra.cluster # connects to localhost by default

cluster.each_host do |host| # automatically discovers all peers
  puts "Host #{host.ip}: id=#{host.id} datacenter=#{host.datacenter} rack=#{host.rack}"
end

keyspace = 'system_schema'
session  = cluster.connect(keyspace) # create session, optionally scoped to a keyspace, to execute queries

future = session.execute_async('SELECT keyspace_name, table_name FROM tables') # fully asynchronous api
future.on_success do |rows|
  rows.each do |row|
    puts "The keyspace #{row['keyspace_name']} has a table called #{row['table_name']}"
  end
end
future.join

Note: The host you specify is just a seed node, the driver will automatically discover all peers in the cluster.

Read more:

Installation

Install via rubygems

gem install cassandra-driver

Install via Gemfile

gem 'cassandra-driver'

Note: if you want to use compression you should also install snappy or lz4-ruby. Read more about compression.

Upgrading from cql-rb

Some of the new features added to the driver have unfortunately led to changes in the original cql-rb API. In the examples directory, you can find an example of how to wrap the ruby driver to achieve almost complete interface parity with cql-rb to assist you with gradual upgrade.

If you are upgrading to DataStax Enterprise, use the Ruby DSE driver for more features and better compatibility.

What's new in v3.2

This minor release adds support for MRI 2.4.x and also contains a few miscellaneous defect fixes. It also removes support for Ruby versions prior to 2.2. This was already officially the case, but the minimum version limit is now enforced.

See the changelog for more information on all changes in this version and past versions.

What's new in v3.1

This minor release introduces features and fixes around resiliency, schema metadata, usability, and performance. One of the most user-impacting of these is the introduction of execution profiles. Execution profiles allow you to group various execution options into a 'profile' and you reference the desired profile at execution time. Get the scoop here.

What's new in v3.0

Features:

  • Add support for Apache Cassandra native protocol v4
  • Add support for smallint, tinyint, date (Cassandra::Date) and time (Cassandra::Time) data types.
  • Include schema metadata for User Defined Functions and User Defined Aggregates.
  • Augment the Cassandra::Table object to expose many more attributes: id, options, keyspace, partition_key, clustering_columns, and clustering_order. This makes it significantly easier to write administration scripts that report various attributes of your schema, which may help to highlight areas for improvement.
  • Include client ip addresses in request traces, only on Cassandra 3.x.
  • Add new retry policy decision Cassandra::Retry::Policy#try_next_host.
  • Support specifying statement idempotence with the new idempotent option when executing.
  • Support sending custom payloads when preparing or executing statements using the new payload option.
  • Expose custom payloads received with responses on server exceptions and Cassandra::Execution::Info instances.
  • Expose server warnings on server exceptions and Cassandra::Execution::Info instances.
  • Add connections_per_local_node, connections_per_remote_node, requests_per_connection cluster configuration options to tune parallel query execution and resource usage.
  • Add Cassandra::Logger class to make it easy for users to enable debug logging in the client.
  • Add protocol_version configuration option to allow the user to force the protocol version to use for communication with nodes.
  • Add support for materialized views and indexes in the schema metadata.
  • Support the ReadError, WriteError, and FunctionCallError Cassandra error responses introduced in Cassandra 2.2.
  • Add support for unset variables in bound statements.
  • Support DSE security (DseAuthenticator, configured for LDAP).
  • Add a timeout option to Cassandra::Future#get.

Breaking Changes from 2.x:

  • Cassandra::Future#join is now an alias to Cassandra::Future#get and will raise an error if the future is resolved with one.
  • Default consistency level is now LOCAL_ONE.
  • Enable tcp no-delay by default.
  • Unavailable errors are retried on the next host in the load balancing plan by default.
  • Statement execution no longer retried on timeouts, unless the statement is marked as idempotent in the call to Cassandra::Session#execute* or when creating a Cassandra::Statement object.
  • Cassandra::Statements::Batch#add and Cassandra::Session#execute* signatures have changed in how one specifies query parameters. Specify the query parameters array as the value of the arguments key:
batch.add(query, ['val1', 'val2'])
# becomes
batch.add(query, arguments: ['val1', 'val2'])

batch.add(query, {p1: 'val1'})
# becomes
batch.add(query, arguments: {p1: 'val1'})
  • The Datacenter-aware load balancing policy (Cassandra::LoadBalancing::Policies::DCAwareRoundRobin) defaults to using nodes in the local DC only. In prior releases, the policy would fall back to remote nodes after exhausting local nodes. Specify a positive value (or nil for unlimited) for max_remote_hosts_to_use when initializing the policy to allow remote node use.
  • Unspecified variables in statements previously resulted in an exception. Now they are essentially ignored or treated as null.

Code examples

The DataStax Ruby Driver uses the awesome Cucumber Framework for both end-to-end, or acceptance, testing and constructing documentation. All of the features supported by the driver have appropriate acceptance tests with easy-to-copy code examples in the features/ directory.

Running tests

If you don't feel like reading through the following instructions on how to run ruby-driver tests, feel free to check out .travis.yml for the entire build code.

  • Check out the driver codebase and install test dependencies:
git clone https://github.com/datastax/ruby-driver.git
cd ruby-driver
bundle install --without docs
  • Install ccm

  • Run tests against different versions of Cassandra:

CASSANDRA_VERSION=3.1.1 bundle exec cucumber # runs end-to-end tests (or bundle exec rake cucumber)
CASSANDRA_VERSION=3.0.0 bundle exec rspec # runs unit tests (or bundle exec rake rspec)
CASSANDRA_VERSION=2.1.12 bundle exec rake integration # run integration tests
CASSANDRA_VERSION=2.1.12 bundle exec rake test # run both as well as integration tests

Changelog & versioning

Check out the releases on GitHub and changelog. Version numbering follows the semantic versioning scheme.

Private and experimental APIs, defined as whatever is not in the public API documentation, i.e. classes and methods marked as @private, will change without warning. If you've been recommended to try an experimental API by the maintainers, please let them know if you depend on that API. Experimental APIs will eventually become public, and knowing how they are used helps in determining their maturity.

Prereleases will be stable, in the sense that they will have finished and properly tested features only, but may introduce APIs that will change before the final release. Please use the prereleases and report bugs, but don't deploy them to production without consulting the maintainers, or doing extensive testing yourself. If you do deploy to production please let the maintainers know as this helps in determining the maturity of the release.

Known bugs & limitations

  • Specifying a protocol_version option of 1 or 2 in cluster options will fail with a NoHostsAvailable error rather than a ProtocolError against Cassandra node versions 3.0-3.4.
  • Because the driver reactor is using IO.select, the maximum number of tcp connections allowed is 1024.
  • Because the driver uses IO#write_nonblock, Windows is not supported.

Please refer to the usage documentation for more information on common pitfalls

Contributing

For contributing read CONTRIBUTING.md

Credits

This driver is based on the original work of Theo Hultberg on cql-rb and adds a series of advanced features that are common across all other DataStax drivers for Apache Cassandra.

The development effort to provide an up to date, high performance, fully featured Ruby Driver for Apache Cassandra will continue on this project, while cql-rb has been discontinued.

Copyright

© DataStax, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

More Repositories

1

spark-cassandra-connector

DataStax Connector for Apache Spark to Apache Cassandra
Scala
1,944
star
2

python-driver

DataStax Python Driver for Apache Cassandra
Python
1,387
star
3

nodejs-driver

DataStax Node.js Driver for Apache Cassandra
JavaScript
1,238
star
4

csharp-driver

DataStax C# Driver for Apache Cassandra
C#
638
star
5

php-driver

[MAINTENANCE ONLY] DataStax PHP Driver for Apache Cassandra
C
433
star
6

cpp-driver

DataStax C/C++ Driver for Apache Cassandra
C++
403
star
7

cass-operator

The DataStax Kubernetes Operator for Apache Cassandra
Go
256
star
8

graph-book

The Code Examples and Notebooks for The Practitioners Guide to Graph Data
Shell
185
star
9

cql-proxy

A client-side CQL proxy/sidecar.
Go
172
star
10

astra-assistants-api

Drop in replacement for the OpenAI Assistants API
Python
146
star
11

ragstack-ai

RAGStack is an out of the box solution simplifying Retrieval Augmented Generation (RAG) in AI apps.
Python
133
star
12

metric-collector-for-apache-cassandra

Drop-in metrics collection and dashboards for Apache Cassandra
Java
111
star
13

dsbulk

DataStax Bulk Loader (DSBulk) is an open-source, Apache-licensed, unified tool for loading into and unloading from Apache Cassandra(R), DataStax Astra and DataStax Enterprise (DSE)
Java
82
star
14

zdm-proxy

An open-source component designed to seamlessly handle the real-time client application activity while a migration is in progress.
Go
76
star
15

docker-images

Docker images published by DataStax.
Shell
73
star
16

dynamo-cassandra-proxy

Preview version of an open source tool that enables developers to run their AWS DynamoDB™ workloads on Apache Cassandra™. With the proxy, developers can run DynamoDB workloads outside of AWS (including on premises, other clouds, and in hybrid configurations).
Java
73
star
17

cstar_perf

Apache Cassandra performance testing platform
Python
72
star
18

ai-chatbot-starter

A starter app to build AI powered chat bots with Astra DB and LlamaIndex
Python
70
star
19

zdm-proxy-automation

An Ansible-based automation suite to deploy and manage the Zero Downtime Migration Proxy
Go
61
star
20

ragbot-starter

An Astra DB and OpenAI chatbot
TypeScript
61
star
21

wikichat

Python
56
star
22

graph-examples

Java
52
star
23

fallout

Distributed System Testing as a Service
Java
51
star
24

pulsar-jms

DataStax Starlight for JMS, a JMS API for Apache Pulsar ®
Java
48
star
25

reactive-pulsar

Reactive Streams adapter for Apache Pulsar Java Client
Java
48
star
26

pulsar-helm-chart

Apache Pulsar Helm chart
Mustache
47
star
27

SwiftieGPT

TypeScript
47
star
28

kafka-examples

Examples of using the DataStax Apache Kafka Connector.
Java
46
star
29

kaap

KAAP, Kubernetes Autoscaling for Apache Pulsar
Java
45
star
30

cassandra-quarkus

An Apache Cassandra(R) extension for Quarkus
Java
40
star
31

cdc-apache-cassandra

Datastax CDC for Apache Cassandra
Java
35
star
32

pulsar-admin-console

Pulsar Admin Console is a web based UI that administrates topics, namespaces, sources, sinks and various aspects of Apache Pulsar features.
Vue
35
star
33

sstable-to-arrow

Java
34
star
34

simulacron

Simulacron - An Apache Cassandra® Native Protocol Server Simulator
Java
32
star
35

astra-cli

Command Line Interface for DataStax Astra
Java
31
star
36

code-samples

Code samples from DataStax
Scala
31
star
37

starlight-for-rabbitmq

Starlight for RabbitMQ, a proxy layer between RabbitMQ/AMQP0.9.1 clients and Apache Pulsar
Java
29
star
38

dse-metric-reporter-dashboards

Prometheus & Grafana dashboards for DSE metric collector
Python
28
star
39

diagnostic-collection

Diagnostic Collector for Apache Cassandra
Python
28
star
40

cassandra-data-migrator

Cassandra Data Migrator - Migrate & Validate data between origin and target Apache Cassandra®-compatible clusters.
Java
28
star
41

spark-cassandra-stress

A tool for testing the DataStax Spark Connector against Apache Cassandra or DSE
Scala
26
star
42

cla-enforcer

A Contributor License Agreement enforcement bot
Ruby
25
star
43

pulsar-heartbeat

Pulsar Heartbeat monitors Pulsar cluster availability, tracks latency of Pulsar message pubsub, and reports failures of the Pulsar cluster. It produces synthetic workloads to measure end-to-end message pubsub latency.
Go
23
star
44

astrapy

AstraPy is a Pythonic interface for DataStax Astra DB and the Data API
Python
21
star
45

cassandra-data-apis

Data APIs for Apache Cassandra
Go
20
star
46

cassandra-log4j-appender

Cassandra appenders for Log4j
Java
20
star
47

terraform-provider-astra

A project that allows DataStax Astra users to manage their full database lifecycle for Astra Serverless databases (built on Apache Cassandra(TM)) using Terraform
Go
20
star
48

labs

DataStax Labs preview program
Java
19
star
49

starlight-for-kafka

DataStax - Starlight for Kafka
Java
17
star
50

dc-failover-demo

Fault Tolerant Applications with Apache Cassandra™ Demo
HCL
17
star
51

astra-sdk-java

Set of client side libraries to help with Astra Platform usage
Java
17
star
52

movies_plus_plus

TypeScript
17
star
53

kafka-sink

Apache Kafka® sink for transferring events/messages from Kafka topics to Apache Cassandra®, DataStax Astra and DataStax Enterprise (DSE).
Java
17
star
54

astrajs

A monorepo containing tools for interacting with DataStax Astra and Stargate
JavaScript
15
star
55

astra-db-ts

Typescript client for Astra DB Vector
TypeScript
15
star
56

native-protocol

An implementation of the Apache Cassandra® native protocol
Java
14
star
57

pulsar-sink

An Apache Pulsar® sink for transferring events/messages from Pulsar topics to Apache Cassandra®, DataStax Astra or DataStax Enterprise (DSE) tables.
Java
14
star
58

block-explorer

TypeScript
13
star
59

go-cassandra-native-protocol

Cassandra Native Protocol bindings for the Go language
Go
13
star
60

cassandra-reactive-demo

A demo application that interacts with Apache Cassandra(R) using the Java driver 4.4+ and reactive programming
Java
12
star
61

adelphi

Automation tool for testing C* OSS that assembles cassandra-diff, nosqlbench, fqltool
Python
10
star
62

pulsar-transformations

Java
10
star
63

astra-db-java

Java Client for DataStax Astra DB and the Data API
Java
10
star
64

dsbulk-migrator

Java
9
star
65

release-notes

Release Notes for DataStax Products
9
star
66

gatling-dse-plugin

Scala
8
star
67

gocql-astra

Support for gocql on Astra
Go
8
star
68

snowflake-connector

Datastax Snowflake Sink Connector for Apache Pulsar
Java
8
star
69

vault-plugin-secrets-datastax-astra

HashiCorp Vault Plugin for Datstax Astra
Go
8
star
70

pulsar-3rdparty-connector

This project provides simple templates and instructions to build Apache Pulsar connectors on base of the existing Apache Kafka connectors.
Shell
8
star
71

astra-client-go

Go
7
star
72

dsbench-labs

DSBench - A Database Testing Power Tool
7
star
73

remote-junit-runner

JUnit runner that executes tests in a remote JVM
Java
7
star
74

cass-config-builder

Configuration builder for Apache Cassandra based on definitions at datastax/cass-config-definitions
Clojure
7
star
75

astra-db-chatbot-starter

Python
6
star
76

java-driver-scala-extras

Scala extensions and utilities for the DataStax Java Driver
Scala
6
star
77

burnell

A proxy to Pulsar cluster
Go
6
star
78

ai-agent-java

AI Agent Starter in Java
6
star
79

gatling-dse-stress

Scala
5
star
80

gatling-dse-simcatalog

Scala
4
star
81

ds-support-diagnostic-collection

Scripts for collection of diagnostic information from DSE/Cassandra clusters running on various platforms
Shell
4
star
82

java-quotient-filter

A Java Quotient Filter implementation.
Java
4
star
83

charts

DataStax Helm Charts
Shell
4
star
84

pulsar-ansible

Shell
4
star
85

ragstack-ai-ts

TypeScript
4
star
86

astra-ide-plugin

Kotlin
3
star
87

terraform-helm-oci-release

HCL
3
star
88

cass-config-definitions

Shell
3
star
89

go-cassandra-simple-client

A simple Go client for the Cassandra native protocol
3
star
90

doyouknowyourstuff

Astro
3
star
91

terraform-datastax-ai-stack

3
star
92

astra-db-recommendations-starter

TypeScript
2
star
93

java-driver-examples-osgi

Examples showing the usage of the DataStax Java driver in OSGi applications.
Java
2
star
94

nodejs-driver-graph

DataStax Node.js Driver Extensions for DSE Graph
JavaScript
2
star
95

aws-secrets-manager-integration-astra

Python
2
star
96

starlight-for-grpc

Java
2
star
97

homebrew-luna-streaming-shell

Shell
2
star
98

astra-block-examples

Various Astra Block Examples
TypeScript
2
star
99

cassandra-drivers-smoke-test

Smoke tests for Apache Cassandra using the DataStax Drivers
Shell
2
star
100

junitpytest

JUnit5 plugin to run pytest via Gradle
Java
2
star