active_postgres 0.8.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0266b3f7dabc2d844b30aa6410cfd7c59131a7fb77a2dea85f01f9a66c2a2443
-  data.tar.gz: fd720306229f1ddea1d4e01a9dc3a5df3b7a60a620c38e86779e82f9698ebcbc
+  metadata.gz: c89909c556964abfe7dbede0550c7fa1fbd60fc332e667fce5de858114ba2146
+  data.tar.gz: e715719391d53f89cb394203018a5e2951f2602018ef97a417ee369d443e410c
 SHA512:
-  metadata.gz: bb3bc17966f9ebe98a55f09f678fe2bc2e57b92615c45848c347a7568f6e3bb61d15788d6bb16008e4498a9b944a3f53241f2e2579b204d28679341b041f4978
-  data.tar.gz: 3863cace22d1ba3aea901d312d26152de067c7ca898ddff5b654a75702a9e6b4c01f6ffbac820fed338fc5db8ce011ad39676143f81f785f66f7fec72cd72ae5
+  metadata.gz: 603d5b28ef5730d595b24bf36b517148a882c5889d339675545fc98ffda547d8c1ead15ff8ee6a048fd6b117b5e257309460e7b5e25a9ee5eb4e55c730050ba4
+  data.tar.gz: 50f632e74185dc90d7da5e6ece125fc625b04665cc4859ca7fd3d136e82df6e295b5fde10d8a2239675ce67a1a527f24ef8ec00cfeff79c57d84601a11168105

data/README.md

@@ -7,7 +7,7 @@ Production-grade PostgreSQL HA for Rails.
 - **High Availability**: Primary/standby replication with automatic failover (repmgr)
 - **Connection Pooling**: PgBouncer integration
 - **Rails Integration**: Automatic database.yml config, migration guard, read replica routing
-- **Modular Components**: Core, Performance Tuning, repmgr, PgBouncer, pgBackRest, Monitoring, SSL, Extensions
+- **Modular Components**: Core, Performance Tuning (opt-in), repmgr, PgBouncer, pgBackRest, Monitoring, SSL, Extensions
 
 ## Quick Start
 
@@ -48,6 +48,7 @@ production:
     superuser_password: $POSTGRES_SUPERUSER_PASSWORD
     replication_password: $POSTGRES_REPLICATION_PASSWORD
     repmgr_password: $POSTGRES_REPMGR_PASSWORD
+    monitoring_password: $POSTGRES_MONITORING_PASSWORD
     app_password: $POSTGRES_APP_PASSWORD
 ```
 
@@ -68,6 +69,8 @@ postgres:
 ```bash
 rake postgres:setup   # Deploy cluster
 rake postgres:status  # Check health
+rake postgres:overview  # Control tower overview
+rake postgres:help    # Task summary
 ```
 
 ## Common Operations
@@ -82,8 +85,10 @@ rake postgres:promote[host]            # Promote standby to primary
 
 # Backups (requires pgBackRest)
 rake postgres:backup:full
+rake postgres:backup:incremental
 rake postgres:backup:list
 rake postgres:backup:restore[backup_id]
+rake postgres:backup:restore_at["2026-01-29 01:15:00",promote]
 
 # Credential rotation (zero downtime)
 rake postgres:credentials:rotate_random
@@ -100,6 +105,7 @@ rake postgres:update:patch             # Security patches
 active_postgres setup --environment=production
 active_postgres setup-standby HOST
 active_postgres status
+active_postgres overview
 active_postgres promote HOST
 active_postgres backup --type=full
 active_postgres cache-secrets
@@ -110,14 +116,134 @@ active_postgres cache-secrets
 | Component | Description | Config |
 |-----------|-------------|--------|
 | **Core** | PostgreSQL installation | Always enabled |
-| **Performance Tuning** | Auto-optimization | Enabled by default |
+| **Performance Tuning** | Auto-optimization | Disabled by default |
 | **repmgr** | HA & automatic failover | `repmgr: {enabled: true}` |
 | **PgBouncer** | Connection pooling | `pgbouncer: {enabled: true}` |
 | **pgBackRest** | Backup & restore | `pgbackrest: {enabled: true}` |
-| **Monitoring** | postgres_exporter | `monitoring: {enabled: true}` |
+| **Monitoring** | postgres_exporter + optional node_exporter/Grafana | `monitoring: {enabled: true}` |
 | **SSL** | Encrypted connections | `ssl: {enabled: true}` |
 | **Extensions** | pgvector, PostGIS, etc. | `extensions: {enabled: true, list: [pgvector]}` |
 
+### Monitoring credentials
+
+`postgres_exporter` uses a dedicated `pg_monitor` user. Provide a password in secrets and optionally set the username.
+Enable node_exporter for host-level metrics, and Grafana if you want a local UI:
+
+```yaml
+components:
+  monitoring:
+    enabled: true
+    user: postgres_exporter
+    node_exporter: true
+    node_exporter_port: 9100
+    # node_exporter_listen_address: 10.8.0.10
+    # grafana:
+    #   enabled: true
+    #   host: grafana.example.com
+    #   listen_address: 10.8.0.10
+    #   port: 3000
+    #   prometheus_url: http://prometheus.example.com:9090
+secrets:
+  monitoring_password: $POSTGRES_MONITORING_PASSWORD
+  # grafana_admin_password: $GRAFANA_ADMIN_PASSWORD
+```
+
+When Grafana is enabled, `grafana_admin_password` is required and Grafana will be installed
+on the configured host. If `prometheus_url` is provided, a Prometheus datasource is provisioned.
+
+### pgBackRest S3-compatible endpoints
+
+For Tigris/MinIO/Wasabi/DO Spaces, set a custom endpoint and use path-style URLs:
+
+```yaml
+components:
+  pgbackrest:
+    enabled: true
+    repo_type: s3
+    s3_bucket: myapp-backups
+    s3_region: auto
+    s3_endpoint: t3.storage.dev
+    s3_uri_style: path
+```
+
+### Point-in-time recovery (PITR)
+
+Ensure WAL retention is long enough for your recovery window:
+
+```yaml
+components:
+  pgbackrest:
+    retention_full: 7
+    retention_archive: 14
+    # You can schedule full + incremental separately:
+    # schedule_full: "0 2 * * *"
+    # schedule_incremental: "0 * * * *"
+```
+
+Run a PITR restore:
+
+```bash
+rake postgres:backup:restore_at["2026-01-29 01:15:00",promote]
+```
+
+If you want the old primary to rejoin without a full re-clone after failover,
+enable pg_rewind support in repmgr:
+
+```yaml
+components:
+  repmgr:
+    use_rewind: true
+```
+
+### Stable app endpoint with PgBouncer
+
+If you run PgBouncer on each PostgreSQL node and want a fixed app URL, enable `follow_primary`.
+Each PgBouncer instance periodically repoints to the current primary using repmgr metadata.
+Put a TCP load balancer or DNS record in front of the PgBouncer nodes.
+
+```yaml
+components:
+  pgbouncer:
+    enabled: true
+    follow_primary: true
+    follow_primary_interval: 5
+```
+
+### Automatic DNS updates on failover (dnsmasq)
+
+If you use Messhy’s mesh DNS (dnsmasq), repmgr can update writer/reader DNS records on failover.
+Enable `dns_failover` under `repmgr` and provide DNS server IPs or hostnames.
+If you run setup from outside the mesh, use objects with both the public SSH host
+and the private WireGuard IP so setup can SSH in and failover updates stay on the mesh.
+If you run setup from inside the mesh, you can use a simple list of private IPs.
+
+```yaml
+components:
+  repmgr:
+    enabled: true
+    dns_failover:
+      enabled: true
+      provider: dnsmasq
+      domain: mesh.internal
+      # Or use multiple domains during cutover:
+      # domains: [mesh.internal, mesh.v2.internal]
+      dns_servers:
+        - host: 18.170.173.14
+          private_ip: 10.8.0.10
+        - host: 98.85.183.175
+          private_ip: 10.8.0.110
+      primary_record: db-primary.mesh.internal
+      replica_record: db-replica.mesh.internal
+      # Or multiple records explicitly:
+      # primary_records: [db-primary.mesh.internal, db-primary.mesh.v2.internal]
+      # replica_records: [db-replica.mesh.internal, db-replica.mesh.v2.internal]
+```
+
+This installs an event hook so repmgr updates `/etc/dnsmasq.d/active_postgres.conf`
+on the DNS servers whenever the primary changes.
+DNS servers must be reachable over the private network and allow SSH from the
+database nodes (active_postgres installs SSH keys on first setup).
+
 ## Secrets Management
 
 ```yaml
@@ -127,7 +253,8 @@ secrets:
 
   # Command execution
   password: $(op read "op://vault/item/field")
-  password: $(rails runner "puts Rails.application.credentials.dig(:postgres, :password)")
+  password: rails_credentials:postgres.password
+  password: credentials:postgres.password
 
   # AWS Secrets Manager
   password: $(aws secretsmanager get-secret-value --secret-id myapp/postgres --query SecretString)
@@ -150,9 +277,19 @@ User.all                     # → Replica
 - Ruby 3.0+
 - PostgreSQL 12+
 - Ubuntu 20.04+ / Debian 11+ with systemd
-- SSH key-based authentication
+- SSH key-based authentication (hosts must be in `~/.ssh/known_hosts`)
 - Rails 6.0+ (optional)
 
+### SSH host key verification
+
+By default, host keys are verified strictly (`always`). For first-time provisioning you can set:
+
+```yaml
+ssh_host_key_verification: accept_new
+```
+
+This trusts a host key the first time and then pins it; prefer `always` once hosts are known.
+
 ## License
 
 MIT

data/lib/active_postgres/cli.rb

@@ -49,6 +49,13 @@ module ActivePostgres
       health_checker.show_status
     end
 
+    desc 'overview', 'Show control tower overview'
+    def overview
+      config = load_config
+      overview = Overview.new(config)
+      overview.show
+    end
+
     desc 'health', 'Run health checks'
     def health
       config = load_config

data/lib/active_postgres/components/core.rb

@@ -189,14 +189,9 @@ module ActivePostgres
         app_password = resolve_app_password
         sql = build_app_user_sql(app_user, app_database, app_password)
 
-        ssh_executor.execute_on_host(host) do
-          upload! StringIO.new(sql), '/tmp/create_app_user.sql'
-          execute :chmod, '644', '/tmp/create_app_user.sql'
-          execute :sudo, '-u', 'postgres', 'psql', '-f', '/tmp/create_app_user.sql'
-          execute :rm, '-f', '/tmp/create_app_user.sql'
+        ssh_executor.run_sql(host, sql, postgres_user: 'postgres', tuples_only: false, capture: false)
 
-          puts "  ✓ Created app user '#{app_user}' and database '#{app_database}'"
-        end
+        puts "  ✓ Created app user '#{app_user}' and database '#{app_database}'"
       rescue StandardError => e
         warn "  Warning: Could not create app user: #{e.message}"
         warn '  You may need to create the user manually'

data/lib/active_postgres/components/extensions.rb

@@ -33,17 +33,27 @@ module ActivePostgres
         puts 'Extensions uninstall not implemented (extensions remain in database)'
       end
 
-      private
+      def restart
+        puts 'Extensions do not require restart (loaded at database connection time)'
+      end
 
-      def install_on_primary(extensions)
-        host = config.primary_host
-        version = config.version
-        db_name = config.secrets_config['database_name'] || 'postgres'
-        postgres_user = config.postgres_user
+      def install_on_standby(standby_host)
+        extensions_config = config.component_config(:extensions)
+        return unless extensions_config[:enabled]
 
-        puts "  Installing extensions on primary (#{host})..."
+        extensions = extensions_config[:list] || []
+        return if extensions.empty?
+
+        puts "Installing extension packages on standby #{standby_host}..."
+        install_packages_on_host(standby_host, extensions)
+      end
+
+      private
 
+      def install_packages_on_host(host, extensions)
+        version = config.version
         packages_to_install = []
+
         extensions.each do |ext_name|
           package = EXTENSION_PACKAGES[ext_name]
           next unless package
@@ -52,46 +62,41 @@ module ActivePostgres
           packages_to_install << package
         end
 
+        return if packages_to_install.empty?
+
         ssh_executor.execute_on_host(host) do
-          unless packages_to_install.empty?
-            execute :sudo, 'apt-get', 'update', '-qq'
-            execute :sudo, 'DEBIAN_FRONTEND=noninteractive', 'apt-get', 'install', '-y', '-qq',
-                    *packages_to_install
-          end
+          execute :sudo, 'apt-get', 'update', '-qq'
+          execute :sudo, 'DEBIAN_FRONTEND=noninteractive', 'apt-get', 'install', '-y', '-qq',
+                  *packages_to_install
+        end
+      end
+
+      def install_on_primary(extensions)
+        host = config.primary_host
+        db_name = config.secrets_config['database_name'] || 'postgres'
+        postgres_user = config.postgres_user
+
+        puts "  Installing extensions on primary (#{host})..."
+
+        install_packages_on_host(host, extensions)
 
+        ssh_executor.execute_on_host(host) do
           extensions.each do |ext_name|
-            sql = "CREATE EXTENSION IF NOT EXISTS #{ext_name};"
+            sql = "CREATE EXTENSION IF NOT EXISTS \"#{ext_name}\";"
             begin
               execute :sudo, '-u', postgres_user, 'psql', '-d', db_name, '-c', sql
-            rescue StandardError
-              nil
+              info "✓ Extension #{ext_name} created/verified"
+            rescue StandardError => e
+              warn "⚠ Could not create extension #{ext_name}: #{e.message}"
             end
           end
         end
       end
 
       def install_on_standbys(extensions)
-        version = config.version
-
         config.standby_hosts.each do |host|
-          puts "  Installing extensions on standby (#{host})..."
-
-          packages_to_install = []
-          extensions.each do |ext_name|
-            package = EXTENSION_PACKAGES[ext_name]
-            next unless package
-
-            package = package.gsub('{version}', version.to_s)
-            packages_to_install << package
-          end
-
-          ssh_executor.execute_on_host(host) do
-            unless packages_to_install.empty?
-              execute :sudo, 'apt-get', 'update', '-qq'
-              execute :sudo, 'DEBIAN_FRONTEND=noninteractive', 'apt-get', 'install', '-y', '-qq',
-                      *packages_to_install
-            end
-          end
+          puts "  Installing extension packages on standby (#{host})..."
+          install_packages_on_host(host, extensions)
         end
       end
     end

data/lib/active_postgres/components/monitoring.rb

@@ -1,12 +1,18 @@
+require 'cgi'
+
 module ActivePostgres
   module Components
     class Monitoring < Base
       def install
         puts 'Installing postgres_exporter for monitoring...'
 
+        ensure_monitoring_user
+
         config.all_hosts.each do |host|
           install_on_host(host)
         end
+
+        install_grafana_if_enabled
       end
 
       def uninstall
@@ -14,10 +20,19 @@ module ActivePostgres
 
         config.all_hosts.each do |host|
           ssh_executor.execute_on_host(host) do
-            execute :sudo, 'systemctl', 'stop', 'postgres_exporter'
-            execute :sudo, 'systemctl', 'disable', 'postgres_exporter'
+            execute :sudo, 'systemctl', 'stop', 'prometheus-postgres-exporter'
+            execute :sudo, 'systemctl', 'disable', 'prometheus-postgres-exporter'
+            execute :sudo, 'apt-get', 'remove', '-y', 'prometheus-postgres-exporter'
+
+            if node_exporter_enabled?
+              execute :sudo, 'systemctl', 'stop', 'prometheus-node-exporter'
+              execute :sudo, 'systemctl', 'disable', 'prometheus-node-exporter'
+              execute :sudo, 'apt-get', 'remove', '-y', 'prometheus-node-exporter'
+            end
           end
         end
+
+        uninstall_grafana_if_enabled
       end
 
       def restart
@@ -25,11 +40,17 @@ module ActivePostgres
 
         config.all_hosts.each do |host|
           ssh_executor.execute_on_host(host) do
-            execute :sudo, 'systemctl', 'restart', 'postgres_exporter'
+            execute :sudo, 'systemctl', 'restart', 'prometheus-postgres-exporter'
+            execute :sudo, 'systemctl', 'restart', 'prometheus-node-exporter' if node_exporter_enabled?
           end
         end
       end
 
+      def install_on_standby(standby_host)
+        puts "Installing postgres_exporter on standby #{standby_host}..."
+        install_on_host(standby_host)
+      end
+
       private
 
       def install_on_host(host)
@@ -42,13 +63,244 @@ module ActivePostgres
         ssh_executor.execute_on_host(host) do
           # Install via package manager or download binary
           execute :sudo, 'apt-get', 'install', '-y', '-qq', 'prometheus-postgres-exporter'
+        end
+
+        configure_exporter_service(host, monitoring_config, exporter_port)
 
+        ssh_executor.execute_on_host(host) do
           # Enable and start
           execute :sudo, 'systemctl', 'enable', 'prometheus-postgres-exporter'
-          execute :sudo, 'systemctl', 'start', 'prometheus-postgres-exporter'
+          execute :sudo, 'systemctl', 'restart', 'prometheus-postgres-exporter'
         end
 
         puts "  Metrics available at: http://#{host}:#{exporter_port}/metrics"
+
+        install_node_exporter(host, monitoring_config) if node_exporter_enabled?
+      end
+
+      def ensure_monitoring_user
+        monitoring_config = config.component_config(:monitoring)
+        monitoring_user = monitoring_config[:user] || 'postgres_exporter'
+        monitoring_password = normalize_monitoring_password(secrets.resolve('monitoring_password'))
+
+        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)
+      end
+
+      def build_monitoring_user_sql(user, password)
+        escaped_password = password.gsub("'", "''")
+
+        [
+          'DO $$',
+          'BEGIN',
+          "  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '#{user}') THEN",
+          "    CREATE USER #{user} WITH LOGIN PASSWORD '#{escaped_password}';",
+          '  ELSE',
+          "    ALTER USER #{user} WITH LOGIN PASSWORD '#{escaped_password}';",
+          '  END IF;',
+          'END $$;',
+          '',
+          "GRANT pg_monitor TO #{user};",
+          ''
+        ].join("\n")
+      end
+
+      def configure_exporter_service(host, monitoring_config, exporter_port)
+        monitoring_user = monitoring_config[:user] || 'postgres_exporter'
+        monitoring_password = normalize_monitoring_password(secrets.resolve('monitoring_password'))
+
+        dsn = build_exporter_dsn(monitoring_config, monitoring_user, monitoring_password)
+        override = <<~CONF
+          [Service]
+          Environment="DATA_SOURCE_NAME=#{escape_systemd_env(dsn)}"
+          Environment="PG_EXPORTER_WEB_LISTEN_ADDRESS=:#{exporter_port}"
+        CONF
+
+        ssh_executor.execute_on_host(host) do
+          execute :sudo, 'mkdir', '-p', '/etc/systemd/system/prometheus-postgres-exporter.service.d'
+          upload! StringIO.new(override), '/tmp/prometheus-postgres-exporter.override'
+          execute :sudo, 'mv', '/tmp/prometheus-postgres-exporter.override',
+                  '/etc/systemd/system/prometheus-postgres-exporter.service.d/override.conf'
+          execute :sudo, 'chown', 'root:root', '/etc/systemd/system/prometheus-postgres-exporter.service.d/override.conf'
+          execute :sudo, 'chmod', '600', '/etc/systemd/system/prometheus-postgres-exporter.service.d/override.conf'
+          execute :sudo, 'systemctl', 'daemon-reload'
+        end
+      end
+
+      def build_exporter_dsn(monitoring_config, monitoring_user, monitoring_password)
+        host = monitoring_config[:database_host] || 'localhost'
+        port = monitoring_config[:database_port] || 5432
+        database = monitoring_config[:database] || 'postgres'
+        sslmode = config.component_enabled?(:ssl) ? 'require' : 'prefer'
+
+        encoded_password = CGI.escape(monitoring_password.to_s)
+        "postgresql://#{monitoring_user}:#{encoded_password}@#{host}:#{port}/#{database}?sslmode=#{sslmode}"
+      end
+
+      def normalize_monitoring_password(raw_password)
+        password = raw_password.to_s.rstrip
+
+        raise Error, 'monitoring_password secret is missing (required for monitoring)' if password.empty?
+
+        password
+      end
+
+      def node_exporter_enabled?
+        monitoring_config = config.component_config(:monitoring)
+        monitoring_config.fetch(:node_exporter, false) == true
+      end
+
+      def install_node_exporter(host, monitoring_config)
+        port = monitoring_config[:node_exporter_port] || 9100
+        listen_address = monitoring_config[:node_exporter_listen_address].to_s.strip
+        puts "  Installing node_exporter on #{host}..."
+
+        ssh_executor.execute_on_host(host) do
+          execute :sudo, 'apt-get', 'install', '-y', '-qq', 'prometheus-node-exporter'
+        end
+
+        configure_node_exporter_service(host, port, listen_address)
+
+        ssh_executor.execute_on_host(host) do
+          execute :sudo, 'systemctl', 'enable', 'prometheus-node-exporter'
+          execute :sudo, 'systemctl', 'restart', 'prometheus-node-exporter'
+        end
+
+        puts "  Node metrics available at: http://#{host}:#{port}/metrics"
+      end
+
+      def configure_node_exporter_service(host, port, listen_address)
+        listen = if listen_address.empty?
+                   ":#{port}"
+                 else
+                   "#{listen_address}:#{port}"
+                 end
+
+        return if listen == ':9100'
+
+        override = <<~CONF
+          [Service]
+          ExecStart=
+          ExecStart=/usr/bin/prometheus-node-exporter --web.listen-address=#{listen}
+        CONF
+
+        ssh_executor.execute_on_host(host) do
+          execute :sudo, 'mkdir', '-p', '/etc/systemd/system/prometheus-node-exporter.service.d'
+          upload! StringIO.new(override), '/tmp/prometheus-node-exporter.override'
+          execute :sudo, 'mv', '/tmp/prometheus-node-exporter.override',
+                  '/etc/systemd/system/prometheus-node-exporter.service.d/override.conf'
+          execute :sudo, 'chown', 'root:root', '/etc/systemd/system/prometheus-node-exporter.service.d/override.conf'
+          execute :sudo, 'chmod', '644', '/etc/systemd/system/prometheus-node-exporter.service.d/override.conf'
+          execute :sudo, 'systemctl', 'daemon-reload'
+        end
+      end
+
+      def install_grafana_if_enabled
+        monitoring_config = config.component_config(:monitoring)
+        grafana_config = monitoring_config[:grafana] || {}
+        return unless grafana_config[:enabled]
+
+        host = grafana_config[:host].to_s.strip
+        raise Error, 'monitoring.grafana.host is required when grafana is enabled' if host.empty?
+
+        admin_password = normalize_grafana_password(secrets.resolve('grafana_admin_password'))
+        prometheus_url = grafana_config[:prometheus_url]
+        listen_address = grafana_config[:listen_address].to_s.strip
+        port = (grafana_config[:port] || 3000).to_i
+
+        puts "Installing Grafana on #{host}..."
+
+        ssh_executor.execute_on_host(host) do
+          execute :sudo, 'apt-get', 'install', '-y', '-qq', 'apt-transport-https', 'software-properties-common', 'wget'
+          execute :sudo, 'wget', '-q', '-O', '/usr/share/keyrings/grafana.gpg', 'https://apt.grafana.com/gpg.key'
+          execute :sudo, 'sh', '-c',
+                  'echo "deb [signed-by=/usr/share/keyrings/grafana.gpg] https://apt.grafana.com stable main" > /etc/apt/sources.list.d/grafana.list'
+          execute :sudo, 'apt-get', 'update', '-qq'
+          execute :sudo, 'apt-get', 'install', '-y', '-qq', 'grafana'
+          execute :sudo, 'systemctl', 'enable', '--now', 'grafana-server'
+          execute :sudo, 'grafana-cli', 'admin', 'reset-admin-password', admin_password
+        end
+
+        configure_grafana_service(host, listen_address, port)
+        configure_grafana_datasource(host, prometheus_url) if prometheus_url
+
+        puts "  Grafana available at: http://#{host}:#{port}"
+      end
+
+      def configure_grafana_service(host, listen_address, port)
+        env_lines = []
+        env_lines << "Environment=\"GF_SERVER_HTTP_ADDR=#{listen_address}\"" unless listen_address.empty?
+        env_lines << "Environment=\"GF_SERVER_HTTP_PORT=#{port}\"" if port && port != 3000
+        return if env_lines.empty?
+
+        override = <<~CONF
+          [Service]
+          #{env_lines.join("\n  ")}
+        CONF
+
+        ssh_executor.execute_on_host(host) do
+          execute :sudo, 'mkdir', '-p', '/etc/systemd/system/grafana-server.service.d'
+          upload! StringIO.new(override), '/tmp/active_postgres_grafana.override'
+          execute :sudo, 'mv', '/tmp/active_postgres_grafana.override',
+                  '/etc/systemd/system/grafana-server.service.d/override.conf'
+          execute :sudo, 'chown', 'root:root', '/etc/systemd/system/grafana-server.service.d/override.conf'
+          execute :sudo, 'chmod', '644', '/etc/systemd/system/grafana-server.service.d/override.conf'
+          execute :sudo, 'systemctl', 'daemon-reload'
+          execute :sudo, 'systemctl', 'restart', 'grafana-server'
+        end
+      end
+
+      def uninstall_grafana_if_enabled
+        monitoring_config = config.component_config(:monitoring)
+        grafana_config = monitoring_config[:grafana] || {}
+        return unless grafana_config[:enabled]
+
+        host = grafana_config[:host].to_s.strip
+        return if host.empty?
+
+        ssh_executor.execute_on_host(host) do
+          execute :sudo, 'systemctl', 'stop', 'grafana-server'
+          execute :sudo, 'systemctl', 'disable', 'grafana-server'
+          execute :sudo, 'apt-get', 'remove', '-y', 'grafana'
+          execute :sudo, 'rm', '-f', '/etc/apt/sources.list.d/grafana.list'
+          execute :sudo, 'rm', '-f', '/usr/share/keyrings/grafana.gpg'
+          execute :sudo, 'rm', '-rf', '/etc/grafana/provisioning/datasources/active_postgres.yml'
+        end
+      end
+
+      def configure_grafana_datasource(host, prometheus_url)
+        datasource = <<~YAML
+          apiVersion: 1
+          datasources:
+            - name: Prometheus
+              type: prometheus
+              access: proxy
+              url: #{prometheus_url}
+              isDefault: true
+        YAML
+
+        ssh_executor.execute_on_host(host) do
+          execute :sudo, 'mkdir', '-p', '/etc/grafana/provisioning/datasources'
+          upload! StringIO.new(datasource), '/tmp/active_postgres_grafana_ds.yml'
+          execute :sudo, 'mv', '/tmp/active_postgres_grafana_ds.yml', '/etc/grafana/provisioning/datasources/active_postgres.yml'
+          execute :sudo, 'chown', 'root:root', '/etc/grafana/provisioning/datasources/active_postgres.yml'
+          execute :sudo, 'chmod', '644', '/etc/grafana/provisioning/datasources/active_postgres.yml'
+          execute :sudo, 'systemctl', 'restart', 'grafana-server'
+        end
+      end
+
+      def normalize_grafana_password(raw_password)
+        password = raw_password.to_s.rstrip
+
+        raise Error, 'grafana_admin_password secret is missing (required for grafana)' if password.empty?
+
+        password
+      end
+
+      def escape_systemd_env(value)
+        value.to_s.gsub('\\', '\\\\').gsub('"', '\\"')
       end
     end
   end