cql-rb 1.0.0.pre8 → 1.0.0

data/README.md

@@ -1,7 +1,5 @@
 # Ruby CQL3 driver
 
-_There has not yet been a stable release of this project._
-
 [![Build Status](https://travis-ci.org/iconara/cql-rb.png?branch=master)](https://travis-ci.org/iconara/cql-rb)
 
 # Requirements
@@ -10,11 +8,11 @@ Cassandra 1.2 with the native transport protocol turned on and a modern Ruby. Te
 
 # Installation
 
-    gem install --prerelease cql-rb
+    gem install cql-rb
 
 ## Configure Cassandra
 
-The native transport protocol (sometimes called binary protocol, or CQL protocol) is not on by default in Cassandra 1.2, to enable it edit the `cassandra.yaml` file on all nodes in your cluster and set `start_native_transport` to `true`. You need to restart the nodes for this to have effect.
+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`.
 
 # Quick start
 
@@ -25,12 +23,14 @@ client = Cql::Client.connect(host: 'cassandra.example.com')
 client.use('system')
 rows = client.execute('SELECT keyspace_name, columnfamily_name FROM schema_columnfamilies')
 rows.each do |row|
-  puts "The keyspace #{row['keyspace_name']} has a table called #{row['columnfamily_name']}""
+  puts "The keyspace #{row['keyspace_name']} has a table called #{row['columnfamily_name']}"
 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.
 
+# Usage
+
 ## Changing keyspaces
 
 ```ruby
@@ -117,7 +117,7 @@ At this time prepared statements are local to a single connection. Even if you c
 
 # Consistency levels
 
-The `#execute` method supports setting the desired consistency level for the statement:
+The `#execute` (of `Client` and `PreparedStatement`) method supports setting the desired consistency level for the statement:
 
 ```ruby
 client.execute('SELECT * FROM peers', :local_quorum)
@@ -144,14 +144,73 @@ This is just a driver for the Cassandra native CQL protocol, it doesn't really k
 
 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).
 
+# Troubleshooting
+
+## I get "Deadlock detected" errors
+
+This means that the driver's IO reactor has crashed hard. Most of the time it means that you're using a framework, server or runtime that forks and you call `Client.connect` in the parent process. Check the documentation and see if there's any way you can register to run some piece of code in the child process just after a fork.
+
+This is how you do it in Resque:
+
+```ruby
+Resque.after_fork = proc do
+  # ...
+end
+```
+
+and this is how you do it in Passenger:
+
+```ruby
+PhusionPassenger.on_event(:starting_worker_process) do |forked|
+  if forked
+    # ...
+  end
+end
+```
+
+in Unicorn you do it in the config file:
+
+```ruby
+after_fork do |server, worker|
+  # ...
+end
+```
+
+If your process does not fork and you still encounter deadlock errors, it might also be a bug. All IO is done is a dedicated thread, and if something happens that makes that thread shut down, Ruby will detect that the locks that the client code is waiting on can't be unlocked.
+
+## 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.
+
+## 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.
+
+## I'm connecting to port 9160 and it doesn't work
+
+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. It's on the roadmap.
+
+## Something else is not working
+
+Open an issue and I'll do my best to help you. 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.
+
 # Known bugs & limitations
 
-* There are still edge cases around connection errors, and there is no automatic reconnection.
-* JRuby 1.6.8 is not supported, although it should be. The only known issue is that connection failures aren't handled gracefully.
 * No automatic peer discovery.
+* No automatic reconnection on connection failures.
+* JRuby 1.6.8 and earlier is not supported, although it probably works fine. The only known issue is that connection failures aren't handled gracefully.
 * Compression is not supported.
 * 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`).
+* No support for request tracing.
 
 ## Copyright
 

data/lib/cql/io/node_connection.rb

@@ -92,7 +92,7 @@ module Cql
 
       def perform_request(request, future)
         stream_id = next_stream_id
-        @write_buffer << request.encode_frame(stream_id)
+        request.encode_frame(stream_id, @write_buffer)
         @response_tasks[stream_id] = future
       rescue => e
         case e

data/lib/cql/protocol/request.rb

@@ -13,9 +13,10 @@ module Cql
 
       def encode_frame(stream_id=0, buffer=ByteBuffer.new)
         raise InvalidStreamIdError, 'The stream ID must be between 0 and 127' unless 0 <= stream_id && stream_id < 128
+        offset = buffer.bytesize
         buffer << [1, 0, stream_id, opcode, 0].pack(Formats::HEADER_FORMAT)
         write(buffer)
-        buffer.update(4, [(buffer.bytesize - 8)].pack(Formats::INT_FORMAT))
+        buffer.update(offset + 4, [(buffer.bytesize - offset - 8)].pack(Formats::INT_FORMAT))
         buffer
       end
     end

data/lib/cql/version.rb

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

data/spec/cql/protocol/request_spec.rb

@@ -8,8 +8,20 @@ module Cql
     describe Request do
       describe '#encode_frame' do
         it 'returns a rendered request frame for the specified channel' do
-          frame = PrepareRequest.new('SELECT * FROM things').encode_frame(3)
-          frame.to_s.should == "\x01\x00\x03\x09\x00\x00\x00\x18\x00\x00\x00\x14SELECT * FROM things"
+          encoded_frame = PrepareRequest.new('SELECT * FROM things').encode_frame(3)
+          encoded_frame.to_s.should == "\x01\x00\x03\x09\x00\x00\x00\x18\x00\x00\x00\x14SELECT * FROM things"
+        end
+
+        it 'appends a rendered request frame to the specified buffer' do
+          buffer = ByteBuffer.new('hello')
+          encoded_frame = PrepareRequest.new('SELECT * FROM things').encode_frame(3, buffer)
+          buffer.to_s.should == "hello\x01\x00\x03\x09\x00\x00\x00\x18\x00\x00\x00\x14SELECT * FROM things"
+        end
+
+        it 'returns the specified buffer' do
+          buffer = ByteBuffer.new('hello')
+          encoded_frame = PrepareRequest.new('SELECT * FROM things').encode_frame(3, buffer)
+          encoded_frame.should equal(buffer)
         end
       end
     end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: cql-rb
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre8
-  prerelease: 6
+  version: 1.0.0
+  prerelease: 
 platform: ruby
 authors:
 - Theo Hultberg
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-07 00:00:00.000000000 Z
+date: 2013-06-13 00:00:00.000000000 Z
 dependencies: []
 description: A pure Ruby CQL3 driver for Cassandra
 email:
@@ -108,9 +108,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
+      segments:
+      - 0
+      hash: -3274197899140325066
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23