active_shard 0.0.1 → 0.1.0.alpha

data/CHANGELOG

@@ -0,0 +1,8 @@
+## 0.1.0.alpha ##
+
+- initial release of code and gem
+- includes working code base, missing completed railtie, better specs.
+
+## 0.0.1 ##
+
+- stub gem while setting up git repo, etc.

data/README.md

@@ -0,0 +1,245 @@
+ActiveShard - Multi-schema sharding for ActiveRecord
+====================================================
+
+ActiveShard is a library built primarily for sharding in ActiveRecord. It also supports multiple databases with differing schemas. As with the other sharding libraries for ActiveRecord (there are a few), this library represents the best solution to the authors' sharding needs. If you've been unhappy with other options, ActiveShard might be for you.
+
+
+## CAVEATS ##
+
+### Railtie isn't finished ... ###
+
+... so there are some additional steps you'll need to take to get this working. Specifically:
+
+Add the following to the end of your config/application.rb:
+
+    ActiveShard.config do |c|
+      definitions = ActiveShard::ShardDefinition.from_yaml_file( File.expand_path( '../shards.yml', __FILE__ ) )
+
+      definitions[ Rails.env.to_sym ].each do |shard|
+        c.add_shard( shard )
+      end
+    end
+
+    require 'active_shard/active_record'
+
+    ActiveRecord::Base.send( :include, ActiveShard::ActiveRecord::ShardSupport )
+
+    ActiveRecord::Base.connection_handler =
+      ActiveShard::ActiveRecord::ConnectionHandler.new(
+        ActiveShard.config.shard_definitions,
+        :shard_lookup => ActiveShard::ShardLookupHandler.new( :scope => ActiveShard.scope, :config => ActiveShard.config )
+      )
+    
+Once we complete the ActiveShard Railtie, these lines will not be necessary.
+
+
+### Where are the specs? ###
+
+Good eye. This library is being extracted from an existing project where application-specific tests were written to test the sharding functionality.
+
+Generic and more detailed specs are being written and will be added shortly.
+
+
+## Design goals ##
+
+The fundamental purpose of ActiveShard is to provide a framework that allows ActiveRecord to connect to multiple databases with multiple different schemas. All other features are a subset of this framework (sharding, replication, etc).
+
+### More framework, less magic ###
+
+ActiveShard doesn't do much guessing or sleight of hand. Queries are executed against whatever shard is marked as active for the schema used. Instances of models do not remember what shards they belong to.
+
+    ActiveShard.with( :main => :db1 ) do
+      user = User.find( 100 )
+    end
+    
+    # this will fail, as no shard is selected at this point -->
+    user.save!
+
+This is an intentional design decision. Other libraries go to great lengths to provide smarter implementations, but do so at the expense of flexibility.
+
+In contrast to other implementations, ActiveShard does not reopen or monkey-patch any Rails or ActiveRecord classes. It has been the authors' experience that any Rails application large enough to need sharding probably contains a fair amount of customization already. Sharding libraries which hack up core Rails classes often do not play nice with existing code. ActiveShard (hopefully!) does.
+
+
+## Install ##
+
+### Rails 3.x ###
+
+Add this line to your Gemfile:
+
+    gem 'active_shard'
+
+Install bundle:
+
+    $ bundle install
+    
+Add to config/application.rb, right under "require 'rails/all'":
+
+    require 'active_shard/active_record/railtie'
+
+
+## Most common usage ##
+
+### config/shards.yml (if used in Rails) ###
+
+Create a config/shards.yml file with your desired database configuration. Shards.yml contains the following structure (pseudo-code):
+
+    <environment>
+      <schema_name>
+        <shard_name>
+          <shard_specification>
+        <shard_name>
+          <shard_specification>
+      <schema_name>
+        <shard_name>
+          <shard_specification>
+          
+Example shards.yml:
+
+    production:
+      directories:
+        directory:
+          adapter: mysql2
+          database: dir_db
+          host: localhost
+          username: root
+
+      main:
+        db1:
+          adapter: mysql2
+          host: localhost
+          database: db1_db
+          username: root
+
+        db2:
+          adapter: mysql2
+          host: localhost
+          database: db2_db
+          username: root
+
+        db3:
+          adapter: mysql2
+          host: localhost
+          database: db3_db
+          username: root
+
+    development:
+      directories:
+        directory:
+          adapter: mysql2
+          host: localhost
+          database: dir_db_development
+          username: root
+
+      main:
+        db1:
+          adapter: mysql2
+          host: localhost
+          database: db1_db_development
+          username: root
+
+
+### Schema name for models ###
+
+ActiveRecord models must have a schema name associated with them. Given the shards.yml file specified above, you might see the following models:
+
+    # contains user lookup fields and the shard name on which user's primary data resides
+    class UserShard < ActiveRecord::Base
+      schema_name :directories
+      
+      # ...
+    end
+    
+    # primary user data
+    class User < ActiveRecord::Base
+      schema_name :main
+      
+      # ...
+    end
+
+
+### Selecting the active shard(s) ###
+
+In order to use a model -- such as the ones specified above -- a shard must be selected as the current active shard *for each schema used.* The easiest way to do this is to pass a block containing the queries to the ActiveShard.with( ... ) method, specifying the active shards in the parameters.
+
+Nested blocks maintain active shard settings for any schemas they do not explicitly set.  Example:
+
+    ActiveShard.with( :directories => :directory ) do
+    
+      # We can now use the UserShard model as a shard has been 
+      # selected for the 'directories' schema.
+      #
+      user_shard = UserShard.find_by_login( 'xavier' )
+      
+      # Using the User model here would raise an exception since there
+      # is no active shard for the schema that User belongs to ('main').
+      #
+      # However, if we select a shard for that schema ...
+      #
+      
+      ActiveShard.with( :main => user_shard.shard_name ) do
+        
+        user = User.find( user_shard.user_id )  # <-- this works.
+        
+        # ActiveShard effectively 'merges' nested shard selections rather
+        # than replace them. The active shards at this point are:
+        #
+        # :directories  => :directory
+        # :main         => <user_shard.shard_name>
+        #
+        
+      end
+      
+      # ... the active shard for the :main schema has been de-selected,
+      # leaving only the :directories => :directory shard as active.
+      
+    end
+
+To better understand what's happening here, see ActiveShard::Scope.
+
+
+### Migrations ###
+
+Migrations for each schema must reside in a directory under db/migrate that corresponds to the schema name.
+
+Example:
+    db/migrate/main
+      20110810103523_create_users_table.rb
+    db/migrate/directories
+      20110810105318_create_user_shards_table.rb
+
+
+You can run migrations against a shard by passing the *shard name* into the shards:migrate rake task, like so:
+
+    $ rake shards:migrate[db1]
+    
+The schema is discovered from the ActiveShard configuration and the proper migrations are executed.
+
+Each shard maintains its own schema_migrations table and can be (must be) migrated independently. This allows you to spin up additional shards in the future by simply adding an entry to your ActiveShard configuration and running migrations against that shard.
+
+
+### Rails Controllers ###
+
+If you want to send a specified action, or all actions from a controller, to a specific shard,  use this syntax:
+  
+    class ApplicationController < ActionController::Base
+      around_filter :activate_shards
+    
+      def activate_shards(&block)
+        ActiveShard.with( :directories => :directory, :main => :db1 )
+      end    
+    end
+
+
+## Other similar libraries ##
+
+There are several, but Octopus (ar-octopus) is the most popular.
+
+
+## Authors ##
+
+Brasten Sager ( brasten@dashwire.com )
+Matt Baker ( matt@dashwire.com )
+
+## Copyright
+
+Copyright (c) 2011 Dashwire Inc., released under the MIT license.

data/lib/active_shard/active_record/connection_handler.rb

@@ -0,0 +1,72 @@
+require 'active_record/connection_adapters/abstract/connection_pool'
+
+module ActiveShard
+  module ActiveRecord
+
+    autoload :SchemaConnectionPool, 'active_shard/active_record/schema_connection_pool'
+
+    class ConnectionHandler < ::ActiveRecord::ConnectionAdapters::ConnectionHandler
+
+      # Used to look up shard names
+      #
+      attr_accessor :shard_lookup
+
+      # Initializes a new ConnectionHandler
+      #
+      # @param [Array<ShardDefinition>] shard_definitions
+      # @param [Hash] options
+      # @option options [ShardLookupHandler] :shard_lookup
+      #
+      def initialize( shard_definitions, options={} )
+        @shard_lookup = options[ :shard_lookup ]
+
+        @connection_pools = {}
+        @schema_pools     = {}
+
+        initialize_shard_definitions( shard_definitions )
+      end
+
+      def initialize_shard_definitions( definitions )
+        definitions.each do |definition|
+          schema_pools[ definition.schema.to_sym ] ||= SchemaConnectionPool.new(
+              ::ActiveRecord::Base::ConnectionSpecification.new( definition.connection_spec, definition.adapter_method )
+            )
+
+
+          connection_pools[ connection_pool_id( definition.schema, definition.name ) ] =
+            ::ActiveRecord::ConnectionAdapters::ConnectionPool.new(
+              ::ActiveRecord::Base::ConnectionSpecification.new( definition.connection_spec, definition.adapter_method )
+            )
+        end
+      end
+
+      #def establish_connection( *args )
+      #  raise NoMethodError, "Sharded models do not support establish_connection"
+      #end
+
+      # Retrieve connection pool for class
+      #
+      def retrieve_connection_pool( klass )
+        schema_name = klass.schema_name
+
+        active_shard_name = shard_lookup.lookup_active_shard( schema_name )
+
+        Rails.logger.debug( "RetrieveConnectionPool for #{klass.name}, schema_name #{schema_name}, active_shard #{active_shard_name}")
+        
+        ( active_shard_name.nil? ?
+            schema_pools[ schema_name.to_sym ] :
+            connection_pools[ connection_pool_id( schema_name, active_shard_name ) ] )
+      end
+
+      private
+
+        attr_reader :schema_pools
+
+        def connection_pool_id( schema_name, shard_name )
+          "#{schema_name.to_s}+#{shard_name.to_s}".to_sym
+        end
+
+
+    end
+  end
+end

data/lib/active_shard/active_record/railtie.rb

@@ -0,0 +1,56 @@
+require "active_shard"
+require "rails"
+
+module ActiveShard
+  module ActiveRecord
+    class Railtie < Rails::Railtie
+
+      config.active_shard = ActiveSupport::OrderedOptions.new
+
+      rake_tasks do
+        load "active_shard/active_record/rails/database.rake"
+      end
+
+      initializer "active_shard.logger" do
+        ActiveSupport.on_load(:active_shard) { self.logger ||= ::Rails.logger }
+      end
+
+      initializer "active_shard.set_configs" do |app|
+        ActiveSupport.on_load(:active_record) do
+          app.config.active_record.each do |k,v|
+            send "#{k}=", v
+          end
+        end
+      end
+
+      initializer "active_shard.initialize_database" do |app|
+        ActiveSupport.on_load(:active_record) do
+          self.configurations = app.config.database_configuration
+          establish_connection
+        end
+      end
+
+  ActiveShard.config do |c|
+    definitions = ActiveShard::ShardDefinition.from_yaml_file( File.expand_path( '../shards.yml', __FILE__ ) )
+
+    definitions[ Rails.env.to_sym ].each do |shard|
+      c.add_shard( shard )
+    end
+  end
+
+  require 'active_shard/active_record'
+
+  ActiveRecord::Base.send( :include, ActiveShard::ActiveRecord::ShardSupport )
+
+  ActiveRecord::Base.connection_handler =
+    ActiveShard::ActiveRecord::ConnectionHandler.new(
+      ActiveShard.config.shard_definitions,
+      :shard_lookup => ActiveShard::ShardLookupHandler.new( :scope => ActiveShard.scope, :config => ActiveShard.config )
+    )
+
+  ActiveRecord::Base.schema_name( :main )
+
+
+    end
+  end
+end

data/lib/active_shard/active_record/schema_connection_adapter.rb

@@ -0,0 +1,23 @@
+require 'active_shard/exceptions'
+
+module ActiveShard
+  module ActiveRecord
+    class SchemaConnectionAdapter
+
+      delegate :columns, :verify, :verify!, :run_callbacks, :quote_table_name, :quote_value, :quote, :to => :adapter
+
+      def initialize( adapter )
+        @adapter = adapter
+      end
+
+      def method_missing( sym, *args, &block )
+        raise ::ActiveShard::NoActiveShardError
+      end
+
+      private
+        def adapter
+          @adapter
+        end
+    end
+  end
+end

data/lib/active_shard/active_record/schema_connection_pool.rb

@@ -0,0 +1,18 @@
+require 'active_record/connection_adapters/abstract/connection_pool'
+
+module ActiveShard
+  module ActiveRecord
+
+    autoload :SchemaConnectionAdapter, 'active_shard/active_record/schema_connection_adapter'
+
+    class SchemaConnectionPool < ::ActiveRecord::ConnectionAdapters::ConnectionPool
+
+      private
+        def new_connection
+          SchemaConnectionAdapter.new( super )
+        end
+
+    end
+
+  end
+end

data/lib/active_shard/active_record/shard_support.rb

@@ -0,0 +1,30 @@
+module ActiveShard
+  module ActiveRecord
+
+    # To enable ActiveShard support in ActiveRecord, mix this module in to your
+    # model superclass.
+    #
+    # eg: ActiveRecord::Base.send( :include, ActiveShard::ActiveRecord::ShardSupport )
+    #
+    # For an explanation of why you'd use ShardedBase or ShardSupport, @see ActiveShard::ActiveRecord
+    #
+    module ShardSupport
+
+      def self.included( base )
+        base.extend( ClassMethods )
+      end
+
+      module ClassMethods
+        
+        # Specifies the schema name for the current model class (and its subclasses)
+        #
+        def schema_name( schema_name=:not_specified )
+          write_inheritable_attribute( :schema_name, schema_name ) unless ( schema_name == :not_specified )
+          read_inheritable_attribute( :schema_name )
+        end
+      end
+
+    end
+
+  end
+end

data/lib/active_shard/active_record/sharded_base.rb

@@ -0,0 +1,18 @@
+require 'active_record/base'
+require 'active_shard/active_record/shard_support'
+
+module ActiveShard
+  module ActiveRecord
+
+    # ShardedBase is a subclass of ActiveRecord::Base which mixes in the ShardSupport
+    # module.
+    #
+    # For an explanation of why you'd use ShardedBase or ShardSupport, @see ActiveShard::ActiveRecord
+    #
+    class ShardedBase < ::ActiveRecord::Base
+      include ::ActiveShard::ActiveRecord::ShardSupport
+      
+    end
+
+  end
+end

data/lib/active_shard/active_record.rb

@@ -0,0 +1,15 @@
+module ActiveShard
+
+  # The ActiveShard::ActiveRecord module contains the code necessary for ActiveRecord
+  # integration.
+  #
+  # -- Need to add explanation of ShardedBase VS ShardSupport --
+  #
+  module ActiveRecord
+    
+    autoload :ConnectionHandler,    'active_shard/active_record/connection_handler'
+    autoload :ShardSupport,         'active_shard/active_record/shard_support'
+    autoload :ShardedBase,          'active_shard/active_record/sharded_base'
+
+  end
+end

data/lib/active_shard/config.rb

@@ -0,0 +1,52 @@
+module ActiveShard
+  autoload :ShardDefinition,    'active_shard/shard_definition'
+  autoload :ShardCollection,    'active_shard/shard_collection'
+
+  class Config
+
+    # Returns a filtered list of shards that belong to
+    # the specified schema
+    #
+    # @return [Array] shards belonging to schema
+    #
+    def shards_by_schema( schema_name )
+      shard_collection.by_schema( schema_name )
+    end
+
+    # Returns the name of a shard usable for schema definition
+    # connections
+    #
+    def schema_shard_name_by_schema( schema_name )
+      shard_def = shard_definitions_by_schema( schema_name ).first
+
+      shard_def.nil? ? nil : shard_def.name.to_sym
+    end
+
+    # Returns a Shard Definition by the shard name
+    #
+    # @return [ShardDefinition]
+    #
+    def shard( name )
+      shard_collection.shard( name )
+    end
+
+    def add_shard( *args )
+      shard_collection.add_shard( *args )
+    end
+
+    def shard_definitions
+      shard_collection.shard_definitions
+    end
+
+    def remove_shard( shard_name )
+      shard_collection.remove_shard( shard_name )
+    end
+
+    private
+      def shard_collection
+        @shard_collection ||= ShardCollection.new
+      end
+
+  end
+  
+end

data/lib/active_shard/exceptions.rb

@@ -0,0 +1,16 @@
+module ActiveShard
+
+  # CODE CONVENTION VIOLATION
+  #
+  # For better visualization, the following code is indented based on class hierarchy rather
+  # than nesting.
+  #
+
+  class ActiveShardError < StandardError; end
+
+    class DefinitionError < ActiveShardError; end
+      class NameNotUniqueError < DefinitionError; end
+
+    class NoActiveShardError < ActiveShardError; end
+
+end

data/lib/active_shard/scope.rb

@@ -0,0 +1,118 @@
+module ActiveShard
+
+  # Maintains the state of current active shards per schema.
+  #
+  # Requests for the current active shard for a schema name will iterate
+  # up the scope stack until it finds an active shard (or nil).
+  #
+  # @example
+  #   scope = Scope.new
+  #   scope.push( :user_data => :db_1, :directories => :directory_1 )
+  #
+  #   # updates current :user_data shard, :directories shard remains
+  #   scope.push( :user_data => :db_3 )
+  #
+  #   scope.active_shard_for_schema( :user_data )
+  #   => :db_3
+  #
+  #   scope.active_shard_for_schema( :directories )
+  #   => :directory_1
+  #
+  class Scope
+
+    def initialize
+      @scope_crumbs   = []
+      @current_shards = {}
+    end
+
+    # Push a new scope on onto the stack.
+    #
+    # The active_shards parameter should be a hash with schema names for
+    # keys and shard names for the corresponding values.
+    #
+    # eg: scope.push( :directory => :dir1, :user_data => :db1 )
+    #
+    # @param [Hash] active_shards
+    #
+    def push( active_shards )
+      scope_crumbs << active_shards
+
+      # shortcutting #build_current_shards for performance reasons
+      if active_shards.is_a?(Symbol)
+        # if active_shards is a Symbol, ALL schemas are using active shard
+        current_shards.keys.each do |schema|
+          current_shards[schema] = active_shards
+        end
+        current_shards[AnyShard] = active_shards
+
+      else
+        current_shards.merge!( normalize_keys( active_shards ) )
+      end
+    end
+
+    # Remove the last scope from the stack
+    #
+    def pop( pop_until=nil )
+      if pop_until.nil?
+        scope_crumbs.pop
+      else
+        (scope_crumbs.size - scope_crumbs.index(pop_until)).times do
+          scope_crumbs.pop
+        end
+      end
+
+      build_current_shards( scope_crumbs )
+    end
+
+    # Returns the name of the active shard by the provided schema name.
+    #
+    # @param [Symbol] schema_name name of schema
+    #
+    # @return [Symbol, nil] current active shard for schema
+    #
+    def active_shard_for_schema( schema_name )
+      current_shards[ schema_name.to_sym ] || current_shards[ AnyShard ]
+    end
+
+    private
+
+      # scope_crumbs and current_shards are two different data structures that
+      # essentially represent the same data. "current_shards" is used for performance
+      # when possible; "scope_crumbs" is used to generate current_shards when
+      # necessary.
+
+      attr_reader :scope_crumbs
+      attr_reader :current_shards
+
+      def build_current_shards( crumbs )
+        current_shards.clear
+
+        crumbs.each do |crumb|
+          case crumb
+          when Symbol
+
+            current_shards.keys.each do |schema|
+              current_shards[schema] = crumb
+            end
+            current_shards[AnyShard] = crumb
+          when Hash
+
+            crumb.each_pair { |schema, shard| current_shards[ schema.to_sym ] = shard.to_sym }
+          end
+        end
+
+        current_shards
+      end
+
+      def normalize_keys( hash )
+        ret = {}
+
+        hash.each_pair { |k, v| ret[ k.to_sym ] = v }
+
+        ret
+      end
+
+      class AnyShard; end
+
+  end
+end

data/lib/active_shard/scope_manager.rb

@@ -0,0 +1,66 @@
+module ActiveShard
+
+  autoload :Scope, 'active_shard/scope'
+
+  # ScopeManager handles the passing of messages to a Scope based on
+  # the current thread.
+  #
+  # Allows consumers to operate on a Scope duck-typed object without
+  # handling the Thread local variable stuff.
+  #
+  class ScopeManager
+
+    # Initializes a scope manager
+    #
+    # @param [Hash] options
+    # @option options [Class,#new] :scope_class class to use when instantiating
+    #   scope instances
+    #
+    def initialize( options={} )
+      @scope_class = options[:scope_class] if options[:scope_class]
+    end
+
+    # @see ActiveShard::Scope#push
+    #
+    def push( *args )
+      scope.push( *args )
+    end
+
+    # @see ActiveShard::Scope#pop
+    #
+    def pop( *args )
+      scope.pop( *args )
+    end
+
+    # @see ActiveShard::Scope#active_shard_for_schema
+    #
+    def active_shard_for_schema( *args )
+      scope.active_shard_for_schema( *args )
+    end
+
+    # Sets the class to use for maintaining Thread-local scopes
+    #
+    # Instances of klass must respond to:
+    #   #push
+    #   #pop
+    #   #active_shard_for_schema
+    #
+    # @param [Class,#new] klass scope_class
+    #
+    def scope_class=( klass )
+      @scope_class = klass
+    end
+
+    # Returns the current scope_class
+    #
+    def scope_class
+      @scope_class ||= Scope
+    end
+
+    private
+      def scope
+        Thread.current[:active_shard_scope] ||= scope_class.new
+      end
+
+  end
+end

data/lib/active_shard/shard_collection.rb

@@ -0,0 +1,137 @@
+require 'active_shard/exceptions'
+
+module ActiveShard
+
+  autoload :ShardDefinition, 'active_shard/shard_definition'
+
+  # Represents a group of shards. Most commonly used to group shards belonging to
+  # the same schema.
+  #
+  # Handles some basic caching of common use cases to (hopefully) increase performance
+  # in most situations.
+  #
+  class ShardCollection
+
+    # Initializes a shard group
+    #
+    # @param [Array<ShardDefinition>] shard_definitions
+    #
+    def initialize( shard_definitions=[] )
+      add_shards( shard_definitions )
+    end
+
+    # Returns a Shard Definition by the shard name
+    #
+    # @return [ShardDefinition]
+    #
+    def shard( name )
+      definitions_by_name[ name.to_sym ]
+    end
+
+    # Adds a list of shard definitions to this collection.
+    #
+    # @return [Array] a list of shards that were added
+    #
+    def add_shards( shard_definitions )
+      added_shards = []
+
+      shard_definitions.each do |definition|
+        begin
+          added_shards << add_shard( definition )
+        rescue NameNotUniqueError
+          # bury
+        end
+      end
+
+      added_shards
+    end
+
+    # Adds a shard definition to the collection
+    #
+    # @return [ShardDefinition] added shard definition
+    #
+    def add_shard( *args )
+      shard_def = ( args.first.is_a?(ShardDefinition) ? args.first : ShardDefinition.new( *args ) )
+
+      duplicate_exists = shard_name_exists?( shard_def.name )
+
+      raise NameNotUniqueError,
+            "Shard named '#{shard_def.name.to_s}' exists for schema '#{shard_def.schema.to_s}'" if duplicate_exists
+
+      definitions << shard_def
+      definitions_by_schema( shard_def.schema ) << shard_def
+      definitions_by_name[ shard_def.name.to_sym ] = shard_def
+
+      shard_def
+    end
+
+    # All shard definitions in collection
+    #
+    # @return [Array<ShardDefinition>] shard definitions
+    #
+    def shard_definitions
+      definitions.dup
+    end
+
+    # Returns a ShardCollection with definitions from this collection
+    # that match the provided schema name
+    #
+    # @param [Symbol] schema_name schema name
+    #
+    # @return [ShardCollection] collection containing applicable definitions
+    #
+    def by_schema( schema_name )
+      self.class.new( definitions_by_schema( schema_name ) )
+    end
+
+    # Removes a shard definition from the collection based on the
+    # provided shard name.
+    #
+    # @param [Symbol] shard_name
+    #
+    # @return [ShardDefinition,nil] the ShardDefinition removed, or
+    #   nil if none was found
+    #
+    def remove_shard( shard_name )
+      shard_def = definitions_by_name.delete( shard_name.to_sym )
+      return nil if shard_def.nil?
+
+      definitions.delete( shard_def )
+      definitions_by_schema( shard_def.schema ).delete( shard_def )
+
+      shard_def
+    end
+
+    # Returns whether or not a Shard exists in this collection with the provided
+    # schema and shard names.
+    #
+    # @return [Boolean]
+    #
+    def shard_name_exists?( shard_name )
+      !( definitions_by_name[ shard_name.to_sym ].nil? )
+    end
+
+    # Returns a random shard name from the group
+    #
+    # @return [Symbol] a shard name
+    #
+    def any_shard
+      definitions[ rand( definitions.size ) ].name
+    end
+
+    private
+
+      def definitions
+        @definitions ||= []
+      end
+
+      def definitions_by_schema( schema_name )
+        ( @definitions_by_schema ||= {} )[ schema_name.nil? ? nil : schema_name.to_sym ] ||= []
+      end
+
+      def definitions_by_name
+        ( @definitions_by_name ||= {} )
+      end
+
+  end
+end

data/lib/active_shard/shard_definition.rb

@@ -0,0 +1,86 @@
+module ActiveShard
+
+  class ShardDefinition
+    attr_accessor :schema
+    attr_accessor :name
+    attr_writer :connection_spec
+
+    class << self
+
+      # Returns a hash with environments as the hash keys and
+      # a list of ShardDefinitions as the hash values
+      #
+      # @param [String] file_name path to Yaml file
+      #
+      # @return [Hash] hash of environments and lists of Definitions
+      #
+      def from_yaml_file( file_name )
+        definitions = {}
+
+        hash = YAML.load( ERB.new( File.open( file_name ).read() ).result )
+
+        hash.each_pair do |environment, schemas|
+          schemas.each_pair do |schema, shards|
+            shards.each_pair do |shard, spec|
+              ( definitions[ environment.to_sym ] ||= [] ) << self.new( shard.to_sym,
+                                                                        spec.merge( :schema => schema.to_sym ) )
+            end
+          end
+        end
+
+        definitions
+      end
+
+    end
+
+    # Returns a new ShardDefinition
+    #
+    # @param [String] name name of the shard
+    # @param [Hash] options
+    # @option options [String] :schema name of the schema
+    # @option options [String] :group group name of shard
+    # @option options all other options passed as connection spec
+    #
+    def initialize( name, options={} )
+      opts = options.dup
+
+      @name             = name
+      @schema           = opts.delete( :schema )
+      @connection_spec  = symbolize_keys( opts )
+    end
+
+    def adapter_method
+      "#{connection_spec[:adapter]}_connection"
+    end
+
+    def connection_spec
+      @connection_spec ||= {}
+    end
+
+    # Returns true if our schema == schema_name and neither
+    # self#schema nor schema_name is nil. Returns false otherwise.
+    #
+    # @param [Symbol] schema_name
+    #
+    # @return [bool]
+    #
+    def belongs_to_schema?( schema_name )
+      return false if ( schema.nil? || schema_name.nil? )
+
+      ( schema.to_sym == schema_name.to_sym )
+    end
+
+    private
+
+      def symbolize_keys( hash )
+        ret = {}
+
+        hash.each_pair do |k,v|
+          ret[k.to_sym] = v
+        end
+
+        ret
+      end
+  end
+
+end

data/lib/active_shard/shard_lookup_handler.rb

@@ -0,0 +1,28 @@
+module ActiveShard
+
+  # Handles current and schema shard resolution using the current
+  # scope and
+  class ShardLookupHandler
+
+    # Initializes a shard lookup handler
+    #
+    # @param [Hash] options
+    # @option options [Scope,ScopeManager] :scope
+    # @option options [Config] :config
+    #   scope instances
+    #
+    def initialize( options={} )
+      @scope  = options[:scope]
+      @config = options[:config]
+    end
+
+    def lookup_active_shard( schema_name )
+      @scope.active_shard_for_schema( schema_name )
+    end
+
+    def lookup_schema_shard( schema_name )
+      @config.schema_shard_name_by_schema( schema_name )
+    end
+
+  end
+end

data/lib/active_shard/version.rb

@@ -0,0 +1,3 @@
+module ActiveShard
+  VERSION = '0.1.0.alpha'
+end

data/lib/active_shard.rb

@@ -0,0 +1,98 @@
+module ActiveShard
+
+  autoload :Config,               'active_shard/config'
+  autoload :ScopeManager,         'active_shard/scope_manager'
+  autoload :ShardLookupHandler,   'active_shard/shard_lookup_handler'
+  autoload :ShardCollection,      'active_shard/shard_collection'
+
+  class << self
+
+    # Returns the current Config object for ActiveShard.
+    #
+    # @yield [c] yields the current config object to the block for setup
+    #
+    # @return [Config] current config
+    #
+    def config()
+      @config ||= Config.new
+
+      yield( @config ) if block_given?
+
+      @config
+    end
+
+    # Sets the current scope handling object.
+    #
+    # Scope handler must respond to the following methods:
+    #   #push( scope ), #pop( scopes ), #active_shard_for_schema( schema )
+    #
+    def scope=( val )
+      @scope = val
+    end
+
+    # Returns current scope object
+    #
+    # @return [#push,#pop,#active_shard_for_schema] current scope object
+    #
+    def scope
+      @scope ||= ScopeManager.new
+    end
+
+    # Sets the active shards before yielding, and reverts them before returning.
+    #
+    # This method will also pop off any additional scopes that were added by the
+    # provided block if they were not already popped.
+    #
+    # @example
+    #
+    #   ActiveShard.with( :users => :user_db1 ) do
+    #     ActiveShard.with( :users => :user_db2 ) do
+    #       ActiveShard.activate_shards( :users => :user_db3 )
+    #       # 3 shard entries on scope stack
+    #     end
+    #     # 1 shard entry on scope stack
+    #   end
+    #
+    # @param [Hash] scopes schemas (keys) and active shards (values)
+    #
+    # @return the return value from the provided block
+    #
+    def with( scopes={}, &block )
+      ret = nil
+
+      begin
+        activate_shards( scopes )
+
+        ret = block.call()
+      ensure
+        pop_to( scopes )
+        ret
+      end
+    end
+
+    # Pushes active shards onto the scope without a block.
+    #
+    def activate_shards( scopes={} )
+      scope.push( scopes )
+    end
+
+    def pop_to( scopes )
+      scope.pop( scopes )
+    end
+
+    def shards_by_schema( schema_name )
+      config.shards_by_schema( schema_name )
+    end
+
+    def logger
+      @logger
+    end
+
+    def logger=(val)
+      @logger = val
+    end
+
+  end
+end
+
+ActiveSupport.run_load_hooks(:active_shard, ActiveShard) if defined?(ActiveSupport)

metadata

@@ -1,8 +1,8 @@
 --- !ruby/object:Gem::Specification 
 name: active_shard
 version: !ruby/object:Gem::Version 
-  prerelease: 
-  version: 0.0.1
+  prerelease: 6
+  version: 0.1.0.alpha
 platform: ruby
 authors: 
 - Brasten Sager
@@ -11,7 +11,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-12 00:00:00 Z
+date: 2011-08-15 00:00:00 Z
 dependencies: []
 
 description: ActiveShard is a library that implements flexible sharding in ActiveRecord and Rails.
@@ -25,7 +25,24 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-- README.rdoc
+- CHANGELOG
+- README.md
+- lib/active_shard/active_record/connection_handler.rb
+- lib/active_shard/active_record/railtie.rb
+- lib/active_shard/active_record/schema_connection_adapter.rb
+- lib/active_shard/active_record/schema_connection_pool.rb
+- lib/active_shard/active_record/shard_support.rb
+- lib/active_shard/active_record/sharded_base.rb
+- lib/active_shard/active_record.rb
+- lib/active_shard/config.rb
+- lib/active_shard/exceptions.rb
+- lib/active_shard/scope.rb
+- lib/active_shard/scope_manager.rb
+- lib/active_shard/shard_collection.rb
+- lib/active_shard/shard_definition.rb
+- lib/active_shard/shard_lookup_handler.rb
+- lib/active_shard/version.rb
+- lib/active_shard.rb
 homepage: 
 licenses: []
 

data/README.rdoc

@@ -1 +0,0 @@
-Stub push. No code actually exists here. Will be pushed soon.