Module: Cql::Client

Defined in:


A CQL client manages connections to one or more Cassandra nodes and you use it run queries, insert and update data.

Client instances are threadsafe.

See Client for the full client API, or Client.connect for the options available when connecting.


Connecting and changing to a keyspace

# create a client and connect to two Cassandra nodes
client = Cql::Client.connect(hosts: %w[node01.cassandra.local node02.cassandra.local])
# change to a keyspace

Query for data

rows = client.execute('SELECT * FROM things WHERE id = 2')
rows.each do |row|
  p row

Inserting and updating data

client.execute("INSERT INTO things (id, value) VALUES (4, 'foo')")
client.execute("UPDATE things SET value = 'bar' WHERE id = 5")

Prepared statements

statement = client.prepare('INSERT INTO things (id, value) VALUES (?, ?)')
statement.execute(9, 'qux')
statement.execute(8, 'baz')

Defined Under Namespace

Classes: Batch, Client, ColumnMetadata, PreparedStatement, PreparedStatementBatch, QueryResult, ResultMetadata, VoidResult

Constant Summary collapse

InvalidKeyspaceNameError =

Class Method Summary collapse

Class Method Details

.connect(options = {}) ⇒ Cql::Client::Client

Create a new client and connect to Cassandra.

By default the client will connect to localhost port 9042, which can be overridden with the :hosts and :port options, respectively. Once connected to the hosts given in :hosts the rest of the nodes in the cluster will automatically be discovered and connected to.

If you have a multi data center setup the client will connect to all nodes in the data centers where the nodes you pass to :hosts are located. So if you only want to connect to nodes in one data center, make sure that you only specify nodes in that data center in :hosts.

The connection will succeed if at least one node is up and accepts the connection. Nodes that don't respond within the specified timeout, or where the connection initialization fails for some reason, are ignored.


  • options (Hash) (defaults to: {})

Options Hash (options):

  • :hosts (Array<String>) — default: ['localhost']

    One or more hostnames used as seed nodes when connecting. Duplicates will be removed.

  • :port (String) — default: 9042

    The port to connect to, this port will be used for all nodes. Because the system.peers table does not contain the port that the nodes are listening on, the port must be the same for all nodes.

  • :connection_timeout (Integer) — default: 5

    Max time to wait for a connection, in seconds.

  • :keyspace (String)

    The keyspace to change to immediately after all connections have been established, this is optional.

  • :credentials (Hash)

    When using Cassandra's built in authentication you can provide your username and password through this option. Example: :credentials => {:username => 'cassandra', :password => 'cassandra'}

  • :auth_provider (Object)

    When using custom authentication use this option to specify the auth provider that will handle the authentication negotiation. See AuthProvider for more info.

  • :connections_per_node (Integer) — default: 1

    The number of connections to open to each node. Each connection can have 128 concurrent requests, so unless you have a need for more than that (times the number of nodes in your cluster), leave this option at its default.

  • :default_consistency (Integer) — default: :quorum

    The consistency to use unless otherwise specified. Consistency can also be specified on a per-request basis.

  • :compressor (Cql::Compression::Compressor)

    An object that can compress and decompress frames. By specifying this option frame compression will be enabled. If the server does not support compression or the specific compression algorithm specified by the compressor, compression will not be enabled and a warning will be logged.

  • :cql_version (String)

    Specifies which CQL version the server should expect.

  • :logger (Integer)

    If you want the client to log significant events pass an object implementing the standard Ruby logger interface (e.g. quacks like Logger from the standard library) with this option.



  • Cql::Io::ConnectionError when a connection couldn't be established to any node

  • Cql::Client::QueryError when the specified keyspace does not exist or when the specifed CQL version is not supported.

# File 'lib/cql/client.rb', line 131

def self.connect(options={})