active_postgres 0.9.6 → 0.9.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d06925c9a64ca3f5b96402257fda9ad13f32bbd0e3ac5377032d737c71fb2ea
-  data.tar.gz: 19cde3ee7e86d325378661aa72350d51d1bfebf33a2e6f03a1c90d34c987a997
+  metadata.gz: c3d6f986ee2ac96f5cdd8b69541a5acae87733f506b10efb94c1046082b990a9
+  data.tar.gz: f64bb049c6601cf853de16c6cfeff8293ebb06d622db9633330298f02ef82135
 SHA512:
-  metadata.gz: 2dbcc33b6ad2ffadeeea4145bc5bc36910203002af908030893298df2005089e87fa8e5d465a425ffae11c60ee01b66f301e1ae594e3bb662d747c0c342b20cb
-  data.tar.gz: 2772e4a192f87c60d54ccaaeb5ea2952f7a98ce34f3daec5839e77758179f75f3f9ac09a76ab74bc929311b8b417e074e5ae156f286bbba55423c3a923b47d77
+  metadata.gz: b07c93095ab642d39d6d658e93ef82c7ca993a30cf06b3f320d02e20dc5f45a546ffcdb2196f5bae0d1ab2051fb3a453a0a445e3e3f49b89ec1e3be9ee19f042
+  data.tar.gz: aeae944d32c7ee5f661470eaee9f66c01ef47c1bb4f578bbae0fd8d3e50f81044d24ddf49f85304a5aa6437de207aa22600cd3cc6cf7167713c5f87204e3cee9

data/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ## Unreleased
 
+## 0.9.8 - 2026-10-02
+
+### Fixed
+
+- Support explicit node IDs so repmgr identities survive primary changes and standby reordering.
+- Reject duplicate or invalid node IDs before deployment.
+
+## 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

data/README.md

@@ -35,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
@@ -43,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}
@@ -56,6 +68,20 @@ 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.
+
+Set a unique positive integer `node_id` on every primary and standby entry
+before permanently changing their roles or reordering standbys. Match the
+existing IDs in `repmgr cluster show`, and keep each ID with its host after a
+switchover. Without explicit IDs, the primary defaults to 1 and standbys use
+their list position starting at 2. Duplicate or invalid IDs are rejected.
+
 Add credentials (`rails credentials:edit`):
 
 ```yaml
@@ -179,8 +205,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 * * * *"
 ```
 

data/lib/active_postgres/components/pgbackrest.rb

@@ -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
@@ -162,10 +163,12 @@ 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 = []
         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
@@ -192,6 +195,7 @@ 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

data/lib/active_postgres/components/repmgr.rb

@@ -1,3 +1,5 @@
+require 'shellwords'
+
 module ActivePostgres
   module Components
     class Repmgr < Base
@@ -22,31 +24,24 @@ module ActivePostgres
       def uninstall
         puts 'Uninstalling repmgr...'
 
-        config.all_hosts.each do |host|
-          is_primary = host == config.primary_host
-          node_id = if is_primary
-                      1
-                    else
-                      begin
-                        config.standby_hosts.index(host) + 2
-                      rescue StandardError
-                        999
-                      end
-                    end
+        config.all_hosts.each { |host| uninstall_from(host) }
+      end
 
-          ssh_executor.execute_on_host(host) do
-            cluster_output = begin
-              capture(:sudo, '-u', 'postgres', 'repmgr', 'cluster', 'show')
-            rescue StandardError
-              ''
-            end
+      def uninstall_from(host)
+        node_id = config.node_id_for(host)
 
-            if cluster_output.include?("| #{node_id}") && cluster_output.include?('running')
-              info "✓ Skipping repmgr removal from #{host} - node #{node_id} is running"
-            else
-              info "Removing repmgr from #{host}"
-              execute :sudo, 'apt-get', 'remove', '-y', '-q', 'postgresql-*-repmgr', '||', 'true'
-            end
+        ssh_executor.execute_on_host(host) do
+          cluster_output = begin
+            capture(:sudo, '-u', 'postgres', 'repmgr', 'cluster', 'show')
+          rescue StandardError
+            ''
+          end
+
+          if cluster_output.include?("| #{node_id}") && cluster_output.include?('running')
+            info "✓ Skipping repmgr removal from #{host} - node #{node_id} is running"
+          else
+            info "Removing repmgr from #{host}"
+            execute :sudo, 'apt-get', 'remove', '-y', '-q', 'postgresql-*-repmgr', '||', 'true'
           end
         end
       end
@@ -62,7 +57,7 @@ module ActivePostgres
       end
 
       def setup_standby_only(standby_host)
-        puts "Setting up standby #{standby_host} (primary will not be touched)..."
+        puts "Setting up standby #{standby_host} (primary stays online)..."
 
         version = config.version
         install_apt_packages(standby_host, "postgresql-#{version}-repmgr")
@@ -103,7 +98,8 @@ module ActivePostgres
         puts '  Setting up primary with repmgr...'
 
         host = config.primary_host
-        repmgr_config = config.component_config(:repmgr)
+        primary_node_id = config.node_id_for(host)
+        repmgr_config = config.repmgr_config_for(host)
         version = config.version
         repmgr_password = normalize_repmgr_password(secrets.resolve('repmgr_password'))
         replication_password = normalize_replication_password(secrets.resolve('replication_password'))
@@ -213,7 +209,7 @@ module ActivePostgres
           unless cluster_show&.match?(/primary/i)
             # Fallback: verify via repmgr metadata in the repmgr database
             db_check = executor.run_sql_on_backend(self,
-                                                   'SELECT type FROM repmgr.nodes WHERE node_id = 1;',
+                                                   "SELECT type FROM repmgr.nodes WHERE node_id = #{primary_node_id};",
                                                    postgres_user: 'postgres',
                                                    database: repmgr_db,
                                                    tuples_only: true,
@@ -236,7 +232,7 @@ module ActivePostgres
         puts "  Setting up standby: #{standby_host}..."
 
         host = standby_host
-        repmgr_config = config.component_config(:repmgr)
+        repmgr_config = config.repmgr_config_for(standby_host)
         primary_replication_host = config.primary_replication_host
         version = config.version
         secrets_obj = secrets
@@ -244,13 +240,18 @@ module ActivePostgres
         repmgr_db = config.repmgr_database
         postgres_user = config.postgres_user
         replication_user = config.replication_user
+        seed_method = config.standby_seed_method_for(standby_host)
+        restore_arguments = if seed_method == :pgbackrest
+                              standby_label = config.node_label_for(standby_host) || "standby-#{standby_host.split('.').first}"
+                              pgbackrest_restore_arguments(build_primary_conninfo(standby_label))
+                            end
 
         # Variables used in ERB templates via binding
         _ = host
         _ = repmgr_config
         _ = secrets_obj
 
-        node_id = config.standby_hosts.index(standby_host) + 2
+        node_id = config.node_id_for(standby_host)
         repmgr_password = normalize_repmgr_password(secrets_obj.resolve('repmgr_password'))
         replication_password = normalize_replication_password(secrets_obj.resolve('replication_password'))
         if replication_user == repmgr_user && replication_password != repmgr_password
@@ -300,58 +301,61 @@ module ActivePostgres
             nil
           end
 
-          info 'Cloning from primary over private network...'
-          # Create a temporary repmgr config for cloning that points to the primary
-          # The regular config points to localhost which doesn't work during initial clone
-          temp_repmgr_conf = <<~CONF
-            node_id=#{node_id}
-            node_name='#{standby_host}'
-            conninfo='host=#{primary_replication_host} user=#{repmgr_user} dbname=#{repmgr_db} connect_timeout=10'
-            data_directory='/var/lib/postgresql/#{version}/main'
-          CONF
-
-          info 'Creating temporary repmgr config for cloning...'
-          upload! StringIO.new(temp_repmgr_conf), '/tmp/repmgr_clone.conf'
-          execute :sudo, 'mv', '/tmp/repmgr_clone.conf', '/etc/repmgr_clone.conf'
-          execute :sudo, 'chown', 'postgres:postgres', '/etc/repmgr_clone.conf'
-          execute :sudo, 'chmod', '600', '/etc/repmgr_clone.conf'
-
-          info 'Running: repmgr standby clone (this may take a few minutes to copy the database)...'
+          if seed_method == :repmgr
+            info 'Cloning from primary over private network...'
+            # Create a temporary repmgr config for cloning that points to the primary.
+            # The regular config points to localhost, which does not work during the initial clone.
+            temp_repmgr_conf = <<~CONF
+              node_id=#{node_id}
+              node_name='#{standby_host}'
+              conninfo='host=#{primary_replication_host} user=#{repmgr_user} dbname=#{repmgr_db} connect_timeout=10'
+              data_directory='/var/lib/postgresql/#{version}/main'
+            CONF
+
+            info 'Creating temporary repmgr config for cloning...'
+            upload! StringIO.new(temp_repmgr_conf), '/tmp/repmgr_clone.conf'
+            execute :sudo, 'mv', '/tmp/repmgr_clone.conf', '/etc/repmgr_clone.conf'
+            execute :sudo, 'chown', 'postgres:postgres', '/etc/repmgr_clone.conf'
+            execute :sudo, 'chmod', '600', '/etc/repmgr_clone.conf'
+            info 'Running: repmgr standby clone (this may take a few minutes to copy the database)...'
+          else
+            info 'Restoring the latest valid pgBackRest backup as a standby...'
+          end
 
           clone_success = false
           begin
-            execute :sudo, '-u', postgres_user, 'env',
-                    'HOME=/var/lib/postgresql',
-                    'repmgr', 'standby', 'clone',
-                    '-h', primary_replication_host,
-                    '-U', repmgr_user,
-                    '-d', repmgr_db,
-                    '-f', '/etc/repmgr_clone.conf',
-                    '--force',
-                    '--verbose'
-
-            info 'Clone command completed'
+            if seed_method == :pgbackrest
+              execute(*restore_arguments)
+              info 'pgBackRest standby restore completed'
+            else
+              execute :sudo, '-u', postgres_user, 'env',
+                      'HOME=/var/lib/postgresql',
+                      'repmgr', 'standby', 'clone',
+                      '-h', primary_replication_host,
+                      '-U', repmgr_user,
+                      '-d', repmgr_db,
+                      '-f', '/etc/repmgr_clone.conf',
+                      '--force',
+                      '--verbose'
+              info 'Clone command completed'
+            end
 
-            # Check if clone actually succeeded
             if test(:sudo, 'test', '-d', "/var/lib/postgresql/#{version}/main")
               clone_success = true
-              info 'Data directory successfully cloned!'
-
-              # Clean up temporary clone config
-              execute :sudo, 'rm', '-f', '/etc/repmgr_clone.conf'
+              info 'Standby data directory successfully seeded!'
+              execute :sudo, 'rm', '-f', '/etc/repmgr_clone.conf' if seed_method == :repmgr
             else
-              error "Data directory /var/lib/postgresql/#{version}/main was not created even though command succeeded!"
+              error "Data directory /var/lib/postgresql/#{version}/main was not created even though seeding succeeded!"
             end
           rescue SSHKit::Command::Failed => e
-            error "Clone command failed with exit code #{e.message}"
+            error "Standby seed command failed with exit code #{e.message}"
           rescue StandardError => e
-            error "Clone command raised exception: #{e.class}: #{e.message}"
+            error "Standby seed command raised exception: #{e.class}: #{e.message}"
           end
 
-          # If clone failed, raise error
           unless clone_success
-            error '✗ repmgr standby clone failed'
-            raise 'repmgr standby clone failed to create data directory'
+            error '✗ Standby data seeding failed'
+            raise 'standby data seeding failed to create data directory'
           end
         end
 
@@ -676,6 +680,7 @@ module ActivePostgres
         puts 'Verifying PostgreSQL HA cluster health...'
 
         primary_host = config.primary_host
+        primary_node_id = config.node_id_for(primary_host)
         standby_hosts = config.standby_hosts
         version = config.version
         postgres_user = config.postgres_user
@@ -706,12 +711,12 @@ module ActivePostgres
           cluster_output = capture(:sudo, '-u', 'postgres',
                                    'repmgr', '-f', '/etc/repmgr.conf', 'cluster', 'show',
                                    raise_on_non_zero_exit: false).to_s
-          # Primary always has node_id=1, check if it's registered and running
-          if cluster_output.match?(/\s+1\s+\|.*primary.*\*\s+running/i)
+          # Check the configured node identity, which survives role changes.
+          if cluster_output.match?(/\s+#{primary_node_id}\s+\|.*primary.*\*\s+running/i)
             info '✓ Primary is registered with repmgr'
           else
             db_check = executor.run_sql_on_backend(self,
-                                                   'SELECT type FROM repmgr.nodes WHERE node_id = 1 AND active IS TRUE;',
+                                                   "SELECT type FROM repmgr.nodes WHERE node_id = #{primary_node_id} AND active IS TRUE;",
                                                    postgres_user: postgres_user,
                                                    database: repmgr_db,
                                                    tuples_only: true,
@@ -907,6 +912,21 @@ module ActivePostgres
         "host=#{primary_host} user=#{user} dbname=#{dbname} application_name=#{standby_label}"
       end
 
+      def pgbackrest_restore_arguments(primary_conninfo)
+        command = Shellwords.join(
+          [
+            'pgbackrest', '--stanza=main', '--type=standby',
+            "--recovery-option=primary_conninfo=#{primary_conninfo}",
+            'restore'
+          ]
+        )
+
+        [
+          :sudo, '-u', config.postgres_user,
+          :bash, '-lc', Shellwords.escape(command)
+        ]
+      end
+
       def normalize_repmgr_password(raw_password)
         password = raw_password.to_s.rstrip
 
@@ -933,7 +953,7 @@ module ActivePostgres
 
       def ensure_primary_registered
         host = config.primary_host
-        config.version
+        primary_node_id = config.node_id_for(host)
         is_registered = false
 
         ssh_executor.execute_on_host(host) do
@@ -947,8 +967,8 @@ module ActivePostgres
             ''
           end
 
-          if cluster_output.include?('| 1') && cluster_output.include?('primary')
-            info '✓ Primary is registered (node_id=1)'
+          if cluster_output.match?(/\b#{primary_node_id}\s+\|.*primary/)
+            info "✓ Primary is registered (node_id=#{primary_node_id})"
           else
             warn "⚠ Primary not found in cluster, assuming it's registered"
           end
@@ -1101,7 +1121,13 @@ module ActivePostgres
       end
 
       def enable_repmgrd_if_configured(host, repmgr_config)
-        return if repmgr_config[:auto_failover] == false
+        if repmgr_config[:auto_failover] == false
+          ssh_executor.execute_on_host(host) do
+            execute :sudo, 'systemctl', 'stop', 'repmgrd', raise_on_non_zero_exit: false
+            execute :sudo, 'systemctl', 'disable', 'repmgrd', raise_on_non_zero_exit: false
+          end
+          return
+        end
 
         default_config = <<~CONF
           REPMGRD_ENABLED=yes

data/lib/active_postgres/configuration/node_identity.rb

@@ -0,0 +1,22 @@
+module ActivePostgres
+  class Configuration
+    module NodeIdentity
+      def node_id_for(host)
+        node = node_config_for(host)
+        raise Error, "Unknown PostgreSQL host: #{host}" unless node
+
+        value = node.fetch('node_id') { host == primary_host ? 1 : standby_hosts.index(host) + 2 }
+        raise Error, "node_id for #{host} must be a positive 32-bit integer" unless value.is_a?(Integer) && value.between?(1, 2_147_483_647)
+
+        value
+      end
+
+      private
+
+      def validate_node_ids!
+        node_ids = all_hosts.map { |host| node_id_for(host) }
+        raise Error, 'PostgreSQL node_id values must be unique' unless node_ids.uniq.size == node_ids.size
+      end
+    end
+  end
+end

data/lib/active_postgres/configuration/pgbackrest_policy.rb

@@ -0,0 +1,19 @@
+module ActivePostgres
+  class Configuration
+    module PgBackRestPolicy
+      private
+
+      def validate_pgbackrest!
+        return unless component_enabled?(:pgbackrest)
+
+        pg_config = component_config(:pgbackrest)
+        retention_full = pg_config[:retention_full]
+        retention_archive = pg_config[:retention_archive]
+        if retention_full && retention_archive && retention_archive.to_i < retention_full.to_i
+          raise Error, 'pgbackrest.retention_archive must be >= retention_full for PITR safety'
+        end
+        raise Error, 'pgbackrest.repo_block requires repo_bundle' if pg_config[:repo_block] && !pg_config[:repo_bundle]
+      end
+    end
+  end
+end

data/lib/active_postgres/configuration/standby_policy.rb

@@ -0,0 +1,24 @@
+module ActivePostgres
+  class Configuration
+    module StandbyPolicy
+      def standby_seed_method_for(host)
+        (standby_config_for(host)&.fetch('seed_method', nil) || 'repmgr').to_s.to_sym
+      end
+
+      private
+
+      def validate_standby_seed_methods!
+        @standbys.each do |standby|
+          host = standby.fetch('host')
+          seed_method = standby_seed_method_for(host)
+          unless %i[repmgr pgbackrest].include?(seed_method)
+            raise Error, "Invalid seed_method '#{seed_method}' for standby #{host}. Use 'repmgr' or 'pgbackrest'."
+          end
+          if seed_method == :pgbackrest && !component_enabled?(:pgbackrest)
+            raise Error, "Standby #{host} requires the pgbackrest component for seed_method 'pgbackrest'"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_postgres/configuration.rb

@@ -1,9 +1,16 @@
 require 'yaml'
+require_relative 'configuration/pgbackrest_policy'
+require_relative 'configuration/standby_policy'
+require_relative 'configuration/node_identity'
 
 module ActivePostgres
   class Configuration
-    attr_reader :environment, :version, :user, :ssh_key, :ssh_host_key_verification, :primary, :standbys, :components, :secrets_config,
-                :database_config
+    include PgBackRestPolicy
+    include StandbyPolicy
+    include NodeIdentity
+
+    attr_reader :environment, :version, :user, :ssh_key, :ssh_known_hosts_file, :ssh_host_key_verification,
+                :primary, :standbys, :jump_hosts, :components, :secrets_config, :database_config
 
     def initialize(config_hash, environment = 'development')
       @environment = environment
@@ -14,6 +21,7 @@ module ActivePostgres
       @version = env_config['version'] || 18
       @user = env_config['user'] || 'ubuntu'
       @ssh_key = File.expand_path(env_config['ssh_key'] || '~/.ssh/id_rsa')
+      @ssh_known_hosts_file = optional_path(env_config['ssh_known_hosts_file'])
       @ssh_host_key_verification = normalize_ssh_host_key_verification(
         env_config['ssh_host_key_verification'] || env_config['ssh_verify_host_key']
       )
@@ -21,6 +29,7 @@ module ActivePostgres
       @primary = env_config['primary'] || {}
       @standbys = env_config['standby'] || []
       @standbys = [@standbys] unless @standbys.is_a?(Array)
+      @jump_hosts = env_config['jump_hosts'] || {}
 
       @components = parse_components(env_config['components'] || {})
       @secrets_config = env_config['secrets'] || {}
@@ -111,6 +120,24 @@ module ActivePostgres
       @standbys.find { |s| s['host'] == host }
     end
 
+    def node_config_for(host)
+      return @primary if host == primary_host
+
+      standby_config_for(host)
+    end
+
+    def jump_host_config_for(host)
+      jump_host_name = node_config_for(host)&.dig('jump_host')
+      return unless jump_host_name
+
+      @jump_hosts[jump_host_name] || raise(Error, "Host #{host} jump_host not found: #{jump_host_name}")
+    end
+
+    def repmgr_config_for(host)
+      overrides = node_config_for(host)&.dig('repmgr') || {}
+      component_config(:repmgr).merge(symbolize_keys(overrides))
+    end
+
     def node_label_for(host)
       if host == primary_host
         @primary['label']
@@ -122,6 +149,8 @@ module ActivePostgres
     def validate!
       raise Error, 'No primary host defined' unless primary_host
 
+      validate_node_ids!
+
       # Validate required secrets if components are enabled
       raise Error, 'Missing replication_password secret' if component_enabled?(:repmgr) && !secrets_config['replication_password']
       raise Error, 'Missing monitoring_password secret' if component_enabled?(:monitoring) && !secrets_config['monitoring_password']
@@ -133,14 +162,7 @@ module ActivePostgres
           raise Error, 'monitoring.grafana.host is required when grafana is enabled'
         end
       end
-      if component_enabled?(:pgbackrest)
-        pg_config = component_config(:pgbackrest)
-        retention_full = pg_config[:retention_full]
-        retention_archive = pg_config[:retention_archive]
-        if retention_full && retention_archive && retention_archive.to_i < retention_full.to_i
-          raise Error, 'pgbackrest.retention_archive must be >= retention_full for PITR safety'
-        end
-      end
+      validate_pgbackrest!
 
       if component_enabled?(:pgbouncer)
         pgbouncer_app_hosts.each do |app_host|
@@ -149,6 +171,17 @@ module ActivePostgres
         end
       end
 
+      all_hosts.each do |host|
+        jump_host_name = node_config_for(host)&.dig('jump_host')
+        next unless jump_host_name
+
+        jump_host = @jump_hosts[jump_host_name]
+        raise Error, "Host #{host} jump_host not found: #{jump_host_name}" unless jump_host
+        raise Error, "Jump host #{jump_host_name} must include host" if jump_host['host'].to_s.strip.empty?
+      end
+
+      validate_standby_seed_methods!
+
       if component_enabled?(:repmgr)
         dns_failover = component_config(:repmgr)[:dns_failover]
         if dns_failover && dns_failover[:enabled]
@@ -246,12 +279,6 @@ module ActivePostgres
       result
     end
 
-    def node_config_for(host)
-      return @primary if host == primary_host
-
-      standby_config_for(host)
-    end
-
     def private_ip_for(node_config)
       return unless node_config
 
@@ -295,5 +322,9 @@ module ActivePostgres
       raise Error,
             "Invalid ssh_host_key_verification '#{value}'. Use 'always' or 'accept_new'."
     end
+
+    def optional_path(path)
+      File.expand_path(path) if path
+    end
   end
 end

data/lib/active_postgres/deployment_flow.rb

@@ -13,12 +13,16 @@ module ActivePostgres
       @skip_validation = skip_validation
     end
 
-    def execute
+    def execute(dry_run: false)
       ErrorHandler.with_handling(context: { operation: operation_name }) do
         print_header
         validate_prerequisites
         run_preflight_checks unless skip_validation
         print_deployment_plan
+        if dry_run
+          logger.info "\n[DRY RUN] No changes made."
+          return
+        end
         return unless confirm_deployment
 
         rollback_manager.with_rollback(description: operation_name) do

data/lib/active_postgres/generators/active_postgres/templates/postgres.yml.erb

@@ -57,6 +57,13 @@ shared: &shared
     
     pgbackrest:
       enabled: false
+      # For large, frequently changed relation files, bundle repository objects
+      # and back up changed blocks instead of copying each whole file.
+      # repo_bundle: true
+      # repo_block: true
+      # schedule_full: "0 2 * * 0"
+      # schedule_differential: "35 2 * * 1-6"
+      # schedule_incremental: "5 */4 * * *"
     
     monitoring:
       enabled: false

data/lib/active_postgres/installer.rb

@@ -28,7 +28,7 @@ module ActivePostgres
         rollback_manager: rollback_manager,
         skip_validation: skip_validation
       )
-      flow.execute
+      flow.execute(dry_run: dry_run)
     end
 
     def setup_component(component_name)
@@ -117,7 +117,7 @@ module ActivePostgres
         rollback_manager: rollback_manager,
         skip_validation: skip_validation
       )
-      flow.execute
+      flow.execute(dry_run: dry_run)
     end
   end
 end

data/lib/active_postgres/ssh_executor.rb

@@ -1,6 +1,8 @@
 require 'sshkit'
 require 'sshkit/dsl'
+require 'net/ssh/proxy/command'
 require 'securerandom'
+require 'shellwords'
 require 'stringio'
 
 module ActivePostgres
@@ -20,11 +22,11 @@ module ActivePostgres
     end
 
     def execute_on_host(host, &)
-      on("#{config.user}@#{host}", &)
+      on(ssh_host_for(host), &)
     end
 
     def execute_on_host_as(host, user, &)
-      on("#{user}@#{host}", &)
+      on(ssh_host_for(host, user:), &)
     end
 
     def execute_on_primary(&)
@@ -32,12 +34,12 @@ module ActivePostgres
     end
 
     def execute_on_standbys(&)
-      hosts = config.standby_hosts.map { |h| "#{config.user}@#{h}" }
+      hosts = config.standby_hosts.map { |host| ssh_host_for(host) }
       on(hosts, in: :parallel, &)
     end
 
     def execute_on_all_hosts(&)
-      hosts = config.all_hosts.map { |h| "#{config.user}@#{h}" }
+      hosts = config.all_hosts.map { |host| ssh_host_for(host) }
       on(hosts, in: :parallel, &)
     end
 
@@ -307,6 +309,8 @@ module ActivePostgres
           number_of_password_prompts: 0
         }
 
+        options[:user_known_hosts_file] = [config.ssh_known_hosts_file] if config.ssh_known_hosts_file
+
         if config.ssh_key && File.exist?(config.ssh_key)
           options[:keys] = [config.ssh_key]
           options[:keys_only] = true
@@ -315,5 +319,58 @@ module ActivePostgres
         ssh.ssh_options = options
       end
     end
+
+    def ssh_host_for(host, user: config.user)
+      ssh_host = SSHKit::Host.new(host)
+      ssh_host.user = user
+
+      node_config = config.node_config_for(host) || {}
+      ssh_host.port = node_config['ssh_port'] || node_config['port'] if node_config['ssh_port'] || node_config['port']
+
+      options = {
+        verify_host_key: config.ssh_host_key_verification || :always
+      }
+      options[:user_known_hosts_file] = [config.ssh_known_hosts_file] if config.ssh_known_hosts_file
+
+      if node_config['ssh_key']
+        options[:keys] = [File.expand_path(node_config['ssh_key'])]
+        options[:keys_only] = true
+      end
+
+      if (jump_host_config = config.jump_host_config_for(host))
+        options[:proxy] = jump_proxy(jump_host_config)
+      end
+
+      ssh_host.ssh_options = options
+      ssh_host
+    end
+
+    def jump_proxy(jump_host_config)
+      jump_user = jump_host_config['ssh_user'] || jump_host_config['user'] || config.user
+      jump_port = jump_host_config['ssh_port'] || jump_host_config['port']
+      jump_key = jump_host_config['ssh_key'] || config.ssh_key
+      command = [
+        'ssh',
+        '-F', '/dev/null',
+        '-o', 'BatchMode=yes',
+        '-o', 'ForwardAgent=no',
+        '-o', "StrictHostKeyChecking=#{open_ssh_host_key_mode}"
+      ]
+
+      command.push('-o', "UserKnownHostsFile=#{config.ssh_known_hosts_file}") if config.ssh_known_hosts_file
+
+      command.push('-i', File.expand_path(jump_key), '-o', 'IdentitiesOnly=yes') if
+        jump_key && File.exist?(File.expand_path(jump_key))
+
+      command.push('-p', jump_port.to_s) if jump_port
+      command.push('-W', '%h:%p', "#{jump_user}@#{jump_host_config.fetch('host')}")
+
+      command_line = Shellwords.join(command).gsub('\\%h', '%h').gsub('\\%p', '%p')
+      Net::SSH::Proxy::Command.new(command_line)
+    end
+
+    def open_ssh_host_key_mode
+      config.ssh_host_key_verification == :accept_new ? 'accept-new' : 'yes'
+    end
   end
 end

data/lib/active_postgres/standby_deployment_flow.rb

@@ -21,9 +21,9 @@ module ActivePostgres
     def validate_specific_requirements
       abort "❌ #{standby_host} is not configured as a standby in config/postgres.yml" unless config.standby_hosts.include?(standby_host)
 
-      return if config.component_enabled?(:repmgr)
+      abort '❌ repmgr component must be enabled to setup standbys' unless config.component_enabled?(:repmgr)
 
-      abort '❌ repmgr component must be enabled to setup standbys'
+      validate_required_secrets!
     end
 
     def run_preflight_checks
@@ -49,17 +49,22 @@ module ActivePostgres
 
     def list_deployment_steps
       logger.info "  • Install PostgreSQL #{config.version} packages on #{standby_host}"
-      logger.info "  • Clone data from primary: #{config.primary_host}"
+      if config.standby_seed_method_for(standby_host) == :pgbackrest
+        logger.info '  • Restore the latest valid pgBackRest backup as a standby'
+      else
+        logger.info "  • Clone data from primary: #{config.primary_host}"
+      end
       logger.info '  • Register standby with repmgr cluster'
     end
 
     def list_warnings
-      logger.info "\n⚠️  Primary database will NOT be touched"
+      logger.info "\n⚠️  Primary stays online; setup performs idempotent role and repmgr checks"
     end
 
     def deploy_components
       deploy_ssl if config.component_enabled?(:ssl)
       deploy_core
+      deploy_pgbackrest if config.component_enabled?(:pgbackrest)
       deploy_repmgr
       deploy_optional_components
     end
@@ -79,8 +84,15 @@ module ActivePostgres
       end
     end
 
+    def deploy_pgbackrest
+      logger.task('Installing pgBackRest on standby') do
+        component = Components::PgBackRest.new(config, ssh_executor, secrets)
+        component.install_on_standby(standby_host)
+      end
+    end
+
     def deploy_repmgr
-      logger.task('Setting up repmgr and cloning from primary') do
+      logger.task('Setting up repmgr and seeding standby') do
         component = Components::Repmgr.new(config, ssh_executor, secrets)
         register_rollback('repmgr', component)
         component.setup_standby_only(standby_host)
@@ -107,13 +119,39 @@ module ActivePostgres
     end
 
     def register_rollback(component_name, component)
-      rollback_manager.register("Uninstall #{component_name} on #{standby_host}", host: standby_host) do
-        component.uninstall
+      target_host = standby_host
+      captured_logger = logger
+
+      rollback_manager.register("Uninstall #{component_name} on #{target_host}") do
+        if component.respond_to?(:uninstall_from)
+          component.uninstall_from(target_host)
+        else
+          component.uninstall
+        end
       rescue StandardError => e
-        logger.warn "Failed to uninstall #{component_name} on #{standby_host}: #{e.message}"
+        captured_logger.warn "Failed to uninstall #{component_name} on #{target_host}: #{e.message}"
       end
     end
 
+    def validate_required_secrets!
+      required = %w[repmgr_password replication_password]
+      required.push('ssl_cert', 'ssl_key') if config.component_enabled?(:ssl)
+      required << 'monitoring_password' if config.component_enabled?(:monitoring)
+
+      if config.component_enabled?(:pgbackrest)
+        pgbackrest = secrets.resolve_value(config.component_config(:pgbackrest))
+        if pgbackrest[:repo_type] == 's3'
+          required.push('s3_access_key', 's3_secret_key')
+          raise Error, 'pgbackrest.s3_bucket did not resolve' if pgbackrest[:s3_bucket].to_s.empty?
+        end
+      end
+
+      missing = required.uniq.select { |key| secrets.resolve(key).to_s.empty? }
+      return if missing.empty?
+
+      raise Error, "Required standby secrets did not resolve: #{missing.join(', ')}"
+    end
+
     def list_next_steps
       logger.info '  1. Check cluster status: active_postgres status'
       logger.info '  2. Verify replication: Check repmgr cluster show'

data/lib/active_postgres/version.rb

@@ -1,3 +1,3 @@
 module ActivePostgres
-  VERSION = '0.9.6'.freeze
+  VERSION = '0.9.8'.freeze
 end

data/templates/pgbackrest.conf.erb

@@ -40,6 +40,15 @@ repo1-path=<%= pgbackrest_config[:repo_path] || '/var/lib/pgbackrest' %>
 repo1-retention-full=<%= pgbackrest_config[:retention_full] || 7 %>
 repo1-retention-archive=<%= pgbackrest_config[:retention_archive] || 14 %>
 
+<% if pgbackrest_config[:repo_bundle] %>
+# Bundle small files and metadata into fewer repository objects.
+repo1-bundle=y
+<% end %>
+<% if pgbackrest_config[:repo_block] %>
+# Back up changed blocks instead of entire relation files.
+repo1-block=y
+<% end %>
+
 # Compression
 compress-type=lz4
 compress-level=3
@@ -69,4 +78,3 @@ pg1-path=/var/lib/postgresql/<%= config.version %>/main
 pg1-port=5432
 pg1-socket-path=/var/run/postgresql
 pg1-user=<%= config.postgres_user %>
-

data/templates/repmgr.conf.erb

@@ -9,7 +9,7 @@
     end
   end
 %>
-node_id=<%= host == config.primary_host ? 1 : config.standby_hosts.index(host) + 2 %>
+node_id=<%= config.node_id_for(host) %>
 node_name='<%= node_label %>'
 <%
   # conninfo describes how OTHER nodes connect to THIS node

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_postgres
 version: !ruby/object:Gem::Version
-  version: 0.9.6
+  version: 0.9.8
 platform: ruby
 authors:
 - BoringCache
@@ -126,6 +126,9 @@ files:
 - lib/active_postgres/components/repmgr.rb
 - lib/active_postgres/components/ssl.rb
 - lib/active_postgres/configuration.rb
+- lib/active_postgres/configuration/node_identity.rb
+- lib/active_postgres/configuration/pgbackrest_policy.rb
+- lib/active_postgres/configuration/standby_policy.rb
 - lib/active_postgres/connection_pooler.rb
 - lib/active_postgres/credentials.rb
 - lib/active_postgres/deployment_flow.rb