cassanity 0.4.0 → 0.5.0

data/.gitignore

@@ -7,7 +7,6 @@ Gemfile.lock
 InstalledFiles
 _yardoc
 coverage
-doc/
 lib/bundler/man
 pkg
 rdoc
@@ -17,3 +16,5 @@ test/version_tmp
 tmp
 bin
 vendor/gems
+.env
+tags

data/.travis.yml

@@ -6,5 +6,6 @@ rvm:
 notifications:
   email: false
 bundler_args: --without guard
+before_script: sudo service cassandra status
 services:
  - cassandra

data/Gemfile

@@ -1,9 +1,12 @@
 source 'https://rubygems.org'
 gemspec
 
+gem 'dotenv'
 gem 'rake'
 gem 'rspec', '~> 2.8'
 gem 'activesupport', :require => false
+gem 'metriks', :require => false
+gem 'statsd-ruby', :require => false
 
 group(:guard) do
   gem 'guard'

data/Guardfile

@@ -7,7 +7,6 @@ guard 'bundler' do
 end
 
 rspec_options = {
-  version: 2,
   all_after_pass: false,
   all_on_start: false,
   keep_failed: false
@@ -21,4 +20,3 @@ guard 'rspec', rspec_options do
   ] }
   watch('spec/helper.rb')  { "spec" }
 end
-

data/README.md

@@ -2,6 +2,10 @@
 
 Layer of goodness on top of cassandra-cql so you do not have to write CQL strings all over the place.
 
+## Note about Cassandra 1.2
+
+At this time, cassandra 1.2 is not supported. Under the hood, cassanity uses [cassandra-cql](https://github.com/kreynolds/cassandra-cql), which does not currently support 1.2. It needs the thrift bindings ([initial pull request](https://github.com/kreynolds/cassandra-cql/pull/39)) updated for 1.2 or to wrap the new binary protocol ([initial pull request](https://github.com/kreynolds/cassandra-cql/pull/40)). I'm hoping to work on this in February or March, but if you want to take a stab, that would be awesome.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -99,9 +103,16 @@ You can also do a lot more. Here are a few more [examples](https://github.com/jn
 * [Column Families](https://github.com/jnunemaker/cassanity/tree/master/examples/column_families.rb)
 * [Select a Range](https://github.com/jnunemaker/cassanity/tree/master/examples/select_range.rb)
 
+## More Reading
+
+* [Instrumentation](https://github.com/jnunemaker/cassanity/tree/master/doc/Instrumentation.md)
+* [Migrations](https://github.com/jnunemaker/cassanity/tree/master/doc/Migrations.md)
+
 ## Compatibility
 
 * Ruby 1.9.3
+* Cassandra CQL 3.x
+* Any version of cassandra that works with cassandra-cql and supports CQL 3.
 
 ## Contributing
 

data/doc/Instrumentation.md

@@ -0,0 +1,40 @@
+# Instrumentation
+
+Cassanity comes with a log subscriber and automatic metriks or statsd instrumentation.
+By default these work with ActiveSupport::Notifications, but only require the
+pieces of ActiveSupport that are needed and only do so if you actually attempt
+to require the instrumentation files listed below.
+
+To use the log subscriber:
+
+```ruby
+# Gemfile
+gem 'activesupport'
+
+# config/initializers/cassanity.rb (or wherever you want it)
+require 'cassanity/instrumentation/log_subscriber'
+```
+
+To use the metriks instrumentation:
+
+```ruby
+# Gemfile
+gem 'activesupport'
+gem 'metriks'
+
+# config/initializers/cassanity.rb (or wherever you want it)
+require 'cassanity/instrumentation/metriks'
+```
+
+To use the statsd instrumentation:
+
+```ruby
+# Gemfile
+gem 'activesupport'
+gem 'statsd-ruby'
+
+# config/initializers/cassanity.rb (or wherever you want it)
+require 'cassanity/instrumentation/statsd'
+
+Cassanity::Instrumentation::StatsdSubscriber.client = Statsd.new
+```

data/doc/Migrations.md

@@ -0,0 +1,132 @@
+# Migrations
+
+Cassanity comes with a migrations framework similar to ActiveRecord. Because not everyone will need migrations, you must require it in addition like so:
+
+```ruby
+require 'cassanity/migrator'
+```
+## Creating Your First Migration
+
+Out of the box, Cassanity comes with no generators for migrations. Fear not, if you can create a file, you can create a migration. For example, let's say that you would like to create a users column family.
+
+First, create the directory that will house your migrations.
+
+```bash
+mkdir -p db/migrate
+```
+
+Second, create a file for the create users migration:
+
+```bash
+touch db/migrate/001_create_users.rb
+```
+
+Now, open the file up in your favorite editor and paste in the following:
+
+```ruby
+class CreateUsers < Cassanity::Migration
+  def up
+    create_column_family :users, {
+      primary_key: :id,
+      columns: {
+        id: :timeuuid,
+        name: :text,
+        age: :int,
+        updated_at: :timestamp,
+      },
+    }
+  end
+
+  def down
+    drop_column_family :users
+  end
+end
+```
+
+If you have ever used Active Record's migrations, the previous migration file should look really familiar. Instead of going for a fancy DSL, like AR's, the convenience methods you get are just a very thing layer on top of Cassanity itself.
+
+The available convenience methods are:
+
+* `create_column_family(column_family_name, schema)` - aliased to add_column_family, create_table and add_table
+* `drop_column_family(column_family_name)` - aliased to drop_table
+* `add_column(column_family_name, column_name, type)` - shortcut for alter_column_family with add
+* `drop_column(column_family_name, column_name)` - shortcut for alter_column_family with drop
+* `alter_column_family(column_family_name, args)` - args are passed straight through to ColumnFamily#alter.
+* `add_index(column_family_name, column_name, options = {})` - create a cassandra secondary index; aliased to create_index
+* `drop_index(column_family_name, index_name)` - drop a cassandra secondary index
+* `say_with_time(message) { # do something }` - spit a message out to the migrators log, time the duration of the block, and also spit out the duration upon finished execution of the block
+* `say(message)` - spit a message out to the migrator's log
+
+You can always check out the [source](https://github.com/jnunemaker/cassanity/blob/master/lib/cassanity/migration.rb) or [specs](https://github.com/jnunemaker/cassanity/blob/master/spec/integration/cassanity/migration_spec.rb) for more about these methods.
+
+## Running migrations
+
+The act of running migrations is performed by a migrator. To migrate all pending migrations, simply call migrate:
+
+```ruby
+require 'pathname'
+require 'cassanity/migrator'
+
+# Assuming the keyspace is already created.
+keyspace = Cassanity::Client.new[:my_app]
+
+# Path to our migrations directory.
+migrations_path = Pathname(__FILE__).dirname.join('db', 'migrate')
+
+# Create a migrator instance.
+migrator = Cassanity::Migrator.new(keyspace, migrations_path)
+
+# Run all the pending migrations, in this instance create_users.
+migrator.migrate
+```
+
+You can run `migrator.migrate` over and over and it will only run migrations that have not yet been performed.
+
+In addition to `migrate`, you can also `migrate_to` a specific version in a direction.
+
+```ruby
+# assuming the same setup as the above example
+
+# migrate all the way back to nothing
+migrator.migrate_to(0, :down)
+
+# migrate our users migration again
+migrator.migrate_to(1, :up)
+```
+
+**Note**: When migrating up, the version you declared is included. However, when migrating down, it does not migrate down the version provided.
+
+```ruby
+# run all migrations that have not been performed
+migrator.migrate
+
+# invoke the down method of all performed migrations with version > 1
+# note that down will not be invoked for migrations with version of 1
+migrator.migrate_to(1, :down)
+
+# invoke the down method for all performed migrations
+migrator.migrate_to(0, :down)
+
+# invoke the up method for migrations with version <= 1
+# note that up will be invoked for migrations with version of 1
+migrator.migrate_to(1, :up)
+```
+
+## Migration Version Numbers
+
+In the example above, I used a migration with a version of 001. The only requirement cassanity enforces on migration version numbers is that they be an integer. This means that you can you timestamped migrations if you prefer. For example, the following are all completely valid migration names.
+
+```
+touch db/migrate/001_create_users.rb
+touch db/migrate/201303_create_users.rb
+touch db/migrate/20130304_create_users.rb
+touch db/migrate/20130304160000_create_users.rb
+```
+
+The version could be year, month, day, hour, minute, second (20130304160000, 4:00pm on March 4, 2013), as in the example I just showed, or you could standardize on year, month, day (20130304, March 4, 2013).
+
+**Note**: Migrations will run in the order they appear on disk. They are sorted by their path, which means if you do not go with timestamped migrations, you should padd migrations with leading zero's, as Rails does (ie: "001" instead of "01" or "1").
+
+## Rake Tasks
+
+What is that? You want some rake tasks to handle migrating? [Here is a gist for that](https://gist.github.com/jnunemaker/5086063). I will try to keep it up to date and I am definitely open to any solutions that would make integrating all of this with your app easier.

data/examples/keyspaces.rb

@@ -30,18 +30,20 @@ keyspace.create
 # use this keyspace
 keyspace.use
 
+apps_schema = {
+  primary_key: :id,
+  columns: {
+    id: :text,
+    name: :text,
+  },
+}
+
 # get an instance of a column family
 apps = keyspace.column_family('apps')
 
 # you can also pass a schema so the column family is all knowing
 apps = keyspace.column_family('apps', {
-  schema: {
-    primary_key: :id,
-    columns: {
-      id: :text,
-      name: :text,
-    },
-  },
+  schema: apps_schema,
 })
 pp apps
 
@@ -52,3 +54,5 @@ apps = Cassanity::ColumnFamily.new({
   schema: apps_schema,
 })
 pp apps
+
+keyspace.recreate

data/lib/cassanity/argument_generators/column_family_delete.rb

@@ -15,7 +15,7 @@ module Cassanity
       def call(args = {})
         name    = args.fetch(:column_family_name)
         where   = args.fetch(:where)
-        columns = args.fetch(:columns) { [] }
+        columns = Array(args.fetch(:columns) { [] })
         using   = args[:using]
 
         if (keyspace_name = args[:keyspace_name])

data/lib/cassanity/argument_generators/columns.rb

@@ -0,0 +1,33 @@
+require 'cassanity/argument_generators/where_clause'
+
+module Cassanity
+  module ArgumentGenerators
+    class Columns
+
+      def initialize(args = {})
+        @where_clause = args.fetch(:where_clause) { WhereClause.new }
+      end
+
+      # Internal
+      def call(args = {})
+        where = {}
+        variables = []
+        cql = 'SELECT * FROM system.schema_columns'
+
+        if (keyspace_name = args[:keyspace_name])
+          where[:keyspace] = keyspace_name
+        end
+
+        if (column_family_name = args[:column_family_name])
+          where[:columnfamily] = column_family_name
+        end
+
+        where_cql, *where_variables = @where_clause.call(where: where)
+        cql << where_cql
+        variables.concat(where_variables)
+
+        [cql, *variables]
+      end
+    end
+  end
+end

data/lib/cassanity/argument_generators/where_clause.rb

@@ -34,7 +34,7 @@ module Cassanity
             wheres << "#{key} #{value.symbol} ?"
             variables << value.value
           else
-            wheres << "#{key} = ?"
+            wheres << "\"#{key}\" = ?"
             variables << value
           end
         end

data/lib/cassanity/client.rb

@@ -29,12 +29,14 @@ module Cassanity
       @options        = options.merge(cql_version: '3.0.0')
       @thrift_options = thrift_options.dup
       @instrumenter   = @options.delete(:instrumenter)
+      @retry_strategy = @options.delete(:retry_strategy)
 
       @driver = CassandraCQL::Database.new(@servers, @options, @thrift_options)
 
       @executor = Cassanity::Executors::CassandraCql.new({
-        client: @driver,
+        driver: @driver,
         instrumenter: @instrumenter,
+        retry_strategy: @retry_strategy,
       })
 
       @connection = Cassanity::Connection.new({

data/lib/cassanity/column.rb

@@ -0,0 +1,48 @@
+module Cassanity
+  class Column
+
+    Types = {
+      "org.apache.cassandra.db.marshal.AsciiType" => :ascii,
+      "org.apache.cassandra.db.marshal.BooleanType" => :boolean,
+      "org.apache.cassandra.db.marshal.BytesType" => :blob,
+      "org.apache.cassandra.db.marshal.CounterColumnType" => :counter,
+      "org.apache.cassandra.db.marshal.DateType" => :timestamp,
+      "org.apache.cassandra.db.marshal.DecimalType" => :decimal,
+      "org.apache.cassandra.db.marshal.DoubleType" => :double,
+      "org.apache.cassandra.db.marshal.FloatType" => :float,
+      "org.apache.cassandra.db.marshal.Int32Type" => :int,
+      "org.apache.cassandra.db.marshal.InetAddressType" => :inet,
+      "org.apache.cassandra.db.marshal.IntegerType" => :varint,
+      "org.apache.cassandra.db.marshal.LongType" => :bigint,
+      "org.apache.cassandra.db.marshal.TimeUUIDType" => :timeuuid,
+      "org.apache.cassandra.db.marshal.UTF8Type" => :text,
+      "org.apache.cassandra.db.marshal.UUIDType" => :uuid,
+    }
+
+    # Public: The name of the column.
+    attr_reader :name
+
+    # Public: The type of the column.
+    attr_reader :type
+
+    # Public: The Cassanity::ColumnFamily the column is in.
+    attr_reader :column_family
+
+    def initialize(args = {})
+      @name = args.fetch(:name).to_sym
+      type = args.fetch(:type)
+      @type = Types.fetch(type, type)
+      @column_family = args.fetch(:column_family)
+    end
+
+    # Public
+    def inspect
+      attributes = [
+        "name=#{@name.inspect}",
+        "type=#{@type.inspect}",
+        "column_family=#{@column_family.inspect}",
+      ]
+      "#<#{self.class.name}:#{object_id} #{attributes.join(', ')}>"
+    end
+  end
+end

data/lib/cassanity/column_family.rb

@@ -24,7 +24,7 @@ module Cassanity
     #        :schema - The schema used to create the column family (optional).
     #
     def initialize(args = {})
-      @name = args.fetch(:name)
+      @name = args.fetch(:name).to_sym
       @keyspace = args.fetch(:keyspace)
       @executor = args.fetch(:executor) { @keyspace.executor }
 
@@ -45,8 +45,11 @@ module Cassanity
         command: :column_families,
         arguments: {
           keyspace_name: @keyspace.name,
+        },
+        transformer_arguments: {
+          keyspace: @keyspace,
         }
-      }).any? { |row| row['columnfamily'].to_s == @name.to_s }
+      }).any? { |column_family| column_family.name == @name }
     end
 
     alias_method :exist?, :exists?
@@ -290,6 +293,22 @@ module Cassanity
       })
     end
 
+    # Public: Get all columns for column family.
+    #
+    # Returns Array of Cassanity::Column instances.
+    def columns
+      @executor.call({
+        command: :columns,
+        arguments: {
+          keyspace_name: @keyspace.name,
+          column_family_name: @name,
+        },
+        transformer_arguments: {
+          column_family: self,
+        }
+      })
+    end
+
     # Internal
     def schema
       @schema || raise(Cassanity::Error.new(message: "No schema found to create #{@name} column family. Please set :schema during initialization or include it as a key in #create call."))