Module: Cql::Client

Defined in:
lib/cql/client.rb,
lib/cql/client/null_logger.rb,
lib/cql/client/query_result.rb,
lib/cql/client/request_runner.rb,
lib/cql/client/column_metadata.rb,
lib/cql/client/result_metadata.rb,
lib/cql/client/keyspace_changer.rb,
lib/cql/client/connection_helper.rb,
lib/cql/client/connection_manager.rb,
lib/cql/client/synchronous_client.rb,
lib/cql/client/asynchronous_client.rb,
lib/cql/client/execute_options_decoder.rb,
lib/cql/client/synchronous_prepared_statement.rb,
lib/cql/client/asynchronous_prepared_statement.rb

Overview

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.

Examples:

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
client.use('stuff')

Query for data

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

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

Modules: SynchronousBacktrace Classes: AsynchronousClient, AsynchronousPreparedStatement, AuthenticationRequired, Client, ColumnMetadata, ConnectionHelper, ConnectionManager, ExecuteOptionsDecoder, KeyspaceChanged, KeyspaceChanger, NullLogger, Pipeline, PreparedStatement, QueryResult, RequestRunner, ResultMetadata, SynchronousClient, SynchronousPreparedStatement

Constant Summary collapse

InvalidKeyspaceNameError = 
Class.new(ClientError)

Class Method Summary collapse

Instance 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.

Parameters:

  • 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.

  • :host (String) — default: 'localhost' —

    A comma separated list of hostnames to use as seed nodes. This is a backwards-compatible version of the :hosts option, and is deprecated.

  • :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.

  • :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.

  • :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.

Returns:

Raises:

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



98
99
100
 
# File 'lib/cql/client.rb', line 98

def self.connect(options={})
  SynchronousClient.new(AsynchronousClient.new(options)).connect
end

Instance Method Details

#close ⇒ Cql::Client

Disconnect from all nodes.

Returns:




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

#connect ⇒ Cql::Client

Connect to all nodes. See connect for the full documentation.

This method needs to be called before any other. Calling it again will have no effect.

Returns:

See Also:




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

#connected? ⇒ true, false

Returns whether or not the client is connected.

Returns:

  • (true, false) 



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

#execute(cql, options_or_consistency = nil) ⇒ nil, Cql::Client::QueryResult

Execute a CQL statement

Parameters:

  • cql (String)
  • options_or_consistency (Hash) (defaults to: nil) —

    Either a consistency as a symbol (e.g. ‘:quorum`), or a options hash (see below). Passing a symbol is equivalent to passing the options `consistency: <symbol>`.

Options Hash (options_or_consistency):

  • :consistency (Symbol) — default: :quorum —

    The consistency to use for this query.

  • :timeout (Symbol) — default: nil —

    How long to wait for a response. If this timeout expires a TimeoutError will be raised.

Returns:

Raises:

  • (Cql::NotConnectedError) —

    raised when the client is not connected

  • (Cql::TimeoutError) —

    raised when a timeout was specified and no response was received within the timeout.

  • (Cql::QueryError) —

    raised when the CQL has syntax errors or for other situations when the server complains.




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

#keyspace ⇒ String

Returns the name of the current keyspace, or ‘nil` if no keyspace has been set yet.

Returns:

  • (String) 



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

#prepare(cql) ⇒ Cql::Client::PreparedStatement

Returns a prepared statement that can be run over and over again with different values.

Parameters:

  • cql (String) —

    The CQL to prepare

Returns:

Raises:

  • (Cql::NotConnectedError) —

    raised when the client is not connected

  • (Cql::Io::IoError) —

    raised when there is an IO error, for example if the server suddenly closes the connection

  • (Cql::QueryError) —

    raised when there is an error on the server side, for example when you specify a malformed CQL query

See Also:




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

#use(keyspace) ⇒ nil

Changes keyspace by sending a ‘USE` statement to all connections.

The the second parameter is meant for internal use only.

Parameters:

  • keyspace (String)

Returns:

  • (nil)

Raises:




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