cql-rb 1.1.0.pre8 → 1.1.0.rc0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NzkxNmUwM2YwMzllNGEyNGU4NmY0Mjg1N2RmYzBmZjQ0NmU1ODE3NQ==
+    MTBkMThlZTE2MTk5MzFiNTgzNmYyMDM4ZTViNjNhNjFhNWM3OGVhNw==
   data.tar.gz: !binary |-
-    ZDJhMzk2Nzg1MGNiODYxNjYwYTcyY2YyMjcwZmRhYjU4OGMyY2MxYg==
+    ZWQ1M2EzZWExOGUyNzUwNzE2ODQxMzgyYmI2MDdkM2ZhY2Q0NTA3OQ==
 SHA512:
   metadata.gz: !binary |-
-    MTBmMzM1NzYyYTk3ODc0YjgyMzE1ODA0ZWE4ODVkMzc3ZjQ0ODE0YTY3MjA0
-    MzRiODU5OGFlMjEzYmZkYTQ2MzI3MmFiMDQxYWNiOTI0NjMzYjQ1YjdlNjE4
-    NDlmNjJjZTI0NjJiMGIyMjhhNzNjYzc0N2JkZmEyNzhkZDViM2E=
+    Y2QzMzNmMTg1ODZhYzVmYTU4Njk5MjYzNDgxZmFlMjExZTYwYzRiNjk2MjVj
+    YmYxOWQ3YzVkNDZlNmM5NWQ2YzYwN2Y5OGMwMDc1NWYzZTBhMzBhZmRlZGU2
+    ODUwMGY4NGIxNTdlNWVlZThlZTc4M2NhZjU4ODVlMGYyYWM5MWM=
   data.tar.gz: !binary |-
-    NWFmNzk3MTc2NzlmOWJhZDlkMDAwYmNjNGNmNDUwN2Q0M2Y2NmEzNTZjY2Fi
-    NjIxMzQ2MjYxMTZiN2NhMzc1Y2M4ODg3MDdjYjQ3MmVjZGEwMDZlOGEwMjY5
-    YTc1YWZjOGU0MzVjOTcwZDIzMTc4OTE4ZDc1N2ZkODk4YjU4MmI=
+    YzQ1ZTRjMjUxM2I4OGJlMGRkZDE4NTkwZmZkNWFmZjc5NTNhNWI2ZmNjZTZi
+    YjE2ZGM0ODIzMDBmNmViNzBjMDU5YzUzZDVkNGNjMTQyMzYzY2FjNDdkYTAx
+    OGQ4ODIwZDk5YzQ4YjRmOGUxMmYzZTcyNmVlMTcwM2VlNWE5ZjQ=

data/README.md

@@ -5,7 +5,7 @@
 
 # Requirements
 
-Cassandra 1.2 with the native transport protocol turned on and a modern Ruby. It's tested continuously in Travis with Ruby 1.9.3, 2.0.0, and JRuby 1.7.x stable and head.
+Cassandra 1.2 or later with the native transport protocol turned on and a modern Ruby. It's tested continuously in Travis with Ruby 1.9.3, 2.0.0, and JRuby 1.7.x stable and head.
 
 # Installation
 
@@ -13,14 +13,14 @@ Cassandra 1.2 with the native transport protocol turned on and a modern Ruby. It
 
 ## Configure Cassandra
 
-If you're running Cassandra 1.2.5 the native transport protocol is enabled by default, if you're running an earlier version (but later than 1.2) you must enable it by editing `cassandra.yaml` and setting `start_native_transport` to `true`.
+If you're running Cassandra 1.2.5 or later the native transport protocol is enabled by default, if you're running an earlier version (but later than 1.2) you must enable it by editing `cassandra.yaml` and setting `start_native_transport` to `true`.
 
 # Quick start
 
 ```ruby
 require 'cql'
 
-client = Cql::Client.connect(host: 'cassandra.example.com')
+client = Cql::Client.connect(hosts: ['cassandra.example.com'])
 client.use('system')
 rows = client.execute('SELECT keyspace_name, columnfamily_name FROM schema_columnfamilies')
 rows.each do |row|
@@ -28,7 +28,13 @@ rows.each do |row|
 end
 ```
 
-when you're done you can call `#close` to disconnect from Cassandra. You can connect to multiple Cassandra nodes by passing multiple comma separated host names to the `:host` option -- _this is deprecated, in v1.1.0 there is a new option `:hosts` that takes a list of host names_.
+The host you specify is just a seed node, the client will automatically connect to all other nodes in the cluster (or nodes in the same data center if you're running multiple rings).
+
+When you're done you can call `#close` to disconnect from Cassandra:
+
+```ruby
+client.close
+```
 
 # Usage
 
@@ -74,6 +80,8 @@ rows = client.execute('SELECT date, description FROM events'
 rows.metadata['date'].type # => :date
 ```
 
+Each call to `#execute` selects a random connection to run the query on.
+
 ## Creating keyspaces and tables
 
 There is no special facility for creating keyspaces and tables, they are created by executing CQL:
@@ -97,11 +105,11 @@ table_definition = <<-TABLEDEF
 TABLEDEF
 
 client.execute(keyspace_definition)
-client.use(measurements)
+client.use('measurements')
 client.execute(table_definition)
 ```
 
-You can also `ALTER` keyspaces and tables.
+You can also `ALTER` keyspaces and tables, and you can read more about that in the [CQL3 syntax documentation](https://github.com/apache/cassandra/blob/cassandra-1.2/doc/cql3/CQL.textile).
 
 ## Prepared statements
 
@@ -116,17 +124,29 @@ A prepared statement can be run many times, but the CQL parsing will only be don
 
 `INSERT`, `UPDATE`, `DELETE` and `SELECT` statements can be prepared, other statements may raise `QueryError`.
 
-At this time prepared statements are local to a single connection. Even if you connect to multiple nodes a prepared statement is only ever going to be executed against one of the nodes.
+Statements are prepared on all connections and each call to `#execute` selects a random connection to run the query on.
 
-# Consistency
+## Consistency
 
-The `#execute` (of `Client` and `PreparedStatement`) method supports setting the desired consistency level for the statement:
+You can specify the default consistency to use when you create a new `Client`:
+
+```ruby
+client = Cql::Client.connect(hosts: %w[localhost], consistency: :all)
+```
+
+The `#execute` (of `Client` and `PreparedStatement`) method also supports setting the desired consistency level on a per-request basis:
+
+```ruby
+client.execute('SELECT * FROM peers', consistency: :local_quorum)
+```
+
+for backwards compatibility with v1.0 you can also pass the consistency as just a symbol:
 
 ```ruby
 client.execute('SELECT * FROM peers', :local_quorum)
 ```
 
-The possible values are: 
+The possible values for consistency are: 
 
 * `:any`
 * `:one`
@@ -137,16 +157,20 @@ The possible values are:
 * `:local_quorum`
 * `:each_quorum`
 
-The default consistency level is `:quorum`.
+The default consistency level unless you've set it yourself is `:quorum`.
 
 Consistency is ignored for `USE`, `TRUNCATE`, `CREATE` and `ALTER` statements, and some (like `:any`) aren't allowed in all situations.
 
-## CQL3
+# CQL3
 
 This is just a driver for the Cassandra native CQL protocol, it doesn't really know anything about CQL. You can run any CQL3 statement and the driver will return whatever Cassandra replies with.
 
 Read more about CQL3 in the [CQL3 syntax documentation](https://github.com/apache/cassandra/blob/cassandra-1.2/doc/cql3/CQL.textile) and the [Cassandra query documentation](http://www.datastax.com/docs/1.2/cql_cli/querying_cql).
 
+# Cassandra 2.0
+
+Cassandra 2.0 introduced a new version of the native protocol with some new features like argument interpolation in non-prepared statements, result set cursors, a new authentication mechanism and the `SERIAL` consistency. These features are not yet supported, but the driver will work with Cassandra 2.0 using the earlier protocol.
+
 # Troubleshooting
 
 ## I get "Deadlock detected" errors
@@ -185,10 +209,6 @@ If your process does not fork and you still encounter deadlock errors, it might
 
 There's a known issue with collections that get too big. The protocol uses a short for the size of collections, but there is no way for Cassandra to stop you from creating a collection bigger than 65536 elements, so when you do the size field overflows with strange results. The data is there, you just can't get it back.
 
-## The error backtraces are weird
-
-Yeah, sorry. All IO is asynchronous, and when an error is returned from Cassandra the call stack from when the request was issued is gone. `QueryError` has a `#cql` field that contains the CQL for the request that failed, hopefully that gives you enough information to understand where the error originated.
-
 ## Authentication doesn't work
 
 Please open an issue. It should be working, but it's hard to write tests for, so there may be edge cases that aren't covered.
@@ -197,10 +217,6 @@ Please open an issue. It should be working, but it's hard to write tests for, so
 
 Port 9160 is the old Thrift interface, the binary protocol runs on 9042. This is also the default port for cql-rb, so unless you've changed the port in `cassandra.yaml`, don't override the port.
 
-## One of my Cassandra nodes crashed, and my application crashed, isn't Cassandra supposed to be fault tolerant?
-
-Yes it is, and your data is probably safe. cql-rb is just not completely there yet. Ideally it should handle connectivity issues and just talk to the nodes it can talk to and reconnect when things get back to normal. _This is fixed in HEAD and will be released with v1.1.0_.
-
 ## Something else is not working
 
 Open an issue and someone will try to help you out. Please include the gem version, Casandra version and Ruby version, and explain as much about what you're doing as you can, preferably the smallest piece of code that reliably triggers the problem. The more information you give, the better the chances you will get help.
@@ -209,16 +225,20 @@ Open an issue and someone will try to help you out. Please include the gem versi
 
 Check out the [releases on GitHub](https://github.com/iconara/cql-rb/releases). Version numbering follows the [semantic versioning](http://semver.org/) scheme.
 
+Private and experimental APIs, defined as whatever is not in the [public API documentation](http://rubydoc.info/gems/cql-rb/frames) 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 determining the maturity of the release.
+
 # Known bugs & limitations
 
-* No automatic peer discovery -- _this is in HEAD and will be released with v1.1.0_.
-* No automatic reconnection on connection failures -- _this is in HEAD and will be released with v1.1.0_.
-* No support for request timeouts (other than server-initiated), but requests to a node fail when that node goes down -- _this is in HEAD and will be released with v1.1.0_.
 * No support for compression.
 * No support for request tracing.
-* JRuby 1.6.8 and earlier is not supported, the tests pass in 1.6.8, but 1.6.4 is known not to work. Travis does not support JRuby 1.6.x so there's no way to get good coverage of what works and not. The only known issue in 1.6.8 is that connection failures aren't handled correctly.
+* JRuby 1.6 is not officially supported, although 1.6.8 should work, if you're stuck in JRuby 1.6.8 try and see if it works for you.
 * Large results are buffered in memory until the whole response has been loaded, the protocol makes it possible to start to deliver rows to the client code as soon as the metadata is loaded, but this is not supported yet.
 * There is no cluster introspection utilities (like the `DESCRIBE` commands in `cqlsh`).
+* New features in v2 of the protocol are not supported
+
+Also check out the [issues](https://github.com/iconara/cql-rb/issues) for open bugs.
 
 # How to contribute
 
@@ -234,7 +254,7 @@ Always remember that the maintainers' work on this project in their free time an
 
 # Copyright
 
-Copyright 2013 Theo Hultberg/Iconara
+Copyright 2013 Theo Hultberg/Iconara and contributors
 
 _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_
 

data/lib/cql/client.rb

@@ -1,6 +1,10 @@
 # encoding: utf-8
 
 module Cql
+  # This error type represents errors sent by the server, the `code` attribute
+  # can be used to find the exact type, and `cql` contains the request's CQL,
+  # if any. `message` contains the human readable error message sent by the
+  # server.
   class QueryError < CqlError
     attr_reader :code, :cql
 
@@ -19,9 +23,14 @@ module Cql
   # 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 {Cql::Client::Client} for the full client API, or {Cql::Client.connect}
+  # for the options available when connecting.
+  #
   # @example Connecting and changing to a keyspace
   #   # create a client and connect to two Cassandra nodes
-  #   client = Cql::Client.connect(host: 'node01.cassandra.local,node02.cassandra.local')
+  #   client = Cql::Client.connect(hosts: %w[node01.cassandra.local node02.cassandra.local])
   #   # change to a keyspace
   #   client.use('stuff')
   #
@@ -39,11 +48,6 @@ module Cql
   #   statement = client.prepare('INSERT INTO things (id, value) VALUES (?, ?)')
   #   statement.execute(9, 'qux')
   #   statement.execute(8, 'baz')
-  #
-  # Client instances are threadsafe.
-  #
-  # See {Cql::Client::Client} for the full client API.
-  #
   module Client
     InvalidKeyspaceNameError = Class.new(ClientError)
 
@@ -54,25 +58,43 @@ module Cql
     # connected to the hosts given in `:hosts` the rest of the nodes in the
     # cluster will automatically be discovered and connected to.
     #
-    # The connection will succeed if at least one node is up. Nodes that don't
-    # respond within the specified timeout, or where the connection initialization
-    # fails for some reason, are ignored.
+    # 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.
     #
-    # @raise Cql::Io::ConnectionError when a connection couldn't be established
-    #   to any node
     # @param [Hash] options
     # @option options [Array<String>] :hosts (['localhost']) One or more
     #   hostnames used as seed nodes when connecting. Duplicates will be removed.
     # @option options [String] :host ('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.
-    # @option options [String] :port (9042) The port to connect to
+    # @option options [String] :port (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.
     # @option options [Integer] :connection_timeout (5) Max time to wait for a
-    #   connection, in seconds
+    #   connection, in seconds.
     # @option options [String] :keyspace The keyspace to change to immediately
     #   after all connections have been established, this is optional.
+    # @option options [Integer] :connections_per_node (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.
+    # @option options [Integer] :default_consistency (:quorum) The consistency
+    #   to use unless otherwise specified. Consistency can also be specified on
+    #   a per-request basis.
+    # @option options [Integer] :logger 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.
+    # @raise Cql::Io::ConnectionError when a connection couldn't be established
+    #   to any node
     # @return [Cql::Client::Client]
-    #
     def self.connect(options={})
       SynchronousClient.new(AsynchronousClient.new(options)).connect
     end
@@ -80,13 +102,13 @@ module Cql
     class Client
       # @!method connect
       #
-      # Connect to all nodes.
+      # Connect to all nodes. See {Cql::Client.connect} for the full
+      # documentation.
       #
-      # You must call this method before you call any of the other methods of a
-      # client. Calling it again will have no effect.
+      # 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
@@ -118,17 +140,26 @@ module Cql
       # @raise [Cql::NotConnectedError] raised when the client is not connected
       # @return [nil]
 
-      # @!method execute(cql, consistency=:quorum)
+      # @!method execute(cql, options_or_consistency=nil)
       #
       # Execute a CQL statement
       #
       # @param [String] cql
-      # @param [Symbol] consistency
+      # @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] :timeout (nil) How long to wait
+      #   for a response. If this timeout expires a {Cql::TimeoutError} will
+      #   be raised.
       # @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] Most statements have no result and return
-      #   `nil`, but `SELECT` statements return an `Enumerable` of rows
+      # @return [nil, Cql::Client::QueryResult] Most queries have no result and
+      #   return `nil`, but `SELECT` statements return an `Enumerable` of rows
       #   (see {Cql::Client::QueryResult}).
 
       # @!method prepare(cql)
@@ -136,30 +167,48 @@ module Cql
       # Returns a prepared statement that can be run over and over again with
       # different values.
       #
-      # @param [String] cql
+      # @see Cql::Client::PreparedStatement
+      # @param [String] cql The CQL to prepare
       # @raise [Cql::NotConnectedError] raised when the client is not connected
-      # @return [Cql::Client::PreparedStatement] an object encapsulating the prepared statement
+      # @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
     end
 
     class PreparedStatement
       # @return [ResultMetadata]
       attr_reader :metadata
 
-      # Execute the prepared statement with a list of values for the bound parameters.
-      #
-      # The number of arguments must equal the number of bound parameters.
-      # To set the consistency for the request you pass a consistency (as a
-      # symbol) as the last argument. Needless to say, if you pass the value for
-      # one bound parameter too few, and then a consistency, or if you pass too
-      # many values, you will get weird errors.
-      #
-      # @param args [Array] the values for the bound parameters, and optionally
-      #   the desired consistency, as a symbol (defaults to :quorum)
+      # 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] Most statements have no result and return
-      #   `nil`, but `SELECT` statements return an `Enumerable` of rows
-      #   (see {Cql::Client::QueryResult}).
+      # @return [nil, Cql::Client::QueryResult] Most statements have no result
+      #    and return `nil`, but `SELECT` statements return an `Enumerable` of
+      #   rows (see {Cql::Client::QueryResult}).
       def execute(*args)
       end
     end

data/lib/cql/client/asynchronous_client.rb

@@ -27,22 +27,16 @@ module Cql
 
       def connect
         @lock.synchronize do
+          raise ClientError, 'Cannot connect a closed client' if @closing || @closed
           return @connected_future if can_execute?
           @connecting = true
           @connected_future = begin
             f = @connection_helper.connect(@hosts, @initial_keyspace)
-            if @closing
-              ff = @closed_future
-              ff = ff.flat_map { f }
-              ff = ff.fallback { f }
-            else
-              ff = f
-            end
-            ff.on_value do |connections|
+            f.on_value do |connections|
               @connection_manager.add_connections(connections)
               register_event_listener(@connection_manager.random_connection)
             end
-            ff.map { self }
+            f.map { self }
           end
         end
         @connected_future.on_complete(&method(:connected))
@@ -140,6 +134,7 @@ module Cql
       def closed(f)
         @lock.synchronize do
           @closing = false
+          @closed = true
           @connected = false
           if f.resolved?
             @logger.info('Cluster disconnect complete')

data/lib/cql/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module Cql
-  VERSION = '1.1.0.pre8'.freeze
+  VERSION = '1.1.0.rc0'.freeze
 end

data/spec/cql/client/asynchronous_client_spec.rb

@@ -400,6 +400,12 @@ module Cql
           io_reactor.stub(:stop).and_return(Future.failed(StandardError.new('Bork!')))
           expect { client.close.value }.to raise_error('Bork!')
         end
+
+        it 'cannot be connected again once closed' do
+          client.connect.value
+          client.close.value
+          expect { client.connect.value }.to raise_error(ClientError)
+        end
       end
 
       describe '#use' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cql-rb
 version: !ruby/object:Gem::Version
-  version: 1.1.0.pre8
+  version: 1.1.0.rc0
 platform: ruby
 authors:
 - Theo Hultberg
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-14 00:00:00.000000000 Z
+date: 2013-10-17 00:00:00.000000000 Z
 dependencies: []
 description: A pure Ruby CQL3 driver for Cassandra
 email: