cql-rb 2.0.0.pre0 → 2.0.0.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1b00538d250d975f9b1ed2795bf947d9baf97c35
-  data.tar.gz: e1b27e7d7665bb8545b14c088fb7076ab5e76b01
+  metadata.gz: ee42c11d2d4d39946b1df62d6d0cd9ef240edf57
+  data.tar.gz: c2d82f55a791696d8ea9e1d0529f0c1fbec31c02
 SHA512:
-  metadata.gz: 9b24cfa7ecbd973138d21c64e6f64ab02673deefc8f9bab46e0cc1658d041bf15b237326aaec3cfd6f83f8152a802d4efed71cef505fc3fe6102d3d87c7fd49e
-  data.tar.gz: b3a5f99e920989e64ebde8669c3339890ee6b8bdd0c882e65ea2354d0055bd29bd48f2089355d13c279b64379fbb258cf0987306b6e9b11c49caec51d86adc54
+  metadata.gz: ced007c5c12672918218c0c3e24d792f77a84d81779c972aeb10b976355f9f5d860615835c1b7878f267380a19e8960a1f2cab347c15e978a65d3a287049a4be
+  data.tar.gz: 896789b373ba5310738f046c823dac12f261f544116000a39594d9f4dd6a30cef37a213e7fbef3a3267565f8469c3124762c4b86475dae79677fb066d9b7d537

data/README.md

@@ -85,6 +85,18 @@ rows = client.execute('SELECT date, description FROM events'
 rows.metadata['date'].type # => :date
 ```
 
+If you're using Cassandra 2.0 or later you no longer have to build CQL strings when you want to insert a value in a query, there's a new feature that lets you use bound values with reqular statements:
+
+```ruby
+client.execute("UPDATE users SET age = ? WHERE user_name = ?", 41, 'Sam')
+```
+
+If you find yourself doing this often, it's better to use prepared statements. As a rule of thumb, if your application is sending a request more than once, a prepared statement is almost always the right choice.
+
+When you use bound values with regular statements the type of the values has to be guessed. Cassandra supports multiple different numeric types, but there's no reliable way of guessing whether or not a Ruby `Fixnum` should be encoded as a `BIGINT` or `INT`, or whether a Ruby `Float` is a `DOUBLE` or `FLOAT`. When there are multiple choices the encoder will pick the larger type (e.g. `BIGINT` over `INT`). For Ruby strings it will always guess `VARCHAR`, never `BLOB`.
+
+You can override the guessing by passing type hints as an option, see the [API docs][1] for more information.
+
 Each call to `#execute` selects a random connection to run the query on.
 
 ## Creating keyspaces and tables
@@ -211,7 +223,7 @@ loop do
   result_page.each do |row|
     p row
   end
-  if result_page.last?
+  if result_page.last_page?
     break
   else
     result_page = result_page.next_page
@@ -224,7 +236,7 @@ end
 You can specify the default consistency to use when you create a new `Client`:
 
 ```ruby
-client = Cql::Client.connect(hosts: %w[localhost], consistency: :all)
+client = Cql::Client.connect(hosts: %w[localhost], default_consistency: :all)
 ```
 
 The `#execute` (of `Client` and `PreparedStatement`) method also supports setting the desired consistency level on a per-request basis:

data/lib/cql.rb

@@ -1,14 +1,19 @@
 # encoding: utf-8
 
+require 'ione'
+
+
 module Cql
   CqlError = Class.new(StandardError)
+
+  Promise = Ione::Promise
+  Future = Ione::Future
+  Io = Ione::Io
+  IoError = Ione::IoError
 end
 
 require 'cql/uuid'
 require 'cql/time_uuid'
-require 'cql/byte_buffer'
-require 'cql/future'
-require 'cql/io'
 require 'cql/compression'
 require 'cql/protocol'
 require 'cql/client'

data/lib/cql/client.rb

@@ -55,6 +55,24 @@ module Cql
   module Client
     InvalidKeyspaceNameError = Class.new(ClientError)
 
+    # @private
+    module SynchronousBacktrace
+      def synchronous_backtrace
+        yield
+      rescue CqlError => e
+        new_backtrace = caller
+        if new_backtrace.first.include?(SYNCHRONOUS_BACKTRACE_METHOD_NAME)
+          new_backtrace = new_backtrace.drop(1)
+        end
+        e.set_backtrace(new_backtrace)
+        raise
+      end
+
+      private
+
+      SYNCHRONOUS_BACKTRACE_METHOD_NAME = 'synchronous_backtrace'
+    end
+
     # Create a new client and connect to Cassandra.
     #
     # By default the client will connect to localhost port 9042, which can be
@@ -117,357 +135,6 @@ module Cql
     def self.connect(options={})
       SynchronousClient.new(AsynchronousClient.new(options)).connect
     end
-
-    class Client
-      # @!method connect
-      #
-      # Connect to all nodes. See {Cql::Client.connect} for the full
-      # documentation.
-      #
-      # This method needs to be called before any other. Calling it again will
-      # have no effect.
-      #
-      # @see Cql::Client.connect
-      # @return [Cql::Client]
-
-      # @!method close
-      #
-      # Disconnect from all nodes.
-      #
-      # @return [Cql::Client]
-
-      # @!method connected?
-      #
-      # Returns whether or not the client is connected.
-      #
-      # @return [true, false]
-
-      # @!method keyspace
-      #
-      # Returns the name of the current keyspace, or `nil` if no keyspace has been
-      # set yet.
-      #
-      # @return [String]
-
-      # @!method use(keyspace)
-      #
-      # Changes keyspace by sending a `USE` statement to all connections.
-      #
-      # The the second parameter is meant for internal use only.
-      #
-      # @param [String] keyspace
-      # @raise [Cql::NotConnectedError] raised when the client is not connected
-      # @return [nil]
-
-      # @!method execute(cql, *values, options_or_consistency={})
-      #
-      # Execute a CQL statement, optionally passing bound values.
-      #
-      # When passing bound values the request encoder will have to guess what
-      # types to encode the values as. For most types this will be no problem,
-      # but for integers and floating point numbers the larger size will be
-      # chosen (e.g. `BIGINT` and `DOUBLE` and not `INT` and `FLOAT`). You can
-      # override the guessing with the `:type_hint` option. Don't use on-the-fly
-      # bound values when you will issue the request multiple times, prepared
-      # statements are almost always a better choice.
-      #
-      # @note On-the-fly bound values are not supported in Cassandra 1.2
-      #
-      # @example A simple CQL query
-      #   result = client.execute("SELECT * FROM users WHERE user_name = 'sue'")
-      #   result.each do |row|
-      #     p row
-      #   end
-      #
-      # @example Using on-the-fly bound values
-      #   client.execute('INSERT INTO users (user_name, full_name) VALUES (?, ?)', 'sue', 'Sue Smith')
-      #
-      # @example Using on-the-fly bound values with type hints
-      #   client.execute('INSERT INTO users (user_name, age) VALUES (?, ?)', 'sue', 33, type_hints: [nil, :int])
-      #
-      # @example Specifying the consistency as a symbol
-      #   client.execute("UPDATE users SET full_name = 'Sue S. Smith' WHERE user_name = 'sue'", consistency: :one)
-      #
-      # @example Specifying the consistency and other options
-      #   client.execute("SELECT * FROM users", consistency: :all, timeout: 1.5)
-      #
-      # @example Activating tracing for a query
-      #   result = client.execute("SELECT * FROM users", tracing: true)
-      #   p result.trace_id
-      #
-      # @param [String] cql
-      # @param [Array] values Values to bind to any binding markers in the
-      #   query (i.e. "?" placeholders) -- using this feature is similar to
-      #   using a prepared statement, but without the type checking. The client
-      #   needs to guess which data types to encode the values as, and will err
-      #   on the side of caution, using types like BIGINT instead of INT for
-      #   integers, and DOUBLE instead of FLOAT for floating point numbers. It
-      #   is not recommended to use this feature for anything but convenience,
-      #   and the algorithm used to guess types is to be considered experimental.
-      # @param [Hash] options_or_consistency 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>`.
-      # @option options_or_consistency [Symbol] :consistency (:quorum) The
-      #   consistency to use for this query.
-      # @option options_or_consistency [Symbol] :serial_consistency (nil) The
-      #   consistency to use for conditional updates (`:serial` or
-      #   `:local_serial`), see the CQL documentation for the semantics of
-      #   serial consistencies and conditional updates. The default is assumed
-      #   to be `:serial` by the server if none is specified. Ignored for non-
-      #   conditional queries.
-      # @option options_or_consistency [Integer] :timeout (nil) How long to wait
-      #   for a response. If this timeout expires a {Cql::TimeoutError} will
-      #   be raised.
-      # @option options_or_consistency [Boolean] :trace (false) Request tracing
-      #   for this request. See {Cql::Client::QueryResult} and
-      #   {Cql::Client::VoidResult} for how to retrieve the tracing data.
-      # @option options_or_consistency [Array] :type_hints (nil) When passing
-      #   on-the-fly bound values the request encoder will have to guess what
-      #   types to encode the values as. Using this option you can give it hints
-      #   and avoid it guessing wrong. The hints must be an array that has the
-      #   same number of arguments as the number of bound values, and each
-      #   element should be the type of the corresponding value, or nil if you
-      #   prefer the encoder to guess. The types should be provided as lower
-      #   case symbols, e.g. `:int`, `:time_uuid`, etc.
-      # @raise [Cql::NotConnectedError] raised when the client is not connected
-      # @raise [Cql::TimeoutError] raised when a timeout was specified and no
-      #   response was received within the timeout.
-      # @raise [Cql::QueryError] raised when the CQL has syntax errors or for
-      #   other situations when the server complains.
-      # @return [nil, Cql::Client::QueryResult, Cql::Client::VoidResult] Some
-      #   queries have no result and return `nil`, but `SELECT` statements
-      #   return an `Enumerable` of rows (see {Cql::Client::QueryResult}), and
-      #   `INSERT` and `UPDATE` return a similar type
-      #   (see {Cql::Client::VoidResult}).
-
-      # @!method prepare(cql)
-      #
-      # Returns a prepared statement that can be run over and over again with
-      # different values.
-      #
-      # @see Cql::Client::PreparedStatement
-      # @param [String] cql The CQL to prepare
-      # @raise [Cql::NotConnectedError] raised when the client is not connected
-      # @raise [Cql::Io::IoError] raised when there is an IO error, for example
-      #   if the server suddenly closes the connection
-      # @raise [Cql::QueryError] raised when there is an error on the server
-      #   side, for example when you specify a malformed CQL query
-      # @return [Cql::Client::PreparedStatement] an object encapsulating the
-      #   prepared statement
-
-      # @!method batch(type=:logged, options={})
-      #
-      # Yields a batch when called with a block. The batch is automatically
-      # executed at the end of the block and the result is returned.
-      #
-      # Returns a batch when called wihtout a block. The batch will remember
-      # the options given and merge these with any additional options given
-      # when {Cql::Client::Batch#execute} is called.
-      #
-      # Please note that the batch object returned by this method _is not thread
-      # safe_.
-      #
-      # The type parameter can be ommitted and the options can then be given
-      # as first parameter.
-      #
-      # @example Executing queries in a batch
-      #   client.batch do |batch|
-      #     batch.add(%(INSERT INTO metrics (id, time, value) VALUES (1234, NOW(), 23423)))
-      #     batch.add(%(INSERT INTO metrics (id, time, value) VALUES (2346, NOW(), 13)))
-      #     batch.add(%(INSERT INTO metrics (id, time, value) VALUES (2342, NOW(), 2367)))
-      #     batch.add(%(INSERT INTO metrics (id, time, value) VALUES (4562, NOW(), 1231)))
-      #   end
-      #
-      # @example Using the returned batch object
-      #   batch = client.batch(:counter, trace: true)
-      #   batch.add('UPDATE counts SET value = value + ? WHERE id = ?', 4, 87654)
-      #   batch.add('UPDATE counts SET value = value + ? WHERE id = ?', 3, 6572)
-      #   result = batch.execute(timeout: 10)
-      #   puts result.trace_id
-      #
-      # @example Providing type hints for on-the-fly bound values
-      #   batch = client.batch
-      #   batch.add('UPDATE counts SET value = value + ? WHERE id = ?', 4, type_hints: [:int])
-      #   batch.execute
-      #
-      # @see Cql::Client::Batch
-      # @param [Symbol] type the type of batch, must be one of `:logged`,
-      #   `:unlogged` and `:counter`. The precise meaning of these  is defined
-      #   in the CQL specification.
-      # @yieldparam [Cql::Client::Batch] batch the batch
-      # @return [Cql::Client::VoidResult, Cql::Client::Batch] when no block is
-      #   given the batch is returned, when a block is given the result of
-      #   executing the batch is returned (see {Cql::Client::Batch#execute}).
-    end
-
-    class PreparedStatement
-      # Metadata describing the bound values
-      #
-      # @return [ResultMetadata]
-      attr_reader :metadata
-
-      # Metadata about the result (i.e. rows) that is returned when executing
-      # this prepared statement.
-      #
-      # @return [ResultMetadata]
-      attr_reader :result_metadata
-
-      # Execute the prepared statement with a list of values to be bound to the
-      # statements parameters.
-      #
-      # The number of arguments must equal the number of bound parameters. You
-      # can also specify options as the last argument, or a symbol as a shortcut
-      # for just specifying the consistency.
-      #
-      # Because you can specify options, or not, there is an edge case where if
-      # the last parameter of your prepared statement is a map, and you forget
-      # to specify a value for your map, the options will end up being sent to
-      # Cassandra. Most other cases when you specify the wrong number of
-      # arguments should result in an `ArgumentError` or `TypeError` being
-      # raised.
-      #
-      # @param args [Array] the values for the bound parameters. The last
-      #   argument can also be an options hash or a symbol (as a shortcut for
-      #   specifying the consistency), see {Cql::Client::Client#execute} for
-      #   full details.
-      # @raise [ArgumentError] raised when number of argument does not match
-      #   the number of parameters needed to be bound to the statement.
-      # @raise [Cql::NotConnectedError] raised when the client is not connected
-      # @raise [Cql::Io::IoError] raised when there is an IO error, for example
-      #   if the server suddenly closes the connection
-      # @raise [Cql::QueryError] raised when there is an error on the server side
-      # @return [nil, Cql::Client::QueryResult, Cql::Client::VoidResult] Some
-      #   queries have no result and return `nil`, but `SELECT` statements
-      #   return an `Enumerable` of rows (see {Cql::Client::QueryResult}), and
-      #   `INSERT` and `UPDATE` return a similar type
-      #   (see {Cql::Client::VoidResult}).
-      def execute(*args)
-      end
-    end
-
-    class Batch
-      # @!method add(cql_or_prepared_statement, *bound_values)
-      #
-      # Add a query or a prepared statement to the batch.
-      #
-      # @example Adding a mix of statements to a batch
-      #   batch.add(%(UPDATE people SET name = 'Miriam' WHERE id = 3435))
-      #   batch.add(%(UPDATE people SET name = ? WHERE id = ?), 'Miriam', 3435)
-      #   batch.add(prepared_statement, 'Miriam', 3435)
-      #
-      # @param [String, Cql::Client::PreparedStatement] cql_or_prepared_statement
-      #   a CQL string or a prepared statement object (obtained through
-      #   {Cql::Client::Client#prepare})
-      # @param [Array] bound_values a list of bound values -- only applies when
-      #   adding prepared statements and when there are binding markers in the
-      #   given CQL. If the last argument is a hash and it has the key
-      #   `:type_hints` this will be passed as type hints to the request encoder
-      #   (if the last argument is any other hash it will be assumed to be a
-      #   bound value of type MAP). See {Cql::Client::Client#execute} for more
-      #   info on type hints.
-      # @return [nil]
-
-      # @!method execute(options={})
-      #
-      # Execute the batch and return the result.
-      #
-      # @param options [Hash] an options hash or a symbol (as a shortcut for
-      #   specifying the consistency), see {Cql::Client::Client#execute} for
-      #   full details about how this value is interpreted.
-      # @raise [Cql::QueryError] raised when there is an error on the server side
-      # @raise [Cql::NotPreparedError] raised in the unlikely event that a
-      #   prepared statement was not prepared on the chosen connection
-      # @return [Cql::Client::VoidResult] a batch always returns a void result
-    end
-
-    class PreparedStatementBatch
-      # @!method add(*bound_values)
-      #
-      # Add the statement to the batch with the specified bound values.
-      #
-      # @param [Array] bound_values the values to bind to the added statement,
-      #   see {Cql::Client::PreparedStatement#execute}.
-      # @return [nil]
-
-      # @!method execute(options={})
-      #
-      # Execute the batch and return the result.
-      #
-      # @raise [Cql::QueryError] raised when there is an error on the server side
-      # @raise [Cql::NotPreparedError] raised in the unlikely event that a
-      #   prepared statement was not prepared on the chosen connection
-      # @return [Cql::Client::VoidResult] a batch always returns a void result
-    end
-
-    # An auth provider is a factory for {Cql::Client::Authenticator} instances
-    # (or objects matching that interface). Its {#create_authenticator} will be
-    # called once for each connection that requires authentication.
-    #
-    # If the authentication requires keeping state, keep that in the
-    # authenticator instances, not in the auth provider.
-    #
-    # @note Creating an authenticator must absolutely not block, or the whole
-    #   connection process will block.
-    #
-    # @note Auth providers given to {Cql::Client.connect} as the `:auth_provider`
-    #   option don't need to be subclasses of this class, but need to
-    #   implement the same methods. This class exists only for documentation
-    #   purposes.
-    class AuthProvider
-      # @!method create_authenticator(authentication_class, protocol_version)
-      #
-      # Create a new authenticator object. This method will be called once per
-      # connection that requires authentication. The auth provider can create
-      # different authenticators for different authentication classes, or return
-      # nil if it does not support the authentication class.
-      #
-      # @note This method must absolutely not block.
-      #
-      # @param authentication_class [String] the authentication class used by
-      #   the server.
-      # @return [Cql::Client::Authenticator, nil] an object with an interface
-      #   matching {Cql::Client::Authenticator} or nil if the authentication
-      #   class is not supported.
-    end
-
-    # An authenticator handles the authentication challenge/response cycles of
-    # a single connection. It can be stateful, but it must not for any reason
-    # block. If any of the method calls block, the whole connection process
-    # will be blocked.
-    #
-    # @note Authenticators created by auth providers don't need to be subclasses
-    #   of this class, but need to implement the same methods. This class exists
-    #   only for documentation purposes.
-    class Authenticator
-      # @!method initial_response
-      #
-      # This method must return the initial authentication token to be sent to
-      # the server.
-      #
-      # @note This method must absolutely not block.
-      #
-      # @return [String] the initial authentication token
-
-      # @!method challenge_response(token)
-      #
-      # If the authentication requires multiple challenge/response cycles this
-      # method will be called when a challenge is returned by the server. A
-      # response token must be created and will be sent back to the server.
-      #
-      # @note This method must absolutely not block.
-      #
-      # @param token [String] a challenge token sent by the server
-      # @return [String] the authentication token to send back to the server
-
-      # @!method authentication_successful(token)
-      #
-      # Called when the authentication is successful.
-      #
-      # @note This method must absolutely not block.
-      #
-      # @param token [String] a token sent by the server
-      # @return [nil]
-    end
   end
 end
 
@@ -479,13 +146,11 @@ require 'cql/client/result_metadata'
 require 'cql/client/query_trace'
 require 'cql/client/execute_options_decoder'
 require 'cql/client/keyspace_changer'
-require 'cql/client/asynchronous_client'
-require 'cql/client/asynchronous_prepared_statement'
-require 'cql/client/synchronous_client'
-require 'cql/client/synchronous_prepared_statement'
+require 'cql/client/client'
+require 'cql/client/prepared_statement'
 require 'cql/client/batch'
 require 'cql/client/query_result'
 require 'cql/client/void_result'
 require 'cql/client/request_runner'
 require 'cql/client/authenticators'
-require 'cql/client/peer_discovery'
+require 'cql/client/peer_discovery'