surus 0.1.0 → 0.2.0

data/README.md

@@ -4,24 +4,28 @@ Surus
 # Description
 
 Surus extends ActiveRecord with PostgreSQL specific functionality. It includes
-hstore and array serializers and helper scopes.
+hstore and array serializers and helper scopes. It also includes a helper to
+control PostgreSQL synchronous commit behavior.
 
 # Installation
 
     gem install surus
     
-    or add to your Gemfile
+Or add to your Gemfile.
     
     gem 'surus'
 
 # Hstore
 
-Hashes can be serialized to an hstore column.
+Hashes can be serialized to an hstore column. hstore is a PostgreSQL key/value
+type that can be indexed for fast searching.
 
     class User < ActiveRecord::Base
       serialize :properties, Surus::Hstore::Serializer.new
     end
     
+    User.create :properties => { :favorite_color => "green", :results_per_page => 20 }
+    
 Even though the underlying hstore can only use strings for keys and values
 (and NULL for values) Surus can successfully maintain type for integers,
 floats, bigdecimals, and dates. It does this by storing an extra key
@@ -34,6 +38,9 @@ Hstores can be searched with helper scopes.
     User.hstore_has_all_keys(:properties, "favorite_color", "gender")
     User.hstore_has_any_keys(:properties, "favorite_color", "favorite_artist")
     
+    
+Read more in the [PostgreSQL hstore documentation](http://www.postgresql.org/docs/9.1/static/hstore.html).
+    
 # Array
 
 Ruby arrays can be serialized to PostgreSQL arrays. Surus includes support
@@ -46,12 +53,99 @@ for text, integer, float, and decimal arrays.
       serialize :favorite_decimals, Surus::Array::DecimalSerializer.new
     end
     
+    User.create :permissions => %w{ read_notes write_notes, manage_topics },
+      :favorite_integers => [1, 2, 3],
+      :favorite_floats => [1.3, 2.2, 3.1],
+      :favorite_decimals => [BigDecimal("3.14"), BigDecimal("4.23"]
+    
 Arrays can be searched with helper scopes.
 
     User.array_has(:permissions, "admin")
     User.array_has(:permissions, "manage_accounts", "manage_users")
     User.array_has_any(:favorite_integers, 7, 11, 42)
 
+# Synchronous Commit
+
+PostgreSQL can trade durability for speed. By disabling synchronous commit,
+transactions will return before the data is actually stored on the disk. This
+can be substantially faster, but it entails a short window where a crash
+could cause data loss (but not data corruption). This can be enabled for an
+entire session or per transaction.
+
+    User.synchronous_commit # -> true
+
+    User.transaction do
+      User.synchronous_commit false
+      @user.save
+    end # This transaction can return before the data is written to the drive
+    
+    # synchronous_commit returns to its former value outside of the transaction
+    User.synchronous_commit # -> true
+    
+    # synchronous_commit can be turned off permanently
+    User.synchronous_commit false
+    
+Read more in the [PostgreSQL asynchronous commit documentation](http://www.postgresql.org/docs/9.1/interactive/wal-async-commit.html).
+
+# Benchmarks
+
+Using PostgreSQL's hstore enables searches to be done quickly in the database.
+
+    jack@moya:~/work/surus$ ruby -I lib -I bench bench/hstore_find.rb
+    Skipping EAV test. Use -e to enable (VERY SLOW!)
+    Skipping YAML test. Use -y to enable (VERY SLOW!)
+    Creating Surus test data... Done.
+
+    2000 records with 5 string key/value pairs
+    Finding all by inclusion of a key 200 times
+                   user     system      total        real
+    Surus      0.120000   0.030000   0.150000 (  0.356240)
+
+Arrays are also searchable.
+
+    jack@moya:~/work/surus$ ruby -I lib -I bench bench/array_find.rb
+    Skipping YAML test. Use -y to enable (VERY SLOW!)
+    Creating Surus test data... Done.
+
+    2000 records with 10 element arrays
+    Finding all where array includes value 200 times
+                   user     system      total        real
+    Surus      0.120000   0.040000   0.160000 (  0.531735)
+
+Disabling synchronous commit can improve commit speed by 50% or more.
+
+    jack@moya:~/work/surus$ ruby -I lib -I bench bench/synchronous_commit.rb
+    Generating random data before test to avoid bias... Done.
+
+    Writing 1000 narrow records
+                                         user     system      total        real
+    enabled                          0.550000   0.870000   1.420000 (  3.025896)
+    disabled                         0.700000   0.580000   1.280000 (  1.788585)
+    disabled per transaction         0.870000   0.580000   1.450000 (  2.072150)
+    enabled / single transaction     0.700000   0.330000   1.030000 (  1.280455)
+    disabled / single transaction    0.660000   0.340000   1.000000 (  1.252301)
+
+    Writing 1000 wide records
+                                         user     system      total        real
+    enabled                          1.030000   0.870000   1.900000 (  3.559709)
+    disabled                         0.930000   0.780000   1.710000 (  2.259340)
+    disabled per transaction         0.970000   0.850000   1.820000 (  2.478290)
+    enabled / single transaction     0.890000   0.500000   1.390000 (  1.693629)
+    disabled / single transaction    0.820000   0.450000   1.270000 (  1.554767)
+    
+Many more benchmarks are in the bench directory. Most accept parameters to
+adjust the amount of test data.
+    
+## Running the benchmarks
+    
+1. Create a database
+2. Configure bench/database.yml to connect to it.
+3. Load bench/database_structure.sql into your bench database.
+4. Run benchmark scripts from root of gem directory (remember pass ruby
+   the include paths for lib and bench)
+
+
+    
 # License
 
 MIT

data/bench/array_create.rb

@@ -0,0 +1,46 @@
+require 'benchmark_helper'
+
+options = {}
+optparse = OptionParser.new do |opts|
+  options[:records] = 1000
+  opts.on '-r NUM', '--records NUM', Integer, 'Number of records to create' do |n|
+    options[:records] = n
+  end
+  
+  options[:elements] = 10
+  opts.on '-e NUM', '--elements NUM', Integer, 'Number of elements' do |n|
+    options[:elements] = n
+  end  
+end
+
+optparse.parse!
+
+clean_database
+
+num_records = options[:records]
+num_elements = options[:elements]
+
+arrays = num_records.times.map do
+  num_elements.times.map { SecureRandom.hex(4) }
+end
+
+puts
+puts "Writing #{num_records} records with a #{num_elements} element string array"
+
+Benchmark.bm(8) do |x|
+  x.report("Surus") do
+    SurusKeyValueRecord.transaction do
+      num_records.times do |i|
+        SurusTextArrayRecord.create! :names => arrays[i]
+      end
+    end
+  end    
+  
+  x.report("YAML") do
+    YamlKeyValueRecord.transaction do
+      num_records.times do |i|
+        YamlArrayRecord.create! :names => arrays[i]
+      end
+    end
+  end  
+end

data/bench/array_find.rb

@@ -0,0 +1,79 @@
+require 'benchmark_helper'
+
+options = {}
+optparse = OptionParser.new do |opts|
+  options[:records] = 2_000
+  opts.on '-r NUM', '--records NUM', Integer, 'Number of records to create' do |n|
+    options[:records] = n
+  end
+  
+  options[:elements] = 10
+  opts.on '-e NUM', '--elements NUM', Integer, 'Number of elements per array' do |n|
+    options[:elements] = n
+  end
+  
+  options[:finds] = 200
+  opts.on '-f NUM', '--finds NUM', Integer, 'Number of finds to perform' do |n|
+    options[:finds] = n
+  end   
+  
+  options[:yaml] = false
+  opts.on '-y', '--yaml', 'Include YAML in benchmark (VERY SLOW!)' do
+    options[:yaml] = true
+  end
+end
+
+optparse.parse!
+
+clean_database
+
+num_records = options[:records]
+num_elements = options[:elements]
+num_finds = options[:finds]
+yaml = options[:yaml]
+
+puts "Skipping YAML test. Use -y to enable (VERY SLOW!)" unless yaml
+
+arrays = num_records.times.map do
+  num_elements.times.map { SecureRandom.hex(4) }
+end
+
+print "Creating Surus test data... "
+SurusKeyValueRecord.transaction do
+  num_records.times do |i|
+    SurusTextArrayRecord.create! :names => arrays[i]
+  end
+end
+puts "Done."
+
+if yaml
+  print "Creating YAML test data... "
+  YamlArrayRecord.transaction do
+    num_records.times do |i|
+      YamlArrayRecord.create! :names => arrays[i]
+    end
+  end
+  puts "Done."
+end
+
+puts
+puts "#{num_records} records with #{num_elements} element arrays"
+puts "Finding all where array includes value #{num_finds} times"
+
+values_to_find = arrays.sample(num_finds).map { |a| a.sample }
+
+Benchmark.bm(8) do |x|
+  x.report("Surus") do
+    values_to_find.each do |value_to_find|
+      SurusTextArrayRecord.array_has(:names, value_to_find).all
+    end
+  end
+
+  if yaml
+    x.report("YAML") do
+      values_to_find.each do |value_to_find|
+        YamlArrayRecord.all.select { |r| r.names.include?(value_to_find) }
+      end
+    end    
+  end
+end

data/bench/array_serialize.rb

@@ -0,0 +1,34 @@
+require 'benchmark_helper'
+
+options = {}
+optparse = OptionParser.new do |opts|
+  options[:elements] = 10
+  opts.on '-e NUM', '--elements NUM', Integer, 'Number of elements per array' do |n|
+    options[:elements] = n
+  end
+end
+
+optparse.parse!
+
+clean_database
+
+num_elements = options[:elements]
+array = num_elements.times.map { SecureRandom.hex(4) }
+
+SurusTextArrayRecord.create! :names => array
+YamlArrayRecord.create! :names => array
+
+num_reads = 3_000
+
+puts
+puts "Reading a single record with a #{num_elements} element array #{num_reads} times"
+
+Benchmark.bm(8) do |x|
+  x.report("Surus") do
+    num_reads.times { SurusTextArrayRecord.first.names }
+  end    
+  
+  x.report("YAML") do
+    num_reads.times { YamlArrayRecord.first.names }
+  end  
+end

data/bench/benchmark_helper.rb

@@ -0,0 +1,65 @@
+require 'surus'
+require 'benchmark'
+require 'securerandom'
+require 'optparse'
+
+database_config = YAML.load_file(File.expand_path("../database.yml", __FILE__))
+ActiveRecord::Base.establish_connection database_config["bench"]
+
+class YamlKeyValueRecord < ActiveRecord::Base
+  serialize :properties
+end
+
+class SurusKeyValueRecord < ActiveRecord::Base
+  serialize :properties, Surus::Hstore::Serializer.new
+end
+
+class EavMasterRecord < ActiveRecord::Base
+  has_many :eav_detail_records
+  
+  def properties
+    @properties ||= eav_detail_records.each_with_object({}) do |d, hash|
+      hash[d.key] = d.value
+    end
+  end
+  
+  def properties=(value)
+    @properties = value
+  end
+  
+  after_save :persist_properties
+  def persist_properties
+    eav_detail_records.clear
+    @properties.each do |k,v|
+      eav_detail_records.create! :key => k, :value => v
+    end
+  end
+end
+
+class EavDetailRecord < ActiveRecord::Base
+  belongs_to :eav_master_record
+end
+
+class YamlArrayRecord < ActiveRecord::Base
+  serialize :names
+end
+
+class SurusTextArrayRecord < ActiveRecord::Base
+  serialize :names, Surus::Array::TextSerializer.new
+end
+
+class WideRecord < ActiveRecord::Base
+end
+
+class NarrowRecord < ActiveRecord::Base
+end
+
+def clean_database
+  YamlKeyValueRecord.delete_all
+  SurusKeyValueRecord.delete_all
+  EavDetailRecord.delete_all
+  EavMasterRecord.delete_all
+  YamlArrayRecord.delete_all
+  WideRecord.delete_all
+  NarrowRecord.delete_all
+end

data/bench/database.yml

@@ -0,0 +1,4 @@
+bench:
+  adapter: postgresql
+  encoding: unicode
+  database: surus_bench

data/bench/database_structure.sql

@@ -0,0 +1,92 @@
+CREATE EXTENSION IF NOT EXISTS hstore;
+
+DROP TABLE IF EXISTS yaml_key_value_records;
+
+CREATE TABLE yaml_key_value_records(
+  id serial PRIMARY KEY,
+  properties varchar
+);
+
+
+DROP TABLE IF EXISTS surus_key_value_records;
+
+CREATE TABLE surus_key_value_records(
+  id serial PRIMARY KEY,
+  properties hstore
+);
+
+CREATE INDEX ON surus_key_value_records USING GIN (properties);
+
+
+DROP TABLE IF EXISTS eav_detail_records;
+DROP TABLE IF EXISTS eav_key_value_records;
+
+CREATE TABLE eav_master_records(
+  id serial PRIMARY KEY
+);
+
+CREATE TABLE eav_detail_records(
+  id serial PRIMARY KEY,
+  eav_master_record_id integer REFERENCES eav_master_records,
+  "key" varchar NOT NULL,
+  "value" varchar NOT NULL
+);
+
+CREATE INDEX ON eav_detail_records (eav_master_record_id);
+CREATE INDEX ON eav_detail_records ("key");
+CREATE UNIQUE INDEX ON eav_detail_records(eav_master_record_id, "key");
+CREATE INDEX ON eav_detail_records ("value");
+
+
+DROP TABLE IF EXISTS yaml_array_records;
+
+CREATE TABLE yaml_array_records(
+  id serial PRIMARY KEY,
+  names text
+);
+
+
+DROP TABLE IF EXISTS surus_text_array_records;
+
+CREATE TABLE surus_text_array_records(
+  id serial PRIMARY KEY,
+  names text[]
+);
+
+CREATE INDEX ON surus_text_array_records USING GIN (names);
+
+
+
+DROP TABLE IF EXISTS wide_records;
+
+-- a couple indexed fields and a number of unindexed fields
+CREATE TABLE wide_records(
+  id serial PRIMARY KEY,
+  a varchar NOT NULL,
+  b varchar NOT NULL,
+  c varchar NOT NULL,
+  d varchar NOT NULL,
+  e varchar NOT NULL,
+  f varchar NOT NULL,
+  g varchar NOT NULL,
+  h varchar NOT NULL,
+  i varchar NOT NULL,
+  j varchar NOT NULL
+);
+
+CREATE INDEX ON wide_records (a);
+CREATE INDEX ON wide_records (b);
+
+
+
+DROP TABLE IF EXISTS narrow_records;
+
+-- a one indexed fields and a couple unindexed fields
+CREATE TABLE narrow_records(
+  id serial PRIMARY KEY,
+  a varchar NOT NULL,
+  b varchar NOT NULL,
+  c varchar NOT NULL
+);
+
+CREATE INDEX ON narrow_records (a);

data/bench/hstore_create.rb

@@ -0,0 +1,57 @@
+require 'benchmark_helper'
+
+options = {}
+optparse = OptionParser.new do |opts|
+  options[:records] = 200
+  opts.on '-r NUM', '--records NUM', Integer, 'Number of records to create' do |n|
+    options[:records] = n
+  end
+  
+  options[:pairs] = 5
+  opts.on '-p NUM', '--pairs NUM', Integer, 'Number of key/value pairs' do |n|
+    options[:pairs] = n
+  end  
+end
+
+optparse.parse!
+
+clean_database
+GC.disable
+
+num_records = options[:records]
+num_key_value_pairs = options[:pairs]
+
+key_value_pairs = num_records.times.map do
+  num_key_value_pairs.times.each_with_object({}) do |n, hash|
+    hash[SecureRandom.hex(4)] = SecureRandom.hex(4)
+  end
+end
+
+puts
+puts "Writing #{num_records} records with #{num_key_value_pairs} string key/value pairs"
+
+Benchmark.bm(8) do |x|
+  x.report("EAV") do
+    EavMasterRecord.transaction do
+      num_records.times do |i|
+        EavMasterRecord.create! :properties => key_value_pairs[i]
+      end
+    end
+  end 
+
+  x.report("Surus") do
+    SurusKeyValueRecord.transaction do
+      num_records.times do |i|
+        SurusKeyValueRecord.create! :properties => key_value_pairs[i]
+      end
+    end
+  end    
+  
+  x.report("YAML") do
+    YamlKeyValueRecord.transaction do
+      num_records.times do |i|
+        YamlKeyValueRecord.create! :properties => key_value_pairs[i]
+      end
+    end
+  end  
+end

data/bench/hstore_find.rb

@@ -0,0 +1,105 @@
+require 'benchmark_helper'
+
+options = {}
+optparse = OptionParser.new do |opts|
+  options[:records] = 2_000
+  opts.on '-r NUM', '--records NUM', Integer, 'Number of records to create' do |n|
+    options[:records] = n
+  end
+  
+  options[:pairs] = 5
+  opts.on '-p NUM', '--pairs NUM', Integer, 'Number of key/value pairs' do |n|
+    options[:pairs] = n
+  end
+
+  options[:eav] = false
+  opts.on '-e', '--eav', 'Include EAV in benchmark (VERY SLOW!)' do
+    options[:eav] = true
+  end
+  
+  options[:yaml] = false
+  opts.on '-y', '--yaml', 'Include YAML in benchmark (VERY SLOW!)' do
+    options[:yaml] = true
+  end
+end
+
+optparse.parse!
+
+clean_database
+
+num_records = options[:records]
+num_key_value_pairs = options[:pairs]
+eav = options[:eav]
+yaml = options[:yaml]
+
+puts "Skipping EAV test. Use -e to enable (VERY SLOW!)" unless eav
+puts "Skipping YAML test. Use -y to enable (VERY SLOW!)" unless yaml
+
+key_value_pairs = num_records.times.map do
+  num_key_value_pairs.times.each_with_object({}) do |n, hash|
+    hash[SecureRandom.hex(2)] = SecureRandom.hex(4)
+  end
+end
+
+if eav
+  print "Creating EAV test data... "
+  EavMasterRecord.transaction do
+    num_records.times do |i|
+      EavMasterRecord.create! :properties => key_value_pairs[i]
+    end
+  end
+  puts "Done."
+end
+
+print "Creating Surus test data... "
+SurusKeyValueRecord.transaction do
+  num_records.times do |i|
+    SurusKeyValueRecord.create! :properties => key_value_pairs[i]
+  end
+end
+puts "Done."
+
+if yaml
+  print "Creating YAML test data... "
+  YamlKeyValueRecord.transaction do
+    num_records.times do |i|
+      YamlKeyValueRecord.create! :properties => key_value_pairs[i]
+    end
+  end
+  puts "Done."
+end
+
+
+num_finds = 200
+keys_to_find = key_value_pairs.sample(num_finds).map { |h| h.keys.sample }
+
+puts
+puts "#{num_records} records with #{num_key_value_pairs} string key/value pairs"
+puts "Finding all by inclusion of a key #{num_finds} times"
+
+Benchmark.bm(8) do |x|
+  if eav
+    x.report("EAV") do
+      keys_to_find.each do |key_to_find|
+        EavMasterRecord
+          .includes(:eav_detail_records)
+          .where("EXISTS(SELECT 1 FROM eav_detail_records WHERE eav_master_records.id=eav_detail_records.eav_master_record_id AND key=?)", key_to_find)
+          .all
+      end
+    end  
+  end
+
+  x.report("Surus") do
+    keys_to_find.each do |key_to_find|
+      SurusKeyValueRecord.hstore_has_key(:properties, key_to_find).all
+    end
+  end
+
+  if yaml
+    x.report("YAML") do
+      keys_to_find.each do |key_to_find|
+        YamlKeyValueRecord.all.select { |r| r.properties.key?(key_to_find) }
+      end
+    end    
+  end
+end

data/bench/hstore_serialize.rb

@@ -0,0 +1,42 @@
+require 'benchmark_helper'
+
+options = {}
+optparse = OptionParser.new do |opts|
+  options[:pairs] = 5
+  opts.on '-p NUM', '--pairs NUM', Integer, 'Number of key/value pairs' do |n|
+    options[:pairs] = n
+  end  
+end
+
+optparse.parse!
+
+clean_database
+
+num_key_value_pairs = options[:pairs]
+
+key_value_pair = num_key_value_pairs.times.each_with_object({}) do |n, hash|
+  hash[SecureRandom.hex(4)] = SecureRandom.hex(4)
+end
+
+EavMasterRecord.create! :properties => key_value_pair
+SurusKeyValueRecord.create! :properties => key_value_pair
+YamlKeyValueRecord.create! :properties => key_value_pair
+
+num_reads = 3_000
+
+puts
+puts "Reading a single record with #{num_key_value_pairs} string key/value pairs #{num_reads} times"
+
+Benchmark.bm(8) do |x|
+  x.report("EAV") do
+    num_reads.times { EavMasterRecord.first.properties }
+  end 
+
+  x.report("Surus") do
+    num_reads.times { SurusKeyValueRecord.first.properties }
+  end    
+  
+  x.report("YAML") do
+    num_reads.times { YamlKeyValueRecord.first.properties }
+  end  
+end

data/bench/synchronous_commit.rb

@@ -0,0 +1,90 @@
+require 'benchmark_helper'
+
+options = {}
+optparse = OptionParser.new do |opts|
+  options[:records] = 1000
+  opts.on '-r NUM', '--records NUM', Integer, 'Number of records to create' do |n|
+    options[:records] = n
+  end
+end
+
+optparse.parse!
+num_records = options[:records]
+narrow_field_width = 8
+wide_field_width = 25
+
+print "Generating random data before test to avoid bias... "
+random_string = SecureRandom.base64(num_records * 10 * wide_field_width)
+puts "Done."
+
+random_io = StringIO.new(random_string)
+
+create_wide_record = lambda do
+  WideRecord.create! :a => random_io.read(wide_field_width),
+    :b => random_io.read(wide_field_width),
+    :c => random_io.read(wide_field_width),
+    :d => random_io.read(wide_field_width),
+    :e => random_io.read(wide_field_width),
+    :f => random_io.read(wide_field_width),
+    :g => random_io.read(wide_field_width),
+    :h => random_io.read(wide_field_width),
+    :i => random_io.read(wide_field_width),
+    :j => random_io.read(wide_field_width)
+end
+
+create_narrow_record = lambda do
+  NarrowRecord.create! :a => random_io.read(narrow_field_width),
+    :b => random_io.read(narrow_field_width),
+    :c => random_io.read(narrow_field_width)
+end
+
+{ "narrow" => create_narrow_record, "wide" => create_wide_record }.each do |text, create_record|
+  puts
+  puts "Writing #{num_records} #{text} records"
+
+  Benchmark.bm(30) do |x|
+    clean_database
+    random_io.rewind
+    WideRecord.synchronous_commit true
+    x.report("enabled") do
+      num_records.times { create_record.call }
+    end 
+
+    clean_database
+    random_io.rewind
+    WideRecord.synchronous_commit false
+    x.report("disabled") do
+      num_records.times { create_record.call }
+    end   
+    
+    clean_database
+    random_io.rewind
+    WideRecord.synchronous_commit true
+    x.report("disabled per transaction") do
+      num_records.times do
+        WideRecord.transaction do
+          WideRecord.synchronous_commit false
+          create_record.call
+        end
+      end
+    end
+    
+    clean_database
+    random_io.rewind
+    WideRecord.synchronous_commit true
+    x.report("enabled / single transaction") do
+      WideRecord.transaction do
+        num_records.times { create_record.call }
+      end
+    end   
+    
+    clean_database
+    random_io.rewind
+    WideRecord.synchronous_commit false
+    x.report("disabled / single transaction") do
+      WideRecord.transaction do
+        num_records.times { create_record.call }
+      end
+    end  
+  end
+end

data/lib/surus.rb

@@ -7,3 +7,5 @@ require 'surus/array/integer_serializer'
 require 'surus/array/float_serializer'
 require 'surus/array/decimal_serializer'
 require 'surus/array/scope'
+require 'surus/synchronous_commit/connection'
+require 'surus/synchronous_commit/model'

data/lib/surus/array/scope.rb

@@ -1,10 +1,22 @@
 module Surus
   module Array
     module Scope
+      # Adds where condition that requires column to contain all values
+      #
+      # Examples:
+      #   User.array_has(:permissions, "manage_users")
+      #   User.array_has(:permissions, "manage_users", "manage_roles")
+      #   User.array_has(:permissions, ["manage_users", "manage_roles"])
       def array_has(column, *values)
         where("#{connection.quote_column_name(column)} @> ARRAY[?]", values.flatten)
       end
       
+      # Adds where condition that requires column to contain any values
+      #
+      # Examples:
+      #   User.array_has_any(:permissions, "manage_users")
+      #   User.array_has_any(:permissions, "manage_users", "manage_roles")
+      #   User.array_has_any(:permissions, ["manage_users", "manage_roles"])
       def array_has_any(column, *values)
         where("#{connection.quote_column_name(column)} && ARRAY[?]", values.flatten)    
       end

data/lib/surus/hstore/scope.rb

@@ -1,18 +1,36 @@
 module Surus
   module Hstore
     module Scope
+      # Adds a where condition that requires column to contain hash
+      #
+      # Example:
+      #   User.hstore_has_pairs(:properties, "favorite_color" => "green")
       def hstore_has_pairs(column, hash)
         where("#{connection.quote_column_name(column)} @> ?", Serializer.new.dump(hash))
       end
       
+      # Adds a where condition that requires column to contain key
+      #
+      # Example:
+      #   User.hstore_has_key(:properties, "favorite_color")
       def hstore_has_key(column, key)
         where("#{connection.quote_column_name(column)} ? :key", :key => key)    
       end
       
+      # Adds a where condition that requires column to contain all keys.
+      #
+      # Example:
+      #    User.hstore_has_all_keys(:properties, "favorite_color", "favorite_song")
+      #    User.hstore_has_all_keys(:properties, ["favorite_color", "favorite_song"])
       def hstore_has_all_keys(column, *keys)
         where("#{connection.quote_column_name(column)} ?& ARRAY[:keys]", :keys => keys.flatten)
       end
       
+      # Adds a where condition that requires column to contain any keys.
+      #
+      # Example:
+      #    User.hstore_has_any_keys(:properties, "favorite_color", "favorite_song")
+      #    User.hstore_has_any_keys(:properties, ["favorite_color", "favorite_song"])
       def hstore_has_any_keys(column, *keys)
         where("#{connection.quote_column_name(column)} ?| ARRAY[:keys]", :keys => keys.flatten)
       end

data/lib/surus/hstore/serializer.rb

@@ -108,6 +108,8 @@ module Surus
       def stringify(value)
         if value.kind_of?(String)
           [value, "String"]
+        elsif value.kind_of?(Symbol)
+          [value.to_s, "Symbol"]
         elsif value.kind_of?(Integer)
           [value.to_s, "Integer"]
         elsif value.kind_of?(Float)
@@ -129,6 +131,8 @@ module Surus
       
       def typecast(value, type)
         case type
+        when "Symbol"
+          value.to_sym
         when "Integer"
           Integer(value)
         when "Float"

data/lib/surus/synchronous_commit/connection.rb

@@ -0,0 +1,34 @@
+module Surus
+  module SynchronousCommit
+    module Connection
+      # When called without any value returns the current synchronous_commit
+      # value.
+      #
+      # When called with a value it is delegated to #synchronous_commit=
+      def synchronous_commit(value=:not_passed_param)
+        if value == :not_passed_param
+          select_value("SHOW synchronous_commit") == "on"
+        else
+          self.synchronous_commit = value
+        end
+      end
+      
+      # Changes current synchronous_commit state. If a transaction is currently
+      # in progress the change will be reverted at the end of the transaction.
+      #
+      # Requires true or false to be passed exactly -- not merely truthy or falsy
+      def synchronous_commit=(value)
+        raise ArgumentError, "argument must be true or false" unless value == true || value == false
+        
+        execute "SET #{'LOCAL' if open_transactions > 0} synchronous_commit TO #{value ? 'ON' : 'OFF'}"
+      end
+    end
+  end
+end
+
+# If Surus is loaded before establish_connection is called then
+# PostgreSQLAdapter will not be loaded yet. require it to ensure
+# it is available
+require "active_record/connection_adapters/postgresql_adapter"
+
+ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.send :include, Surus::SynchronousCommit::Connection

data/lib/surus/synchronous_commit/model.rb

@@ -0,0 +1,11 @@
+module Surus
+  module SynchronousCommit
+    # synchronous_commit and synchronous_commit= are delegated to the underlying
+    # connection object
+    module Model
+      delegate :synchronous_commit, :synchronous_commit=, :to => :connection
+    end
+  end
+end
+
+ActiveRecord::Base.extend Surus::SynchronousCommit::Model

data/lib/surus/version.rb

@@ -1,3 +1,3 @@
 module Surus
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/spec/hstore/serializer_spec.rb

@@ -30,6 +30,7 @@ describe Surus::Hstore::Serializer do
   end
   
   [
+    [:foo, "symbol"],
     [0, "integer 0"],
     [1, "positive integer"],
     [-1, "negative integer"],

data/spec/spec_helper.rb

@@ -31,7 +31,7 @@ end
 
 
 RSpec.configure do |config|
-  config.around do |example|
+  config.around :disable_transactions => nil do |example|
     ActiveRecord::Base.transaction do
       example.call
       raise ActiveRecord::Rollback

data/spec/synchronous_commit/connection_spec.rb

@@ -0,0 +1,95 @@
+require 'spec_helper'
+
+describe Surus::SynchronousCommit::Connection, :disable_transactions => true do
+  let(:conn) { ActiveRecord::Base.connection }
+  before { conn.execute "SET synchronous_commit TO ON;" }
+  after { conn.execute "SET synchronous_commit TO ON;" }
+  
+  describe "synchronous_commit" do
+    context "without parameter" do
+      subject { conn.synchronous_commit }
+    
+      context "when synchronous_commit commit is off" do
+        before { conn.execute "SET synchronous_commit TO OFF;" }
+        it { should == false }
+      end
+    
+      context "when synchronous_commit commit is on" do
+        before { conn.execute "SET synchronous_commit TO ON;" }
+        it { should == true }
+      end
+    end
+    
+    context "with parameter" do
+      context "true" do
+        before { conn.execute "SET synchronous_commit TO OFF;" }
+        it "sets synchronous_commit to on" do
+          conn.synchronous_commit true
+          conn.select_value("SHOW synchronous_commit").should == "on"
+        end
+      end
+      
+      context "false" do
+        before { conn.execute "SET synchronous_commit TO ON;" }
+        it "sets synchronous_commit to off" do
+          conn.synchronous_commit false
+          conn.select_value("SHOW synchronous_commit").should == "off"
+        end
+      end
+      
+      context "invalid value" do
+        it "raises ArgumentError" do
+          expect{conn.synchronous_commit "foo"}.to raise_error(ArgumentError)
+        end
+      end      
+      
+      context "inside transaction" do
+        before { conn.execute "SET synchronous_commit TO OFF;" }
+        
+        it "only persists for duration of transaction" do
+          conn.transaction do
+            conn.synchronous_commit true
+            conn.select_value("SHOW synchronous_commit").should == "on"
+          end
+          conn.select_value("SHOW synchronous_commit").should == "off"
+        end
+      end
+    end
+  end
+  
+  describe "synchronous_commit=" do
+    context "true" do
+      before { conn.execute "SET synchronous_commit TO OFF;" }
+      it "sets synchronous_commit to on" do
+        conn.synchronous_commit true
+        conn.select_value("SHOW synchronous_commit").should == "on"
+      end
+    end
+    
+    context "false" do
+      before { conn.execute "SET synchronous_commit TO ON;" }
+      it "sets synchronous_commit to off" do
+        conn.synchronous_commit false
+        conn.select_value("SHOW synchronous_commit").should == "off"
+      end
+    end
+    
+    context "invalid value" do
+      it "raises ArgumentError" do
+        expect{conn.synchronous_commit "foo"}.to raise_error(ArgumentError)
+      end
+    end      
+    
+    context "inside transaction" do
+      before { conn.execute "SET synchronous_commit TO OFF;" }
+      
+      it "only persists for duration of transaction" do
+        conn.transaction do
+          conn.synchronous_commit true
+          conn.select_value("SHOW synchronous_commit").should == "on"
+        end
+        conn.select_value("SHOW synchronous_commit").should == "off"
+      end
+    end
+  end  
+end

data/spec/synchronous_commit/model_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+describe Surus::SynchronousCommit::Model do
+  let(:conn) { ActiveRecord::Base.connection }
+  
+  describe "synchronous_commit" do
+    it "is delegated to connection" do
+      conn.should_receive(:synchronous_commit)
+      ActiveRecord::Base.synchronous_commit
+    end
+  end
+  
+  describe "synchronous_commit=" do
+    it "is delegated to connection" do
+      conn.should_receive(:synchronous_commit=)
+      ActiveRecord::Base.synchronous_commit = true
+    end
+  end  
+end

data/surus.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
   s.email       = ["jack@jackchristensen.com"]
   s.homepage    = "https://github.com/JackC/surus"
   s.summary     = %q{PostgreSQL extensions for ActiveRecord}
-  s.description = %q{PostgreSQL extensions for ActiveRecord}
+  s.description = %q{Includes serializers and search scopes for hstore and array. Also includes control over synchronous_commit to boost insert and update speed.}
 
   s.rubyforge_project = ""
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: surus
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-03 00:00:00.000000000 Z
+date: 2012-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
-  requirement: &17079080 !ruby/object:Gem::Requirement
+  requirement: &13148960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *17079080
+  version_requirements: *13148960
 - !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: &17091280 !ruby/object:Gem::Requirement
+  requirement: &13161940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: 3.1.0
   type: :runtime
   prerelease: false
-  version_requirements: *17091280
+  version_requirements: *13161940
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &17089120 !ruby/object:Gem::Requirement
+  requirement: &13159120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 2.8.0
   type: :development
   prerelease: false
-  version_requirements: *17089120
+  version_requirements: *13159120
 - !ruby/object:Gem::Dependency
   name: guard
-  requirement: &17086120 !ruby/object:Gem::Requirement
+  requirement: &13155700 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: 0.10.0
   type: :development
   prerelease: false
-  version_requirements: *17086120
+  version_requirements: *13155700
 - !ruby/object:Gem::Dependency
   name: guard-rspec
-  requirement: &17102600 !ruby/object:Gem::Requirement
+  requirement: &13173200 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,8 +65,9 @@ dependencies:
         version: 0.6.0
   type: :development
   prerelease: false
-  version_requirements: *17102600
-description: PostgreSQL extensions for ActiveRecord
+  version_requirements: *13173200
+description: Includes serializers and search scopes for hstore and array. Also includes
+  control over synchronous_commit to boost insert and update speed.
 email:
 - jack@jackchristensen.com
 executables: []
@@ -81,6 +82,16 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- bench/array_create.rb
+- bench/array_find.rb
+- bench/array_serialize.rb
+- bench/benchmark_helper.rb
+- bench/database.yml
+- bench/database_structure.sql
+- bench/hstore_create.rb
+- bench/hstore_find.rb
+- bench/hstore_serialize.rb
+- bench/synchronous_commit.rb
 - lib/surus.rb
 - lib/surus/array/decimal_serializer.rb
 - lib/surus/array/float_serializer.rb
@@ -89,6 +100,8 @@ files:
 - lib/surus/array/text_serializer.rb
 - lib/surus/hstore/scope.rb
 - lib/surus/hstore/serializer.rb
+- lib/surus/synchronous_commit/connection.rb
+- lib/surus/synchronous_commit/model.rb
 - lib/surus/version.rb
 - spec/array/decimal_serializer_spec.rb
 - spec/array/float_serializer_spec.rb
@@ -100,6 +113,8 @@ files:
 - spec/hstore/scope_spec.rb
 - spec/hstore/serializer_spec.rb
 - spec/spec_helper.rb
+- spec/synchronous_commit/connection_spec.rb
+- spec/synchronous_commit/model_spec.rb
 - surus.gemspec
 homepage: https://github.com/JackC/surus
 licenses: []