partition_gardener 0.3.0

data/lib/partition_gardener/cli.rb

@@ -0,0 +1,190 @@
+require "json"
+require "optparse"
+
+module PartitionGardener
+  class CLI
+    def self.start(argv = ARGV)
+      new(argv).run
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+      @options = {
+        pretty: false,
+        rails: false,
+        registry: nil,
+        table: nil,
+        all: false,
+        confirm: false
+      }
+    end
+
+    def run
+      parse_options!
+      command = @argv.shift || "help"
+      @options[:table] ||= @argv.first
+
+      case command
+      when "plan"
+        load_context!
+        print_json(plan_output)
+      when "audit"
+        load_context!
+        print_json(audit_output)
+      when "apply"
+        abort_with_help("apply requires --confirm (mutates the database)") unless @options[:confirm]
+        load_context!
+        print_json(apply_output)
+      when "help", "-h", "--help"
+        print_help
+      else
+        abort_with_help("unknown command: #{command}")
+      end
+    end
+
+    private
+
+    def parse_options!
+      OptionParser.new do |parser|
+        parser.banner = "Usage: partition_gardener [options] <plan|audit|apply> [table_name]"
+        parser.on("--table NAME", "Table name (default: first positional argument)") { |value| @options[:table] = value }
+        parser.on("--all", "All registered tables") { @options[:all] = true }
+        parser.on("--registry PATH", "Load registry from JSON file") { |value| @options[:registry] = value }
+        parser.on("--rails", "Load registry from Rails environment") { @options[:rails] = true }
+        parser.on("--pretty", "Pretty-print JSON") { @options[:pretty] = true }
+        parser.on("--confirm", "Required for apply (mutates the database)") { @options[:confirm] = true }
+      end.parse!(@argv)
+    end
+
+    def load_context!
+      if @options[:registry]
+        ConfigDocument.load_registry_file!(@options[:registry])
+      elsif @options[:rails]
+        load_rails!
+      elsif Registry.tables.empty?
+        abort_with_help("no tables registered; pass --registry PATH or --rails")
+      end
+    end
+
+    def load_rails!
+      root = find_rails_root(Dir.pwd) || abort("could not find Rails application root")
+      require File.join(root, "config", "environment")
+    end
+
+    def find_rails_root(start_directory)
+      directory = start_directory
+      loop do
+        return directory if File.exist?(File.join(directory, "config", "application.rb"))
+
+        parent = File.dirname(directory)
+        return nil if parent == directory
+
+        directory = parent
+      end
+    end
+
+    def plan_output
+      if @options[:all]
+        {
+          schema_version: PlanReport::SCHEMA_VERSION,
+          tables: PartitionGardener.send(:plan_all)
+        }
+      else
+        table_name = required_table_name!
+        configs = Registry.configs_for_table(table_name)
+        abort_with_help("no config for table #{table_name}") if configs.empty?
+
+        if configs.one?
+          PlanReport.build(configs.first).to_h
+        else
+          {
+            schema_version: PlanReport::SCHEMA_VERSION,
+            parent_table_name: table_name,
+            tables: configs.map { |config| PlanReport.build(config).to_h }
+          }
+        end
+      end
+    end
+
+    def audit_output
+      if @options[:all]
+        {
+          schema_version: Audit::SCHEMA_VERSION,
+          tables: Registry.expanded_table_configs.map { |config| audit_to_h(config[:table_name], config: config) }
+        }
+      else
+        table_name = required_table_name!
+        configs = Registry.configs_for_table(table_name)
+        abort_with_help("no config for table #{table_name}") if configs.empty?
+
+        if configs.one?
+          audit_to_h(table_name, config: configs.first)
+        else
+          {
+            schema_version: Audit::SCHEMA_VERSION,
+            parent_table_name: table_name,
+            tables: configs.map { |config| audit_to_h(config[:table_name], config: config) }
+          }
+        end
+      end
+    end
+
+    def apply_output
+      table_name = @options[:all] ? nil : @options[:table]
+      PartitionGardener.run!(table_name: table_name).to_h
+    end
+
+    def audit_to_h(table_name, config: nil)
+      result = Audit.call(table_name, config: config)
+      {
+        schema_version: Audit::SCHEMA_VERSION,
+        table_name: result.table_name,
+        partitioned: result.partitioned,
+        default_row_count: result.default_row_count,
+        attached_child_count: result.attached_child_count,
+        horizon_days: result.horizon_days,
+        gaps: result.gaps.map { |gap| {range_start: gap.range_start, range_end: gap.range_end, message: gap.message} },
+        warnings: result.warnings
+      }
+    end
+
+    def required_table_name!
+      table_name = @options[:table]
+      abort_with_help("table name is required (or pass --all)") unless table_name
+
+      table_name
+    end
+
+    def print_json(payload)
+      json = if @options[:pretty]
+        JSON.pretty_generate(payload)
+      else
+        JSON.generate(payload)
+      end
+
+      puts json
+    end
+
+    def print_help
+      puts <<~HELP
+        partition_gardener — plan, audit, and apply partition maintenance
+
+        Commands:
+          plan   Print target layout diff as JSON (dry-run)
+          audit  Print partition layout audit warnings as JSON
+          apply  Run maintenance for registered tables (single table unless --all)
+
+        Examples:
+          partition_gardener --rails plan audits
+          partition_gardener --registry config/tables.json audit --all
+          partition_gardener --rails apply --confirm audits
+      HELP
+    end
+
+    def abort_with_help(message)
+      warn message
+      print_help
+      exit 1
+    end
+  end
+end

data/lib/partition_gardener/config_document.rb

@@ -0,0 +1,240 @@
+module PartitionGardener
+  module ConfigDocument
+    SCHEMA_PATH = File.expand_path("../../docs/schemas/partition_garden.schema.json", __dir__)
+    PLAN_SCHEMA_PATH = File.expand_path("../../docs/schemas/plan_report.schema.json", __dir__)
+
+    PORTABLE_KEYS = %i[
+      table_name
+      layout
+      bucket
+      partition_key_column
+      conflict_key
+      active_months
+      active_days
+      active_weeks
+      active_quarters
+      active_years
+      premake_months
+      split_row_threshold
+      move_batch_size
+      statement_timeout
+      retention_months
+      retention_apply
+      retention_keep_table
+      retention_detach_concurrently
+      hash_modulus
+      maintenance_backend
+      incremental_rebalance
+      run_record_enabled
+      analyze_after_rebalance
+    ].freeze
+
+    IMPORTABLE_LAYOUTS = %w[
+      sliding_window
+      rolling_current
+      calendar_year
+      premake_monthly
+      integer_window
+      hash_branches
+    ].freeze
+
+    ALLOWED_REGISTRY_KEYS = (
+      %w[table_name layout partition_key_column conflict_key bucket] +
+      PORTABLE_KEYS.map(&:to_s)
+    ).uniq.freeze
+
+    module_function
+
+    def export(config)
+      PORTABLE_KEYS.each_with_object({}) do |key, document|
+        next unless config.key?(key)
+
+        document[key] = config[key]
+      end
+    end
+
+    def export_all(configs)
+      configs.map { |config| export(config) }
+    end
+
+    def from_hash(document)
+      layout = document.fetch("layout").to_sym
+      table_name = document.fetch("table_name")
+      partition_key_column = document.fetch("partition_key_column")
+      conflict_key = document.fetch("conflict_key")
+      options = document.except("table_name", "layout", "partition_key_column", "conflict_key").transform_keys(&:to_sym)
+
+      case layout
+      when :sliding_window
+        import_sliding_window(
+          table_name: table_name,
+          partition_key_column: partition_key_column,
+          conflict_key: conflict_key,
+          **options
+        )
+      when :rolling_current
+        Templates.rolling_current_monthly(
+          table_name: table_name,
+          partition_key_column: partition_key_column,
+          conflict_key: conflict_key,
+          **options
+        )
+      when :premake_monthly
+        Templates.premake_monthly(
+          table_name: table_name,
+          partition_key_column: partition_key_column,
+          conflict_key: conflict_key,
+          **options
+        )
+      when :calendar_year
+        Templates.calendar_year(
+          table_name: table_name,
+          partition_key_column: partition_key_column,
+          conflict_key: conflict_key,
+          **options
+        )
+      when :integer_window
+        Templates.integer_window(
+          table_name: table_name,
+          partition_key_column: partition_key_column,
+          conflict_key: conflict_key,
+          **options
+        )
+      when :hash_branches
+        Templates.hash_branches(
+          table_name: table_name,
+          partition_key_column: partition_key_column,
+          conflict_key: conflict_key,
+          **options
+        )
+      else
+        raise ArgumentError, "layout #{layout} is not supported in JSON config import"
+      end
+    end
+
+    def import_sliding_window(table_name:, partition_key_column:, conflict_key:, bucket: :month, **options)
+      case bucket.to_sym
+      when :day
+        Templates.sliding_window_daily(
+          table_name: table_name,
+          partition_key_column: partition_key_column,
+          conflict_key: conflict_key,
+          **options
+        )
+      when :week
+        Templates.sliding_window_weekly(
+          table_name: table_name,
+          partition_key_column: partition_key_column,
+          conflict_key: conflict_key,
+          **options
+        )
+      when :quarter
+        Templates.sliding_window_quarterly(
+          table_name: table_name,
+          partition_key_column: partition_key_column,
+          conflict_key: conflict_key,
+          **options
+        )
+      else
+        Templates.sliding_window_monthly(
+          table_name: table_name,
+          partition_key_column: partition_key_column,
+          conflict_key: conflict_key,
+          **options
+        )
+      end
+    end
+
+    def load_registry_file!(path)
+      Registry.reset!
+      payload = JSON.parse(File.read(path))
+
+      case payload
+      when Array
+        payload.each { |document| register_validated_document!(document) }
+      when Hash
+        if payload["tables"].is_a?(Array)
+          payload["tables"].each { |document| register_validated_document!(document) }
+        else
+          register_validated_document!(payload)
+        end
+      else
+        raise ArgumentError, "registry file must be a JSON object or array"
+      end
+    end
+
+    def validate_registry_document!(document)
+      raise ArgumentError, "registry entry must be a JSON object" unless document.is_a?(Hash)
+
+      validate_registry_required_keys!(document)
+      validate_registry_unknown_keys!(document)
+      validate_registry_layout!(document)
+      validate_registry_core_strings!(document)
+      validate_registry_conflict_key!(document)
+      validate_registry_optional_bucket!(document)
+      validate_registry_optional_maintenance_backend!(document)
+      document
+    end
+
+    def validate_registry_required_keys!(document)
+      missing_keys = %w[table_name layout partition_key_column conflict_key] - document.keys
+      return if missing_keys.empty?
+
+      raise ArgumentError, "registry entry missing required keys: #{missing_keys.join(", ")}"
+    end
+
+    def validate_registry_unknown_keys!(document)
+      unknown_keys = document.keys - ALLOWED_REGISTRY_KEYS
+      return if unknown_keys.empty?
+
+      raise ArgumentError, "registry entry has unsupported keys: #{unknown_keys.join(", ")}"
+    end
+
+    def validate_registry_layout!(document)
+      layout = document.fetch("layout")
+      return if layout.is_a?(String) && IMPORTABLE_LAYOUTS.include?(layout)
+
+      supported = IMPORTABLE_LAYOUTS.join(", ")
+      raise ArgumentError, "layout #{layout.inspect} is not supported in JSON import (supported: #{supported}; composite and list_split require Ruby registration)"
+    end
+
+    def validate_registry_core_strings!(document)
+      unless document.fetch("table_name").is_a?(String) && !document.fetch("table_name").empty?
+        raise ArgumentError, "table_name must be a non-empty string"
+      end
+
+      unless document.fetch("partition_key_column").is_a?(String) && !document.fetch("partition_key_column").empty?
+        raise ArgumentError, "partition_key_column must be a non-empty string"
+      end
+    end
+
+    def validate_registry_conflict_key!(document)
+      conflict_key = document.fetch("conflict_key")
+      return if conflict_key.is_a?(Array) && conflict_key.any? && conflict_key.all? { |column| column.is_a?(String) && !column.empty? }
+
+      raise ArgumentError, "conflict_key must be a non-empty array of strings"
+    end
+
+    def validate_registry_optional_bucket!(document)
+      return unless document.key?("bucket")
+
+      bucket = document.fetch("bucket")
+      return if bucket.is_a?(String) && %w[day week month quarter year].include?(bucket)
+
+      raise ArgumentError, "bucket must be one of: day, week, month, quarter, year"
+    end
+
+    def validate_registry_optional_maintenance_backend!(document)
+      return unless document.key?("maintenance_backend")
+
+      backend = document.fetch("maintenance_backend")
+      return if backend.is_a?(String) && %w[gardener pg_partman hybrid_layout_only].include?(backend)
+
+      raise ArgumentError, "maintenance_backend must be gardener, pg_partman, or hybrid_layout_only"
+    end
+
+    def register_validated_document!(document)
+      Registry.register(from_hash(validate_registry_document!(document)))
+    end
+  end
+end

data/lib/partition_gardener/configuration.rb

@@ -0,0 +1,102 @@
+module PartitionGardener
+  class Configuration
+    attr_accessor :notifier,
+      :connection_resolver,
+      :statement_timeout_wrapper,
+      :today_resolver,
+      :schema_name,
+      :continue_on_error,
+      :advisory_lock_mode,
+      :analyze_after_rebalance,
+      :incremental_rebalance,
+      :run_record_enabled,
+      :retention_detach_concurrently,
+      :strict_maintenance_backend_validation,
+      :current_run_metrics
+
+    attr_writer :run_record_store
+
+    def initialize
+      @notifier = ->(_message_or_error, context: {}) {}
+      @connection_resolver = method(:default_connection_resolver)
+      @statement_timeout_wrapper = ->(_timeout, &block) { block.call }
+      @today_resolver = -> { Date.today }
+      @schema_name = "public"
+      @continue_on_error = true
+      @advisory_lock_mode = :transaction
+      @analyze_after_rebalance = false
+      @incremental_rebalance = true
+      @run_record_enabled = true
+      @run_record_store = nil
+      @retention_detach_concurrently = false
+      @strict_maintenance_backend_validation = false
+      @current_run_metrics = nil
+    end
+
+    def run_record_store
+      @run_record_store ||= default_run_record_store
+    end
+
+    def connection
+      resolved = @connection_resolver.call
+      raise ArgumentError, "PartitionGardener connection is not configured" unless resolved
+
+      resolved
+    end
+
+    def notify(message_or_error, context: {})
+      @notifier.call(message_or_error, context: context)
+    end
+
+    def with_statement_timeout(timeout, &block)
+      @statement_timeout_wrapper.call(timeout, &block)
+    end
+
+    def today
+      @today_resolver.call
+    end
+
+    private
+
+    def default_run_record_store
+      return MemoryRunRecordStore.new unless sql_run_record_store_available?
+
+      SqlRunRecordStore.new
+    rescue
+      MemoryRunRecordStore.new
+    end
+
+    def default_connection_resolver
+      return ActiveRecord::Base.connection if defined?(ActiveRecord::Base)
+
+      database_url = ENV["DATABASE_URL"]
+      return nil if Blank.blank?(database_url)
+
+      @pg_connection ||= PgConnection.connect(database_url).tap do
+        # Standalone maintenance runs many statements; session locks avoid one long transaction.
+        @advisory_lock_mode = :session if @advisory_lock_mode == :transaction
+      end
+    end
+
+    def sql_run_record_store_available?
+      return true if defined?(ActiveRecord::Base)
+
+      Blank.present?(ENV["DATABASE_URL"])
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end