activerecord-health 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8ffd824e810c1dc16ebe84ec333bacd29867f80320b278b95ba5f9132e3929e0
+  data.tar.gz: 28599edb6d93b0e21b9cfd1c52f938a4394060e6757cf805195f0e410489548b
+SHA512:
+  metadata.gz: 3c185ce40c985568ad318b5d356cc967e5781a3e5ee98259ebc9edbff3a28f4d409fde79945a00f7b00a8dd31b9df84de3785f66f9993745be08a87861b8c755
+  data.tar.gz: c3199b2e98cfdd1059e2e98bdbd1c640b8a0efa3d4de5ceddd1e70efcb9f8502d2a365ccd934158a2b2a01bddc51a4f7ab8821bfd774ce4aaacb092d6e1164b4

data/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+## Development
+
+### Requirements
+
+- Ruby 3.2+
+- Docker (for integration tests)
+
+### Running Tests
+
+```bash
+# Unit tests only
+bundle exec rake test
+
+# Start test databases
+docker-compose up -d
+
+# All tests (unit + integration)
+bundle exec rake test_all
+
+# Stop test databases
+docker-compose down
+```
+
+### Project Structure
+
+```
+lib/
+├── activerecord-health.rb          # Main entry point
+└── activerecord/
+    └── health/
+        ├── configuration.rb        # Config handling
+        ├── extensions.rb           # Optional model/connection methods
+        └── adapters/
+            ├── postgresql_adapter.rb
+            └── mysql_adapter.rb
+test/
+├── unit/                           # Fast tests with mocks
+└── integration/                    # Tests against real databases
+```

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nate Berkopec
+
+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,239 @@
+# ActiveRecord::Health
+
+Monitor your database's health by tracking active sessions. When load gets too high, shed work to keep your app running.
+
+## Why Use This?
+
+This gem was inspired by [Simon Eskildsen](https://www.youtube.com/watch?v=N8NWDHgWA28), who described a similar system in place at Shopify.
+
+Databases slow down when they have too many active queries. This gem helps you:
+
+- **Shed load safely.** Skip low-priority work when the database is busy.
+- **Protect your app.** Return 503 errors instead of timing out, which allows higher-priority work to get through.
+
+The gem counts active database sessions. It compares this count to your database's vCPU count. When active sessions exceed a threshold, the database is "unhealthy."
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "activerecord-health"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+```ruby
+# config/initializers/activerecord_health.rb
+ActiveRecord::Health.configure do |config|
+  config.vcpu_count = 16        # Required: your database server's vCPU count
+  config.cache = Rails.cache    # Required: any ActiveSupport::Cache store
+end
+```
+
+Now check if your database is healthy:
+
+```ruby
+ActiveRecord::Health.ok?
+# => true
+```
+
+## Configuration
+
+```ruby
+ActiveRecord::Health.configure do |config|
+  # Required settings
+  config.vcpu_count = 16          # Number of vCPUs on your database server
+  config.cache = Rails.cache      # Cache store for health check results
+
+  # Optional settings
+  config.threshold = 0.75         # Max healthy load (default: 0.75)
+  config.cache_ttl = 60           # Cache duration in seconds (default: 60)
+end
+```
+
+> [!IMPORTANT]
+> You must set `vcpu_count` and `cache`. The gem raises an error without them.
+
+### What Does Threshold Mean?
+
+The threshold is the maximum healthy load as a ratio of vCPUs.
+
+With `vcpu_count = 16` and `threshold = 0.75`:
+- Up to 12 active sessions = healthy (12/16 = 0.75)
+- More than 12 active sessions = unhealthy
+
+## API
+
+### Check Health
+
+```ruby
+# Returns true if database is healthy
+ActiveRecord::Health.ok?
+
+# Get current load as a percentage
+ActiveRecord::Health.load_pct
+# => 0.5 (50% of vCPUs in use)
+```
+
+### Shed Work
+
+Use `sheddable` to skip work when the database is overloaded:
+
+```ruby
+ActiveRecord::Health.sheddable do
+  GenerateReport.perform(user_id: current_user.id)
+end
+```
+
+Use `sheddable_pct` for different priority levels:
+
+```ruby
+# High priority: only run below 50% load
+ActiveRecord::Health.sheddable_pct(pct: 0.5) do
+  BulkImport.perform(data)
+end
+
+# Low priority: only run below 90% load
+ActiveRecord::Health.sheddable_pct(pct: 0.9) do
+  SendAnalyticsEmail.perform(user_id: current_user.id)
+end
+```
+
+## Usage Examples
+
+### Controller Filter
+
+Return 503 when the database is overloaded:
+
+```ruby
+class ReportsController < ApplicationController
+  before_action :check_database_health
+
+  private
+
+  def check_database_health
+    return if ActiveRecord::Health.ok?
+    render json: { error: "Service temporarily unavailable" },
+           status: :service_unavailable
+  end
+end
+```
+
+### Sidekiq Middleware
+
+Retry jobs when the database is unhealthy:
+
+```ruby
+# config/initializers/sidekiq.rb
+class DatabaseHealthMiddleware
+  THROTTLED_QUEUES = %w[reports analytics bulk_import].freeze
+
+  def call(_worker, job, _queue)
+    if THROTTLED_QUEUES.include?(job["queue"]) && !ActiveRecord::Health.ok?
+      raise ActiveRecord::Health::Unhealthy
+    end
+    yield
+  end
+end
+
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add DatabaseHealthMiddleware
+  end
+end
+```
+
+## Multi-Database Support
+
+Pass the model class that connects to your database:
+
+```ruby
+# Check the primary database (default)
+ActiveRecord::Health.ok?
+
+# Check a specific database
+ActiveRecord::Health.ok?(model: AnimalsRecord)
+```
+
+Configure each database separately:
+
+```ruby
+ActiveRecord::Health.configure do |config|
+  config.vcpu_count = 16  # Default for primary database
+  config.cache = Rails.cache
+
+  config.for_model(AnimalsRecord) do |db|
+    db.vcpu_count = 8
+    db.threshold = 0.5
+  end
+end
+```
+
+## Database Support
+
+| Database | Supported |
+|----------|-----------|
+| PostgreSQL 10+ | Yes |
+| MySQL 5.1+ | Yes |
+| MySQL 8.0.22+ | Yes (uses performance_schema) |
+| MariaDB | Yes |
+| SQLite | No |
+
+## Observability
+
+Send load data to Datadog, StatsD, or other tools. The gem fires an event each time it checks the database:
+
+```ruby
+ActiveSupport::Notifications.subscribe("health_check.activerecord_health") do |*, payload|
+  StatsD.gauge("db.load_pct", payload[:load_pct], tags: ["db:#{payload[:database]}"])
+  StatsD.gauge("db.active_sessions", payload[:active_sessions], tags: ["db:#{payload[:database]}"])
+end
+```
+
+> [!TIP]
+> Start by tracking `load_pct` for a few days. This helps you learn what "normal" looks like before you set thresholds.
+
+The event fires only when the gem runs a query. It does not fire when reading from cache.
+
+**Event payload:**
+
+| Key | Description |
+|-----|-------------|
+| `database` | Connection name |
+| `load_pct` | Load as a ratio (0.0 to 1.0+) |
+| `active_sessions` | Number of active sessions |
+
+## Optional Extensions
+
+Add convenience methods to connections and models:
+
+```ruby
+require "activerecord/health/extensions"
+
+ActiveRecord::Base.connection.healthy?
+# => true
+
+ActiveRecord::Base.connection.load_pct
+# => 0.75
+
+ActiveRecord::Base.database_healthy?
+# => true
+```
+
+## Known Issues
+
+This gem is simple by design. Keep these limits in mind:
+
+- **Errors look like overload.** The health check query can fail for many reasons: network problems, DNS issues, or connection pool limits. When this happens, the gem marks the database as unhealthy. It caches this result for `cache_ttl` seconds. This can cause load shedding even when the database is fine.
+- **Session counts can be wrong.** The gem assumes many active sessions means the CPU is busy. But sessions can be active while waiting on locks, disk reads, or slow clients. The database may have room to spare, but the gem still reports it as unhealthy.
+
+## License
+
+MIT License. See [LICENSE](LICENSE.txt) for details.

data/Rakefile

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "standard/rake"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/unit/**/*_test.rb"]
+end
+
+Rake::TestTask.new(:test_integration) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/integration/**/*_test.rb"]
+end
+
+Rake::TestTask.new(:test_all) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: %i[test standard]

data/docker-compose.yml

@@ -0,0 +1,27 @@
+services:
+  postgres:
+    image: postgres:latest
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: activerecord_health_test
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  mysql:
+    image: mysql:latest
+    environment:
+      MYSQL_ROOT_PASSWORD: root
+      MYSQL_DATABASE: activerecord_health_test
+    ports:
+      - "3306:3306"
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
+      interval: 5s
+      timeout: 5s
+      retries: 5

data/lib/activerecord/health/adapters/mysql_adapter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Health
+    module Adapters
+      class MySQLAdapter
+        PERFORMANCE_SCHEMA_MIN_VERSION = Gem::Version.new("8.0.22")
+
+        attr_reader :version_string
+
+        def initialize(version_string)
+          @version_string = version_string
+        end
+
+        def name
+          :mysql
+        end
+
+        def active_session_count_query
+          uses_performance_schema? ? performance_schema_query : information_schema_query
+        end
+
+        def uses_performance_schema?
+          !mariadb? && mysql_version >= PERFORMANCE_SCHEMA_MIN_VERSION
+        end
+
+        private
+
+        def mariadb?
+          version_string.downcase.include?("mariadb")
+        end
+
+        def mysql_version
+          Gem::Version.new(version_string.split("-").first)
+        end
+
+        def performance_schema_query
+          <<~SQL.squish
+            SELECT COUNT(*)
+            FROM performance_schema.processlist
+            WHERE COMMAND != 'Sleep'
+              AND ID != CONNECTION_ID()
+              AND USER NOT IN ('event_scheduler', 'system user')
+          SQL
+        end
+
+        def information_schema_query
+          <<~SQL.squish
+            SELECT COUNT(*)
+            FROM information_schema.processlist
+            WHERE Command != 'Sleep'
+              AND ID != CONNECTION_ID()
+              AND User NOT IN ('event_scheduler', 'system user')
+              AND Command NOT IN ('Binlog Dump', 'Binlog Dump GTID')
+          SQL
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/health/adapters/postgresql_adapter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Health
+    module Adapters
+      class PostgreSQLAdapter
+        def name
+          :postgresql
+        end
+
+        def active_session_count_query
+          <<~SQL.squish
+            SELECT count(*)
+            FROM pg_stat_activity
+            WHERE state = 'active'
+              AND backend_type = 'client backend'
+              AND pid != pg_backend_pid()
+          SQL
+        end
+      end
+    end
+  end
+end

data/lib/activerecord/health/configuration.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Health
+    class ConfigurationError < StandardError; end
+
+    class Configuration
+      attr_accessor :vcpu_count, :threshold, :cache, :cache_ttl
+
+      def initialize
+        @threshold = 0.75
+        @cache_ttl = 60
+        @model_configs = {}
+      end
+
+      def validate!
+        raise ConfigurationError, "vcpu_count must be configured" if vcpu_count.nil?
+        raise ConfigurationError, "cache must be configured" if cache.nil?
+      end
+
+      def for_model(model, &block)
+        if block_given?
+          config = ModelConfiguration.new(self)
+          block.call(config)
+          @model_configs[model] = config
+        else
+          @model_configs[model] || self
+        end
+      end
+
+      def max_healthy_sessions
+        (vcpu_count * threshold).floor
+      end
+    end
+
+    class ModelConfiguration
+      attr_accessor :vcpu_count
+      attr_writer :threshold
+
+      def initialize(parent)
+        @parent = parent
+      end
+
+      def cache
+        @parent.cache
+      end
+
+      def cache_ttl
+        @parent.cache_ttl
+      end
+
+      def threshold
+        @threshold || @parent.threshold
+      end
+
+      def max_healthy_sessions
+        (vcpu_count * threshold).floor
+      end
+    end
+  end
+end

data/lib/activerecord/health/extensions.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../health"
+
+module ActiveRecord
+  module Health
+    module ConnectionExtension
+      def healthy?
+        db_config_name = pool.db_config.name
+        ActiveRecord::Health.ok?(model: ConnectionModelProxy.new(db_config_name, self))
+      end
+
+      def load_pct
+        db_config_name = pool.db_config.name
+        ActiveRecord::Health.load_pct(model: ConnectionModelProxy.new(db_config_name, self))
+      end
+    end
+
+    module ModelExtension
+      def database_healthy?
+        ActiveRecord::Health.ok?(model: self)
+      end
+    end
+
+    class ConnectionModelProxy
+      attr_reader :connection
+
+      def initialize(db_config_name, connection)
+        @db_config_name = db_config_name
+        @connection = connection
+      end
+
+      def connection_db_config
+        DbConfigProxy.new(@db_config_name)
+      end
+
+      def class
+        ActiveRecord::Base
+      end
+    end
+
+    DbConfigProxy = Struct.new(:name)
+  end
+end

data/lib/activerecord/health/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Health
+    class Railtie < Rails::Railtie
+      initializer "activerecord_health.validate_configuration" do
+        ActiveRecord::Health.configuration.validate!
+      end
+    end
+  end
+end

data/lib/activerecord/health/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Activerecord
+  module Health
+    VERSION = "0.1.0"
+  end
+end