activerecord-trilogy-failover 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5e6f84d43760ea21937b7eb3818b3c117e2aa5a43716568dfb7c800fbff16a40
+  data.tar.gz: cc3629c63028c92df3f3285dbc3f219c3fa9c00df61944d6250aaf93460b7e77
+SHA512:
+  metadata.gz: 675583f7a32b1253ce365502761e838950393fd529ca438ec7cefca5846cd62b702dff2f7fa74f89bc437e1addde5e4625c0c4f6163a46d1e73520a2cee2e32e
+  data.tar.gz: 5a037835f24cc566a69a954019d190c6a875d67e2e69c8d1e9277662bf7b8332b1bcf568551f0d2e5d21c37914942d2c01697336517df0845c801c5c856032eb

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Shia
+
+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,79 @@
+# activerecord-trilogy-failover
+
+Automatic reconnection on MySQL read-only errors for ActiveRecord's Trilogy adapter.
+
+When a MySQL server switches to read-only mode (e.g., Aurora failover, ProxySQL routing change, RDS Multi-AZ switchover), existing connections receive `ER_OPTION_PREVENTS_STATEMENT (1290)` on write attempts. This gem translates that error into `ActiveRecord::ConnectionFailed`, enabling Rails' built-in retry mechanism to transparently reconnect to the new writer.
+
+## How it works
+
+The gem prepends a thin patch to `TrilogyAdapter#translate_exception`:
+
+```
+Write attempt → 1290 error → ConnectionFailed → Rails retry → reconnect! → new writer
+```
+
+- **SELECT** (with `allow_retry: true`): Automatically retried and reconnected
+- **INSERT / UPDATE / DELETE**: Error propagates to the caller (no double-execution risk)
+
+This is the correct behavior — writes should not be silently retried.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "activerecord-trilogy-failover", github: "riseshia/activerecord-trilogy-failover"
+```
+
+## Usage
+
+**With Rails**: No configuration needed. The Railtie automatically patches `TrilogyAdapter` on load.
+
+**Without Rails**: Manually prepend the patch:
+
+```ruby
+require "activerecord_trilogy_failover"
+
+ActiveRecord::ConnectionAdapters::TrilogyAdapter.prepend(
+  ActiveRecordTrilogyFailover::AdapterPatch
+)
+```
+
+### database.yml tuning
+
+Rails' built-in retry settings work with this gem:
+
+```yaml
+production:
+  adapter: trilogy
+  connection_retries: 2    # default: 1
+  retry_deadline: 5        # seconds, default: none
+```
+
+## Compatibility
+
+- Ruby >= 3.2
+- ActiveRecord >= 7.1
+- Trilogy >= 2.0
+- MySQL 8.0 (other versions are not tested)
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+### Integration test
+
+Integration tests run against a real MySQL instance using Docker:
+
+```bash
+docker compose up -d            # start MySQL on port 3307
+MYSQL_PORT=3307 bundle exec rspec spec/integration/
+docker compose down -v          # cleanup
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/activerecord-trilogy-failover.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "activerecord_trilogy_failover"

data/lib/activerecord_trilogy_failover/adapter_patch.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ActiveRecordTrilogyFailover
+  module AdapterPatch
+    # MySQL error code for ER_OPTION_PREVENTS_STATEMENT
+    # Raised when the server is running with --read-only
+    MYSQL_READ_ONLY_ERROR_CODE = 1290
+
+    private
+
+    def translate_exception(exception, message:, sql:, binds:)
+      if read_only_error?(exception)
+        return ActiveRecord::ConnectionFailed.new(
+          "#{exception.class}: #{exception.message}",
+          connection_pool: @pool
+        )
+      end
+      super
+    end
+
+    def read_only_error?(exception)
+      exception.respond_to?(:error_code) &&
+        exception.error_code == MYSQL_READ_ONLY_ERROR_CODE &&
+        exception.message.include?("--read-only")
+    end
+  end
+end

data/lib/activerecord_trilogy_failover/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ActiveRecordTrilogyFailover
+  class Railtie < Rails::Railtie
+    initializer "activerecord_trilogy_failover.patch" do
+      ActiveSupport.on_load(:active_record_trilogyadapter) do
+        prepend ActiveRecordTrilogyFailover::AdapterPatch
+      end
+    end
+  end
+end

data/lib/activerecord_trilogy_failover/version.rb

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

data/lib/activerecord_trilogy_failover.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "activerecord_trilogy_failover/version"
+require_relative "activerecord_trilogy_failover/adapter_patch"
+require_relative "activerecord_trilogy_failover/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-trilogy-failover
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shia
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: trilogy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: |
+  Handles MySQL ER_OPTION_PREVENTS_STATEMENT (1290) errors by translating them
+  into ActiveRecord::ConnectionFailed, enabling Rails' built-in retry mechanism
+  to transparently reconnect. Useful for Aurora failover, ProxySQL, RDS Multi-AZ,
+  or any MySQL read-only switchover scenario.
+email:
+- rise.and.and@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/activerecord-trilogy-failover.rb
+- lib/activerecord_trilogy_failover.rb
+- lib/activerecord_trilogy_failover/adapter_patch.rb
+- lib/activerecord_trilogy_failover/railtie.rb
+- lib/activerecord_trilogy_failover/version.rb
+homepage: https://github.com/riseshia/activerecord-trilogy-failover
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/riseshia/activerecord-trilogy-failover
+  source_code_uri: https://github.com/riseshia/activerecord-trilogy-failover
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Automatic reconnection on MySQL read-only errors for ActiveRecord Trilogy
+  adapter
+test_files: []