dynashard 0.2.0 → 0.3.0

data/README.md

@@ -2,17 +2,22 @@
 
 This package provides database sharding functionality for ActiveRecord models.
 
-Sharding is disabled by default and is enabled with +Dynashard.enable+.  This allows
-sharding behavior to be enabled globally or only for specific environments so for
-example production environments could be sharded while development environments could
+Sharding is disabled by default and is enabled with `Dynashard.enable`.  This allows
+sharding behavior to be enabled globally or only for specific environments; for example,
+production environments could be sharded while development environments could
 use a single database.
 
 Models may be configured to determine the appropriate shard (database connection) to
-use based on context defined prior to performing queries.
+use based on context defined prior to performing queries.  Different
+models may shard using different contexts.
 
     class Widget < ActiveRecord::Base
       shard :by => :user
     end
+
+    class Doohickie < ActiveRecord::Base
+      shard :by => :vhost
+    end
   
     class WidgetController < ApplicationController
       around_filter :set_shard_context
@@ -20,12 +25,15 @@ use based on context defined prior to performing queries.
       def index
         # Widgets will be loaded using the connection for the current user's shard
         @widgets = Widget.find(:all)
+
+        # Doohickies will be loaded using the connection for the vhost's shard
+        @doohickies = Doohickie.find(:all)
       end
   
       private
   
         def set_shard_context
-          Dynashard.with_context(:user => current_user.shard) do
+          Dynashard.with_context(:user => current_user.shard, :vhost => request.env['HTTP_HOST']) do
             yield
           end
         end
@@ -65,6 +73,77 @@ association's owner.
 
   New associations are saved on the Company's shard.
 
+Shard context values may be a valid argument to establish_connection()
+such as a string reference to a configuration from config/database.yml
+or a hash with database connection parameters.  Values may also be an
+object that responds to :call and returns a valid argument to
+establish_connection().
+
+  Load widgets from a shard defined in database.yml
+
+    $ cat config/database.yml
+
+    development:
+      database: db/development.sqlite3
+      <<: *defaults
+
+    shard1:
+      database: db/shard1.sqlite3
+      <<: *defaults
+
+    shard2:
+      database: db/shard2.sqlite3
+      <<: *defaults
+
+    > @widgets = Dynashard.with_context(:user => 'shard1') { Widget.find(:all) }
+    => [#<Widget id:1>, #<Widget id:2>]
+
+  Load widgets from a shard using a hash of connection params
+
+    > conn = {:adapter => 'sqlite3', :database => 'db/shard3.sqlite3'}
+    > @widgets = Dynashard.with_context(:user => conn) { Widget.find(:all) }
+    => [#<Widget id:1>, #<Widget id:2>]
+
+  Create a widget using a method to determine the shard
+
+    widget_shard = lambda do
+      # Store widgets by month/day
+      {:adapter => 'sqlite3', :database => "db/dayslice#{Time.now.strftime("%m%d")}"}
+    end
+
+    > Time.now
+    => Mon Jan 31 17:37:23 -0800 2011
+
+    > widget_shard.call
+    => {:database=>"db/dayslice0131", :adapter=>"sqlite3"}
+
+    > new_widget = Dynashard.with_context(:user => widget_shard) do
+        Widget.create(:name => 'The newest of the widgets')
+      end
+    => <#Widget id:3>
+
+  Use a Rails initializer for one-time configuration of shard context
+
+    $ cat config/initializers/dynashard.rb
+
+    # Put user-sharded data on the smallest shard
+    Dynashard.shard_context[:user] = lambda do
+      Shard.order(:size).find(:first).dsn
+    end
+
+    > new_widget = Widget.create(:name => 'Put this on the smallest shard')
+    => <#Widget id:4>
+
+  Use with_context to override an earlier context setting
+
+    > Dynashard.shard_context[:user] = 'shard1'
+    > new_widget = Widget.create(:name => 'Put this on shard1')
+    => <#Widget id:5>
+    > new_widget = Dynashard.with_context(:user => 'shard2') do
+        Widget.create(:name => 'Put this on shard2')
+      do
+    > <#Widget id:6>
+
 ## TODO: add gotcha section, eg:
 
  - uniqueness validations should be scoped by whatever is sharding

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/dynashard.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{dynashard}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Nick Hengeveld"]
-  s.date = %q{2011-01-31}
+  s.date = %q{2011-02-01}
   s.description = %q{Dynashard allows you to shard your ActiveRecord models.  Models can be configured to shard based on context that can be defined dynamically.}
   s.email = %q{nickh@verticalresponse.com}
   s.extra_rdoc_files = [
@@ -32,6 +32,8 @@ Gem::Specification.new do |s|
     "lib/dynashard/validations.rb",
     "spec/associations_spec.rb",
     "spec/connection_handler_spec.rb",
+    "spec/db/database.yml",
+    "spec/db/schema.rb",
     "spec/dynashard_spec.rb",
     "spec/model_spec.rb",
     "spec/spec_helper.rb",

data/spec/db/database.yml

@@ -0,0 +1,16 @@
+shared: &shared
+  adapter: sqlite3
+  pool: 5
+  timeout: 5000
+
+test:
+  database: <%= plugin_test_dir %>/db/base.sqlite3
+  <<: *shared
+
+shard1:
+  database: <%= plugin_test_dir %>/db/shard1.sqlite3
+  <<: *shared
+
+shard2:
+  database: <%= plugin_test_dir %>/db/shard2.sqlite3
+  <<: *shared

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Nick Hengeveld
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-31 00:00:00 -08:00
+date: 2011-02-01 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -140,13 +140,14 @@ files:
 - lib/dynashard/validations.rb
 - spec/associations_spec.rb
 - spec/connection_handler_spec.rb
+- spec/db/database.yml
+- spec/db/schema.rb
 - spec/dynashard_spec.rb
 - spec/model_spec.rb
 - spec/spec_helper.rb
 - spec/support/factories.rb
 - spec/support/models.rb
 - spec/validation_spec.rb
-- spec/db/schema.rb
 has_rdoc: true
 homepage: http://github.com/nickh/dynashard
 licenses: 
@@ -161,7 +162,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -2881092534266890665
+      hash: 2742474365578406990
       segments: 
       - 0
       version: "0"