makara 0.5.1 → 0.6.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fca781edcd318b4e4e598fbf7223d38ead88e124a3721258cb5452251a34ec92
-  data.tar.gz: 5b9d4fced7583800c371a34a011944a1beef844c61b83cb73ab8668f4d597d11
+  metadata.gz: a421cf24f6e652ac4b137d83325de56710ea14215971d958f6dc13726ec2898f
+  data.tar.gz: 297a249df8d86aa04b84173fd0de9943080fb59f293df959c8772937bb53997d
 SHA512:
-  metadata.gz: e9f4f963a2e577fb347913862f317c797521a2f32df73707b0e17b90b8cf25c76d8328dc9cbedefc16db0bc14a3a5bb144c931a534a9b40ccf5e8822338fd93c
-  data.tar.gz: b91fac6c7de164fe396b0a6ae2f30c743d89f093cda8e80d52664d95926ccf96f821d1574386618bb26b8e886f971c3df976b5ebb1153150bbc8b7f8052b402f
+  metadata.gz: c187bc3841763896882419eab2bac8cb3ba323a06353e2e7d522a25ded7de5f588a463bef270a361556b41aa53471523224d7c302a7f88fd4f4e1e91a77a6c07
+  data.tar.gz: ef575dec489cee7219eda6f767a4b23e9fcdb816f0b33927bba14fcdf31f17fd0b71a6eaed30845352e90e2000750886172d04cdf273d358e1df95318f0a7e82

data/.github/workflows/CI.yml

@@ -29,10 +29,6 @@ jobs:
             ruby: '3.0'
           - activerecord: '5.2'
             ruby: head
-          - activerecord: head
-            ruby: '2.5'
-          - activerecord: head
-            ruby: '2.6'
     continue-on-error: ${{ matrix.ruby == 'jruby' || matrix.ruby == 'head' || matrix.activerecord == 'head' }}
     name: Ruby ${{ matrix.ruby }} / ActiveRecord ${{ matrix.activerecord }}
     services:

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2021-01-19 22:10:17 UTC using RuboCop version 1.8.1.
+# on 2021-01-20 22:15:06 UTC using RuboCop version 1.8.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -71,7 +71,7 @@ Layout/FirstHashElementIndentation:
     - 'lib/makara/config_parser.rb'
     - 'spec/strategies/shard_aware_spec.rb'
 
-# Offense count: 4
+# Offense count: 10
 # Cop supports --auto-correct.
 # Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
 # SupportedHashRocketStyles: key, separator, table
@@ -243,7 +243,7 @@ Lint/UnusedBlockArgument:
   Exclude:
     - 'lib/makara/strategies/priority_failover.rb'
 
-# Offense count: 28
+# Offense count: 25
 # Cop supports --auto-correct.
 # Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods.
 Lint/UnusedMethodArgument:
@@ -283,7 +283,7 @@ Metrics/BlockNesting:
 # Offense count: 4
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 240
+  Max: 253
 
 # Offense count: 3
 # Configuration parameters: IgnoredMethods.
@@ -514,7 +514,7 @@ Style/NumericPredicate:
     - 'lib/makara/context.rb'
     - 'lib/makara/proxy.rb'
 
-# Offense count: 2
+# Offense count: 3
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?
 Style/OptionalBooleanParameter:
@@ -662,7 +662,7 @@ Style/TrivialAccessors:
 Style/WordArray:
   EnforcedStyle: brackets
 
-# Offense count: 25
+# Offense count: 27
 # Cop supports --auto-correct.
 # Configuration parameters: AutoCorrect, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
 # URISchemes: http, https

data/CHANGELOG.md

@@ -3,9 +3,11 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
-### v0.5.1 - 2021-06-04
+## v0.6.0.pre - 2021-01-08
 [Full Changelog](https://github.com/instacart/makara/compare/v0.5.0...v0.6.0.pre)
 - Use ActiveRecord URL resolver instead of copying definition [#294](https://github.com/instacart/makara/pull/294) Matt Larraz
+- Deprecated the term `master` in favor of `primary` [#290](https://github.com/instacart/makara/pull/290) Matt Larraz
+- Deprecated the term `slave` in favor of `replica` [#286](https://github.com/instacart/makara/pull/286) Matt Larraz
 - Fix Ruby 2.7 kwarg warning and add Ruby 3 support [#283](https://github.com/instacart/makara/pull/283) Matt Larraz
 - Drop support for Ruby < 2.5 and ActiveRecord < 5.2 [#281](https://github.com/instacart/makara/pull/281) Matt Larraz
 

data/README.md

@@ -5,7 +5,7 @@
 [![Code Climate](https://codeclimate.com/repos/526886a7f3ea00679b00cae6/badges/7905f7a000492a1078f7/gpa.png)](https://codeclimate.com/repos/526886a7f3ea00679b00cae6/feed)
 
 
-Makara is generic master/slave proxy. It handles the heavy lifting of managing, choosing, blacklisting, and cycling through connections. It comes with an ActiveRecord database adapter implementation.
+Makara is generic primary/replica proxy. It handles the heavy lifting of managing, choosing, blacklisting, and cycling through connections. It comes with an ActiveRecord database adapter implementation.
 
 ## Installation
 
@@ -37,18 +37,18 @@ Next, you need to decide which methods are proxied and which methods should be s
   send_to_all :connect, :reconnect, :disconnect, :clear_cache
 ```
 
-Assuming you don't need to split requests between a master and a slave, you're done. If you do need to, implement the `needs_master?` method:
+Assuming you don't need to split requests between a primary and a replica, you're done. If you do need to, implement the `needs_primary?` method:
 
 ```ruby
   # within MyAwesomeSqlProxy
-  def needs_master?(method_name, args)
+  def needs_primary?(method_name, args)
     return false if args.empty?
     sql = args.first
     sql !~ /^select/i
   end
 ```
 
-This implementation will send any request not like "SELECT..." to a master connection. There are more methods you can override and more control over blacklisting - check out the [makara database adapter](lib/active_record/connection_adapters/makara_abstract_adapter.rb) for examples of advanced usage.
+This implementation will send any request not like "SELECT..." to a primary connection. There are more methods you can override and more control over blacklisting - check out the [makara database adapter](lib/active_record/connection_adapters/makara_abstract_adapter.rb) for examples of advanced usage.
 
 ### Config Parsing
 
@@ -58,13 +58,13 @@ Makara comes with a config parser which will handle providing subconfigs to the
 
 Makara handles stickiness by keeping track of which proxies are stuck at any given moment. The context is basically a mapping of proxy ids to the timestamp until which they are stuck.
 
-To handle persistence of context across requests in a Rack app, makara provides a middleware. It lays a cookie named `_mkra_stck` which contains the current context. If the next request is executed before the cookie expires, that given context will be used. If something occurs which naturally requires master on the second request, the context is updated and stored again.
+To handle persistence of context across requests in a Rack app, makara provides a middleware. It lays a cookie named `_mkra_stck` which contains the current context. If the next request is executed before the cookie expires, that given context will be used. If something occurs which naturally requires the primary on the second request, the context is updated and stored again.
 
 #### Stickiness Impact
 
-When `sticky:true`, once a query as been sent to master, all queries for the rest of the request will also be sent to master.  In addition, the cookie described above will be set client side with an expiration defined by time at end of original request + `master_ttl`.  As long as the cookie is valid, all requests will send queries to master.
+When `sticky:true`, once a query as been sent to the primary, all queries for the rest of the request will also be sent to the primary.  In addition, the cookie described above will be set client side with an expiration defined by time at end of original request + `primary_ttl`.  As long as the cookie is valid, all requests will send queries to primary.
 
-When `sticky:false`, only queries that need to go to master will go there.  Subsequent read queries in the same request will go to slaves.
+When `sticky:false`, only queries that need to go to the primary will go there.  Subsequent read queries in the same request will go to replicas.
 
 #### Releasing stuck connections (clearing context)
 
@@ -82,28 +82,28 @@ Makara::Context.release('redis')
 ...
 ```
 
-A context is local to the curent thread of execution. This will allow you to stick to master safely in a single thread
+A context is local to the curent thread of execution. This will allow you to stick to the primary safely in a single thread
 in systems such as sidekiq, for instance.
 
 
-#### Forcing Master
+#### Forcing Primary
 
-If you need to force master in your app then you can simply invoke stick_to_master! on your connection:
+If you need to force the primary in your app then you can simply invoke stick_to_primary! on your connection:
 
 ```ruby
 persist = true # or false, it's true by default
-proxy.stick_to_master!(persist)
+proxy.stick_to_primary!(persist)
 ```
 
-It'll keep the proxy stuck to master for the current request, and if `persist = true` (default), it'll be also stored in the context for subsequent requests, keeping the proxy stuck up to the duration of `master_ttl` configured for the proxy.
+It'll keep the proxy stuck to the primary for the current request, and if `persist = true` (default), it'll be also stored in the context for subsequent requests, keeping the proxy stuck up to the duration of `primary_ttl` configured for the proxy.
 
 #### Skipping the Stickiness
 
-If you're using the `sticky: true` configuration and you find yourself in a situation where you need to write information through the proxy but you don't want the context to be stuck to master, you should use a `without_sticking` block:
+If you're using the `sticky: true` configuration and you find yourself in a situation where you need to write information through the proxy but you don't want the context to be stuck to the primary, you should use a `without_sticking` block:
 
 ```ruby
 proxy.without_sticking do
-  # do my stuff that would normally cause the proxy to stick to master
+  # do my stuff that would normally cause the proxy to stick to the primary
 end
 ```
 
@@ -117,23 +117,23 @@ Makara::Logging::Logger.logger = ::Logger.new(STDOUT)
 
 ## ActiveRecord Database Adapter
 
-So you've found yourself with an ActiveRecord-based project which is starting to get some traffic and you realize 95% of you DB load is from reads. Well you've come to the right spot. Makara is a great solution to break up that load not only between master and slave but potentially multiple masters and/or multiple slaves.
+So you've found yourself with an ActiveRecord-based project which is starting to get some traffic and you realize 95% of you DB load is from reads. Well you've come to the right spot. Makara is a great solution to break up that load not only between primary and replica but potentially multiple primaries and/or multiple replicas.
 
 By creating a makara database adapter which simply acts as a proxy we avoid any major complexity surrounding specific database implementations. The makara adapter doesn't care if the underlying connection is mysql, postgresql, etc it simply cares about the sql string being executed.
 
 ### What goes where?
 
-In general: Any `SELECT` statements will execute against your slave(s), anything else will go to master.
+In general: Any `SELECT` statements will execute against your replica(s), anything else will go to the primary.
 
 There are some edge cases:
 * `SET` operations will be sent to all connections
 * Execution of specific methods such as `connect!`, `disconnect!`, and `clear_cache!` are invoked on all underlying connections
-* Calls inside a transaction will always be sent to the master (otherwise changes from within the transaction could not be read back on most transaction isolation levels)
-* Locking reads (e.g. `SELECT ... FOR UPDATE`) will always be sent to the master
+* Calls inside a transaction will always be sent to the primary (otherwise changes from within the transaction could not be read back on most transaction isolation levels)
+* Locking reads (e.g. `SELECT ... FOR UPDATE`) will always be sent to the primary
 
 ### Errors / blacklisting
 
-Whenever a node fails an operation due to a connection issue, it is blacklisted for the amount of time specified in your database.yml. After that amount of time has passed, the connection will begin receiving queries again. If all slave nodes are blacklisted, the master connection will begin receiving read queries as if it were a slave. Once all nodes are blacklisted the error is raised to the application and all nodes are whitelisted.
+Whenever a node fails an operation due to a connection issue, it is blacklisted for the amount of time specified in your database.yml. After that amount of time has passed, the connection will begin receiving queries again. If all replica nodes are blacklisted, the primary connection will begin receiving read queries as if it were a replica. Once all nodes are blacklisted the error is raised to the application and all nodes are whitelisted.
 
 ### Database.yml
 
@@ -152,19 +152,19 @@ production:
     id: mysql
     # the following are default values
     blacklist_duration: 5
-    master_ttl: 5
-    master_strategy: round_robin
+    primary_ttl: 5
+    primary_strategy: round_robin
     sticky: true
 
     # list your connections with the override values (they're merged into the top-level config)
-    # be sure to provide the role if master, role is assumed to be a slave if not provided
+    # be sure to provide the role if primary, role is assumed to be a replica if not provided
     connections:
-      - role: master
-        host: master.sql.host
-      - role: slave
-        host: slave1.sql.host
-      - role: slave
-        host: slave2.sql.host
+      - role: primary
+        host: primary.sql.host
+      - role: replica
+        host: replica1.sql.host
+      - role: replica
+        host: replica2.sql.host
 ```
 
 Let's break this down a little bit. At the top level of your config you have the standard `adapter` choice. Currently the available adapters are listed in [lib/active_record/connection_adapters/](lib/active_record/connection_adapters/). They are in the form of `#{db_type}_makara` where db_type is mysql, postgresql, etc.
@@ -174,31 +174,31 @@ Following the adapter choice is all the standard configurations (host, port, ret
 The makara subconfig sets up the proxy with a few of its own options, then provides the connection list. The makara options are:
 * id - an identifier for the proxy, used for sticky behaviour and context. The default is to use a MD5 hash of the configuration contents, so if you are setting `sticky` to true, it's a good idea to also set an `id`. Otherwise any stuck connections will be cleared if the configuration changes (as the default MD5 hash id would change as well)
 * blacklist_duration - the number of seconds a node is blacklisted when a connection failure occurs
-* disable_blacklist - do not blacklist node at any error, useful in case of one master
+* disable_blacklist - do not blacklist node at any error, useful in case of one primary
 * sticky - if a node should be stuck to once it's used during a specific context
-* master_ttl - how long the master context is persisted. generally, this needs to be longer than any replication lag
-* master_strategy - use a different strategy for picking the "current" master node: `failover` will try to keep the same one until it is blacklisted. The default is `round_robin` which will cycle through available ones.
-* slave_strategy - use a different strategy for picking the "current" slave node: `failover` will try to keep the same one until it is blacklisted. The default is `round_robin` which will cycle through available ones.
+* primary_ttl - how long the primary context is persisted. generally, this needs to be longer than any replication lag
+* primary_strategy - use a different strategy for picking the "current" primary node: `failover` will try to keep the same one until it is blacklisted. The default is `round_robin` which will cycle through available ones.
+* replica_strategy - use a different strategy for picking the "current" replica node: `failover` will try to keep the same one until it is blacklisted. The default is `round_robin` which will cycle through available ones.
 * connection_error_matchers - array of custom error matchers you want to be handled gracefully by Makara (as in, errors matching these regexes will result in blacklisting the connection as opposed to raising directly).
 
-Connection definitions contain any extra node-specific configurations. If the node should behave as a master you must provide `role: master`. Any previous configurations can be overridden within a specific node's config. Nodes can also contain weights if you'd like to balance usage based on hardware specifications. Optionally, you can provide a name attribute which will be used in sql logging.
+Connection definitions contain any extra node-specific configurations. If the node should behave as a primary you must provide `role: primary`. Any previous configurations can be overridden within a specific node's config. Nodes can also contain weights if you'd like to balance usage based on hardware specifications. Optionally, you can provide a name attribute which will be used in sql logging.
 
 ```yml
 connections:
-  - role: master
-    host: mymaster.sql.host
+  - role: primary
+    host: myprimary.sql.host
     blacklist_duration: 0
 
-  # implicit role: slave
-  - host: mybigslave.sql.host
+  # implicit role: replica
+  - host: mybigreplica.sql.host
     weight: 8
-    name: Big Slave
-  - host: mysmallslave.sql.host
+    name: Big Replica
+  - host: mysmallreplica.sql.host
     weight: 2
-    name: Small Slave
+    name: Small Replica
 ```
 
-In the previous config the "Big Slave" would receive ~80% of traffic.
+In the previous config the "Big Replica" would receive ~80% of traffic.
 
 #### DATABASE_URL
 
@@ -206,7 +206,7 @@ Connections may specify a `url` parameter in place of host, username, password,
 
 ```yml
 connections:
-  - role: master
+  - role: primary
     blacklist_duration: 0
     url: 'mysql2://db_username:db_password@localhost:3306/db_name'
 ```
@@ -215,11 +215,11 @@ We recommend, if using environmental variables, to interpolate them via ERb.
 
 ```yml
 connections:
-  - role: master
+  - role: primary
     blacklist_duration: 0
-    url: <%= ENV['DATABASE_URL_MASTER'] %>
-  - role: slave
-    url: <%= ENV['DATABASE_URL_SLAVE'] %>
+    url: <%= ENV['DATABASE_URL_PRIMARY'] %>
+  - role: replica
+    url: <%= ENV['DATABASE_URL_REPLICA'] %>
 ```
 
 **Important**: *Do NOT use `ENV['DATABASE_URL']`*, as it inteferes with the the database configuration
@@ -244,7 +244,7 @@ For more information on url parsing, as used in
   - ActiveRecord::ConnectionHandling::MergeAndResolveDefaultUrlConfig.new(url_config).resolve
 - 4.2
  [ActiveRecord::ConnectionAdapters::ConnectionSpecification::ConnectionUrlResolver.new(url).to_hash](https://github.com/rails/rails/blob/4-2-stable/activerecord/lib/active_record/connection_handling.rb#L60-L81)
-- master
+- primary
  [ActiveRecord::ConnectionAdapters::ConnectionSpecification::ConnectionUrlResolver.new(url).to_hash](https://github.com/rails/rails/blob/97b980b4e61aea3cee429bdee4b2eae2329905cd/activerecord/lib/active_record/connection_handling.rb#L60-L81)
 
 
@@ -269,15 +269,15 @@ You can provide strings or regexes.  In the case of strings, if they start with
 
 ## Common Problems / Solutions
 
-On occasion your app may deal with a situation where makara is not present during a write but a read should use master. In the generic proxy details above you are encouraged to use `stick_to_master!` to accomplish this. Here's an example:
+On occasion your app may deal with a situation where makara is not present during a write but a read should use primary. In the generic proxy details above you are encouraged to use `stick_to_primary!` to accomplish this. Here's an example:
 
 ```ruby
-# some third party creates a resource in your db, slave replication may not have completed yet
+# some third party creates a resource in your db, replication may not have completed yet
 # ...
 # then your app is told to read the resource.
 def handle_request_after_third_party_record_creation
-  CreatedResourceClass.connection.stick_to_master!
-  CreatedResourceClass.find(params[:id]) # will go to master
+  CreatedResourceClass.connection.stick_to_primary!
+  CreatedResourceClass.find(params[:id]) # will go to the primary
 end
 ```
 

data/lib/active_record/connection_adapters/makara_abstract_adapter.rb

@@ -95,17 +95,32 @@ module ActiveRecord
       control_method :close, :steal!, :expire, :lease, :in_use?, :owner, :schema_cache, :pool=, :pool,
          :schema_cache=, :lock, :seconds_idle, :==
 
-      SQL_MASTER_MATCHERS           = [/\A\s*select.+for update\Z/i, /select.+lock in share mode\Z/i, /\A\s*select.+(nextval|currval|lastval|get_lock|release_lock|pg_advisory_lock|pg_advisory_unlock)\(/i].map(&:freeze).freeze
-      SQL_SLAVE_MATCHERS            = [/\A\s*(select|with.+\)\s*select)\s/i].map(&:freeze).freeze
+      SQL_PRIMARY_MATCHERS          = [/\A\s*select.+for update\Z/i, /select.+lock in share mode\Z/i, /\A\s*select.+(nextval|currval|lastval|get_lock|release_lock|pg_advisory_lock|pg_advisory_unlock)\(/i].map(&:freeze).freeze
+      SQL_REPLICA_MATCHERS          = [/\A\s*(select|with.+\)\s*select)\s/i].map(&:freeze).freeze
       SQL_ALL_MATCHERS              = [/\A\s*set\s/i].map(&:freeze).freeze
       SQL_SKIP_STICKINESS_MATCHERS  = [/\A\s*show\s([\w]+\s)?(field|table|database|schema|view|index)(es|s)?/i, /\A\s*(set|describe|explain|pragma)\s/i].map(&:freeze).freeze
 
+      SQL_MASTER_MATCHERS = SQL_PRIMARY_MATCHERS
+      deprecate_constant :SQL_MASTER_MATCHERS
+      SQL_SLAVE_MATCHERS = SQL_REPLICA_MATCHERS
+      deprecate_constant :SQL_SLAVE_MATCHERS
+
+      def sql_primary_matchers
+        SQL_PRIMARY_MATCHERS
+      end
+
       def sql_master_matchers
-        SQL_MASTER_MATCHERS
+        warn "#{self.class}#sql_master_matchers is deprecated. Use #sql_primary_matchers"
+        sql_primary_matchers
+      end
+
+      def sql_replica_matchers
+        SQL_REPLICA_MATCHERS
       end
 
       def sql_slave_matchers
-        SQL_SLAVE_MATCHERS
+        warn "#{self.class}#sql_slave_matchers is deprecated. Use #sql_replica_matchers"
+        sql_replica_matchers
       end
 
       def sql_all_matchers
@@ -126,21 +141,17 @@ module ActiveRecord
 
       def appropriate_connection(method_name, args, &block)
         if needed_by_all?(method_name, args)
-
           handling_an_all_execution(method_name) do
             hijacked do
-              # slave pool must run first.
-              @slave_pool.send_to_all(nil, &block)  # just yields to each con
-              @master_pool.send_to_all(nil, &block) # just yields to each con
+              # replica pool must run first.
+              @replica_pool.send_to_all(nil, &block) # just yields to each con
+              @primary_pool.send_to_all(nil, &block) # just yields to each con
             end
           end
-
         else
-
           super(method_name, args) do |con|
             yield con
           end
-
         end
       end
 
@@ -158,12 +169,17 @@ module ActiveRecord
         false
       end
 
-      def needs_master?(method_name, args)
-        sql = coerce_query_to_sql_string(args.first)
-        return true if sql_master_matchers.any?{|m| sql =~ m }
-        return false if sql_slave_matchers.any?{|m| sql =~ m }
+      def needs_primary?(method_name, args)
+        if respond_to?(:needs_master?)
+          warn "#{self.class}#needs_master? is deprecated. Switch to #needs_primary?"
+          needs_master?(method_name, args)
+        else
+          sql = coerce_query_to_sql_string(args.first)
+          return true if sql_primary_matchers.any?{|m| sql =~ m }
+          return false if sql_replica_matchers.any?{|m| sql =~ m }
 
-        true
+          true
+        end
       end
 
       def coerce_query_to_sql_string(sql_or_arel)

data/lib/makara/config_parser.rb

@@ -10,114 +10,39 @@ require 'cgi'
 #   top_level: 'variable'
 #   another: 'top level variable'
 #   makara:
-#     master_ttl: 3
+#     primary_ttl: 3
 #     blacklist_duration: 20
 #     connections:
-#       - role: 'master'
-#       - role: 'slave'
-#       - role: 'slave'
-#         name: 'slave2'
+#       - role: 'master' # Deprecated in favor of 'primary'
+#       - role: 'primary'
+#       - role: 'slave' # Deprecated in favor of 'replica'
+#       - role: 'replica'
+#         name: 'replica2'
 
 module Makara
   class ConfigParser
     DEFAULTS = {
-      master_ttl: 5,
+      primary_ttl: 5,
       blacklist_duration: 30,
       sticky: true
     }
 
-    # ConnectionUrlResolver is borrowed from Rails 4-2 since its location and implementation
-    # vary slightly among Rails versions, but the behavior is the same.  Thus, borrowing the
-    # class should be the most future-safe way to parse a database url.
-    #
-    # Expands a connection string into a hash.
-    class ConnectionUrlResolver # :nodoc:
-      # == Example
-      #
-      #   url = "postgresql://foo:bar@localhost:9000/foo_test?pool=5&timeout=3000"
-      #   ConnectionUrlResolver.new(url).to_hash
-      #   # => {
-      #     "adapter"  => "postgresql",
-      #     "host"     => "localhost",
-      #     "port"     => 9000,
-      #     "database" => "foo_test",
-      #     "username" => "foo",
-      #     "password" => "bar",
-      #     "pool"     => "5",
-      #     "timeout"  => "3000"
-      #   }
-      def initialize(url)
-        raise "Database URL cannot be empty" if url.blank?
-
-        @uri     = URI.parse(url)
-        @adapter = @uri.scheme.tr('-', '_')
-        @adapter = "postgresql" if @adapter == "postgres"
-
-        if @uri.opaque
-          @uri.opaque, @query = @uri.opaque.split('?', 2)
-        else
-          @query = @uri.query
-        end
-      end
-
-      # Converts the given URL to a full connection hash.
-      def to_hash
-        config = raw_config.reject { |_,value| value.blank? }
-        config.map { |key,value| config[key] = CGI.unescape(value) if value.is_a? String }
-        config
-      end
-
-      private
-
-      def uri
-        @uri
-      end
-
-      # Converts the query parameters of the URI into a hash.
-      #
-      #   "localhost?pool=5&reaping_frequency=2"
-      #   # => { "pool" => "5", "reaping_frequency" => "2" }
-      #
-      # returns empty hash if no query present.
-      #
-      #   "localhost"
-      #   # => {}
-      def query_hash
-        Hash[(@query || '').split("&").map { |pair| pair.split("=") }]
-      end
-
-      def raw_config
-        if uri.opaque
-          query_hash.merge({
-            "adapter"  => @adapter,
-            "database" => uri.opaque })
-        else
-          query_hash.merge({
-            "adapter"  => @adapter,
-            "username" => uri.user,
-            "password" => uri.password,
-            "port"     => uri.port,
-            "database" => database_from_path,
-            "host"     => uri.host })
-        end
-      end
-
-      # Returns name of the database.
-      def database_from_path
-        if @adapter == 'sqlite3'
-          # 'sqlite3:/foo' is absolute, because that makes sense. The
-          # corresponding relative version, 'sqlite3:foo', is handled
-          # elsewhere, as an "opaque".
-
-          uri.path
-        else
-          # Only SQLite uses a filename as the "database" name; for
-          # anything else, a leading slash would be silly.
-
-          uri.path.sub(%r{^/}, "")
-        end
+    DEPRECATED_KEYS = {
+      slave_strategy:       :replica_strategy,
+      slave_shard_aware:    :replica_shard_aware,
+      slave_default_shard:  :replica_default_shard,
+      master_strategy:      :primary_strategy,
+      master_shard_aware:   :primary_shard_aware,
+      master_default_shard: :primary_default_shard,
+      master_ttl:           :primary_ttl
+    }.freeze
+
+    ConnectionUrlResolver =
+      if ::ActiveRecord::VERSION::STRING >= "6.1.0"
+        ::ActiveRecord::DatabaseConfigurations::ConnectionUrlResolver
+      else
+        ::ActiveRecord::ConnectionAdapters::ConnectionSpecification::ConnectionUrlResolver
       end
-    end
 
     # NOTE: url format must be, e.g.
     # url: mysql2://...
@@ -145,6 +70,9 @@ module Makara
       @config = config.symbolize_keys
       @makara_config = DEFAULTS.merge(@config[:makara] || {})
       @makara_config = @makara_config.symbolize_keys
+
+      replace_deprecated_keys!
+
       @id = sanitize_id(@makara_config[:id])
     end
 
@@ -155,24 +83,45 @@ module Makara
       end
     end
 
-    def master_configs
+    def primary_configs
       all_configs
-        .select { |config| config[:role] == 'master' }
+        .select { |config| config[:role] == 'primary' }
         .map { |config| config.except(:role) }
     end
 
-    def slave_configs
+    def master_configs
+      warn "#{self.class}#master_configs is deprecated. Switch to #primary_configs"
+      primary_configs
+    end
+
+    def replica_configs
       all_configs
-        .reject { |config| config[:role] == 'master' }
+        .reject { |config| config[:role] == 'primary' }
         .map { |config| config.except(:role) }
     end
 
+    def slave_configs
+      warn "#{self.class}#slave_configs is deprecated. Switch to #replica_configs"
+      replica_configs
+    end
+
     protected
 
     def all_configs
-      @makara_config[:connections].map do |connection|
-        base_config.merge(makara_config.except(:connections))
-                   .merge(connection.symbolize_keys)
+      @all_configs ||= @makara_config[:connections].map do |connection|
+        config = base_config.merge(makara_config.except(:connections)).merge(connection.symbolize_keys)
+
+        if config[:role] == "master"
+          warn "Makara role 'master' is deprecated. Use 'primary' instead"
+          config[:role] = "primary"
+        end
+
+        if config[:role] == "slave"
+          warn "Makara role 'slave' is deprecated. Use 'replica' instead"
+          config[:role] = "primary"
+        end
+
+        config
       end
     end
 
@@ -199,5 +148,15 @@ module Makara
         end
       end
     end
+
+    def replace_deprecated_keys!
+      DEPRECATED_KEYS.each do |key, replacement|
+        next unless @makara_config[key]
+
+        warn "Makara config key #{key.inspect} is deprecated, use #{replacement.inspect} instead"
+
+        @makara_config[replacement] = @makara_config.delete(key)
+      end
+    end
   end
 end