active_record_shards 3.11.2 → 3.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: bbc0fcaa322a29df41febb37f52fd52dfb4e9259
-  data.tar.gz: 460544575270a626b64fc671d95d706bfac532a6
+SHA256:
+  metadata.gz: 24b77105aa8df10b1e79313f01b54fe87dba293938c9d41dc103f41cac64ec84
+  data.tar.gz: ec1da959a6dc2adbb6f287f73a3346c68fd49db30f7922dbc9adca7368532af2
 SHA512:
-  metadata.gz: 7d7cb9f8d135e1c230c2f467dbb761b844004c7e86d77cf5af267e6966654af8f5061d34852c76bdcc59af606a6c9688bb5ac70cfa2c928bdbec4c4ffd7f1345
-  data.tar.gz: 5e471616a88ccab4a18eb8c29a707911ad1246623729ea61c576d5964c73ddfd5f50a30847399d87012310b2457afb141c09411368c6dae27e8a19a610a4297e
+  metadata.gz: 5ccae049b9c4a450f04cc2ae6b0cfca9eba75ac72d5f795c0c49ae5fc19e37fad1341d14f3ba34f75c684696131586a663fb306bcd35c2dad9fc625ad36955f3
+  data.tar.gz: 0b46d1cafa4fecae447a01106bfc4de592b7271fc17fef4c254a44a80cc22b22f5155e460d6aba036baad1a229f6f0b6935c3d108c935c5fd5cec9e6271eab83

data/README.md

@@ -1,11 +1,20 @@
-[![Build Status](https://secure.travis-ci.org/zendesk/active_record_shards.png)](http://travis-ci.org/zendesk/active_record_shards)
+[![Build Status](https://github.com/zendesk/active_record_shards/workflows/CI/badge.svg)](https://github.com/zendesk/active_record_shards/actions?query=workflow%3ACI)
 
 # ActiveRecord Shards
 
-ActiveRecord Shards is an extension for ActiveRecord that provides support for sharded database and slaves. Basically it is just a nice way to
+ActiveRecord Shards is an extension for ActiveRecord that provides support for sharded database and replicas. Basically it is just a nice way to
 switch between database connections. We've made the implementation very small, and have tried not to reinvent any wheels already present in ActiveRecord.
 
-ActiveRecord Shards has been used and tested on Rails 3.2, 4.2 and 5.0 and has in some form or another been used in production on a large Rails app for several years.
+ActiveRecord Shards has been used and tested on Rails 4.2, 5.x and 6.0, and has in some form or another been used in production on large Rails apps for several years.
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Migrations](#migrations)
+  - [Example](#example)
+    - [Shared Model](#create-a-table-for-the-shared-not-sharded-model)
+    - [Sharded Model](#create-a-table-for-the-sharded-model)
+- [Usage](#usage)
+- [Debugging](#debugging)
 
 ## Installation
 
@@ -15,85 +24,139 @@ and make sure to require 'active\_record\_shards' in some way.
 
 ## Configuration
 
-Add the slave and shard configuration to config/database.yml:
-
-    production:
-      adapter: mysql
-      encoding: utf8
-      database: my_app_main
-      pool: 5
-      host: db1
-      username: root
-      password:
-      slave:
-        host: db1_slave
-      shards:
-        1:
-          host: db_shard1
-          database: my_app_shard
-          slave:
-            host: db_shard1_slave
-        2:
-          host: db_shard2
-          database: my_app_shard
-          slave:
-            host: db_shard2_slave
+Add the replica and shard configuration to config/database.yml:
+
+```yaml
+production:
+  adapter: mysql
+  encoding: utf8
+  database: my_app_main
+  pool: 5
+  host: db1
+  username: root
+  password:
+  replica:
+    host: db1_replica
+  shards:
+    1:
+      host: db_shard1
+      database: my_app_shard
+      replica:
+        host: db_shard1_replica
+    2:
+      host: db_shard2
+      database: my_app_shard
+      replica:
+        host: db_shard2_replica
+```
 
 basically connections inherit configuration from the parent configuration file.
 
+## Migrations
+
+ActiveRecord Shards also patches migrations to support running migrations on a shared (not sharded) or a sharded database.
+Each migration class has to specify a shard spec indicating where to run the migration.
+
+Valid shard specs:
+
+* `:none` - Run this migration on the shared database, not any shards
+* `:all` - Run this migration on all of the shards, not the shared database
+
+#### Example
+
+###### Create a table for the shared (not sharded) model
+
+```ruby
+class CreateAccounts < ActiveRecord::Migration
+  shard :none
+
+  def change
+    create_table :accounts do |t|
+      # This is NOT necessary for the gem to work, we just use it in the examples below demonstrating one way to switch shards
+      t.integer :shard_id, null: false
+
+      t.string :name
+    end
+  end
+end
+```
+
+###### Create a table for the sharded model
+
+```ruby
+class CreateProjects < ActiveRecord::Migration
+  shard :all
+
+  def change
+    create_table :projects do |t|
+      t.references :account
+      t.string :name
+    end
+  end
+end
+```
+
 ## Usage
 
 Normally you have some models that live on a shared database, and you might need to query this data in order to know what shard to switch to.
 All the models that live on the shared database must be marked as not\_sharded:
 
-    class Account < ActiveRecord::Base
-      not_sharded
+```ruby
+class Account < ActiveRecord::Base
+  not_sharded
 
-      has_many :projects
-    end
+  has_many :projects
+end
 
-    class Project < ActiveRecord::Base
-      belongs_to :account
-    end
+class Project < ActiveRecord::Base
+  belongs_to :account
+end
+```
 
 So in this setup the accounts live on the shared database, but the projects are sharded. If accounts have a shard\_id column, you could lookup the account
 in a rack middleware and switch to the right shard:
 
-    class AccountMiddleware
-      def initialize(app)
-        @app = app
-      end
-
-      def call(env)
-        account = lookup_account(env)
+```ruby
+class AccountMiddleware
+  def initialize(app)
+    @app = app
+  end
 
-        if account
-          ActiveRecord::Base.on_shard(account.shard_id) do
-            @app.call(env)
-          end
-        else
-          @app.call(env)
-        end
-      end
+  def call(env)
+    account = lookup_account(env)
 
-      def lookup_account(env)
-        ...
+    if account
+      ActiveRecord::Base.on_shard(account.shard_id) do
+        @app.call(env)
       end
+    else
+      @app.call(env)
     end
+  end
 
-You can switch to the slave databases at any point by wrapping your code in an on\_slave block:
+  def lookup_account(env)
+    # ...
+  end
+end
+```
 
-    ActiveRecord::Base.on_slave do
-      Account.find_by_big_expensive_query
-    end
+You can switch to the replica databases at any point by wrapping your code in an on\_replica block:
 
-This will perform the query on the slave, and mark the returned instances as read only. There is also a shortcut for this:
+```ruby
+ActiveRecord::Base.on_replica do
+  Account.find_by_big_expensive_query
+end
+```
+
+This will perform the query on the replica, and mark the returned instances as read only. There is also a shortcut for this:
 
-    Account.on_slave.find_by_big_expensive_query
+```ruby
+Account.on_replica.find_by_big_expensive_query
+```
 
 ## Debugging
 
-Show if a query went to master or slave in the logs:
+Show if a query went to primary or replica in the logs:
 
 ```Ruby
 require 'active_record_shards/sql_comments'

data/lib/active_record_shards/association_collection_connection_selection.rb

@@ -1,42 +1,49 @@
 # frozen_string_literal: true
+
 module ActiveRecordShards
   module AssociationCollectionConnectionSelection
-    def on_slave_if(condition)
-      condition ? on_slave : self
+    def on_replica_if(condition)
+      condition ? on_replica : self
     end
+    alias_method :on_slave_if, :on_replica_if
 
-    def on_slave_unless(condition)
-      on_slave_if(!condition)
+    def on_replica_unless(condition)
+      on_replica_if(!condition)
     end
+    alias_method :on_slave_unless, :on_replica_unless
 
-    def on_master_if(condition)
-      condition ? on_master : self
+    def on_primary_if(condition)
+      condition ? on_primary : self
     end
+    alias_method :on_master_if, :on_primary_if
 
-    def on_master_unless(condition)
-      on_master_if(!condition)
+    def on_primary_unless(condition)
+      on_primary_if(!condition)
     end
+    alias_method :on_master_unless, :on_primary_unless
 
-    def on_slave
-      MasterSlaveProxy.new(self, :slave)
+    def on_replica
+      PrimaryReplicaProxy.new(self, :replica)
     end
+    alias_method :on_slave, :on_replica
 
-    def on_master
-      MasterSlaveProxy.new(self, :master)
+    def on_primary
+      PrimaryReplicaProxy.new(self, :primary)
     end
+    alias_method :on_master, :on_primary
 
-    class MasterSlaveProxy
+    class PrimaryReplicaProxy
       def initialize(association_collection, which)
         @association_collection = association_collection
         @which = which
       end
 
-      def method_missing(method, *args, &block) # rubocop:disable Style/MethodMissing
-        # would love to not rely on version here, unfortunately @association_collection
-        # is a sensitive little bitch of an object.
+      def method_missing(method, *args, &block) # rubocop:disable Style/MethodMissingSuper, Style/MissingRespondToMissing
         reflection = @association_collection.proxy_association.reflection
         reflection.klass.on_cx_switch_block(@which) { @association_collection.send(method, *args, &block) }
       end
     end
+
+    MasterSlaveProxy = PrimaryReplicaProxy
   end
 end

data/lib/active_record_shards/configuration_parser.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require 'active_support/core_ext'
 
 module ActiveRecordShards
@@ -6,10 +7,15 @@ module ActiveRecordShards
     module_function
 
     def explode(conf)
-      conf = conf.deep_dup
+      conf = conf.to_h.deep_dup
 
       conf.to_a.each do |env_name, env_config|
         next unless shards = env_config.delete('shards')
+
+        unless shards.keys.all? { |shard_name| shard_name.is_a?(Integer) }
+          raise "All shard names must be integers: #{shards.keys.inspect}."
+        end
+
         env_config['shard_names'] = shards.keys
         shards.each do |shard_name, shard_conf|
           expand_child!(env_config, shard_conf)
@@ -18,10 +24,18 @@ module ActiveRecordShards
       end
 
       conf.to_a.each do |env_name, env_config|
-        if slave_conf = env_config.delete('slave')
-          expand_child!(env_config, slave_conf)
-          conf["#{env_name}_slave"] = slave_conf
+        if replica_conf = env_config.delete('replica')
+          expand_child!(env_config, replica_conf)
+          conf["#{env_name}_replica"] = replica_conf
+        end
+
+        # rubocop:disable Style/Next
+        if legacy_replica_conf = env_config.delete('slave')
+          ActiveRecordShards::Deprecation.warn('`slave` configuration keys should be replaced with `replica` keys!')
+          expand_child!(env_config, legacy_replica_conf)
+          conf["#{env_name}_replica"] = legacy_replica_conf
         end
+        # rubocop:enable Style/Next
       end
 
       conf
@@ -29,7 +43,7 @@ module ActiveRecordShards
 
     def expand_child!(parent, child)
       parent.each do |key, value|
-        unless ['slave', 'shards'].include?(key) || value.is_a?(Hash)
+        unless ['slave', 'replica', 'shards'].include?(key) || value.is_a?(Hash)
           child[key] ||= value
         end
       end

data/lib/active_record_shards/connection_handler.rb

@@ -1,13 +1,8 @@
 # frozen_string_literal: true
+
 ActiveRecord::ConnectionAdapters::ConnectionHandler.class_eval do
   remove_method :retrieve_connection_pool
-  if ActiveRecord::VERSION::MAJOR >= 4
-    def retrieve_connection_pool(klass)
-      class_to_pool[klass.connection_pool_name] ||= pool_for(klass)
-    end
-  else
-    def retrieve_connection_pool(klass)
-      (@class_to_pool || @connection_pools)[klass.connection_pool_name]
-    end
+  def retrieve_connection_pool(klass)
+    class_to_pool[klass.connection_pool_name] ||= pool_for(klass)
   end
 end

data/lib/active_record_shards/connection_pool.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module ActiveRecordShards
   ConnectionPoolNameDecorator = Struct.new(:name)
 

data/lib/active_record_shards/connection_specification.rb

@@ -1,16 +1,12 @@
 # frozen_string_literal: true
+
 class << ActiveRecord::Base
-  remove_method :establish_connection unless ActiveRecord::VERSION::MAJOR == 4
+  remove_method :establish_connection if ActiveRecord::VERSION::MAJOR >= 5
   def establish_connection(spec = ENV["DATABASE_URL"])
-    if ActiveRecord::VERSION::MAJOR >= 4
-      spec ||= ActiveRecord::ConnectionHandling::DEFAULT_ENV.call
-      spec = spec.to_sym if spec.is_a?(String)
-      resolver = ActiveRecordShards::ConnectionSpecification::Resolver.new configurations
-      spec = resolver.spec(spec)
-    else
-      resolver = ActiveRecordShards::ConnectionSpecification::Resolver.new spec, configurations
-      spec = resolver.spec
-    end
+    spec ||= ActiveRecord::ConnectionHandling::DEFAULT_ENV.call
+    spec = spec.to_sym if spec.is_a?(String)
+    resolver = ActiveRecordShards::ConnectionSpecification::Resolver.new configurations
+    spec = resolver.spec(spec)
 
     unless respond_to?(spec.adapter_method)
       raise AdapterNotFound, "database configuration specifies nonexistent #{spec.config[:adapter]} adapter"
@@ -18,11 +14,6 @@ class << ActiveRecord::Base
 
     remove_connection
     specification_cache[connection_pool_name] = spec
-
-    if ActiveRecord::VERSION::MAJOR >= 4
-      connection_handler.establish_connection self, spec
-    else
-      connection_handler.establish_connection connection_pool_name, spec
-    end
+    connection_handler.establish_connection self, spec
   end
 end

data/lib/active_record_shards/connection_switcher-4-2.rb

@@ -0,0 +1,56 @@
+module ActiveRecordShards
+  module ConnectionSwitcher
+    # Name of the connection pool. Used by ConnectionHandler to retrieve the current connection pool.
+    def connection_pool_name # :nodoc:
+      name = current_shard_selection.shard_name(self)
+
+      # e.g. if "production_replica" is not defined in `Configuration`, fall back to "production"
+      if configurations[name].nil? && on_replica?
+        current_shard_selection.shard_name(self, false)
+      else
+        name
+      end
+    end
+
+    private
+
+    def ensure_shard_connection
+      establish_shard_connection unless connected_to_shard?
+    end
+
+    def establish_shard_connection
+      name = connection_pool_name
+      spec = configurations[name]
+
+      if spec.nil?
+        raise ActiveRecord::AdapterNotSpecified, "No database defined by #{name} in your database config. (configurations: #{configurations.keys.inspect})"
+      end
+
+      specification_cache[name] ||= begin
+        resolver = ActiveRecordShards::ConnectionSpecification::Resolver.new configurations
+        resolver.spec(spec)
+      end
+
+      connection_handler.establish_connection(self, specification_cache[name])
+    end
+
+    def specification_cache
+      @@specification_cache ||= {}
+    end
+
+    # Helper method to clear global state when testing.
+    def clear_specification_cache
+      @@specification_cache = {}
+    end
+
+    def connection_pool_key
+      specification_cache[connection_pool_name]
+    end
+
+    def connected_to_shard?
+      specs_to_pools = Hash[connection_handler.connection_pool_list.map { |pool| [pool.spec, pool] }]
+
+      specs_to_pools.key?(connection_pool_key)
+    end
+  end
+end

data/lib/active_record_shards/connection_switcher-5-0.rb

@@ -4,7 +4,7 @@ module ActiveRecordShards
       name = current_shard_selection.resolve_connection_name(sharded: is_sharded?, configurations: configurations)
 
       unless configurations[name] || name == "primary"
-        raise ActiveRecord::AdapterNotSpecified, "No database defined by #{name} in database.yml"
+        raise ActiveRecord::AdapterNotSpecified, "No database defined by #{name} in your database config. (configurations: #{configurations.keys.inspect})"
       end
 
       name

data/lib/active_record_shards/connection_switcher-5-1.rb

@@ -4,7 +4,7 @@ module ActiveRecordShards
       name = current_shard_selection.resolve_connection_name(sharded: is_sharded?, configurations: configurations)
 
       unless configurations[name] || name == "primary"
-        raise ActiveRecord::AdapterNotSpecified, "No database defined by #{name} in database.yml"
+        raise ActiveRecord::AdapterNotSpecified, "No database defined by #{name} in your database config. (configurations: #{configurations.keys.inspect})"
       end
 
       name