active_postgres 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dbeebfa934a6587194e20aa39a3d459b7db2568c996f4faec1b781d70a4254ee
+  data.tar.gz: 47867c12a1fbb44652da9a79bb775ce38aaf8ff7b527a0a14ce0e042ca091877
+SHA512:
+  metadata.gz: cd6849746528e378cc7e5d3c7707b20d974dc44cc10e61f4600b7eaccbfd7c9793e20b8741ae7339ab866618aa7357ee6781bf4d7ba7ee0eff959ad9c0af1b24
+  data.tar.gz: fc7635c0908c5920e4f21f702badd030c305819b05e63e6a0a6b54793b563e7338738445d38f11e1269566afba9fb0e6efcbea436287ace088518f6bce42a777

data/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2024 Gaurav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

data/README.md

@@ -0,0 +1,158 @@
+# active_postgres
+
+Production-grade PostgreSQL HA for Rails.
+
+## Features
+
+- **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
+
+## Quick Start
+
+### 1. Install
+
+```bash
+gem install active_postgres
+# or add to Gemfile: gem 'active_postgres'
+```
+
+### 2. Configure (Rails)
+
+```bash
+rails generate active_postgres:install
+```
+
+Edit `config/postgres.yml`:
+
+```yaml
+production:
+  version: 18
+  user: ubuntu
+  ssh_key: ~/.ssh/id_rsa
+
+  primary:
+    host: 34.12.234.81        # Public IP for SSH
+    private_ip: 10.8.0.10     # Private IP for database connections
+
+  standby:
+    - host: 52.23.45.67
+      private_ip: 10.8.0.11
+
+  components:
+    repmgr: {enabled: true}
+    pgbouncer: {enabled: true}
+
+  secrets:
+    superuser_password: $POSTGRES_SUPERUSER_PASSWORD
+    replication_password: $POSTGRES_REPLICATION_PASSWORD
+    repmgr_password: $POSTGRES_REPMGR_PASSWORD
+    app_password: $POSTGRES_APP_PASSWORD
+```
+
+Add credentials (`rails credentials:edit`):
+
+```yaml
+postgres:
+  username: myapp
+  password: "your_app_password"
+  database: myapp_production
+  primary_host: 10.8.0.10
+  replica_host: 10.8.0.11
+  port: 6432  # 6432 for PgBouncer, 5432 for direct
+```
+
+### 3. Deploy
+
+```bash
+rake postgres:setup   # Deploy cluster
+rake postgres:status  # Check health
+```
+
+## Common Operations
+
+### Rake Tasks
+
+```bash
+rake postgres:setup                    # Deploy HA cluster
+rake postgres:status                   # Check cluster status
+rake postgres:verify                   # Comprehensive health check
+rake postgres:promote[host]            # Promote standby to primary
+
+# Backups (requires pgBackRest)
+rake postgres:backup:full
+rake postgres:backup:list
+rake postgres:backup:restore[backup_id]
+
+# Credential rotation (zero downtime)
+rake postgres:credentials:rotate_random
+rake postgres:credentials:rotate_all
+
+# Rolling updates (zero downtime)
+rake postgres:update:version[18]       # Major version upgrade
+rake postgres:update:patch             # Security patches
+```
+
+### CLI (Standalone)
+
+```bash
+active_postgres setup --environment=production
+active_postgres setup-standby HOST
+active_postgres status
+active_postgres promote HOST
+active_postgres backup --type=full
+active_postgres cache-secrets
+```
+
+## Components
+
+| Component | Description | Config |
+|-----------|-------------|--------|
+| **Core** | PostgreSQL installation | Always enabled |
+| **Performance Tuning** | Auto-optimization | Enabled 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}` |
+| **SSL** | Encrypted connections | `ssl: {enabled: true}` |
+| **Extensions** | pgvector, PostGIS, etc. | `extensions: {enabled: true, list: [pgvector]}` |
+
+## Secrets Management
+
+```yaml
+secrets:
+  # Environment variables
+  password: $POSTGRES_PASSWORD
+
+  # Command execution
+  password: $(op read "op://vault/item/field")
+  password: $(rails runner "puts Rails.application.credentials.dig(:postgres, :password)")
+
+  # AWS Secrets Manager
+  password: $(aws secretsmanager get-secret-value --secret-id myapp/postgres --query SecretString)
+```
+
+## Read/Write Splitting (Rails 6+)
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  connects_to database: { writing: :primary, reading: :primary_replica }
+end
+
+# Writes go to primary, reads go to replica
+User.create(name: "Alice")  # → Primary
+User.all                     # → Replica
+```
+
+## Requirements
+
+- Ruby 3.0+
+- PostgreSQL 12+
+- Ubuntu 20.04+ / Debian 11+ with systemd
+- SSH key-based authentication
+- Rails 6.0+ (optional)
+
+## License
+
+MIT

data/exe/activepostgres

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/active_postgres'
+
+ActivePostgres::CLI.start(ARGV)

data/lib/active_postgres/cli.rb

@@ -0,0 +1,157 @@
+require 'thor'
+
+module ActivePostgres
+  class CLI < Thor
+    class_option :environment, aliases: '-e', default: ENV['BORING_ENVIRONMENT'] || ENV['RAILS_ENV'] || 'development'
+    class_option :config, aliases: '-c', default: 'config/postgres.yml'
+
+    desc 'setup', 'Setup PostgreSQL HA cluster'
+    option :dry_run, type: :boolean, default: false
+    option :only, type: :string, desc: 'Setup only specific component (core, repmgr, pgbouncer, etc.)'
+    def setup
+      config = load_config
+      installer = Installer.new(config, dry_run: options[:dry_run])
+
+      if options[:only]
+        installer.setup_component(options[:only])
+      else
+        installer.setup
+      end
+    end
+
+    desc 'setup-primary', '[DEPRECATED] Use "setup" instead - it auto-detects primary-only vs HA'
+    option :dry_run, type: :boolean, default: false
+    def setup_primary
+      puts '⚠️  DEPRECATED: Use "active_postgres setup" instead.'
+      puts '   The setup command now auto-detects whether to deploy primary-only or HA based on your config.'
+      puts ''
+      setup
+    end
+
+    desc 'setup-standby HOST', 'Setup a single standby server without touching the primary'
+    option :dry_run, type: :boolean, default: false
+    def setup_standby(host)
+      config = load_config
+      installer = Installer.new(config, dry_run: options[:dry_run])
+
+      unless config.standby_hosts.include?(host)
+        puts "Error: #{host} is not configured as a standby in config/postgres.yml"
+        exit 1
+      end
+
+      installer.setup_standby_only(host)
+    end
+
+    desc 'status', 'Show cluster status'
+    def status
+      config = load_config
+      health_checker = HealthChecker.new(config)
+      health_checker.show_status
+    end
+
+    desc 'health', 'Run health checks'
+    def health
+      config = load_config
+      health_checker = HealthChecker.new(config)
+      health_checker.run_health_checks
+    end
+
+    desc 'promote HOST', 'Promote standby to primary'
+    option :node, type: :string
+    def promote(host = nil)
+      host ||= options[:node]
+
+      unless host
+        puts 'Error: Must specify host or --node'
+        exit 1
+      end
+
+      config = load_config
+      failover = Failover.new(config)
+      failover.promote(host)
+    end
+
+    desc 'backup', 'Create backup'
+    option :type, default: 'full', desc: 'Backup type: full, incremental'
+    def backup
+      config = load_config
+
+      unless config.component_enabled?(:pgbackrest)
+        puts 'Error: pgBackRest component not enabled'
+        exit 1
+      end
+
+      installer = Installer.new(config)
+      installer.run_backup(options[:type])
+    end
+
+    desc 'restore BACKUP_ID', 'Restore from backup'
+    def restore(backup_id)
+      config = load_config
+
+      unless config.component_enabled?(:pgbackrest)
+        puts 'Error: pgBackRest component not enabled'
+        exit 1
+      end
+
+      installer = Installer.new(config)
+      installer.run_restore(backup_id)
+    end
+
+    desc 'list-backups', 'List available backups'
+    def list_backups
+      config = load_config
+
+      unless config.component_enabled?(:pgbackrest)
+        puts 'Error: pgBackRest component not enabled'
+        exit 1
+      end
+
+      installer = Installer.new(config)
+      installer.list_backups
+    end
+
+    desc 'install COMPONENT', 'Install specific component'
+    def install(component)
+      config = load_config
+      installer = Installer.new(config)
+      installer.setup_component(component)
+    end
+
+    desc 'uninstall COMPONENT', 'Uninstall specific component'
+    def uninstall(component)
+      config = load_config
+      installer = Installer.new(config)
+      installer.uninstall_component(component)
+    end
+
+    desc 'restart COMPONENT', 'Restart specific component'
+    def restart(component)
+      config = load_config
+      installer = Installer.new(config)
+      installer.restart_component(component)
+    end
+
+    desc 'cache-secrets', 'Fetch and cache secrets locally'
+    option :directory, default: '.secrets'
+    def cache_secrets
+      config = load_config
+      secrets = Secrets.new(config)
+      secrets.cache_to_files(options[:directory])
+    end
+
+    desc 'version', 'Show version'
+    def version
+      puts "active_postgres #{ActivePostgres::VERSION}"
+    end
+
+    private
+
+    def load_config
+      Configuration.load(options[:config], options[:environment])
+    rescue StandardError => e
+      puts "Error loading config: #{e.message}"
+      exit 1
+    end
+  end
+end

data/lib/active_postgres/cluster_deployment_flow.rb

@@ -0,0 +1,85 @@
+module ActivePostgres
+  class ClusterDeploymentFlow < DeploymentFlow
+    private
+
+    def operation_name
+      if standbys?
+        'PostgreSQL HA Cluster Setup'
+      else
+        'PostgreSQL Primary Setup'
+      end
+    end
+
+    def print_targets
+      logger.info "Primary: #{config.primary_host}"
+      if standbys?
+        logger.info "Standbys: #{config.standby_hosts.join(', ')}"
+      else
+        logger.info 'Standbys: None (primary-only setup)'
+      end
+    end
+
+    def validate_specific_requirements
+      return unless config.component_enabled?(:repmgr) && !standbys?
+
+      logger.warn '⚠️  repmgr is enabled but no standbys configured - will skip repmgr setup'
+    end
+
+    def list_deployment_steps
+      if standbys?
+        logger.info "  • Install/recreate PostgreSQL #{config.version} on all servers"
+        logger.info '  • Configure repmgr for high availability' if should_setup_repmgr?
+      else
+        logger.info "  • Install/recreate PostgreSQL #{config.version} on primary"
+      end
+
+      logger.info '  • Setup pgbouncer connection pooling' if config.component_enabled?(:pgbouncer)
+      logger.info '  • Configure pgbackrest backups' if config.component_enabled?(:pgbackrest)
+      logger.info '  • Install postgres_exporter monitoring' if config.component_enabled?(:monitoring)
+      logger.info '  • Enable SSL/TLS connections' if config.component_enabled?(:ssl)
+    end
+
+    def deploy_components
+      hosts_to_deploy = standbys? ? config.all_hosts : [config.primary_host]
+
+      setup_component('ssl', hosts_to_deploy) if config.component_enabled?(:ssl)
+      setup_component('core', hosts_to_deploy)
+
+      components = %i[pgbouncer pgbackrest monitoring extensions]
+      components.unshift(:repmgr) if should_setup_repmgr?
+
+      components.each do |component|
+        setup_component(component.to_s, hosts_to_deploy) if config.component_enabled?(component)
+      end
+
+      # Create application users AFTER repmgr to avoid being wiped by cluster recreation
+      create_application_users_if_configured
+    end
+
+    def list_next_steps
+      logger.info ''
+      logger.info '📋 Next Steps:'
+      logger.info '  1. Verify cluster: rake postgres:verify'
+      logger.info "  2. Update database.yml to use: #{config.primary_host}:#{config.component_enabled?(:pgbouncer) ? '6432' : '5432'}"
+      logger.info '  3. Run migrations: rake postgres:migrate'
+      logger.info '  4. Update PgBouncer userlist: rake postgres:pgbouncer:update_userlist[your_app_user]' if config.component_enabled?(:pgbouncer)
+
+      return if standbys?
+
+      logger.info '  5. To add HA later: Add standbys to config → run: rake postgres:setup'
+    end
+
+    def standbys?
+      config.standby_hosts.any?
+    end
+
+    def should_setup_repmgr?
+      config.component_enabled?(:repmgr) && standbys?
+    end
+
+    def create_application_users_if_configured
+      core_component = Components::Core.new(config, ssh_executor, secrets)
+      core_component.create_application_users
+    end
+  end
+end

data/lib/active_postgres/component_resolver.rb

@@ -0,0 +1,24 @@
+module ActivePostgres
+  module ComponentResolver
+    def component_class_for(component_name)
+      case component_name.to_s.downcase
+      when 'core'
+        Components::Core
+      when 'repmgr'
+        Components::Repmgr
+      when 'pgbouncer'
+        Components::PgBouncer
+      when 'pgbackrest'
+        Components::PgBackRest
+      when 'monitoring'
+        Components::Monitoring
+      when 'ssl'
+        Components::SSL
+      when 'extensions'
+        Components::Extensions
+      else
+        raise Error, "Unknown component: #{component_name}"
+      end
+    end
+  end
+end

data/lib/active_postgres/components/base.rb

@@ -0,0 +1,38 @@
+module ActivePostgres
+  module Components
+    class Base
+      attr_reader :config, :ssh_executor, :secrets
+
+      def initialize(config, ssh_executor, secrets)
+        @config = config
+        @ssh_executor = ssh_executor
+        @secrets = secrets
+      end
+
+      def install
+        raise NotImplementedError, 'Subclass must implement #install'
+      end
+
+      def uninstall
+        raise NotImplementedError, 'Subclass must implement #uninstall'
+      end
+
+      def restart
+        raise NotImplementedError, 'Subclass must implement #restart'
+      end
+
+      protected
+
+      def render_template(template_name, binding_context)
+        template_path = File.join(ActivePostgres.root, 'templates', template_name)
+        template = ERB.new(File.read(template_path), trim_mode: '-')
+        template.result(binding_context)
+      end
+
+      def upload_template(host, template_name, remote_path, binding_context, mode: '644', owner: nil)
+        content = render_template(template_name, binding_context)
+        ssh_executor.upload_file(host, content, remote_path, mode: mode, owner: owner)
+      end
+    end
+  end
+end

data/lib/active_postgres/components/core.rb

@@ -0,0 +1,158 @@
+module ActivePostgres
+  module Components
+    class Core < Base
+      def install
+        puts 'Installing PostgreSQL core...'
+
+        # Install on primary
+        install_on_host(config.primary_host, is_primary: true)
+
+        # NOTE: App user creation moved to after repmgr setup to avoid being wiped
+        # See: create_application_user_and_database method called from deployment flow
+
+        # Install on standbys
+        # If repmgr is enabled, only install packages (cluster will be cloned by repmgr)
+        # If repmgr is disabled, install everything including cluster creation
+        config.standby_hosts.each do |host|
+          if config.component_enabled?(:repmgr)
+            install_packages_only(host)
+          else
+            install_on_host(host, is_primary: false)
+          end
+        end
+      end
+
+      def uninstall
+        puts 'Uninstalling PostgreSQL is not recommended and must be done manually.'
+      end
+
+      def restart
+        puts 'Restarting PostgreSQL...'
+
+        # Restart on all hosts
+        config.all_hosts.each do |host|
+          ssh_executor.restart_postgres(host, config.version)
+        end
+      end
+
+      # Public method to create application users - called after repmgr setup
+      # This is done after repmgr to avoid being wiped by cluster recreation
+      def create_application_users
+        return unless config.app_user && config.app_database
+
+        puts "\n📝 Creating application users and databases..."
+        create_app_user_and_database(config.primary_host)
+      end
+
+      private
+
+      def install_on_host(host, is_primary:)
+        puts "  Installing on #{host}..."
+
+        ssh_executor.install_postgres(host, config.version)
+        ssh_executor.ensure_cluster_exists(host, config.version)
+
+        # Get base component config
+        component_config = config.component_config(:core)
+
+        # Calculate optimal PostgreSQL settings if performance tuning is enabled
+        # pg_config is used in ERB template via binding
+        pg_config = if config.component_enabled?(:performance_tuning)
+                      calculate_tuned_settings(host, component_config)
+                    else
+                      component_config[:postgresql] || {}
+                    end
+        _ = pg_config # Used in ERB template
+
+        upload_template(host, 'postgresql.conf.erb', "/etc/postgresql/#{config.version}/main/postgresql.conf", binding,
+                        owner: 'postgres:postgres')
+        upload_template(host, 'pg_hba.conf.erb', "/etc/postgresql/#{config.version}/main/pg_hba.conf", binding,
+                        owner: 'postgres:postgres')
+
+        ssh_executor.restart_postgres(host, config.version)
+      end
+
+      def calculate_tuned_settings(host, component_config)
+        tuning_config = config.component_config(:performance_tuning)
+        db_type = tuning_config[:db_type] || 'web'
+
+        puts "  Auto-tuning PostgreSQL for #{db_type} workload..."
+
+        # Initialize tuner and calculate optimal settings
+        tuner = PerformanceTuner.new(config, ssh_executor)
+        optimal_settings = tuner.tune_for_host(host, db_type: db_type)
+
+        # Merge: user config overrides calculated settings
+        user_postgresql = component_config[:postgresql] || {}
+        optimal_settings.merge(user_postgresql)
+      end
+
+      def install_packages_only(host)
+        puts "  Installing packages on #{host} (cluster will be created by repmgr)..."
+        ssh_executor.install_postgres(host, config.version)
+      end
+
+      def create_app_user_and_database(host)
+        app_user = config.app_user
+        app_database = config.app_database
+
+        return unless app_user && app_database
+
+        puts "  Creating application user '#{app_user}' and database '#{app_database}'..."
+        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'
+
+          puts "  ✓ Created app user '#{app_user}' and database '#{app_database}'"
+        end
+      rescue StandardError => e
+        warn "  Warning: Could not create app user: #{e.message}"
+        warn '  You may need to create the user manually'
+      end
+
+      def resolve_app_password
+        app_password = secrets.resolve('app_password')
+        if app_password.nil? || app_password.empty?
+          raise Error, 'app_password is empty or nil. Check your postgres.yml secrets section and ensure RAILS_ENV=production is set.'
+        end
+
+        app_password
+      rescue StandardError => e
+        raise Error, "Cannot resolve app_password: #{e.message}. Make sure RAILS_ENV is set when running deployment."
+      end
+
+      def build_app_user_sql(app_user, app_database, app_password)
+        escaped_password = app_password.gsub("'", "''")
+
+        [
+          '-- Create app user if not exists',
+          'DO $$',
+          'BEGIN',
+          "  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '#{app_user}') THEN",
+          "    CREATE USER #{app_user} WITH PASSWORD '#{escaped_password}' CREATEDB;",
+          '  ELSE',
+          "    ALTER USER #{app_user} WITH PASSWORD '#{escaped_password}';",
+          '  END IF;',
+          'END $$;',
+          '',
+          '-- Ensure user has CREATEDB',
+          "ALTER USER #{app_user} CREATEDB;",
+          '',
+          '-- Create database if not exists',
+          "SELECT 'CREATE DATABASE #{app_database} OWNER #{app_user}'",
+          "WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '#{app_database}')\\gexec",
+          '',
+          '-- Grant privileges',
+          "GRANT ALL PRIVILEGES ON DATABASE #{app_database} TO #{app_user};",
+          "\\c #{app_database}",
+          "GRANT ALL ON SCHEMA public TO #{app_user};"
+        ].join("\n")
+      end
+    end
+  end
+end