Class: Cequel::Metal::Keyspace

Inherits:
Object
  • Object
show all
Extended by:
Util::Forwardable
Includes:
Logging, MonitorMixin
Defined in:
lib/cequel/metal/keyspace.rb

Overview

Handle to a Cassandra keyspace (database). Keyspace objects are factories for DataSet instances and provide a handle to a Schema::Keyspace instance.

Since:

  • 1.0.0

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util::Forwardable

delegate

Methods included from Logging

#slowlog=

Constructor Details

#initialize(configuration = {}) ⇒ Keyspace

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Keyspace.

Parameters:

  • configuration (Options) (defaults to: {})

Options Hash (configuration):

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

    hostname of single Cassandra instance to connect to

  • :port (Integer) — default: 9042 —

    port on which to connect to all specified hosts

  • :max_retries (Integer) —

    maximum number of retries on connection failure

  • :hosts (Array<String>) —

    list of Cassandra instances to connect to (hostnames only)

  • :username (String) —

    user to auth with (leave blank for no auth)

  • :password (String) —

    password to auth with (leave blank for no auth)

  • :keyspace (String) —

    name of keyspace to connect to

  • :ssl (Boolean) —

    enable/disable ssl/tls support

  • :server_cert (String) —

    path to ssl server certificate

  • :client_cert (String) —

    path to ssl client certificate

  • :private_key (String) —

    path to ssl client private key

  • :passphrase (String) —

    the passphrase for client private key

  • :cassandra_error_policy (String) —

    A mixin for handling errors from Cassandra

  • :cassandra_options (Hash) —

    A hash of arbitrary options to pass to Cassandra

See Also:

Since:

  • 1.0.0



96
97
98
99
 
# File 'lib/cequel/metal/keyspace.rb', line 96

def initialize(configuration={})
  @lock = Monitor.new
  configure(configuration)
end

Instance Attribute Details

#cassandra_options ⇒ Hash (readonly)

Returns A hash of additional options passed to Cassandra, if any.

Returns:

  • (Hash) —

    A hash of additional options passed to Cassandra, if any

Since:

  • 1.0.0



34
35
36
 
# File 'lib/cequel/metal/keyspace.rb', line 34

def cassandra_options
  @cassandra_options
end

#client_compression ⇒ Symbol (readonly)

Returns The client compression option.

Returns:

  • (Symbol) —

    The client compression option

Since:

  • 1.0.0



32
33
34
 
# File 'lib/cequel/metal/keyspace.rb', line 32

def client_compression
  @client_compression
end

#configuration ⇒ Hash (readonly)

Returns configuration options for this keyspace.

Returns:

  • (Hash) —

    configuration options for this keyspace

Since:

  • 1.0.0



17
18
19
 
# File 'lib/cequel/metal/keyspace.rb', line 17

def configuration
  @configuration
end

#credentials ⇒ Hash (readonly)

Returns credentials for connect to cassandra.

Returns:

  • (Hash) —

    credentials for connect to cassandra

Since:

  • 1.0.0



28
29
30
 
# File 'lib/cequel/metal/keyspace.rb', line 28

def credentials
  @credentials
end

#default_consistency ⇒ Symbol

Returns the default consistency for queries in this keyspace.

Returns:

  • (Symbol) —

    the default consistency for queries in this keyspace

Since:

  • 1.1.0



266
267
268
 
# File 'lib/cequel/metal/keyspace.rb', line 266

def default_consistency
  @default_consistency || :quorum
end

#error_policy ⇒ Object (readonly)

Returns The error policy object in use by this keyspace.

Returns:

  • (Object) —

    The error policy object in use by this keyspace

Since:

  • 1.0.0



36
37
38
 
# File 'lib/cequel/metal/keyspace.rb', line 36

def error_policy
  @error_policy
end

#hosts ⇒ Array<String> (readonly)

Returns list of hosts to connect to.

Returns:

  • (Array<String>) —

    list of hosts to connect to

Since:

  • 1.0.0



21
22
23
 
# File 'lib/cequel/metal/keyspace.rb', line 21

def hosts
  @hosts
end

#name ⇒ String (readonly)

Returns name of the keyspace.

Returns:

  • (String) —

    name of the keyspace

Since:

  • 1.0.0



19
20
21
 
# File 'lib/cequel/metal/keyspace.rb', line 19

def name
  @name
end

#port ⇒ Object (readonly)

Returns Integer port to connect to Cassandra nodes on.

Returns:

  • Integer port to connect to Cassandra nodes on

Since:

  • 1.0.0



23
24
25
 
# File 'lib/cequel/metal/keyspace.rb', line 23

def port
  @port
end

#ssl_config ⇒ Hash (readonly)

Returns SSL Configuration options.

Returns:

  • (Hash) —

    SSL Configuration options

Since:

  • 1.0.0



30
31
32
 
# File 'lib/cequel/metal/keyspace.rb', line 30

def ssl_config
  @ssl_config
end

Class Method Details

.sanitize(statement, bind_vars) ⇒ String

Combine a statement with bind vars into a fully-fledged CQL query. This will no longer be needed once the CQL driver supports bound values natively.

Parameters:

  • statement (String) —

    CQL statement with ? placeholders for bind vars

  • bind_vars (Array) —

    bind variables corresponding to ? in the statement

Returns:

  • (String) —

    CQL statement with quoted values in place of bind variables

Since:

  • 1.0.0



79
80
81
82
 
# File 'lib/cequel/metal/keyspace.rb', line 79

def self.sanitize(statement, bind_vars)
  each_bind_var = bind_vars.each
  statement.gsub('?') { Type.quote(each_bind_var.next) }
end

Instance Method Details

#[](table_name) ⇒ DataSet

Returns data set encapsulating table.

Parameters:

  • table_name (Symbol) —

    the name of the table

Returns:

  • (DataSet) —

    data set encapsulating table

Since:

  • 1.0.0



165
166
167
 
# File 'lib/cequel/metal/keyspace.rb', line 165

def [](table_name)
  DataSet.new(table_name.to_sym, self)
end

#batch { ... } ⇒ Object

Note:

If this method is created while already in a batch of the same type (logged or unlogged), this method is a no-op.

Execute write operations in a batch. Any inserts, updates, and deletes inside this method’s block will be executed inside a CQL BATCH operation.

Examples:

Perform inserts in a batch

DB.batch do
  DB[:posts].insert(:id => 1, :title => 'One')
  DB[:posts].insert(:id => 2, :title => 'Two')
end

Parameters:

  • options (Hash)

Yields:

  • context within which all write operations will be batched

Returns:

  • return value of block

Raises:

  • (ArgumentError) —

    if attempting to start a logged batch while already in an unlogged batch, or vice versa.



65
 
# File 'lib/cequel/metal/keyspace.rb', line 65

def_delegator :batch_manager, :batch

#bug8733_version? ⇒ Boolean

return true if Cassandra server version is known to include bug CASSANDRA-8733

Returns:

  • (Boolean)

Since:

  • 1.0.0



290
291
292
293
294
295
296
297
298
299
 
# File 'lib/cequel/metal/keyspace.rb', line 290

def bug8733_version?
  version_file = File.expand_path('../../../../.cassandra-versions', __FILE__)
  @all_versions ||= File.read(version_file).split("\n").map(&:strip)

  # bug exists in versions 0.3.0-2.0.12 and 2.1.0-2.1.2
  @bug8733_versions ||= @all_versions[0..@all_versions.index('2.0.12')] +
      @all_versions[@all_versions.index('2.1.0')..@all_versions.index('2.1.2')]

  @bug8733_versions.include?(cassandra_version)
end

#cassandra_version ⇒ String

Returns Cassandra version number.

Returns:

  • (String) —

    Cassandra version number

Since:

  • 1.0.0



276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/cequel/metal/keyspace.rb', line 276

def cassandra_version
  return @cassandra_version if @cassandra_version

  statement = <<-CQL
    SELECT release_version
    FROM system.local
  CQL

  log('CQL', statement) do
    @cassandra_version = client_without_keyspace.execute(statement).first['release_version']
  end
end

#clear_active_connections! ⇒ void

This method returns an undefined value.

Clears all active connections

Since:

  • 1.0.0



247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/cequel/metal/keyspace.rb', line 247

def clear_active_connections!
  synchronize do
    if defined? @client
      remove_instance_variable(:@client)
    end
    if defined? @client_without_keyspace
      remove_instance_variable(:@client_without_keyspace)
    end
    if defined? @cluster
      @cluster.close
      remove_instance_variable(:@cluster)
    end
  end
end

#client ⇒ Cql::Client::Client

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the low-level client provided by the adapter.

Returns:

  • (Cql::Client::Client) —

    the low-level client provided by the adapter

Since:

  • 1.0.0



174
175
176
177
178
 
# File 'lib/cequel/metal/keyspace.rb', line 174

def client
  synchronize do
    @client ||= cluster.connect(name)
  end
end

#cluster ⇒ Object

Since:

  • 1.0.0



301
302
303
304
305
 
# File 'lib/cequel/metal/keyspace.rb', line 301

def cluster
  synchronize do
    @cluster ||= Cassandra.cluster(client_options)
  end
end

#configure(configuration = {}) ⇒ void

This method returns an undefined value.

Configure this keyspace from a hash of options

Parameters:

  • configuration (Options) (defaults to: {}) —

    configuration options

Options Hash (configuration):

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

    hostname of single Cassandra instance to connect to

  • :port (Integer) — default: 9042 —

    port on which to connect to all specified hosts

  • :max_retries (Integer) —

    maximum number of retries on connection failure

  • :hosts (Array<String>) —

    list of Cassandra instances to connect to (hostnames only)

  • :username (String) —

    user to auth with (leave blank for no auth)

  • :password (String) —

    password to auth with (leave blank for no auth)

  • :keyspace (String) —

    name of keyspace to connect to

  • :ssl (Boolean) —

    enable/disable ssl/tls support

  • :server_cert (String) —

    path to ssl server certificate

  • :client_cert (String) —

    path to ssl client certificate

  • :private_key (String) —

    path to ssl client private key

  • :passphrase (String) —

    the passphrase for client private key

  • :cassandra_error_policy (String) —

    A mixin for handling errors from Cassandra

  • :cassandra_options (Hash) —

    A hash of arbitrary options to pass to Cassandra

Since:

  • 1.0.0



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/cequel/metal/keyspace.rb', line 133

def configure(configuration = {})
  if configuration.key?(:thrift)
    warn "Cequel no longer uses the Thrift transport to communicate " \
         "with Cassandra. The :thrift option is deprecated and ignored."
  end
  @configuration = configuration
  
  @error_policy = extract_cassandra_error_policy(configuration)
  @cassandra_options = extract_cassandra_options(configuration)
  @hosts, @port = extract_hosts_and_port(configuration)
  @credentials  = extract_credentials(configuration)
  @ssl_config = extract_ssl_config(configuration)

  @name = configuration[:keyspace]
  @default_consistency = configuration[:default_consistency].try(:to_sym)
  @client_compression = configuration[:client_compression].try(:to_sym)

  # reset the connections
  clear_active_connections!
end

#execute(statement, *bind_vars) ⇒ Enumerable

Execute a CQL query in this keyspace

If a connection error occurs, will retry a maximum number of
time (default 3) before re-raising the original connection
error.

Parameters:

  • statement (String) —

    CQL string

  • bind_vars (Object) —

    values for bind variables

Returns:

  • (Enumerable) —

    the results of the query

See Also:

Since:

  • 1.0.0



193
194
195
 
# File 'lib/cequel/metal/keyspace.rb', line 193

def execute(statement, *bind_vars)
  execute_with_options(Statement.new(statement, bind_vars), { consistency: default_consistency })
end

#execute_with_options(statement, options = {}) ⇒ Enumerable

Execute a CQL query in this keyspace with the given options

Parameters:

  • statement (String, Statement, Batch) —

    statement to execute

  • options (Options) (defaults to: {}) —

    options for statement execution

Returns:

  • (Enumerable) —

    the results of the query

Since:

  • 1.1.0



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/cequel/metal/keyspace.rb', line 206

def execute_with_options(statement, options={})
  options[:consistency] ||= default_consistency

  cql, options = *case statement
                  when Statement
                    [prepare_statement(statement),
                     {arguments: statement.bind_vars}.merge(options)]
                  when Cassandra::Statements::Batch
                    [statement, options]
                  end

  log('CQL', statement) do
    error_policy.execute_stmt(self) do
      client.execute(cql, options)
    end
  end
end

#exists? ⇒ Boolean

Returns true if the keyspace exists.

Returns:

  • (Boolean) —

    true if the keyspace exists

Since:

  • 1.0.0



271
272
273
 
# File 'lib/cequel/metal/keyspace.rb', line 271

def exists?
  cluster.has_keyspace?(name)
end

#prepare_statement(statement) ⇒ Cassandra::Statement::Prepared

Wraps the prepare statement in the default retry strategy

Parameters:

  • statement (String, Statement) —

    statement to prepare

Returns:

  • (Cassandra::Statement::Prepared) —

    the prepared statement

Since:

  • 1.0.0



230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/cequel/metal/keyspace.rb', line 230

def prepare_statement(statement)
  cql = case statement
        when Statement
          statement.cql
        else
          statement
        end
  error_policy.execute_stmt(self) do
    client.prepare(cql)
  end
end

#sanitize ⇒ String

Combine a statement with bind vars into a fully-fledged CQL query. This will no longer be needed once the CQL driver supports bound values natively.

Parameters:

  • statement (String) —

    CQL statement with ? placeholders for bind vars

  • bind_vars (Array) —

    bind variables corresponding to ? in the statement

Returns:

  • (String) —

    CQL statement with quoted values in place of bind variables



88
 
# File 'lib/cequel/metal/keyspace.rb', line 88

def_delegator 'self.class', :sanitize

#schema ⇒ Schema::Keyspace

Returns schema object providing full read/write access to database schema.

Returns:

  • (Schema::Keyspace) —

    schema object providing full read/write access to database schema

Since:

  • 1.0.0



157
158
159
 
# File 'lib/cequel/metal/keyspace.rb', line 157

def schema
  Schema::Keyspace.new(self)
end

#write(statement, *bind_vars) ⇒ void

This method returns an undefined value.

Write data to this keyspace using a CQL query. Will be included the current batch operation if one is present.



47
 
# File 'lib/cequel/metal/keyspace.rb', line 47

def_delegator :write_target, :execute, :write

#write_with_options(statement, bind_vars, consistency) ⇒ void

This method returns an undefined value.

Write data to this keyspace using a CQL query at the given consistency. Will be included the current batch operation if one is present.



58
59
 
# File 'lib/cequel/metal/keyspace.rb', line 58

def_delegator :write_target, :execute_with_options,
:write_with_options