cql-rb 1.2.2 → 2.0.0.pre0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6dd6370f6131da7cfdd42516a511d5bcc0edbc6a
-  data.tar.gz: fc06b032f6f7c1219b8ed6f05c6421b97b76a9ee
+  metadata.gz: 1b00538d250d975f9b1ed2795bf947d9baf97c35
+  data.tar.gz: e1b27e7d7665bb8545b14c088fb7076ab5e76b01
 SHA512:
-  metadata.gz: cc7feeb45c85c6dae447196786859fcd30e045a03c200fa7dea908bcdc923ca456de9ea320693f68d60cbd4eba0daf077f67098d095225d04116695e1cc0b889
-  data.tar.gz: f2a77f2ea81b1b910fb7064e373c1cca1a4658184369d85d2d589f27a03ed12d2303abe7b9ed33f394d774d1df3394c62d3ed356e8a0f97ed5846c7b3bacc702
+  metadata.gz: 9b24cfa7ecbd973138d21c64e6f64ab02673deefc8f9bab46e0cc1658d041bf15b237326aaec3cfd6f83f8152a802d4efed71cef505fc3fe6102d3d87c7fd49e
+  data.tar.gz: b3a5f99e920989e64ebde8669c3339890ee6b8bdd0c882e65ea2354d0055bd29bd48f2089355d13c279b64379fbb258cf0987306b6e9b11c49caec51d86adc54

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+--markup markdown
+lib/**/*.rb
+-- README

data/README.md

@@ -2,20 +2,21 @@
 
 [![Build Status](https://travis-ci.org/iconara/cql-rb.png?branch=master)](https://travis-ci.org/iconara/cql-rb)
 [![Coverage Status](https://coveralls.io/repos/iconara/cql-rb/badge.png)](https://coveralls.io/r/iconara/cql-rb)
+[![Blog](http://b.repl.ca/v1/blog-cqlrb-ff69b4.png)](http://architecturalatrocities.com/tagged/cqlrb)
 
-_Please note that this is the readme for the development version and that some features described here might not yet have been released._
+_If you're reading this on GitHub, please note that this is the readme for the development version and that some features described here might not yet have been released. You can find the readme for a specific version either through [rubydoc.info](http://rubydoc.info/find/gems?q=cql-rb) or via the release tags ([here is an example](https://github.com/iconara/cql-rb/tree/v1.2.0))._
 
 # Requirements
 
-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, JRuby 1.7 and Rubinius 2.0.
+Cassandra 1.2 or later with the native transport protocol turned on and a modern Ruby. It's [tested continuously using Travis](https://travis-ci.org/iconara/cql-rb) with Cassandra 2.0.5, Ruby 1.9.3, 2.0, JRuby 1.7 and Rubinius 2.1.
 
 # Installation
 
     gem install cql-rb
 
-## Configure Cassandra
+if you want to use compression you should also install the [snappy gem](http://rubygems.org/gems/snappy):
 
-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`.
+    gem install snappy
 
 # Quick start
 
@@ -40,7 +41,7 @@ client.close
 
 # Usage
 
-The full [API documentation](http://rubydoc.info/gems/cql-rb/frames) is available from [rubydoc.info](http://rubydoc.info/).
+The full [API documentation][1] is available from [rubydoc.info](http://rubydoc.info/).
 
 ## Changing keyspaces
 
@@ -113,7 +114,7 @@ client.use('measurements')
 client.execute(table_definition)
 ```
 
-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).
+You can also `ALTER` keyspaces and tables, and you can read more about that in the [CQL3 syntax documentation][2].
 
 ## Prepared statements
 
@@ -130,6 +131,94 @@ A prepared statement can be run many times, but the CQL parsing will only be don
 
 Statements are prepared on all connections and each call to `#execute` selects a random connection to run the query on.
 
+## Batching
+
+If you're using Cassandra 2.0 or later you can build batch requests, either from regular queries or from prepared statements. Batches can consist of `INSERT`, `UPDATE` and `DELETE` statements.
+
+There are a few different ways to work with batches, one is with a block where you build up a batch that is sent when the block ends:
+
+```ruby
+client.batch do |batch|
+  batch.add("UPDATE users SET name = 'Sue' WHERE user_id = 'unicorn31'")
+  batch.add("UPDATE users SET name = 'Kim' WHERE user_id = 'dudezor13'")
+  batch.add("UPDATE users SET name = 'Jim' WHERE user_id = 'kittenz98'")
+end
+```
+
+Another is by creating a batch and sending it yourself:
+
+```ruby
+batch = client.batch
+batch.add("UPDATE users SET name = 'Sue' WHERE user_id = 'unicorn31'")
+batch.add("UPDATE users SET name = 'Kim' WHERE user_id = 'dudezor13'")
+batch.add("UPDATE users SET name = 'Jim' WHERE user_id = 'kittenz98'")
+batch.execute
+```
+
+You can mix any combination of statements in a batch:
+
+```ruby
+prepared_statement = client.prepare("UPDATE users SET name = ? WHERE user_id = ?")
+client.batch do |batch|
+  batch.add(prepared_statement, 'Sue', 'unicorn31')
+  batch.add("UPDATE users SET age = 19 WHERE user_id = 'unicorn31'")
+  batch.add("INSERT INTO activity (user_id, what, when) VALUES (?, 'login', NOW())", 'unicorn31')
+end
+```
+
+Batches can have one of three different types: `logged`, `unlogged` or `counter`, where `logged` is the default. Their exact semantics are defined in the [Cassandra documentation][3], but this is how you specify which one you want:
+
+```ruby
+counter_statement = client.prepare("UPDATE my_counter_table SET my_counter = my_counter + ? WHERE id = ?")
+client.batch(:counter) do |batch|
+  batch.add(counter_statement, 3, 'some_counter')
+  batch.add(counter_statement, 2, 'another_counter')
+end
+```
+
+You can also specify the regular options such as consistency, timeout and whether or not to enable tracing:
+
+```ruby
+client.batch(:unlogged, trace: true) do |batch|
+  # ...
+end
+
+client.batch(trace: true, consistency: :all) do |batch|
+  # ...
+end
+
+batch = client.batch
+# ...
+batch.execute(consistency: :quorum)
+
+batch = client.batch(trace: true)
+# ...
+batch.execute(consistency: :quorum)
+```
+
+As you can see you can specify the options either when creating the batch or when sending it (when using the variant where you call `#execute` yourself). The options given to `#execute` take precedence. You can omit the batch type and specify the options as the only parameter when you want to use the the default batch type.
+
+Cassandra 1.2 also supported batching, but only as a CQL feature, you had to build the batch as a string, and it didn't really play well with prepared statements.
+
+## Paging
+
+If you're using Cassandra 2.0 or later you can page your query results by adding the `:page_size` option to a query:
+
+```ruby
+result_page = client.execute("SELECT * FROM large_table WHERE id = 'partition_with_lots_of_data'", page_size: 100)
+
+loop do
+  result_page.each do |row|
+    p row
+  end
+  if result_page.last?
+    break
+  else
+    result_page = result_page.next_page
+  end
+end
+```
+
 ## Consistency
 
 You can specify the default consistency to use when you create a new `Client`:
@@ -179,17 +268,37 @@ compressor = Cql::Compression::SnappyCompressor.new
 client = Cql::Client.connect(hosts: %w[localhost], compressor: compressor)
 ```
 
+## Logging
+
+You can pass a standard Ruby logger to the client to get some more information about what is going on:
+
+```ruby
+require 'logger'
+
+client = Cql::Client.connect(logger: Logger.new($stderr))
+```
+
+Most of the logging will be when the driver connects and discovers new nodes, when connections fail and so on, but also when statements are prepared. The logging is designed to not cause much overhead and only relatively rare events are logged (e.g. normal requests are not logged).
+
+## Thread safety
+
+Except for results and batches everything in cql-rb is thread safe. You only need a single client object in your application, in fact creating more than one is a bad idea. Similarily prepared statements are thread safe and should be shared.
+
+There are two things that you should be aware are not thread safe: result objects and batches. Result objects are wrappers around an array of rows and their primary use case is iteration, something that makes little sense to do concurrently. Because of this they've been designed to not be thread safe to avoid the unnecessary cost of locking. Similarily it creating batches aren't usually built concurrently, so to avoid the cost of locking they are not thread safe. If you, for some reason, need to use results or batches concurrently, you're responsible for locking around them. If you do this, you're probably doing something wrong, though.
+
 # 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).
+Read more about CQL3 in the [CQL3 syntax documentation][2] and the [Cassandra query documentation][3].
 
-# Cassandra 2.0
+# Troubleshooting
 
-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. Support for all of the features of the new protocol is being worked on. If there is a particular feature that you would want to see implemented, open an issue and describe your use case. This helps with prioritizing what should be implemented first.
+## I get "connection refused" errors
 
-# Troubleshooting
+Make sure that the native transport protocol is enabled. 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`.
+
+To verify that the native transport protocol is enabled, search your logs for the message "Starting listening for CQL clients" and look at which IP and port it is binding to.
 
 ## I get "Deadlock detected" errors
 
@@ -227,15 +336,19 @@ If your process does not fork and you still encounter deadlock errors, it might
 
 If you're using cql-rb on Windows there's an [experimental branch with Windows support](https://github.com/iconara/cql-rb/tree/windows_support). The problem is that Windows does not support non blocking reads on IO objects other than sockets, and the fix is very small. Unfortunately I have no way of properly testing things in Windows, so therefore the "experimental" label.
 
+## I get `QueryError`
+
+All errors that originate on the server side are raised as `QueryError`. If you get one of these the error is in your CQL or on the server side.
+
 ## I'm not getting all elements back from my list/set/map
 
 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.
 
 ## 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.
+Please open an issue. It should be working, but it's hard to set up and write automated tests for, so there may be edge cases that aren't covered. If you're using Cassandra 2.0 or DataStax Enterprise 4.0 or higher and are using something other than the built in `PasswordAuthenticator` your setup is theoretically supported, but it's not field tested.
 
-If you are using DataStax Enterprise and authentication it is unfortunately not supported yet. DataStax backported the authentication from Cassandra 2.0 into DSE, even though it only uses Cassandra 1.2. The authentication mechanism in Cassandra 2.0 is very different and you will have to wait until support for Cassandra 2.0 is added to cql-rb before it will work with DSE.
+If you are using DataStax Enterprise earlier than 4.0 authentication is unfortunately supported. Please open an issue and we might be able to get it working, I just need someone who's willing to test it out. DataStax backported the authentication from Cassandra 2.0 into DSE, even though it only uses Cassandra 1.2. The authentication logic might not be able to handle this and will try to authenticate with DSE using an earlier version of the protocol. In short, DSE before 4.0 uses a non-standard protocol, but it should be possible to get it working.
 
 ## I'm connecting to port 9160 and it doesn't work
 
@@ -259,9 +372,13 @@ Applications using cql-rb and JRuby can do over 10,000 write requests per second
 
 ## Try batching
 
-Batching in Cassandra isn't always as good as in other (non-distributed) databases. Since rows are distributed accross the cluster the coordinator node must still send the individual pieces of a batch to other nodes, and you could have done that yourself instead. Batches also mean that in most cases you need to smash strings together to create a big CQL string, so you increase the size of your requests, using up more bandwidth and making the server have to do more CQL parsing. Prepared statements are almost always a better choice for performance.
+Batching in Cassandra isn't always as good as in other (non-distributed) databases. Since rows are distributed accross the cluster the coordinator node must still send the individual pieces of a batch to other nodes, and you could have done that yourself instead.
+
+For Cassandra 1.2 it is often best not to use batching at all, you'll have to smash strings together to create the batch statements, and that will waste time on the client side, will take longer to push over the network, and will take longer to parse and process on the server side. Prepared statements are almost always a better choice.
 
-Cassandra 2.0 introduced a new form of batches where you can send a batch of prepared statement executions as one request, when support for that arrives in cql-rb, this advice should be reconsidered.
+Cassandra 2.0 introduced a new form of batches where you can send a batch of prepared statement executions as one request (you can send non-prepared statements too, but we're talking performance here). These bring the best of both worlds and can be beneficial for some use cases. Some of the same caveats still apply though and you should test it for your use case.
+
+Whenever you use batching, try compression too.
 
 ## Try compression
 
@@ -269,6 +386,8 @@ If your requests or responses are big, compression can help decrease the amound
 
 In read-heavy applications requests are often small, and need no compression, but responses can be big. In these situations you can modify the compressor used to turn off compression for requests completely. The Snappy compressor that comes with cql-rb will not compress frames less than 64 bytes, for example, and you can change this threshold when you create the compressor.
 
+Compression works best for large requests, so if you use batching you should benchmark if compression gives you a speed boost.
+
 # Try experimental features
 
 To get maximum performance you can't wait for a request to complete before sending the next. At it's core cql-rb embraces this completely and uses non-blocking IO and a completely asynchronous model for the request processing. The synchronous API that you use is just a thin façade on top that exists for convenience. If you need to scale to thousands of requests per second, have a look at the client code and look at the asynchronous core, it works very much like the public API, _but using it they should be considererd **experimental**_. Experimental in this context does not mean buggy, it is the core of cql-rb after all, but it means that you cannot rely on it being backwards compatible.
@@ -277,7 +396,7 @@ To get maximum performance you can't wait for a request to complete before sendi
 
 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.
+Private and experimental APIs, defined as whatever is not in the [public API documentation][1], i.e. classes and methods marked as `@private`, 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.
 
@@ -287,7 +406,6 @@ Prereleases will be stable, in the sense that they will have finished and proper
 * Windows is not supported (there is experimental support in the [`windows` branch](https://github.com/iconara/cql-rb/tree/windows_support)).
 * 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`) -- but it's not clear whether that will ever be added, it would be useful, but it is also something that another gem could add on top.
-* New features in v2 of the protocol are not supported -- this is planned and in progress
 
 Also check out the [issues](https://github.com/iconara/cql-rb/issues) for open bugs.
 
@@ -303,4 +421,8 @@ _Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 
 [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
 
-_Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License._
+_Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License._
+
+  [1]: http://rubydoc.info/github/iconara/cql-rb/frames
+  [2]: https://github.com/apache/cassandra/blob/cassandra-2.0/doc/cql3/CQL.textile
+  [3]: http://www.datastax.com/documentation/cql/3.1/webhelp/index.html

data/lib/cql/client.rb

@@ -21,6 +21,8 @@ module Cql
   ClientError = Class.new(CqlError)
   AuthenticationError = Class.new(ClientError)
   IncompleteTraceError = Class.new(ClientError)
+  UnsupportedProtocolVersionError = Class.new(ClientError)
+  NotPreparedError = Class.new(ClientError)
 
   # A CQL client manages connections to one or more Cassandra nodes and you use
   # it run queries, insert and update data.
@@ -83,6 +85,12 @@ module Cql
     #   connection, in seconds.
     # @option options [String] :keyspace The keyspace to change to immediately
     #   after all connections have been established, this is optional.
+    # @option options [Hash] :credentials When using Cassandra's built in
+    #   authentication you can provide your username and password through this
+    #   option. Example: `:credentials => {:username => 'cassandra', :password => 'cassandra'}`
+    # @option options [Object] :auth_provider When using custom authentication
+    #   use this option to specify the auth provider that will handle the
+    #   authentication negotiation. See {Cql::Client::AuthProvider} for more info.
     # @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
@@ -95,12 +103,16 @@ module Cql
     #   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.
+    # @option options [String] :cql_version Specifies which CQL version the
+    #   server should expect.
     # @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
+    # @raise Cql::Client::QueryError when the specified keyspace does not exist
+    #   or when the specifed CQL version is not supported.
     # @return [Cql::Client::Client]
     def self.connect(options={})
       SynchronousClient.new(AsynchronousClient.new(options)).connect
@@ -147,9 +159,19 @@ module Cql
       # @raise [Cql::NotConnectedError] raised when the client is not connected
       # @return [nil]
 
-      # @!method execute(cql, options_or_consistency=nil)
+      # @!method execute(cql, *values, options_or_consistency={})
       #
-      # Execute a CQL statement.
+      # 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'")
@@ -157,6 +179,12 @@ module Cql
       #     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)
       #
@@ -168,17 +196,39 @@ module Cql
       #   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] :timeout (nil) How long to wait
+      # @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 [Symbol] :trace (false) Request tracing
+      # @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.
@@ -204,12 +254,64 @@ module Cql
       #   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.
       #
@@ -242,16 +344,138 @@ module Cql
       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
 
 require 'cql/client/connection_manager'
-require 'cql/client/connection_helper'
+require 'cql/client/connector'
 require 'cql/client/null_logger'
 require 'cql/client/column_metadata'
 require 'cql/client/result_metadata'
-require 'cql/client/query_result'
-require 'cql/client/void_result'
 require 'cql/client/query_trace'
 require 'cql/client/execute_options_decoder'
 require 'cql/client/keyspace_changer'
@@ -259,4 +483,9 @@ 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/request_runner'
+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'