janus-ar 8.1.0 → 8.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd05e24e1306fce67609a9e991fddad6c4d7014ce58f696a01eb64317838e837
-  data.tar.gz: d07db4e1d21a6363ed9f0f1ea41736b1d71d1ae0fd6c419f34f15e5f74e8825f
+  metadata.gz: 1720a88365b20f91d220065128ca260baf91380779a7a1d9a6f9aa8fffc13ae8
+  data.tar.gz: 2987d7e690b1038946a489a80df29917a192c1a07b85bc16932fb0bf8c2df531
 SHA512:
-  metadata.gz: 9bc3a5029f1b51374051a2c6f8ccc743192780bae4eaaafe18ea6578d9fb77826760ae95a6714bb5ea8f3cd128ef51a3247d39416ae78b8af7b5554ee652ab64
-  data.tar.gz: 0fc71666876765b84cc70ddc4ffc016cd175ae8594fb68dd0a442b047a27aced86e5597ebb1fcf3cebc10d00e81081f8ff63122fcacc4eefa680a89c0fdc4ca2
+  metadata.gz: ae79f4f2c54ea96d6191a2b7597982a558027ed911d894e66bbb205041d2339e0b33bb9004ac8331162c2766ac91c922f1ebd11e125ecd18e2f30db8b8cf173c
+  data.tar.gz: 1224b98a5c03641329d47f1eee868247141cfd6299f98a1f364aed01bef7eb4c3897c4a1e3675734a04aabde3b4ca8165ddb58fe07f36c4f97691c8fcec89e17

data/Gemfile

@@ -1,4 +1,2 @@
-# frozen_string_literal: true
-
 source 'https://rubygems.org'
 gemspec

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    janus-ar (8.1.0)
+    janus-ar (8.1.1)
       activerecord (>= 8.0, < 9.0)
 
 GEM
@@ -51,6 +51,8 @@ GEM
     parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
+    pg (1.6.3-arm64-darwin)
+    pg (1.6.3-x86_64-linux)
     prism (1.9.0)
     pry (0.16.0)
       coderay (~> 1.1)
@@ -128,6 +130,7 @@ DEPENDENCIES
   activesupport (>= 8.0)
   janus-ar!
   mysql2
+  pg
   pry
   rake
   rspec (~> 3)

data/README.md

@@ -11,13 +11,13 @@
 [![CI](https://github.com/OLIOEX/janus-ar/actions/workflows/ci.yml/badge.svg)](https://github.com/OLIOEX/janus-ar/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/janus-ar.svg)](https://badge.fury.io/rb/janus-ar)
 
-Janus ActiveRecord is a generic primary/replica proxy for ActiveRecord 8 and MySQL (via `mysql2` and `trilogy`). It handles the switching of connections between primary and replica database servers. It comes with an ActiveRecord database adapter implementation.
+Janus ActiveRecord is a generic primary/replica proxy for ActiveRecord 8, supporting MySQL (via `mysql2` and `trilogy`) and PostgreSQL (via `pg`). It handles the switching of connections between primary and replica database servers. It comes with an ActiveRecord database adapter implementation.
 
 Janus is heavily inspired by [Makara](https://github.com/instacart/makara) from TaskRabbit and then Instacart. Unfortunately this project is unmaintained and broke for us with Rails 7.1. This is an attempt to start afresh on the project. It is definitely not as fully featured as Makara at this stage.
 
 Learn more about its origins: [https://tech.olioex.com/ruby/2024/04/16/introducing-janus.html](https://tech.olioex.com/ruby/2024/04/16/introducing-janus.html).
 
-Notes: the gem requires ActiveRecord `>= 8.0, < 9.0` and Ruby `>= 3.2`, and is tested against MySQL 8.
+Notes: the gem requires ActiveRecord `>= 8.0, < 9.0` and Ruby `>= 3.2`, and is tested against MySQL 8 and PostgreSQL 16 and 17.
 
 ## Installation
 
@@ -45,6 +45,8 @@ require 'rails/all'
 ActiveRecord::ConnectionAdapters.register("janus_trilogy", "ActiveRecord::ConnectionAdapters::JanusTrilogyAdapter", 'janus-ar/active_record/connection_adapters/janus_trilogy_adapter')
 # ...or...
 ActiveRecord::ConnectionAdapters.register("janus_mysql2", "ActiveRecord::ConnectionAdapters::JanusMysql2Adapter", 'janus-ar/active_record/connection_adapters/janus_mysql2_adapter')
+# ...or...
+ActiveRecord::ConnectionAdapters.register("janus_postgresql", "ActiveRecord::ConnectionAdapters::JanusPostgreSQLAdapter", 'janus-ar/active_record/connection_adapters/janus_postgresql_adapter')
 ```
 
 #### Rails <= 7.1
@@ -81,6 +83,45 @@ Note: For `trilogy` please use adapter "janus_trilogy". You'll probably need to
 Otherwise you will get an error like the following (see https://github.com/trilogy-libraries/trilogy/issues/26):
 > trilogy_auth_recv: caching_sha2_password requires either TCP with TLS or a unix socket: TRILOGY_UNSUPPORTED"
 
+#### PostgreSQL
+
+Use adapter `janus_postgresql`, and add the `pg` gem to your `Gemfile`:
+
+```yml
+development:
+  adapter: janus_postgresql
+  database: database_name
+  janus:
+    primary:
+      <<: *default
+      host: primary-host.local
+      username: app
+      password: primary_password
+    replica:
+      <<: *default
+      host: replica-host.local
+      username: app_readonly
+      password: replica_password
+```
+
+Anything the adapter reads out of its own configuration — `pool`, `prepared_statements`,
+`insert_returning`, `variables`, `schema_search_path`, SSL settings and so on — must go
+inside the `primary:` and `replica:` blocks rather than alongside `adapter:`, because each
+connection is built from its own block.
+
+Two things worth knowing about the PostgreSQL adapter specifically:
+
+* Unlike MySQL, PostgreSQL never inlines bind values into the statement: reads
+  reach the replica as `$1` placeholders plus a separate parameter list, and
+  prepared statements are cached per connection. The adapter forwards binds and
+  the prepare flag to the replica, so each connection maintains its own
+  statement cache.
+* Type OIDs are resolved against whichever connection served the lookup. This is
+  correct for a physical (streaming) replica, where OIDs are identical to the
+  primary's by construction. If you point Janus at a logical replica whose custom
+  types, enums or extensions were created independently, the OIDs can diverge and
+  results may be cast with the wrong type.
+
 ### Forcing connections
 
 A context is local to the current unit of work (thread or fiber, following ActiveRecord's configured isolation level). This allows you to stick to the primary safely within a single request or job, in systems such as Sidekiq for instance.
@@ -119,7 +160,9 @@ There are some edge cases:
 * `SET` operations will be sent to all connections
 * Execution of specific methods such as `connect!`, `disconnect!`, `reconnect!`, and `clear_cache!` are invoked on all underlying connections
 * 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`, `FOR UPDATE SKIP LOCKED`, `FOR SHARE`, `LOCK IN SHARE MODE`, `GET_LOCK(...)`) will always be sent to the primary
+* Locking reads (e.g. `SELECT ... FOR UPDATE`, `FOR UPDATE SKIP LOCKED`, `FOR SHARE`, `FOR NO KEY UPDATE`, `FOR KEY SHARE`, `LOCK IN SHARE MODE`) will always be sent to the primary
+* So will reads that call a locking or sequence function — `GET_LOCK(...)`, `IS_FREE_LOCK(...)`, `nextval(...)`, `setval(...)` and PostgreSQL's advisory lock family (`pg_advisory_lock`, `pg_try_advisory_xact_lock_shared`, `pg_advisory_unlock_all`, and so on)
+* PostgreSQL cursor statements (`DECLARE`, `FETCH`, `MOVE`, `CLOSE`) go to the primary, so a cursor is always fetched on the connection that declared it
 
 # Notes
 

data/Rakefile

@@ -1,3 +1 @@
-# frozen_string_literal: true
-
 require 'bundler/gem_tasks'

data/janus-ar.gemspec

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require File.expand_path('lib/janus-ar/version.rb', __dir__)
 
 Gem::Specification.new do |gem|
@@ -26,6 +24,7 @@ Gem::Specification.new do |gem|
   gem.add_dependency 'activerecord', '>= 8.0', '< 9.0'
   gem.add_development_dependency 'activesupport', '>= 8.0'
   gem.add_development_dependency 'mysql2'
+  gem.add_development_dependency 'pg'
   gem.add_development_dependency 'trilogy'
   gem.add_development_dependency 'pry'
   gem.add_development_dependency 'rake'

data/lib/janus-ar/active_record/connection_adapters/janus_mysql2_adapter.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'active_record/connection_adapters/abstract_adapter'
 require 'active_record/connection_adapters/mysql2_adapter'
 require_relative '../../../janus-ar'

data/lib/janus-ar/active_record/connection_adapters/janus_postgresql_adapter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'active_record/connection_adapters/abstract_adapter'
+require 'active_record/connection_adapters/postgresql_adapter'
+require_relative '../../../janus-ar'
+require_relative '../../adapter_extensions'
+
+module ActiveRecord
+  module ConnectionHandling
+    def janus_postgresql_connection(config)
+      ActiveRecord::ConnectionAdapters::JanusPostgreSQLAdapter.new(config)
+    end
+  end
+
+  class Base
+    def self.janus_postgresql_adapter_class
+      ActiveRecord::ConnectionAdapters::JanusPostgreSQLAdapter
+    end
+  end
+
+  module ConnectionAdapters
+    class JanusPostgreSQLAdapter < ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
+      include Janus::AdapterExtensions
+
+      private
+
+      def replica_adapter_class
+        ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
+      end
+
+      # PostgreSQL compiles statements to `$1` placeholders and passes the values
+      # separately, so the replica needs the whole call, not just the SQL.
+      #
+      # `raw_execute` is private on a stock adapter, hence the `send`. It is the
+      # right target rather than the public `execute`: the statement has already
+      # been through `preprocess_query`, which we do not want applied twice.
+      def forward_raw_execute(sql, ...)
+        replica_connection.send(:raw_execute, sql, ...)
+      end
+    end
+  end
+end

data/lib/janus-ar/active_record/connection_adapters/janus_trilogy_adapter.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'active_record/connection_adapters/abstract_adapter'
 require 'active_record/connection_adapters/trilogy_adapter'
 require_relative '../../../janus-ar'

data/lib/janus-ar/adapter_extensions.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module Janus
   # Behaviour shared by the Janus MySQL2 and Trilogy adapters.
   #
@@ -34,17 +32,17 @@ module Janus
       @connection_parameters ||= args[0]
     end
 
-    # The argument lists below intentionally use anonymous splats and a bare
+    # The argument lists below intentionally use argument forwarding and a bare
     # `super`: ActiveRecord's `raw_execute`/`execute` signatures differ between
     # versions, so we forward whatever we are given unchanged rather than
     # restating (and pinning ourselves to) the current signature.
-    def raw_execute(sql, *, **)
+    def raw_execute(sql, ...)
       case where_to_send?(sql)
       when :all
-        send_to_replica(sql, :all)
+        send_raw_to_replica(sql, :all, ...)
         super
       when :replica
-        send_to_replica(sql, :replica)
+        send_raw_to_replica(sql, :replica, ...)
       else
         mark_primary(sql)
         super
@@ -108,5 +106,17 @@ module Janus
       Janus::Context.used_connection(connection)
       replica_connection.execute(sql)
     end
+
+    def send_raw_to_replica(sql, connection, ...)
+      Janus::Context.used_connection(connection)
+      forward_raw_execute(sql, ...)
+    end
+
+    # The MySQL adapters inline bind values into the SQL string, so replaying the
+    # statement alone is enough. Adapters that keep binds separate must override
+    # this to carry them across.
+    def forward_raw_execute(sql, *, **)
+      replica_connection.execute(sql)
+    end
   end
 end

data/lib/janus-ar/client.rb

@@ -1,4 +1,3 @@
-# frozen_string_literal: true
 module Janus
   class Client
     FOUND_ROWS = 2

data/lib/janus-ar/context.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'active_support/isolated_execution_state'
 
 module Janus

data/lib/janus-ar/db_console_config.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module Janus
   class DbConsoleConfig
     def initialize(config)

data/lib/janus-ar/logging/logger.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module Janus
   module Logging
     class Logger

data/lib/janus-ar/logging/subscriber.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module Janus
   module Logging
     module Subscriber

data/lib/janus-ar/query_director.rb

@@ -1,17 +1,22 @@
-# frozen_string_literal: true
 module Janus
   class QueryDirector
     ALL = :all
     REPLICA = :replica
     PRIMARY = :primary
 
+    # Regexp fragments, not literal names: PostgreSQL's advisory lock family has
+    # too many members to list.
     LOCK_FUNCTIONS = %w(
-      nextval currval lastval get_lock release_lock is_free_lock is_used_lock
-      pg_advisory_lock pg_advisory_unlock
+      nextval currval lastval setval get_lock release_lock is_free_lock is_used_lock
+      pg_(?:try_)?advisory_(?:xact_)?(?:un)?lock(?:_shared|_all)?
     ).freeze
 
+    # A string rather than a Regexp: interpolating a Regexp below would wrap it in
+    # a group that resets the /im flags, so `FOR UPDATE` would stop matching.
+    ROW_LOCK_STRENGTHS = 'no\s+key\s+update|key\s+share|update|share'
+
     SQL_PRIMARY_MATCHERS = [
-      /\A\s*select\b.*\bfor\s+(update|share)\b/im,
+      /\A\s*select\b.*\bfor\s+(?:#{ROW_LOCK_STRENGTHS})\b/im,
       /\A\s*select\b.*\block\s+in\s+share\s+mode\b/im,
       /\A\s*select\b.*\b(#{LOCK_FUNCTIONS.join('|')})\s*\(/im,
       /\A\s*show\b/i,

data/lib/janus-ar/railtie.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'rails/railtie'
 
 module Janus

data/lib/janus-ar/version.rb

@@ -1,11 +1,9 @@
-# frozen_string_literal: true
-
 module Janus
   unless defined?(::Janus::VERSION)
     module VERSION
       MAJOR = 8
       MINOR = 1
-      PATCH = 0
+      PATCH = 1
       PRE = nil
 
       def self.to_s

data/lib/janus-ar.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'active_support'
 
 module Janus

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janus-ar
 version: !ruby/object:Gem::Version
-  version: 8.1.0
+  version: 8.1.1
 platform: ruby
 authors:
 - Lloyd Watkin
@@ -57,6 +57,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: trilogy
   requirement: !ruby/object:Gem::Requirement
@@ -199,6 +213,7 @@ files:
 - janus-ar.gemspec
 - lib/janus-ar.rb
 - lib/janus-ar/active_record/connection_adapters/janus_mysql2_adapter.rb
+- lib/janus-ar/active_record/connection_adapters/janus_postgresql_adapter.rb
 - lib/janus-ar/active_record/connection_adapters/janus_trilogy_adapter.rb
 - lib/janus-ar/adapter_extensions.rb
 - lib/janus-ar/client.rb