active_postgres 0.9.4 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0966aed96fa6f906e7b048ef7804a0b9994c54f841f8dc9f00425f57f565a71
-  data.tar.gz: 86582950fc4afa733cba7052682dbaf0f3e76275c9397559f2d3398c8f92da86
+  metadata.gz: 5d06925c9a64ca3f5b96402257fda9ad13f32bbd0e3ac5377032d737c71fb2ea
+  data.tar.gz: 19cde3ee7e86d325378661aa72350d51d1bfebf33a2e6f03a1c90d34c987a997
 SHA512:
-  metadata.gz: 18644b19453727a1b14918f9bc7d055fdf2c8cbaab962d94acdb058be4fa6b969e72e569ea5e1a2f0848cc45433e35c47dfa69af699370cb267b64c0a61114d5
-  data.tar.gz: '08b112f2121747a9b970809bf0c662dfbed99166edf6e3b18e88daab4fff0a65fcae13821c37fa69af218497b9ac05978d2bf6cd157c197d0f719f968088f407'
+  metadata.gz: 2dbcc33b6ad2ffadeeea4145bc5bc36910203002af908030893298df2005089e87fa8e5d465a425ffae11c60ee01b66f301e1ae594e3bb662d747c0c342b20cb
+  data.tar.gz: 2772e4a192f87c60d54ccaaeb5ea2952f7a98ce34f3daec5839e77758179f75f3f9ac09a76ab74bc929311b8b417e074e5ae156f286bbba55423c3a923b47d77

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to Active Postgres will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/).
+
+## Unreleased
+
+## 0.9.6 - 2026-08-20
+
+### Changed
+
+- Require Ruby 4.0 or newer and Rails 8.1 or newer for Rails integration.
+- Align runtime and development dependencies with the maintained toolchain.
+- Add blocking test, lint, dependency-audit, and package-build CI checks.
+- Add automated Bundler and GitHub Actions dependency updates.
+- Document network, credential, failover, and recovery responsibilities.
+
+## 0.9.5
+
+- Current published release. See the repository history for changes included in
+  earlier releases.

data/README.md

@@ -1,6 +1,10 @@
 # active_postgres
 
-Production-grade PostgreSQL HA for Rails.
+PostgreSQL high-availability automation for Ruby and Rails applications.
+
+Active Postgres configures hosts you control over SSH. It is an operations tool,
+not a managed database service: you remain responsible for network isolation,
+capacity planning, monitoring, backups, recovery drills, and failover decisions.
 
 ## Features
 
@@ -272,11 +276,23 @@ User.all                     # → Replica
 
 ## Requirements
 
-- Ruby 3.0+
-- PostgreSQL 12+
+- Ruby 4.0+
+- A PostgreSQL version supported by the target Linux distribution
 - Ubuntu 20.04+ / Debian 11+ with systemd
 - SSH key-based authentication (hosts must be in `~/.ssh/known_hosts`)
-- Rails 6.0+ (optional)
+- Rails 8.1+ (optional)
+
+## Operational safety
+
+- Keep PostgreSQL, PgBouncer, exporters, and backup endpoints behind a private
+  network or narrowly scoped firewall rules.
+- Test promotion, application reconnection, backup restore, and point-in-time
+  recovery in a disposable environment before using them in production.
+- Review generated configuration and package changes before each rollout;
+  automatic failover cannot determine whether an application is safe to write
+  after a network partition.
+- Store database, replication, monitoring, and backup credentials in a secret
+  manager. Do not commit resolved values or generated configuration.
 
 ### SSH host key verification
 

data/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for a potential vulnerability. Email
+[security@boringcache.com](mailto:security@boringcache.com) or use
+[GitHub private vulnerability reporting](https://github.com/boringcache/active_postgres/security/advisories/new).
+
+Include the affected version, expected impact, and enough reproduction detail
+for us to investigate. Do not include database credentials, private keys,
+backups, customer data, or production configuration.
+
+## Supported Versions
+
+Only the latest published release is supported. Security fixes are normally
+shipped in a new release rather than backported.
+
+## Scope
+
+Reports about PostgreSQL authentication, replication, backup/restore, SSH host
+verification, secret handling, generated SQL, or release integrity are welcome.

data/lib/active_postgres/components/base.rb

@@ -1,3 +1,5 @@
+require 'erb'
+
 module ActivePostgres
   module Components
     class Base

data/lib/active_postgres/components/core.rb

@@ -136,7 +136,7 @@ module ActivePostgres
       end
 
       def ensure_standby_compatible(pg_config)
-        primary_settings = get_primary_replication_settings
+        primary_settings = primary_replication_settings
         return pg_config if primary_settings.empty?
 
         adjustments = []
@@ -154,17 +154,24 @@ module ActivePostgres
         end
 
         if adjustments.any?
-          puts "  ⚠️  Adjusting standby settings to match primary minimum:"
+          puts '  ⚠️  Adjusting standby settings to match primary minimum:'
           adjustments.each { |adj| puts "      #{adj}" }
         end
 
         pg_config
       end
 
-      def get_primary_replication_settings
+      def primary_replication_settings
         @primary_replication_settings ||= begin
           settings = {}
-          sql = "SELECT name || '=' || setting FROM pg_settings WHERE name IN ('max_connections', 'max_worker_processes', 'max_wal_senders', 'max_prepared_transactions', 'max_locks_per_transaction')"
+          setting_names = %w[
+            max_connections
+            max_worker_processes
+            max_wal_senders
+            max_prepared_transactions
+            max_locks_per_transaction
+          ]
+          sql = "SELECT name || '=' || setting FROM pg_settings WHERE name IN (#{setting_names.map { |name| "'#{name}'" }.join(', ')})"
           result = ssh_executor.run_sql(config.primary_host, sql)
           result.strip.split("\n").each do |line|
             name, val = line.split('=')

data/lib/active_postgres/components/monitoring.rb

@@ -1,4 +1,4 @@
-require 'cgi'
+require 'cgi/escape'
 
 module ActivePostgres
   module Components
@@ -83,7 +83,7 @@ module ActivePostgres
         sql = build_monitoring_user_sql(monitoring_user, monitoring_password)
 
         ssh_executor.run_sql(config.primary_host, sql, postgres_user: 'postgres', port: 5432, tuples_only: false,
-                                                     capture: false)
+                                                       capture: false)
       end
 
       def build_monitoring_user_sql(user, password)

data/lib/active_postgres/components/pgbackrest.rb

@@ -3,9 +3,9 @@ require 'shellwords'
 module ActivePostgres
   module Components
     class PgBackRest < Base
-      LOG_ARCHIVE_CRON_FILE = '/etc/cron.d/postgres-log-archive'
-      LOG_ARCHIVE_ENV_FILE = '/etc/active-postgres-log-archive.env'
-      LOG_ARCHIVE_SCRIPT = '/usr/local/bin/active-postgres-archive-logs'
+      LOG_ARCHIVE_CRON_FILE = '/etc/cron.d/postgres-log-archive'.freeze
+      LOG_ARCHIVE_ENV_FILE = '/etc/active-postgres-log-archive.env'.freeze
+      LOG_ARCHIVE_SCRIPT = '/usr/local/bin/active-postgres-archive-logs'.freeze
 
       def install
         puts 'Installing pgBackRest for backups...'
@@ -135,9 +135,7 @@ module ActivePostgres
           execute :sudo, 'chown', "#{postgres_user}:#{postgres_user}", '/var/spool/pgbackrest'
 
           # Only create stanza on primary - standbys share the same backup repo
-          if create_stanza
-            execute :sudo, '-u', postgres_user, 'pgbackrest', '--stanza=main', 'stanza-create'
-          end
+          execute :sudo, '-u', postgres_user, 'pgbackrest', '--stanza=main', 'stanza-create' if create_stanza
         end
 
         if log_archive_enabled?(pgbackrest_config)
@@ -167,12 +165,8 @@ module ActivePostgres
         schedule_incremental = pgbackrest_config[:schedule_incremental]
 
         schedules = []
-        if schedule_full
-          schedules << { type: 'full', schedule: schedule_full, file: '/etc/cron.d/pgbackrest-backup' }
-        end
-        if schedule_incremental
-          schedules << { type: 'incremental', schedule: schedule_incremental, file: '/etc/cron.d/pgbackrest-backup-incremental' }
-        end
+        schedules << { type: 'full', schedule: schedule_full, file: '/etc/cron.d/pgbackrest-backup' } if schedule_full
+        schedules << { type: 'incr', schedule: schedule_incremental, file: '/etc/cron.d/pgbackrest-backup-incremental' } if schedule_incremental
 
         schedules
       end
@@ -204,15 +198,13 @@ module ActivePostgres
 
       def setup_log_archive(host, pgbackrest_config)
         log_archive_config = pgbackrest_config[:log_archive] || {}
-        unless pgbackrest_config[:repo_type] == 's3'
-          raise Error, 'pgbackrest.log_archive requires pgbackrest.repo_type: s3'
-        end
+        raise Error, 'pgbackrest.log_archive requires pgbackrest.repo_type: s3' unless pgbackrest_config[:repo_type] == 's3'
 
         postgres_user = config.postgres_user
         env_content = log_archive_env(pgbackrest_config, log_archive_config, host)
         cron_content = log_archive_cron(log_archive_config)
 
-        install_apt_packages(host, 'awscli')
+        install_apt_packages(host, 's3cmd')
 
         ssh_executor.upload_file(host, env_content, LOG_ARCHIVE_ENV_FILE, mode: '640', owner: "root:#{postgres_user}")
 
@@ -260,13 +252,13 @@ module ActivePostgres
           'POSTGRES_LOG_ARCHIVE_NODE' => config.node_label_for(host) || host
         }.compact
 
-        env.map { |key, value| "#{key}=#{Shellwords.escape(value.to_s)}" }.join("\n") + "\n"
+        "#{env.map { |key, value| "#{key}=#{Shellwords.escape(value.to_s)}" }.join("\n")}\n"
       end
 
       def s3_endpoint_url(pgbackrest_config)
         endpoint = pgbackrest_config[:s3_endpoint]
         return nil if endpoint.to_s.empty?
-        return endpoint if endpoint.match?(/\Ahttps?:\/\//)
+        return endpoint if endpoint.match?(%r{\Ahttps?://})
 
         "https://#{endpoint}"
       end

data/lib/active_postgres/components/pgbouncer.rb

@@ -8,12 +8,16 @@ module ActivePostgres
           is_standby = config.standby_hosts.include?(host)
           install_on_host(host, is_standby: is_standby)
         end
+
+        pgbouncer_app_hosts.each do |app_host|
+          install_on_app_host(app_host)
+        end
       end
 
       def uninstall
         puts 'Uninstalling PgBouncer...'
 
-        config.all_hosts.each do |host|
+        (config.all_hosts + pgbouncer_app_hosts.map { |app_host| app_host.fetch('host') }).each do |host|
           ssh_executor.execute_on_host(host) do
             execute :sudo, 'systemctl', 'disable', '--now', 'pgbouncer-follow-primary.timer', '||', 'true'
             execute :sudo, 'rm', '-f', '/usr/local/bin/pgbouncer-follow-primary',
@@ -29,7 +33,7 @@ module ActivePostgres
       def restart
         puts 'Restarting PgBouncer...'
 
-        config.all_hosts.each do |host|
+        (config.all_hosts + pgbouncer_app_hosts.map { |app_host| app_host.fetch('host') }).each do |host|
           ssh_executor.execute_on_host(host) do
             execute :sudo, 'systemctl', 'restart', 'pgbouncer'
           end
@@ -46,6 +50,15 @@ module ActivePostgres
             execute :sudo, 'systemctl', 'reload', 'pgbouncer'
           end
         end
+
+        pgbouncer_app_hosts.each do |app_host|
+          host = app_host.fetch('host')
+          create_userlist_from_primary(host)
+
+          ssh_executor.execute_on_host(host) do
+            execute :sudo, 'systemctl', 'reload', 'pgbouncer'
+          end
+        end
       end
 
       def install_on_standby(standby_host)
@@ -55,6 +68,12 @@ module ActivePostgres
 
       private
 
+      def pgbouncer_app_hosts
+        return config.pgbouncer_app_hosts if config.respond_to?(:pgbouncer_app_hosts)
+
+        []
+      end
+
       def install_on_host(host, is_standby: false)
         puts "  Installing PgBouncer on #{host}..."
 
@@ -62,9 +81,7 @@ module ActivePostgres
 
         follow_primary = follow_primary_for?(host, is_standby: is_standby, user_config: user_config)
 
-        if follow_primary && !config.component_enabled?(:repmgr)
-          raise Error, 'PgBouncer follow_primary requires repmgr to be enabled'
-        end
+        raise Error, 'PgBouncer follow_primary requires repmgr to be enabled' if follow_primary && !config.component_enabled?(:repmgr)
 
         max_connections = get_postgres_max_connections(host)
         optimal_pool = ConnectionPooler.calculate_optimal_pool_sizes(max_connections)
@@ -106,6 +123,45 @@ module ActivePostgres
         install_follow_primary(host, pgbouncer_config) if follow_primary
       end
 
+      def install_on_app_host(app_host)
+        host = app_host.fetch('host')
+        puts "  Installing PgBouncer on app host #{host}..."
+
+        user_config = config.component_config(:pgbouncer)
+        max_connections = get_postgres_max_connections(config.primary_host)
+        optimal_pool = ConnectionPooler.calculate_optimal_pool_sizes(max_connections)
+
+        pgbouncer_config = optimal_pool.merge(user_config)
+        pgbouncer_config[:database_host] = app_host_value(app_host, :database_host) || pgbouncer_primary_record
+        pgbouncer_config[:database_port] = app_host_value(app_host, :database_port) || pgbouncer_config[:database_port] || 5432
+        pgbouncer_config[:listen_addr] = app_host_value(app_host, :listen_addr) || pgbouncer_config[:app_listen_addr] || '127.0.0.1'
+        pgbouncer_config[:listen_port] = app_host_value(app_host, :listen_port) || pgbouncer_config[:app_listen_port] ||
+                                         pgbouncer_config[:listen_port] || 6432
+        ssl_enabled = config.component_enabled?(:ssl)
+        has_ca_cert = ssl_enabled && secrets.resolve('ssl_chain')
+        secrets_obj = secrets
+        _ = pgbouncer_config
+        _ = has_ca_cert
+        _ = secrets_obj
+
+        puts "  Calculated app pool settings for max_connections=#{max_connections}"
+
+        install_apt_packages(host, 'pgbouncer', 'postgresql-client')
+
+        upload_template(host, 'pgbouncer.ini.erb', '/etc/pgbouncer/pgbouncer.ini', binding, mode: '644')
+
+        setup_app_ssl_certs(host) if ssl_enabled
+
+        create_userlist_from_primary(host)
+
+        ssh_executor.execute_on_host(host) do
+          execute :sudo, 'systemctl', 'enable', 'pgbouncer'
+          execute :sudo, 'systemctl', 'restart', 'pgbouncer'
+        end
+
+        install_follow_dns_primary(host, pgbouncer_config)
+      end
+
       def follow_primary_for?(host, is_standby:, user_config:)
         if is_standby
           standby_config = config.standby_config_for(host) || {}
@@ -130,9 +186,33 @@ module ActivePostgres
         end
 
         ssl_chain = secrets.resolve('ssl_chain')
-        if ssl_chain
-          ssh_executor.upload_file(host, ssl_chain, '/etc/pgbouncer/ca.crt', mode: '644', owner: 'postgres:postgres')
+        return unless ssl_chain
+
+        ssh_executor.upload_file(host, ssl_chain, '/etc/pgbouncer/ca.crt', mode: '644', owner: 'postgres:postgres')
+      end
+
+      def setup_app_ssl_certs(host)
+        puts '  Setting up SSL certificates for app PgBouncer...'
+
+        ssl_cert = secrets.resolve('ssl_cert')
+        ssl_key = secrets.resolve('ssl_key')
+        ssl_chain = secrets.resolve('ssl_chain')
+
+        raise Error, 'PgBouncer app_hosts require ssl_cert and ssl_key secrets when ssl is enabled' unless ssl_cert && ssl_key
+
+        full_cert = if ssl_chain
+                      "#{ssl_cert.strip}\n#{ssl_chain.strip}\n"
+                    else
+                      ssl_cert
+                    end
+
+        ssh_executor.execute_on_host(host) do
+          execute :sudo, 'mkdir', '-p', '/etc/pgbouncer'
         end
+
+        ssh_executor.upload_file(host, full_cert, '/etc/pgbouncer/server.crt', mode: '644', owner: 'postgres:postgres')
+        ssh_executor.upload_file(host, ssl_key, '/etc/pgbouncer/server.key', mode: '600', owner: 'postgres:postgres')
+        ssh_executor.upload_file(host, ssl_chain, '/etc/pgbouncer/ca.crt', mode: '644', owner: 'postgres:postgres') if ssl_chain
       end
 
       def get_postgres_max_connections(host)
@@ -154,18 +234,43 @@ module ActivePostgres
       def create_userlist(host)
         puts '  Creating PgBouncer userlist with database users...'
 
-        postgres_user = config.postgres_user
-        app_user = config.app_user
-        users_to_add = [postgres_user, (app_user if app_user != postgres_user)].compact
-        pgbouncer = self
+        component = self
 
         ssh_executor.execute_on_host(host) do
-          backend = self
-          userlist_entries = users_to_add.filter_map { |user| pgbouncer.send(:fetch_user_hash, backend, user, postgres_user) }
-          pgbouncer.send(:write_userlist_file, backend, userlist_entries)
+          userlist_entries = component.send(:userlist_entries_from_backend, self)
+          component.send(:write_userlist_file, self, userlist_entries)
         end
       end
 
+      def create_userlist_from_primary(host)
+        puts '  Creating app PgBouncer userlist from primary database users...'
+
+        userlist_entries = nil
+        component = self
+
+        ssh_executor.execute_on_host(config.primary_host) do
+          userlist_entries = component.send(:userlist_entries_from_backend, self)
+        end
+
+        ssh_executor.execute_on_host(host) do
+          component.send(:write_userlist_file, self, userlist_entries || [])
+        end
+      end
+
+      def userlist_entries_from_backend(backend)
+        postgres_user = config.postgres_user
+        users_to_add = pgbouncer_database_users
+
+        users_to_add.filter_map { |user| fetch_user_hash(backend, user, postgres_user) }
+      end
+
+      def pgbouncer_database_users
+        postgres_user = config.postgres_user
+        app_user = config.app_user
+
+        [postgres_user, (app_user if app_user != postgres_user)].compact
+      end
+
       def fetch_user_hash(backend, user, postgres_user)
         sql = build_user_hash_sql(user)
 
@@ -241,6 +346,40 @@ module ActivePostgres
           execute :sudo, 'systemctl', 'start', 'pgbouncer-follow-primary.service'
         end
       end
+
+      def install_follow_dns_primary(host, pgbouncer_config)
+        interval = pgbouncer_config[:follow_primary_interval] || 5
+        interval = interval.to_i
+        interval = 5 if interval <= 0
+        primary_record = pgbouncer_config[:database_host]
+        _ = interval
+        _ = primary_record
+        _ = pgbouncer_config
+
+        upload_template(host, 'pgbouncer_follow_dns_primary.sh.erb', '/usr/local/bin/pgbouncer-follow-primary',
+                        binding, mode: '755', owner: 'root:root')
+        upload_template(host, 'pgbouncer-follow-primary.service.erb',
+                        '/etc/systemd/system/pgbouncer-follow-primary.service', binding, mode: '644', owner: 'root:root')
+        upload_template(host, 'pgbouncer-follow-primary.timer.erb',
+                        '/etc/systemd/system/pgbouncer-follow-primary.timer', binding, mode: '644', owner: 'root:root')
+
+        ssh_executor.execute_on_host(host) do
+          execute :sudo, 'systemctl', 'daemon-reload'
+          execute :sudo, 'systemctl', 'enable', '--now', 'pgbouncer-follow-primary.timer'
+          execute :sudo, 'systemctl', 'start', 'pgbouncer-follow-primary.service'
+        end
+      end
+
+      def pgbouncer_primary_record
+        return config.pgbouncer_primary_record if config.respond_to?(:pgbouncer_primary_record)
+
+        dns_failover = config.component_config(:repmgr)[:dns_failover] || {}
+        dns_failover[:primary_record] || config.primary_replication_host
+      end
+
+      def app_host_value(app_host, key)
+        app_host[key.to_s] || app_host[key]
+      end
     end
   end
 end