trilogy_aurora 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b68247e00782c8fd79fe8aacb267418d8615ec7cf355870df6c7a01669c44f13
+  data.tar.gz: d7387204da336b760389f2c2baa65a64332f399ff4940e0e6a27221cc3c31cb4
+SHA512:
+  metadata.gz: 31cf25f9b38fc5f275d1c0fe0d61c47788fef802adb4359180b7c680f063a85aaf7c71f0b685005e522ac4a086fa424c4e631b853d994ee6d7b0f9dc68be45d5
+  data.tar.gz: 575264af4b39956126cba399667eb958359687d0a286427092e25f2dd74b54b228313e8d48dd94cec0f80e0ec5ba6cf59a754410600a1ef29d9c84e797893d85

data/.dockerignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rdoc_options

@@ -0,0 +1,33 @@
+---
+encoding: UTF-8
+static_path: []
+rdoc_include: []
+page_dir:
+charset: UTF-8
+exclude:
+- "~\\z"
+- "\\.orig\\z"
+- "\\.rej\\z"
+- "\\.bak\\z"
+- "\\.gemspec\\z"
+- "Dockerfile"
+- "Gemfile"
+- "Gemfile.lock"
+- "bin"
+- "coverage"
+- "Rakefile"
+hyperlink_all: false
+line_numbers: false
+locale:
+locale_dir: locale
+locale_name:
+main_page:
+markup: markdown
+output_decoration: true
+show_hash: false
+skip_tests: true
+tab_width: 8
+template_stylesheets: []
+title:
+visibility: :protected
+webcvs:

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,30 @@
+require:
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/MethodLength:
+  Max: 20
+
+RSpec/MultipleExpectations:
+  Max: 2
+
+RSpec/NestedGroups:
+  Max: 5
+
+RSpec/MessageSpies:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2023-09-03
+
+- Initial release

data/Dockerfile

@@ -0,0 +1,16 @@
+ARG RUBY_VERSION=3.2
+
+FROM ruby:${RUBY_VERSION}-alpine
+
+# Create application directory.
+RUN mkdir /app
+WORKDIR /app
+
+# Install packages
+RUN apk upgrade && apk add --update build-base git linux-headers libxml2-dev libxslt-dev mariadb-dev ruby-dev tzdata yaml-dev zlib-dev
+
+# Deploy application
+ADD . /app
+
+# Install gems
+RUN sh /app/bin/setup

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Aidan Lavis
+
+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,86 @@
+# ⚠️ Warning
+
+As far as I'm aware, this hasn't been used in production.  Please test before using!
+
+If you use this gem in production, please let me know so I can update this README!
+
+# TrilogyAurora
+
+Modifies [Trilogy](https://github.com/trilogy-libraries/trilogy) to support AWS Aurora failover.
+
+Essentially, the [mysql2-aurora](https://github.com/alfa-jpn/mysql2-aurora) gem but for Trilogy.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add trilogy_aurora
+
+## Usage
+
+In addition to existing initialization options for `Trilogy`, you can now also use the `aurora_max_retry` and `aurora_disconnect_on_readonly` options.
+
+```ruby
+Trilogy.new(
+  host:             'localhost',
+  username:         'root',
+  password:         'change_me',
+  aurora_max_retry: 5,
+  aurora_disconnect_on_readonly: true
+)
+```
+
+with Rails >= 7.1, in `database.yml`
+
+```yml
+development:
+  adapter:          trilogy
+  host:             localhost
+  username:         root
+  password:         change_me
+  aurora_max_retry: 5
+  aurora_disconnect_on_readonly: true
+```
+
+From the README of [mysql2-aurora](https://github.com/alfa-jpn/mysql2-aurora):
+> There are essentially two methods for handling and RDS Aurora failover. When there is an Aurora RDS failover event the primary writable server can change it's role to become a read_only replica. This can happen without active database connections droppping.
+> This leaves the connection in a state where writes will fail, but the application belives it's connected to a writeable server. Writes will now perpetually fail until the database connection is closed and re-established connecting back to the new primary.
+>
+> To provide automatic recovery from this method you can use either a graceful retry, or an immediate disconnection option.
+> ### Retry
+>
+> Setting aurora_max_retry, mysql2 will not disconnect and automatically attempt re-connection to the database when a read_only error message is encountered.
+> This has the benefit that to the application the error is transparent and the query will be re-run against the new primary when the connection succeeds.
+>
+> It is however not safe to use with transactions
+>
+> Consider:
+>
+> * Transaction is started on the primary server A
+> * Failover event occurs, A is now readonly
+> * Application issues a write statement, read_only exception is thrown
+> * mysql2-aurora gem handles this by reconnecting transparently to the new primary B
+> * Aplication continues issuing writes however on a new connection in auto-commit mode, no new transaction was started
+>
+> The application remains un-aware it is now operating outside of a transaction, this can leave data in an inconcistent state, and issuing a ROLLBACK, or COMMIT will not have the expected outcome.
+>
+> ### Immediate disconnect
+>
+> Setting aurora_disconnect_on_readonly to true, will cause mysql2 to close the connection to the database on read_only exception. The original exception will be thrown up the stack to the application.
+> With the database connection disconnected, the next statement will hit the disconnected error and the application can handle this as it would normally when been disconnected from the database.
+>
+> This is safe with transactions.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/a-lavis/trilogy_aurora.
+
+## Testing
+
+```shell
+# Image build
+bin/docker-build
+
+# Run tests
+bin/docker-test
+```

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,23 @@
+services:
+  app:
+    build:
+      context: .
+    environment:
+      TEST_DB_HOST: 'mysql'
+      TEST_DB_USER: 'root'
+      TEST_DB_PASS: ''
+    volumes:
+      - .:/app
+    depends_on:
+      mysql:
+        condition: service_healthy
+  mysql:
+    image: mysql:8.0
+    environment:
+      MYSQL_ROOT_PASSWORD: ''
+      MYSQL_ALLOW_EMPTY_PASSWORD: 1
+    healthcheck:
+      test: ["CMD-SHELL", "mysqladmin ping -h mysql"]
+      interval: 10s
+      timeout: 5s
+      retries: 3

data/lib/trilogy_aurora/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module TrilogyAurora
+  # The version of this gem.
+  VERSION = "0.1.0"
+end

data/lib/trilogy_aurora.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "trilogy_aurora/version"
+require "trilogy"
+
+# This module contains Trilogy, a wrapper around ::Trilogy that handles read-only errors from Aurora.
+#
+# It also contains the original ::Trilogy class as ORIGINAL_TRILOGY_CLASS.
+module TrilogyAurora
+  # A wrapper around ::Trilogy that handles read-only errors from Aurora.
+  class Trilogy
+    # The ::Trilogy instance.
+    attr_reader :trilogy
+
+    # Pass in any options that ::Trilogy accepts.
+    #
+    # Additionally, you can pass in the `aurora_max_retry` and `aurora_disconnect_on_readonly` options:
+    #
+    # - `aurora_max_retry` is the number of times to retry a query when it fails due to a read-only error.
+    # The default is 5.
+    #
+    # - `aurora_disconnect_on_readonly` is a boolean that determines whether or not to disconnect from the database
+    # after a read-only error is encountered.
+    # The default is false.
+    def initialize(opts)
+      @opts = opts&.transform_keys(&:to_sym)
+      @max_retry = @opts.delete(:aurora_max_retry) || 5
+      @disconnect_only = @opts.delete(:aurora_disconnect_on_readonly) || false
+      reconnect!
+    end
+
+    # Execute a ::Trilogy query, disconnecting or reconnecting after read-only errors
+    # based on initialization options.
+    def query(...)
+      try_count = 0
+
+      begin
+        trilogy.query(...)
+      rescue TrilogyAurora::ORIGINAL_TRILOGY_CLASS::Error => e
+        raise e unless e.message&.include?("--read-only")
+
+        try_count += 1
+
+        if @disconnect_only
+          warn(
+            "[trilogy_aurora] Database is readonly, Aurora failover event likely occured, closing database connection"
+          )
+          disconnect!
+        elsif try_count <= @max_retry
+          retry_interval_seconds = [1.5 * (try_count - 1), 10].min
+
+          warn "[trilogy_aurora] Database is readonly. Retry after #{retry_interval_seconds}seconds"
+          sleep retry_interval_seconds
+          reconnect!
+          retry
+        end
+
+        raise e
+      end
+    end
+
+    # Disconnect and re-initialize ::Trilogy
+    def reconnect!
+      disconnect!
+
+      @trilogy = TrilogyAurora::ORIGINAL_TRILOGY_CLASS.new(@opts)
+    end
+
+    # Close ::Trilogy connection
+    def disconnect!
+      @trilogy&.close
+    rescue StandardError
+      nil
+    end
+
+    # Delegate instance method calls to ::Trilogy instance.
+    def method_missing(name, ...)
+      trilogy.public_send(name, ...)
+    end
+
+    # Delegate `respond_to?` to ::Trilogy instance.
+    def respond_to_missing?(name, ...)
+      trilogy.respond_to?(name, ...)
+    end
+
+    # Delegate class method calls to ::Trilogy.
+    def self.method_missing(name, ...)
+      TrilogyAurora::ORIGINAL_TRILOGY_CLASS.public_send(name, ...)
+    end
+
+    # Delegate `respond_to?` to ::Trilogy.
+    def self.respond_to_missing?(name, ...)
+      TrilogyAurora::ORIGINAL_TRILOGY_CLASS.respond_to?(name, ...)
+    end
+
+    # Delegate const reference to ::Trilogy.
+    def self.const_missing(name)
+      TrilogyAurora::ORIGINAL_TRILOGY_CLASS.const_get(name)
+    end
+  end
+
+  # The original ::Trilogy class.
+  ORIGINAL_TRILOGY_CLASS = ::Trilogy
+  # Swap out the original ::Trilogy class with our wrapper (Trilogy).
+  ::Trilogy = TrilogyAurora::Trilogy
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: trilogy_aurora
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Aidan Lavis
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-09-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: trilogy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+description:
+email:
+- aidanlavis@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".dockerignore"
+- ".rdoc_options"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Dockerfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- docker-compose.yml
+- lib/trilogy_aurora.rb
+- lib/trilogy_aurora/version.rb
+homepage: https://github.com/a-lavis/trilogy_aurora
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/a-lavis/trilogy_aurora
+  source_code_uri: https://github.com/a-lavis/trilogy_aurora
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.33
+signing_key:
+specification_version: 4
+summary: Adds AWS Aurora failover support to Trilogy.
+test_files: []