janus-ar 0.15.2 → 7.2.0

data/README.md

@@ -1,110 +1,129 @@
-# Janus ActiveRecord
-
-<p align="center">
-  <img src="assets/janus-logo.png"
-     alt="Janus Logo"
-     style="float: left; margin: 0 auto; height: 500px;" />
-</p>
-
-> In ancient Roman religion and myth, Janus (/ˈdʒeɪnəs/ JAY-nəs; Latin: Ianvs [ˈi̯aːnʊs]) is the god of beginnings, gates, transitions, time, duality, doorways,[2] passages, frames, and endings. [(wikipedia)](https://en.wikipedia.org/wiki/Janus)
-
-[![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 generic primary/replica proxy for ActiveRecord 7.1+ 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.
-
-Note: Trilogy support is experimental at this stage.
-
-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: GEM is currently tested with MySQL 8, Ruby 3.2, ActiveRecord 7.1+
-
-## Installation
-
-Use the current version of the gem from [rubygems](https://rubygems.org/gems/janus-ar) in your `Gemfile`.
-
-```ruby
-gem 'janus-ar'
-```
-
-This project assumes that your read/write endpoints are handled by a separate system (e.g. DNS).
-
-## Usage
-
-After a write request during a thread the adapter will continue using the `primary` server, unless the context is specifically released.
-
-### Configuration
-
-Update your **database.yml** as follows:
-
-```yml
-development:
-  adapter: janus_mysql2
-  database: database_name
-  janus:
-    primary:
-      <<: *default
-      host: primary-host.local
-    replica:
-      <<: *default
-      password: ithappenstobedifferent
-      host: replica-host.local
-```
-Note: For `trilogy` please use adapter "janus_trilogy". You'll probably need to add the following to your configuration to have it connect:
-
-```yml
-  ssl: true
-  ssl_mode: 'REQUIRED'
-  tls_min_version: 3
-```
-
-`tls_min_version` here refers to TLS1.2.
-
-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"
-
-### Forcing connections
-
-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.
-
-#### Releasing stuck connections (clearing context)
-
-If you need to clear the current context, releasing any stuck connections, all you have to do is:
-
-```ruby
-Janus::Context.release_all
-```
-
-#### Forcing connection to primary server
-
-```ruby
-Janus::Context.stick_to_primary
-```
-
-### Logging
-
-You can set a logger instance to `::Janus::Logging::Logger.logger`:
-
-```ruby
-Janus::Logging::Logger.logger = ::Logger.new(STDOUT)
-```
-
-If using `ActiveRecord` logging, Janus will append the name of the connection used to any logs e.g. `[primary]` or `[replica]`.
-
-### What queries goes where?
-
-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!`, `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`) will always be sent to the primary
-
-
-# Acknowlegements
-
-Amazing project logo by @undevelopedbruce.
+# Janus ActiveRecord
+
+<p align="center">
+  <img src="assets/janus-logo.png"
+     alt="Janus Logo"
+     style="float: left; margin: 0 auto; height: 500px;" />
+</p>
+
+> In ancient Roman religion and myth, Janus (/ˈdʒeɪnəs/ JAY-nəs; Latin: Ianvs [ˈi̯aːnʊs]) is the god of beginnings, gates, transitions, time, duality, doorways,[2] passages, frames, and endings. [(wikipedia)](https://en.wikipedia.org/wiki/Janus)
+
+[![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 generic primary/replica proxy for ActiveRecord 7.1+ 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.
+
+Note: Trilogy support is experimental at this stage.
+
+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: GEM is currently tested with MySQL 8, Ruby 3.2, ActiveRecord 7.1+
+
+## Installation
+
+Use the current version of the gem from [rubygems](https://rubygems.org/gems/janus-ar) in your `Gemfile`.
+
+```ruby
+gem 'janus-ar'
+```
+
+This project assumes that your read/write endpoints are handled by a separate system (e.g. DNS).
+
+## Usage
+
+After a write request during a thread the adapter will continue using the `primary` server, unless the context is specifically released.
+
+## Rails 7.2+
+
+For Rails 7.2 you'll need to manually register the database adaptor in `config/application.rb` after requiring rails but before entering the application configuration, e.g.
+
+```ruby
+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')
+```
+
+## Rails <= 7.1
+
+ActiveRecord 7.1 was tested up to releases v0.15.*. After this release we only tested  Rails 7.2+. This does not mean it is not compatible, just not tested.
+
+### Configuration
+
+Update your **database.yml** as follows:
+
+```yml
+development:
+  adapter: janus_mysql2
+  database: database_name
+  janus:
+    primary:
+      <<: *default
+      host: primary-host.local
+    replica:
+      <<: *default
+      password: ithappenstobedifferent
+      host: replica-host.local
+```
+Note: For `trilogy` please use adapter "janus_trilogy". You'll probably need to add the following to your configuration to have it connect:
+
+```yml
+  ssl: true
+  ssl_mode: 'REQUIRED'
+  tls_min_version: 3
+```
+
+`tls_min_version` here refers to TLS1.2.
+
+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"
+
+### Forcing connections
+
+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.
+
+#### Releasing stuck connections (clearing context)
+
+If you need to clear the current context, releasing any stuck connections, all you have to do is:
+
+```ruby
+Janus::Context.release_all
+```
+
+#### Forcing connection to primary server
+
+```ruby
+Janus::Context.stick_to_primary
+```
+
+### Logging
+
+You can set a logger instance to `::Janus::Logging::Logger.logger`:
+
+```ruby
+Janus::Logging::Logger.logger = ::Logger.new(STDOUT)
+```
+
+If using `ActiveRecord` logging, Janus will append the name of the connection used to any logs e.g. `[primary]` or `[replica]`.
+
+### What queries goes where?
+
+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!`, `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`) will always be sent to the primary
+
+# Notes
+
+Janus does not support Rails' read/write split or sharding using `with_connection`.
+
+# Acknowlegements
+
+Amazing project logo by @undevelopedbruce.

data/Rakefile

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

data/janus-ar.gemspec

@@ -1,36 +1,36 @@
-# frozen_string_literal: true
-
-require File.expand_path('lib/janus/version.rb', __dir__)
-
-Gem::Specification.new do |gem|
-  gem.authors       = ['Lloyd Watkin']
-  gem.email         = ['lloyd@olioex.com']
-  gem.description   = 'Read/Write proxy for ActiveRecord using primary/replica databases'
-  gem.summary       = 'Read/Write proxy for ActiveRecord using primary/replica databases'
-  gem.homepage      = 'https://github.com/olioex/janus-ar'
-  gem.licenses      = %w(MIT)
-  gem.metadata      = {
-    'source_code_uri' => 'https://github.com/olioex/janus-ar',
-  }
-
-  gem.files         = `git ls-files`.split($OUTPUT_RECORD_SEPARATOR)
-  gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
-  gem.name          = 'janus-ar'
-  gem.require_paths = %w(lib)
-  gem.version       = Janus::VERSION
-
-  gem.required_ruby_version = '>= 3.2.0'
-
-  gem.add_development_dependency 'activerecord', '>= 7.1.0'
-  gem.add_development_dependency 'activesupport', '>= 7.1.0'
-  gem.add_development_dependency 'mysql2'
-  gem.add_development_dependency 'trilogy'
-  gem.add_development_dependency 'pry'
-  gem.add_development_dependency 'rake'
-  gem.add_development_dependency 'rspec', '~> 3'
-  gem.add_development_dependency 'rubocop', '~> 1.63.0'
-  gem.add_development_dependency 'rubocop-rails', '~> 2.24.0'
-  gem.add_development_dependency 'rubocop-rspec'
-  gem.add_development_dependency 'rubocop-thread_safety'
-  gem.add_development_dependency 'rubocop-performance'
-end
+# frozen_string_literal: true
+
+require File.expand_path('lib/janus-ar/version.rb', __dir__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ['Lloyd Watkin']
+  gem.email         = ['lloyd@olioex.com']
+  gem.description   = 'Read/Write proxy for ActiveRecord using primary/replica databases'
+  gem.summary       = 'Read/Write proxy for ActiveRecord using primary/replica databases'
+  gem.homepage      = 'https://github.com/olioex/janus-ar'
+  gem.licenses      = %w(MIT)
+  gem.metadata      = {
+    'source_code_uri' => 'https://github.com/olioex/janus-ar',
+  }
+
+  gem.files         = `git ls-files`.split($OUTPUT_RECORD_SEPARATOR)
+  gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+  gem.name          = 'janus-ar'
+  gem.require_paths = %w(lib)
+  gem.version       = Janus::VERSION
+
+  gem.required_ruby_version = '>= 3.2.0'
+
+  gem.add_dependency 'activerecord', '~> 7.2'
+  gem.add_development_dependency 'activesupport', '>= 7.2.0'
+  gem.add_development_dependency 'mysql2'
+  gem.add_development_dependency 'trilogy'
+  gem.add_development_dependency 'pry'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec', '~> 3'
+  gem.add_development_dependency 'rubocop', '~> 1.65.0'
+  gem.add_development_dependency 'rubocop-rails', '~> 2.26.0'
+  gem.add_development_dependency 'rubocop-rspec'
+  gem.add_development_dependency 'rubocop-thread_safety'
+  gem.add_development_dependency 'rubocop-performance'
+end

data/lib/{active_record → janus-ar/active_record}/connection_adapters/janus_mysql2_adapter.rb

@@ -1,144 +1,148 @@
-# frozen_string_literal: true
-
-require 'active_record/connection_adapters/abstract_adapter'
-require 'active_record/connection_adapters/mysql2_adapter'
-require_relative '../../janus'
-
-module ActiveRecord
-  module ConnectionHandling
-    def janus_mysql2_connection(config)
-      ActiveRecord::ConnectionAdapters::JanusMysql2Adapter.new(config)
-    end
-  end
-end
-
-module ActiveRecord
-  class Base
-    def self.janus_mysql2_adapter_class
-      ActiveRecord::ConnectionAdapters::JanusMysql2Adapter
-    end
-  end
-end
-
-module ActiveRecord
-  module ConnectionAdapters
-    class JanusMysql2Adapter < ActiveRecord::ConnectionAdapters::Mysql2Adapter
-      FOUND_ROWS = 'FOUND_ROWS'
-
-      attr_reader :config
-
-      class << self
-        def dbconsole(config, options = {})
-          connection_config = Janus::DbConsoleConfig.new(config)
-
-          super(connection_config, options)
-        end
-      end
-
-      def initialize(*args)
-        args[0][:janus]['replica']['database'] = args[0][:database]
-        args[0][:janus]['primary']['database'] = args[0][:database]
-
-        @replica_config = args[0][:janus]['replica']
-        args[0] = args[0][:janus]['primary']
-
-        super(*args)
-        @connection_parameters ||= args[0]
-        update_config
-      end
-
-      def raw_execute(sql, name, async: false, allow_retry: false, materialize_transactions: true)
-        case where_to_send?(sql)
-        when :all
-          send_to_replica(sql, connection: :all, method: :raw_execute)
-          super
-        when :replica
-          send_to_replica(sql, connection: :replica, method: :raw_execute)
-        else
-          Janus::Context.stick_to_primary if write_query?(sql)
-          Janus::Context.used_connection(:primary)
-          super
-        end
-      end
-
-      def execute(sql)
-        case where_to_send?(sql)
-        when :all
-          send_to_replica(sql, connection: :all, method: :execute)
-          super(sql)
-        when :replica
-          send_to_replica(sql, connection: :replica, method: :execute)
-        else
-          Janus::Context.stick_to_primary if write_query?(sql)
-          Janus::Context.used_connection(:primary)
-          super(sql)
-        end
-      end
-
-      def execute_and_free(sql, name = nil, async: false)
-        case where_to_send?(sql)
-        when :all
-          send_to_replica(sql, connection: :all, method: :execute)
-          super(sql, name, async:)
-        when :replica
-          send_to_replica(sql, connection: :replica, method: :execute)
-        else
-          Janus::Context.stick_to_primary if write_query?(sql)
-          Janus::Context.used_connection(:primary)
-          super(sql, name, async:)
-        end
-      end
-
-      def connect!(...)
-        replica_connection.connect!(...)
-        super
-      end
-
-      def reconnect!(...)
-        replica_connection.reconnect!(...)
-        super
-      end
-
-      def disconnect!(...)
-        replica_connection.disconnect!(...)
-        super
-      end
-
-      def clear_cache!(...)
-        replica_connection.clear_cache!(...)
-        super
-      end
-
-      def replica_connection
-        @replica_connection ||= ActiveRecord::ConnectionAdapters::Mysql2Adapter.new(@replica_config)
-      end
-
-      private
-
-      def where_to_send?(sql)
-        Janus::QueryDirector.new(sql, open_transactions).where_to_send?
-      end
-
-      def send_to_replica(sql, connection: nil, method: :exec_query)
-        Janus::Context.used_connection(connection) if connection
-        if method == :execute
-          replica_connection.execute(sql)
-        elsif method == :raw_execute
-          replica_connection.execute(sql)
-        else
-          replica_connection.exec_query(sql)
-        end
-      end
-
-      def update_config
-        @config[:flags] ||= 0
-
-        if @config[:flags].is_a? Array
-          @config[:flags].push FOUND_ROWS
-        else
-          @config[:flags] |= ::Janus::Client::FOUND_ROWS
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+require 'active_record/connection_adapters/abstract_adapter'
+require 'active_record/connection_adapters/mysql2_adapter'
+require_relative '../../../janus-ar'
+
+module ActiveRecord
+  module ConnectionHandling
+    def janus_mysql2_connection(config)
+      ActiveRecord::ConnectionAdapters::JanusMysql2Adapter.new(config)
+    end
+  end
+end
+
+module ActiveRecord
+  class Base
+    def self.janus_mysql2_adapter_class
+      ActiveRecord::ConnectionAdapters::JanusMysql2Adapter
+    end
+  end
+end
+
+module ActiveRecord
+  module ConnectionAdapters
+    class JanusMysql2Adapter < ActiveRecord::ConnectionAdapters::Mysql2Adapter
+      FOUND_ROWS = 'FOUND_ROWS'
+
+      attr_reader :config
+
+      class << self
+        def dbconsole(config, options = {})
+          connection_config = Janus::DbConsoleConfig.new(config)
+
+          super(connection_config, options)
+        end
+      end
+
+      def initialize(*args)
+        args[0][:janus]['replica']['database'] = args[0][:database]
+        args[0][:janus]['primary']['database'] = args[0][:database]
+
+        @replica_config = args[0][:janus]['replica']
+        args[0] = args[0][:janus]['primary']
+
+        super(*args)
+        @connection_parameters ||= args[0]
+        update_config
+      end
+
+      def with_connection(_args = {})
+        self
+      end
+
+      def raw_execute(sql, name, async: false, allow_retry: false, materialize_transactions: true)
+        case where_to_send?(sql)
+        when :all
+          send_to_replica(sql, connection: :all, method: :raw_execute)
+          super
+        when :replica
+          send_to_replica(sql, connection: :replica, method: :raw_execute)
+        else
+          Janus::Context.stick_to_primary if write_query?(sql)
+          Janus::Context.used_connection(:primary)
+          super
+        end
+      end
+
+      def execute(sql)
+        case where_to_send?(sql)
+        when :all
+          send_to_replica(sql, connection: :all, method: :execute)
+          super(sql)
+        when :replica
+          send_to_replica(sql, connection: :replica, method: :execute)
+        else
+          Janus::Context.stick_to_primary if write_query?(sql)
+          Janus::Context.used_connection(:primary)
+          super(sql)
+        end
+      end
+
+      def execute_and_free(sql, name = nil, async: false)
+        case where_to_send?(sql)
+        when :all
+          send_to_replica(sql, connection: :all, method: :execute)
+          super(sql, name, async:)
+        when :replica
+          send_to_replica(sql, connection: :replica, method: :execute)
+        else
+          Janus::Context.stick_to_primary if write_query?(sql)
+          Janus::Context.used_connection(:primary)
+          super(sql, name, async:)
+        end
+      end
+
+      def connect!(...)
+        replica_connection.connect!(...)
+        super
+      end
+
+      def reconnect!(...)
+        replica_connection.reconnect!(...)
+        super
+      end
+
+      def disconnect!(...)
+        replica_connection.disconnect!(...)
+        super
+      end
+
+      def clear_cache!(...)
+        replica_connection.clear_cache!(...)
+        super
+      end
+
+      def replica_connection
+        @replica_connection ||= ActiveRecord::ConnectionAdapters::Mysql2Adapter.new(@replica_config)
+      end
+
+      private
+
+      def where_to_send?(sql)
+        Janus::QueryDirector.new(sql, open_transactions).where_to_send?
+      end
+
+      def send_to_replica(sql, connection: nil, method: :exec_query)
+        Janus::Context.used_connection(connection) if connection
+        if method == :execute
+          replica_connection.execute(sql)
+        elsif method == :raw_execute
+          replica_connection.execute(sql)
+        else
+          replica_connection.exec_query(sql)
+        end
+      end
+
+      def update_config
+        @config[:flags] ||= 0
+
+        if @config[:flags].is_a? Array
+          @config[:flags].push FOUND_ROWS
+        else
+          @config[:flags] |= ::Janus::Client::FOUND_ROWS
+        end
+      end
+    end
+  end
+end