active_record_proxy_adapters 0.1.0.rc2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a84998cef36e3e7ba5c4e69909a41db4641a22aaa2b589988fe38f74abefa600
+  data.tar.gz: e0ab2ac9b05420d952c89f7259c6d3539eadf7b44fd791bb178dc28e91066b30
+SHA512:
+  metadata.gz: 39d6c4508378596812e6dbdf523e05ff662b279ace17f6ec0ec2db24171645374e9447fe5aff6e6a9f9f2bfb227fce4a0dddc6deebe016b2d2a1f62234f198f9
+  data.tar.gz: 8b423c0d1464157eff63c0c161481acb2a2ba55e95f9337c4a27819c1acbfe41ccf83e7e59bdb98cea1e80419159b475060a166336251c59759d4298fe0c502f

data/.rspec

@@ -0,0 +1,4 @@
+--format documentation
+--color
+--order random
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,20 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+RSpec/NestedGroups:
+  Enabled: true
+  Max: 5
+
+# TODO: Enable MFA once we open source the gem
+Gemspec/RequireMFA:
+  Enabled: false 

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [0.1.0.rc2] - 2024-10-28
+
+- Add PostgreSQLProxyAdapter
+
+## [Unreleased]

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/Dockerfile

@@ -0,0 +1,18 @@
+ARG RUBY_VERSION=3.2.3
+ARG DOCKER_REGISTRY=docker.io
+FROM $DOCKER_REGISTRY/ruby:$RUBY_VERSION-alpine
+ARG RAILS_VERSION="~> 6.1.0"
+ENV RAILS_VERSION=$RAILS_VERSION
+
+RUN apk --update add \
+    build-base \
+    git \
+    postgresql-dev \
+    postgresql-client
+RUN gem install bundler -v 2.5.13
+
+COPY . /app
+WORKDIR /app
+
+RUN bundle install
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Nasdaq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,114 @@
+# ActiveRecordProxyAdapters
+
+A set of ActiveRecord adapters that leverage Rails native multiple database setup to allow automatic connection switching from _one_ primary pool to _one_ replica pool at the database statement level.
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add 'UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG'
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+
+## Usage
+
+### On Rails
+
+In `config/database.yml`, use `postgresql_proxy` as the adapter for the `primary` database, and keep `postgresql` for the replica database.
+
+```yaml
+# config/database.yml
+development:
+  primary:
+    adapter: postgresql_proxy
+    # your primary credentials here
+
+  primary_replica:
+    adapter: postgresql
+    replica: true
+    # your replica credentials here
+```
+
+### Off Rails
+
+```ruby
+# In your application setup
+require "active_record_proxy_adapters"
+
+ActiveSupport.on_load :active_record do
+  require "active_record_proxy_adapters/connection_handling"
+  ActiveRecord::Base.extend(ActiveRecordProxyAdapters::ConnectionHandling)
+end
+
+# in your base model
+class ApplicationRecord << ActiveRecord::Base
+    establish_connection(
+        {
+            adapter: 'postgresql_proxy',
+            # your primary credentials here
+        },
+        role: :writing
+    )
+
+    establish_connection(
+        {
+            adapter: 'postgresql',
+            # your replica credentials here
+        },
+        role: :reading
+    )
+end
+```
+
+### Configuration
+
+The gem comes preconfigured out of the box. However, if default configuration does not suit your needs, you can modify them by using a `.configure` block:
+
+```ruby
+# config/initializers/active_record_proxy_adapters.rb
+ActiveRecordProxyAdapters.configure do |config|
+  # How long proxy should reroute all read requests to primary after a write
+  config.proxy_delay = 5.seconds # defaults to 2.seconds
+
+  # How long proxy should wait for replica to connect.
+  config.checkout_timeout = 5.seconds # defaults to 2.seconds
+end
+```
+
+### How it works
+
+The proxy will analyze each SQL string, using pattern matching, to decide the appropriate connection for it (i.e. if it should go to the primary or replica).
+
+- All queries inside a transaction go to the primary
+- All `SET` queries go to all connections
+- All `INSERT`, `UPDATE` and `DELETE` queries go to the primary
+- All `SELECT FOR UPDATE` queries go to the primary
+- All `lock` queries (e.g `get_lock`) go the primary
+- All sequence methods (e.g `nextval`) go the primary
+- Everything else goes to the replica
+
+#### TL;DR
+
+All `SELECT` queries go to the _replica_, everything else goes to _primary_.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nasdaq/active_record_proxy_adapters. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/nasdaq/active_record_proxy_adapters/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the ActiveRecordProxyAdapters project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/nasdaq/active_record_proxy_adapters/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docker-compose.yml

@@ -0,0 +1,77 @@
+name: active_record_proxy_adapters
+
+x-postgres-common: &postgres-common
+  restart: always
+  user: postgres
+  healthcheck:
+    test: 'pg_isready -U postgres_primary_test --dbname=postgres'
+    interval: 10s
+    timeout: 5s
+    retries: 5
+  networks:
+    - postgres
+
+services:
+  app:
+    build:
+      args:
+        - RUBY_VERSION=${RUBY_VERSION:-3.2.3}
+        - RAILS_VERSION=${RAILS_VERSION:-~> 6.1.0}
+    container_name: app
+    image: active_record_proxy_adapters-app:${ENV_TAG:-latest}
+    tty: true
+    stdin_open: true
+    environment:
+      PGHOST: postgres_primary
+      PG_PRIMARY_USER: postgres_primary_test
+      PG_PRIMARY_PASSWORD: postgres_primary_test
+      PG_PRIMARY_HOST: postgres_primary
+      PG_PRIMARY_PORT: 5432
+      PG_REPLICA_USER: postgres_primary_test
+      PG_REPLICA_PASSWORD: postgres_primary_test
+      PG_REPLICA_HOST: postgres_replica
+      PG_REPLICA_PORT: 5432
+    depends_on:
+      - postgres_primary
+      - postgres_replica
+    networks:
+      - app
+      - postgres
+    volumes:
+      - .:/app
+  postgres_primary:
+    <<: *postgres-common
+    build:
+      context: .
+      dockerfile: postgres_primary.dockerfile
+      args:
+        - POSTGRES_LOGGING_COLLECTOR=${POSTGRES_LOGGING_COLLECTOR:-}
+        - POSTGRES_LOG_DESTINATION=${POSTGRES_LOG_DESTINATION:-}
+        - POSTGRES_LOG_STATEMENT=${POSTGRES_LOG_STATEMENT:-}
+        - REPLICA_USER=replicator
+        - REPLICA_PASSWORD=replicator
+    environment:
+      POSTGRES_DB: postgres
+      POSTGRES_USER: postgres_primary_test
+      POSTGRES_PASSWORD: postgres_primary_test
+      POSTGRES_HOST_AUTH_METHOD: "scram-sha-256\nhost replication all 0.0.0.0/0 md5"
+      POSTGRES_INITDB_ARGS: "--auth-host=scram-sha-256"
+
+  postgres_replica:
+    <<: *postgres-common
+    build:
+      context: .
+      dockerfile: postgres_replica.dockerfile
+    container_name: postgres_replica
+    environment:
+      PGUSER: replicator
+      PGPASSWORD: replicator
+      PRIMARY_DATABASE_HOST: postgres_primary
+    depends_on:
+      - postgres_primary
+networks:
+  app:
+  postgres:
+
+volumes:
+  postgres_primary:

data/lib/active_record/connection_adapters/postgresql_proxy_adapter.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "active_record/tasks/postgresql_proxy_database_tasks"
+require "active_record/connection_adapters/postgresql_adapter"
+require "active_record_proxy_adapters/postgresql_proxy"
+require "active_record_proxy_adapters/hijackable"
+
+module ActiveRecord
+  module ConnectionAdapters
+    # This adapter is a proxy to the original PostgreSQLAdapter, allowing the use of the
+    # ActiveRecordProxyAdapters::PrimaryReplicaProxy.
+    class PostgreSQLProxyAdapter < PostgreSQLAdapter
+      include ActiveRecordProxyAdapters::Hijackable
+
+      ADAPTER_NAME = "PostgreSQLProxy"
+
+      delegate_to_proxy :execute, :exec_query, :exec_no_cache, :exec_cache
+
+      def initialize(...)
+        @proxy = ActiveRecordProxyAdapters::PostgreSQLProxy.new(self)
+
+        super
+      end
+
+      private
+
+      attr_reader :proxy
+    end
+  end
+end
+
+if ActiveRecordProxyAdapters::ActiveRecordContext.active_record_v7_2?
+  ActiveRecord::ConnectionAdapters.register(
+    "postgresql_proxy",
+    "ActiveRecord::ConnectionAdapters::PostgreSQLProxyAdapter",
+    "active_record/connection_adapters/postgresql_proxy_adapter"
+  )
+end

data/lib/active_record/tasks/postgresql_proxy_database_tasks.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Tasks
+    # Defines the postgresql tasks for dropping, creating, loading schema and dumping schema.
+    # Bypasses all the proxy logic to send all requests to primary.
+    class PostgreSQLProxyDatabaseTasks < PostgreSQLDatabaseTasks
+      def create(...)
+        sticking_to_primary { super }
+      end
+
+      def drop(...)
+        sticking_to_primary { super }
+      end
+
+      def structure_dump(...)
+        sticking_to_primary { super }
+      end
+
+      def structure_load(...)
+        sticking_to_primary { super }
+      end
+
+      def purge(...)
+        sticking_to_primary { super }
+      end
+
+      private
+
+      def sticking_to_primary(&)
+        ActiveRecord::Base.connected_to(role: context.writing_role, &)
+      end
+
+      def context
+        ActiveRecordProxyAdapters::ActiveRecordContext.new
+      end
+    end
+  end
+end
+
+# Allow proxy adapter to run rake tasks, i.e. db:drop, db:create, db:schema:load db:migrate, etc...
+ActiveRecord::Tasks::DatabaseTasks.register_task(
+  /postgresql_proxy/,
+  "ActiveRecord::Tasks::PostgreSQLProxyDatabaseTasks"
+)

data/lib/active_record_proxy_adapters/active_record_context.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ActiveRecordProxyAdapters
+  # Collection of helpers to handle common active record methods that are defined in different places in different
+  # versions of rails.
+  class ActiveRecordContext
+    delegate :reading_role, :reading_role=, :writing_role, :writing_role=, to: :role_context
+    delegate :legacy_connection_handling, :legacy_connection_handling=, to: :connection_handling_context
+    delegate :version, to: :ActiveRecord, prefix: :active_record
+
+    class << self
+      delegate_missing_to :new
+    end
+
+    NullConnectionHandlingContext = Class.new do
+      def legacy_connection_handling
+        false
+      end
+
+      def legacy_connection_handling=(_value)
+        nil
+      end
+    end
+
+    def reading_role
+      role_context.reading_role
+    end
+
+    def writing_role
+      role_context.writing_role
+    end
+
+    def connection_class_for(connection)
+      klass = active_record_v6_1? ? connection.connection_klass : connection.connection_class
+
+      klass || ActiveRecord::Base
+    end
+
+    def connection_handling_context
+      # This config option has been removed in Rails 7.1+
+      return NullConnectionHandlingContext.new if active_record_v7_1? || active_record_v7_2?
+
+      global_configuration_context
+    end
+
+    def role_context
+      global_configuration_context
+    end
+
+    def global_configuration_context
+      active_record_v6_1? ? ActiveRecord::Base : ActiveRecord
+    end
+
+    def active_record_v6_1?
+      active_record_version >= Gem::Version.new("6.1") && active_record_version < Gem::Version.new("7.0")
+    end
+
+    def active_record_v7_1?
+      active_record_version >= Gem::Version.new("7.1") && active_record_version < Gem::Version.new("7.2")
+    end
+
+    def active_record_v7_2?
+      active_record_version >= Gem::Version.new("7.2") && active_record_version < Gem::Version.new("8.0")
+    end
+  end
+end

data/lib/active_record_proxy_adapters/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/integer/time"
+
+module ActiveRecordProxyAdapters
+  # Provides a global configuration object to configure how the proxy should behave.
+  class Configuration
+    PROXY_DELAY      = 2.seconds.freeze
+    CHECKOUT_TIMEOUT = 2.seconds.freeze
+
+    # @return [ActiveSupport::Duration] How long the proxy should reroute all read requests to the primary database
+    #   since the latest write. Defaults to PROXY_DELAY.
+    attr_accessor :proxy_delay
+    # @return [ActiveSupport::Duration] How long the proxy should wait for a connection from the replica pool.
+    #   Defaults to CHECKOUT_TIMEOUT.
+    attr_accessor :checkout_timeout
+
+    def initialize
+      self.proxy_delay      = PROXY_DELAY
+      self.checkout_timeout = CHECKOUT_TIMEOUT
+    end
+  end
+end

data/lib/active_record_proxy_adapters/connection_handling.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "active_record/connection_adapters/postgresql_proxy_adapter"
+
+module ActiveRecordProxyAdapters
+  # Module to extend ActiveRecord::Base with the connection handling methods.
+  # Required to make adapter work in ActiveRecord versions <= 7.2.x
+  module ConnectionHandling
+    def postgresql_proxy_adapter_class
+      ::ActiveRecord::ConnectionAdapters::PostgreSQLProxyAdapter
+    end
+
+    # This method is a copy and paste from Rails' postgresql_connection,
+    # replacing PostgreSQLAdapter by PostgreSQLProxyAdapter
+    # This is required by ActiveRecord versions <= 7.2.x to establish a connection using the adapter.
+    def postgresql_proxy_connection(config) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      conn_params = config.symbolize_keys.compact
+
+      # Map ActiveRecords param names to PGs.
+      conn_params[:user]   = conn_params.delete(:username) if conn_params[:username]
+      conn_params[:dbname] = conn_params.delete(:database) if conn_params[:database]
+
+      # Forward only valid config params to PG::Connection.connect.
+      valid_conn_param_keys = PG::Connection.conndefaults_hash.keys + [:requiressl]
+      conn_params.slice!(*valid_conn_param_keys)
+
+      postgresql_proxy_adapter_class.new(
+        postgresql_proxy_adapter_class.new_client(conn_params),
+        logger,
+        conn_params,
+        config
+      )
+    end
+  end
+end

data/lib/active_record_proxy_adapters/hijackable.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "active_record/tasks/postgresql_proxy_database_tasks"
+require "active_record/connection_adapters/postgresql_adapter"
+require "active_record_proxy_adapters/primary_replica_proxy"
+
+module ActiveRecordProxyAdapters
+  # Defines mixins to delegate specific methods from the proxy to the adapter.
+  module Hijackable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Renames the methods from the original Adapter using the proxy suffix (_unproxied)
+      # and delegate the original method name to the proxy.
+      # Example: delegate_to_proxy(:execute) creates a method `execute_unproxied`,
+      # while delegating :execute to the proxy.
+      # @param method_name [Array<Symbol>] the names of methods to be redefined.
+      def delegate_to_proxy(*method_names)
+        method_names.each do |method_name|
+          proxy_method_name = proxy_method_name_for(method_name)
+          proxy_method_private = private_method_defined?(method_name)
+
+          # some adapter methods are private. We need to make them public before aliasing.
+          public method_name if proxy_method_private
+
+          alias_method proxy_method_name, method_name
+
+          # If adapter method was originally private. We now make them private again.
+          private method_name, proxy_method_name if proxy_method_private
+        end
+
+        delegate(*method_names, to: :proxy)
+      end
+
+      private
+
+      def proxy_method_name_for(method_name)
+        :"#{method_name}#{ActiveRecordProxyAdapters::PrimaryReplicaProxy::UNPROXIED_METHOD_SUFFIX}"
+      end
+    end
+  end
+end

data/lib/active_record_proxy_adapters/postgresql_proxy.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "active_record_proxy_adapters/primary_replica_proxy"
+
+module ActiveRecordProxyAdapters
+  # Proxy to the original PostgreSQLAdapter, allowing the use of the ActiveRecordProxyAdapters::PrimaryReplicaProxy.
+  class PostgreSQLProxy < PrimaryReplicaProxy
+    # ActiveRecord::PostgreSQLAdapter methods that should be proxied.
+    hijack_method :execute, :exec_query, :exec_no_cache, :exec_cache
+  end
+end

data/lib/active_record_proxy_adapters/primary_replica_proxy.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "active_record_proxy_adapters/configuration"
+require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/object/blank"
+require "concurrent-ruby"
+require "active_record_proxy_adapters/active_record_context"
+
+module ActiveRecordProxyAdapters
+  # This is the base class for all proxies. It defines the methods that should be proxied
+  # and the logic to determine which database to use.
+  class PrimaryReplicaProxy # rubocop:disable Metrics/ClassLength
+    # All queries that match these patterns should be sent to the primary database
+    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
+    # All queries that match these patterns should be sent to the replica database
+    SQL_REPLICA_MATCHERS     = [/\A\s*(select|with.+\)\s*select)\s/i].map(&:freeze).freeze
+    # All queries that match these patterns should be sent to all databases
+    SQL_ALL_MATCHERS         = [/\A\s*set\s/i].map(&:freeze).freeze
+    # Local sets queries should not be sent to all datbases
+    SQL_SKIP_ALL_MATCHERS    = [/\A\s*set\s+local\s/i].map(&:freeze).freeze
+    # These patterns define which database statments are considered write statments, so we can shortly re-route all
+    # requests to the primary database so the replica has time to replicate
+    WRITE_STATEMENT_MATCHERS = [/\ABEGIN/i, /\ACOMMIT/i, /INSERT\sINTO\s/i, /UPDATE\s/i, /DELETE\sFROM\s/i,
+                                /DROP\s/i].map(&:freeze).freeze
+    UNPROXIED_METHOD_SUFFIX  = "_unproxied"
+
+    # Defines which methods should be hijacked from the original adapter and use the proxy
+    # @param method_names [Array<Symbol>] the list of method names from the adapter
+    def self.hijack_method(*method_names)
+      method_names.each do |method_name|
+        define_method(method_name) do |*args, **kwargs, &block|
+          proxy_bypass_method = "#{method_name}#{UNPROXIED_METHOD_SUFFIX}"
+          sql_string          = coerce_query_to_string(args.first)
+
+          appropriate_connection(sql_string) do |conn|
+            method_to_call = conn == primary_connection ? proxy_bypass_method : method_name
+
+            conn.send(method_to_call, *args, **kwargs, &block)
+          end
+        end
+      end
+    end
+
+    # @param primary_connection [ActiveRecord::ConnectionAdatpers::AbstractAdapter]
+    def initialize(primary_connection)
+      @primary_connection    = primary_connection
+      @last_write_at         = 0
+      @active_record_context = ActiveRecordContext.new
+    end
+
+    private
+
+    attr_reader :primary_connection, :last_write_at, :active_record_context
+
+    delegate :connected_to_stack, to: :connection_class
+    delegate :reading_role, :writing_role, to: :active_record_context
+
+    def connection_class
+      active_record_context.connection_class_for(primary_connection)
+    end
+
+    def replica_pool
+      ActiveRecord::Base.connected_to(role: reading_role) { ActiveRecord::Base.connection_pool }
+    end
+
+    def coerce_query_to_string(sql_or_arel)
+      sql_or_arel.respond_to?(:to_sql) ? sql_or_arel.to_sql : sql_or_arel.to_s
+    end
+
+    def appropriate_connection(sql_string, &block)
+      roles_for(sql_string).map do |role|
+        connection_for(role, sql_string) do |connection|
+          block.call(connection)
+        end
+      end.last
+    end
+
+    def roles_for(sql_string)
+      return [top_of_connection_stack_role] if top_of_connection_stack_role.present?
+
+      if need_all?(sql_string)
+        [reading_role, writing_role]
+      elsif need_primary?(sql_string)
+        [writing_role]
+      else
+        [reading_role]
+      end
+    end
+
+    def top_of_connection_stack_role
+      return if connected_to_stack.empty?
+
+      top = connected_to_stack.last
+      role = top[:role]
+      return unless role.present?
+
+      [reading_role, writing_role].include?(role) ? role : nil
+    end
+
+    def connection_for(role, sql_string) # rubocop:disable Metrics/MethodLength
+      connection = if role == writing_role
+                     primary_connection
+                   else
+                     begin
+                       replica_pool.checkout(checkout_timeout)
+                     # rescue NoDatabaseError to avoid crashing when running db:create rake task
+                     # rescue ConnectionNotEstablished to handle connectivity issues in the replica
+                     # (for example, replication delay)
+                     rescue ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished
+                       primary_connection
+                     end
+                   end
+
+      result = yield(connection)
+      update_primary_latest_write_timestamp if !replica_connection?(connection) && write_statement?(sql_string)
+
+      result
+    ensure
+      replica_connection?(connection) && replica_pool.checkin(connection)
+    end
+
+    def replica_connection?(connection)
+      connection != primary_connection
+    end
+
+    # @return [TrueClass] if there has been a write within the last {#proxy_delay} seconds
+    # @return [TrueClass] if sql_string matches a write statement (i.e. INSERT, UPDATE, DELETE, SELECT FOR UPDATE)
+    # @return [FalseClass] if sql_string matches a read statement (i.e. SELECT)
+    def need_primary?(sql_string)
+      return true if recent_write_to_primary?
+
+      return true  if in_transaction?
+      return true  if SQL_PRIMARY_MATCHERS.any?(&match_sql?(sql_string))
+      return false if SQL_REPLICA_MATCHERS.any?(&match_sql?(sql_string))
+
+      true
+    end
+
+    def need_all?(sql_string)
+      return false if SQL_SKIP_ALL_MATCHERS.any?(&match_sql?(sql_string))
+
+      SQL_ALL_MATCHERS.any?(&match_sql?(sql_string))
+    end
+
+    def write_statement?(sql_string)
+      WRITE_STATEMENT_MATCHERS.any?(&match_sql?(sql_string))
+    end
+
+    def match_sql?(sql_string)
+      proc { |matcher| matcher.match?(sql_string) }
+    end
+
+    # TODO: implement a context API to re-route requests to the primary database if a recent query was sent to it to
+    # avoid replication delay issues
+    # @return Boolean
+    def recent_write_to_primary?
+      Concurrent.monotonic_time - last_write_at < proxy_delay
+    end
+
+    def in_transaction?
+      primary_connection.open_transactions.positive?
+    end
+
+    def update_primary_latest_write_timestamp
+      @last_write_at = Concurrent.monotonic_time
+    end
+
+    def proxy_delay
+      proxy_config.proxy_delay
+    end
+
+    def checkout_timeout
+      proxy_config.checkout_timeout
+    end
+
+    def proxy_config
+      ActiveRecordProxyAdapters.config
+    end
+  end
+end

data/lib/active_record_proxy_adapters/railtie.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "active_support"
+
+module ActiveRecordProxyAdapters
+  # Hooks into rails boot process to extend ActiveRecord with the proxy adapter.
+  class Railtie < Rails::Railtie
+    ActiveSupport.on_load :active_record do
+      require "active_record_proxy_adapters/connection_handling"
+      ActiveRecord::Base.extend(ActiveRecordProxyAdapters::ConnectionHandling)
+    end
+
+    config.to_prepare do
+      Rails.autoloaders.each do |autoloader|
+        autoloader.inflector.inflect(
+          "postgresql_proxy_adapter" => "PostgreSQLProxyAdapter"
+        )
+      end
+    end
+  end
+end

data/lib/active_record_proxy_adapters/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveRecordProxyAdapters
+  VERSION = "0.1.0.rc2"
+end

data/lib/active_record_proxy_adapters.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_record_proxy_adapters/version"
+require "active_record_proxy_adapters/configuration"
+
+# The gem namespace.
+module ActiveRecordProxyAdapters
+  class Error < StandardError; end
+
+  module_function
+
+  def configure
+    yield(config)
+  end
+
+  def config
+    @config ||= Configuration.new
+  end
+end
+
+require_relative "active_record_proxy_adapters/railtie" if defined?(Rails::Railtie)

data/postgres_primary.dockerfile

@@ -0,0 +1,34 @@
+FROM docker.io/postgres:14-alpine
+
+ARG REPLICA_USER=replicator
+ARG REPLICA_PASSWORD=replicator
+ARG REPLICATION_SLOT_NAME=replication_slot
+ARG INIT_SQL=00_init.sql
+ARG POSTGRES_LOGGING_COLLECTOR=
+ARG POSTGRES_LOG_DESTINATION=
+ARG POSTGRES_LOG_STATEMENT=
+ENV CONF_SAMPLE="/usr/local/share/postgresql/postgresql.conf.sample"
+
+WORKDIR /docker-entrypoint-initdb.d
+
+USER root
+
+RUN touch $INIT_SQL
+RUN chown -R postgres:postgres $INIT_SQL
+RUN echo "CREATE USER ${REPLICA_USER} WITH REPLICATION ENCRYPTED PASSWORD '${REPLICA_PASSWORD}';" > $INIT_SQL
+RUN echo "SELECT pg_create_physical_replication_slot('${REPLICATION_SLOT_NAME}');" >> $INIT_SQL
+
+# Enable logging collector if given
+RUN if [[ ! -z "${POSTGRES_LOGGING_COLLECTOR}" ]]; then sed -i "s/#\(logging_collector = \)off\(.*\)/\1${POSTGRES_LOGGING_COLLECTOR}\2/" ${CONF_SAMPLE}; fi
+
+# Override  default log destination if given
+RUN if [[ ! -z "${POSTGRES_LOG_DESTINATION}" ]]; then sed -i "s/#\(log_destination = \)'stderr'\(.*\)/\1'${POSTGRES_LOG_DESTINATION}'\2/" ${CONF_SAMPLE}; fi
+
+# Override log statement if given
+RUN if [[ ! -z "${POSTGRES_LOG_STATEMENT}" ]]; then sed -i "s/#\(log_statement = \)'none'\(.*\)/\1'${POSTGRES_LOG_STATEMENT}'\2/" ${CONF_SAMPLE}; fi
+
+WORKDIR /
+
+USER postgres
+
+CMD  ["postgres", "-c", "wal_level=replica", "-c", "hot_standby=on", "-c", "max_wal_senders=10", "-c", "max_replication_slots=10", "-c", "hot_standby_feedback=on" ]

data/postgres_replica.dockerfile

@@ -0,0 +1,23 @@
+FROM docker.io/postgres:14-alpine
+
+ENV PRIMARY_DATABASE_HOST=localhost
+ENV PRIMARY_DATABASE_PORT=5432
+ENV PRIMARY_REPLICATION_SLOT=replication_slot
+
+USER root
+RUN printf '' > cmd.sh
+
+RUN echo 'until pg_basebackup --pgdata=/var/lib/postgresql/data -R --slot=$PRIMARY_REPLICATION_SLOT --host=$PRIMARY_DATABASE_HOST --port=$PRIMARY_DATABASE_PORT' >> cmd.sh
+RUN echo 'do' >> cmd.sh
+RUN echo "echo 'Waiting for primary to connect...'" >> cmd.sh
+RUN echo 'sleep 1s' >> cmd.sh
+RUN echo 'done' >> cmd.sh
+RUN echo "echo 'Backup done, starting replica...'" >> cmd.sh
+RUN echo 'chmod 0700 /var/lib/postgresql/data' >> cmd.sh
+RUN echo 'postgres' >> cmd.sh
+
+RUN chown -R postgres:postgres cmd.sh
+USER postgres
+RUN chmod u+rwx cmd.sh
+
+CMD [ "./cmd.sh" ]

data/sig/active_record_proxy_adapters.rbs

@@ -0,0 +1,4 @@
+module ActiveRecordProxyAdapters
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: active_record_proxy_adapters
+version: !ruby/object:Gem::Version
+  version: 0.1.0.rc2
+platform: ruby
+authors:
+- Matt Cruz
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-11-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.a
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.a
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.a
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.a
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: |-
+  This gem allows automatic connection switching between a primary and one read replica database in ActiveRecord.
+  It pattern matches the SQL statement being sent to decide whether it should go to the replica (SELECT) or the
+  primary (INSERT, UPDATE, DELETE).
+email:
+- matt.cruz@nasdaq.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Dockerfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- docker-compose.yml
+- lib/active_record/connection_adapters/postgresql_proxy_adapter.rb
+- lib/active_record/tasks/postgresql_proxy_database_tasks.rb
+- lib/active_record_proxy_adapters.rb
+- lib/active_record_proxy_adapters/active_record_context.rb
+- lib/active_record_proxy_adapters/configuration.rb
+- lib/active_record_proxy_adapters/connection_handling.rb
+- lib/active_record_proxy_adapters/hijackable.rb
+- lib/active_record_proxy_adapters/postgresql_proxy.rb
+- lib/active_record_proxy_adapters/primary_replica_proxy.rb
+- lib/active_record_proxy_adapters/railtie.rb
+- lib/active_record_proxy_adapters/version.rb
+- postgres_primary.dockerfile
+- postgres_replica.dockerfile
+- sig/active_record_proxy_adapters.rbs
+homepage: https://github.com/Nasdaq/active_record_proxy_adapters
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org/
+  homepage_uri: https://github.com/Nasdaq/active_record_proxy_adapters
+  source_code_uri: https://github.com/Nasdaq/active_record_proxy_adapters
+  changelog_uri: https://github.com/Nasdaq/active_record_proxy_adapters/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Read replica proxy adapters for ActiveRecord!
+test_files: []