active_postgres 0.9.5 → 0.9.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f31b928d75edd1c1c63a6534023a3c7255f4bce000487da5fb39ddd0bd357fb
-  data.tar.gz: ee835da34ead4b417ac2c5087e9fae0db12641c7dddb44e91fe795d083f4e61a
+  metadata.gz: 2f7bf86efa4e32bcb1543e317bd6219983f9f42eb0ed0bf8787ff75b6a573a48
+  data.tar.gz: 8a2b2f0ec44bdfd94552dfa0fd84145b64ded472b4f421f216c86af71e2d859e
 SHA512:
-  metadata.gz: 81cc77508c361ab128d840dbaac52ae9f3fc50b431fa971aaede91fc573ed9186521a53f8098e038515b6c96c82141100fd7ce797b0eae5c4b2840bd01330212
-  data.tar.gz: bcdeb64f655cbc0e702f5b70fc3c749daa103ac74945a9432627aeff6926de9b1974fa52547b32e1d99acec687d30b252473a15a75ffadd299e6bc951e9e2bf2
+  metadata.gz: 1d4a26f7284e14c84bcaa4d1e982da9162a25a098b15f9423b4923e7b7a9ab007112620761e5184a1da514f40495edd00647e8c2a269bbbb0511e2611e44118f
+  data.tar.gz: 4dfb7b6e19345e3324d38a798a82bdfa111001cb94736348aa88ba6146f9c3a6bc47fed8977039faefc271d412529f61995ad36f42be93b96a8789437187423e

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# 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.7 - 2026-09-01
+
+### Added
+
+- Support strict operator SSH through declared jump hosts.
+- Allow a standby to override repmgr failover and priority policy.
+- Allow a standby to be seeded from the latest valid pgBackRest backup.
+- Make deployment-flow `--dry-run` stop before confirmation or mutation.
+- Fail standby setup before mutation when required credentials do not resolve.
+- Scope standby rollback to the requested host and keep existing cluster nodes intact.
+- Preserve pgBackRest recovery options as one shell-safe argument during remote restore.
+- Preserve the complete pgBackRest command as the single `bash -lc` command string.
+- Run component rollback in local Ruby context instead of an SSHKit backend scope.
+- Explicitly stop SysV-backed repmgrd before disabling it on manual-failover standbys.
+- Support opt-in bundled block backups for large, frequently changed PostgreSQL relations.
+- Support independent full, differential, and incremental pgBackRest schedules.
+
+## 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
 
@@ -31,6 +35,11 @@ production:
   version: 18
   user: ubuntu
   ssh_key: ~/.ssh/id_rsa
+  ssh_known_hosts_file: config/ssh_known_hosts
+
+  jump_hosts:
+    app-oci:
+      host: 129.213.194.40
 
   primary:
     host: 34.12.234.81        # Public IP for SSH
@@ -39,6 +48,13 @@ production:
   standby:
     - host: 52.23.45.67
       private_ip: 10.8.0.11
+    - host: 100.63.4.227
+      private_ip: 10.8.0.12
+      jump_host: app-oci
+      seed_method: pgbackrest
+      repmgr:
+        auto_failover: false
+        priority: 0
 
   components:
     repmgr: {enabled: true}
@@ -52,6 +68,14 @@ production:
     app_password: $POSTGRES_APP_PASSWORD
 ```
 
+`jump_host` keeps the operator SSH key on the workstation and proxies the
+connection through a declared host. A standby-level `repmgr` block overrides
+the cluster defaults, so a cross-provider disaster-recovery replica can remain
+manual-promotion while the ordinary standby retains automatic failover.
+`seed_method: pgbackrest` restores the latest valid backup with standby recovery
+settings before repmgr registration, avoiding a full base-backup stream from
+the primary. The `pgbackrest` component must be enabled.
+
 Add credentials (`rails credentials:edit`):
 
 ```yaml
@@ -175,8 +199,13 @@ components:
   pgbackrest:
     retention_full: 7
     retention_archive: 14
-    # You can schedule full + incremental separately:
-    # schedule_full: "0 2 * * *"
+    # Reduce incremental backup churn for large, frequently changed relations.
+    # Block backups require repository bundling.
+    repo_bundle: true
+    repo_block: true
+    # You can schedule full, differential, and incremental backups separately:
+    # schedule_full: "0 2 * * 0"
+    # schedule_differential: "35 2 * * 1-6"
     # schedule_incremental: "0 * * * *"
 ```
 
@@ -272,11 +301,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...'
@@ -26,6 +26,7 @@ module ActivePostgres
           ssh_executor.execute_on_host(host) do
             execute :sudo, 'apt-get', 'remove', '-y', 'pgbackrest'
             execute :sudo, 'rm', '-f', '/etc/cron.d/pgbackrest-backup'
+            execute :sudo, 'rm', '-f', '/etc/cron.d/pgbackrest-backup-differential'
             execute :sudo, 'rm', '-f', '/etc/cron.d/pgbackrest-backup-incremental'
             execute :sudo, 'rm', '-f', LOG_ARCHIVE_CRON_FILE
             execute :sudo, 'rm', '-f', LOG_ARCHIVE_ENV_FILE
@@ -135,9 +136,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)
@@ -164,15 +163,13 @@ module ActivePostgres
 
       def backup_schedules(pgbackrest_config)
         schedule_full = pgbackrest_config[:schedule_full] || pgbackrest_config[:schedule]
+        schedule_differential = pgbackrest_config[:schedule_differential]
         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: 'diff', schedule: schedule_differential, file: '/etc/cron.d/pgbackrest-backup-differential' } if schedule_differential
+        schedules << { type: 'incr', schedule: schedule_incremental, file: '/etc/cron.d/pgbackrest-backup-incremental' } if schedule_incremental
 
         schedules
       end
@@ -198,15 +195,14 @@ module ActivePostgres
       def remove_backup_schedule(host)
         ssh_executor.execute_on_host(host) do
           execute :sudo, 'rm', '-f', '/etc/cron.d/pgbackrest-backup'
+          execute :sudo, 'rm', '-f', '/etc/cron.d/pgbackrest-backup-differential'
           execute :sudo, 'rm', '-f', '/etc/cron.d/pgbackrest-backup-incremental'
         end
       end
 
       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)
@@ -260,13 +256,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

@@ -81,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)
@@ -188,9 +186,9 @@ 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')
-        end
+        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)
@@ -200,9 +198,7 @@ module ActivePostgres
         ssl_key = secrets.resolve('ssl_key')
         ssl_chain = secrets.resolve('ssl_chain')
 
-        unless ssl_cert && ssl_key
-          raise Error, 'PgBouncer app_hosts require ssl_cert and ssl_key secrets when ssl is enabled'
-        end
+        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"