partition_gardener 0.3.0

data/lib/partition_gardener/gap_detection.rb

@@ -0,0 +1,59 @@
+module PartitionGardener
+  class GapDetection
+    Gap = Data.define(:range_start, :range_end, :message)
+
+    def self.call(table_name, config: Registry.find_by_table_name(table_name))
+      new(table_name, config: config).call
+    end
+
+    def initialize(table_name, config: nil)
+      @table_name = table_name
+      @config = config || Registry.find_by_table_name(table_name)
+    end
+
+    def call
+      return [] unless @config
+
+      strategy = Strategy.for(@config)
+      return [] unless range_layout?(strategy)
+
+      segments = strategy.attached_tail_segments
+      return [] if segments.empty?
+
+      sorted = segments.sort_by { |segment| [segment.range_start.to_s, segment.name] }
+      gaps = []
+
+      sorted.each_cons(2) do |left, right|
+        left_end = normalize_range_end(left.range_end)
+        right_start = right.range_start
+        next if left_end == right_start
+
+        gaps << Gap.new(
+          range_start: left_end,
+          range_end: right_start,
+          message: "uncovered range between #{left.name} and #{right.name} (#{left_end}..#{right_start})"
+        )
+      end
+
+      unless sorted.any? { |segment| segment.range_end == :max }
+        gaps << Gap.new(
+          range_start: sorted.last.range_end,
+          range_end: :max,
+          message: "no attached tail partition extends to MAXVALUE"
+        )
+      end
+
+      gaps
+    end
+
+    private
+
+    def range_layout?(strategy)
+      strategy.is_a?(Strategy::DateRange) || strategy.is_a?(Strategy::IntegerRange)
+    end
+
+    def normalize_range_end(range_end)
+      (range_end == :max) ? nil : range_end
+    end
+  end
+end

data/lib/partition_gardener/hash_routing.rb

@@ -0,0 +1,70 @@
+module PartitionGardener
+  module HashRouting
+    module_function
+
+    def collect_bucket_counts(config)
+      table_name = config[:table_name]
+      modulus = config.fetch(:hash_modulus, Strategy::HashBranches::DEFAULT_MODULUS)
+      bucket_counts = Hash.new(0)
+
+      Connection.attached_partitions(table_name).each do |partition|
+        next if partition.default
+
+        remainder = remainder_from_partition(partition, table_name)
+        next if remainder.nil?
+
+        bucket_counts[remainder] += Connection.count_rows_in_partition_table(partition.name)
+      end
+
+      default_name = Naming.default_partition_name(table_name)
+      if Connection.partition_exists?(default_name) && Connection.partition_attached?(table_name, default_name)
+        counts_in_default(default_name, config[:partition_key_column], modulus).each do |remainder, count|
+          bucket_counts[remainder] += count
+        end
+      end
+
+      bucket_counts
+    end
+
+    def remainder_from_partition(partition, table_name)
+      if partition.range_start.is_a?(Hash) && partition.range_start.key?(:remainder)
+        return partition.range_start[:remainder]
+      end
+
+      match = partition.name.match(/^#{Regexp.escape(table_name)}_[ha]_(\d+)$/)
+      return match[1].to_i if match
+
+      nil
+    end
+
+    def counts_in_default(partition_name, partition_key_column, modulus)
+      connection = Connection.connection
+      column = connection.quote_column_name(partition_key_column)
+      remainder_sql = remainder_sql_expression(column, modulus, connection)
+
+      sql = <<~SQL
+        SELECT #{remainder_sql} AS remainder,
+               COUNT(*)::int AS row_count
+        FROM #{Connection.quoted_table(partition_name)}
+        GROUP BY 1
+      SQL
+
+      connection.execute(sql).each_with_object({}) do |row, counts|
+        counts[row["remainder"].to_i] = row["row_count"].to_i
+      end
+    end
+
+    def remainder_sql_expression(quoted_column, modulus, connection)
+      if integer_column?(quoted_column)
+        "mod(abs(hashint8extended(#{quoted_column}::bigint, 0)), #{modulus})"
+      else
+        "mod(abs(hashtextextended(#{quoted_column}::text, 0)), #{modulus})"
+      end
+    end
+
+    def integer_column?(quoted_column)
+      normalized = quoted_column.delete('"').downcase
+      normalized == "id" || normalized.end_with?("_id")
+    end
+  end
+end

data/lib/partition_gardener/layout/calendar_year.rb

@@ -0,0 +1,28 @@
+module PartitionGardener
+  module Layout
+    class CalendarYear
+      DEFAULT_ACTIVE_YEARS = Strategy::DateRange::DEFAULT_ACTIVE_YEARS
+
+      class << self
+        def active_end(active_start:, active_years: DEFAULT_ACTIVE_YEARS)
+          DateCalendar.add_years(active_start, active_years)
+        end
+
+        def build_segments(config:, active_start:, active_end:, hot_years:)
+          strategy = Strategy::DateRange.new(config.merge(bucket: :year))
+          buckets = strategy.send(:each_bucket_in_range, active_start, active_end)
+
+          ZoneSegments.build_filler_and_hot_segments(
+            table_name: config[:table_name],
+            buckets: buckets,
+            hot_buckets: hot_years,
+            active_start: active_start,
+            active_end: active_end,
+            hot_bucket_name: config[:partition_name_format],
+            bucket_end: ->(bucket) { DateCalendar.beginning_of_year(DateCalendar.next_year(bucket)) }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/partition_gardener/layout/integer_window.rb

@@ -0,0 +1,28 @@
+module PartitionGardener
+  module Layout
+    class IntegerWindow
+      DEFAULT_ACTIVE_ID_WIDTH = Strategy::IntegerRange::DEFAULT_ACTIVE_ID_WIDTH
+
+      class << self
+        def active_end(active_start:, active_id_width: DEFAULT_ACTIVE_ID_WIDTH)
+          active_start + active_id_width
+        end
+
+        def build_segments(config:, active_start:, active_end:, hot_buckets:)
+          strategy = Strategy::IntegerRange.new(config)
+          buckets = strategy.send(:each_bucket_in_range, active_start, active_end)
+
+          ZoneSegments.build_filler_and_hot_segments(
+            table_name: config[:table_name],
+            buckets: buckets,
+            hot_buckets: hot_buckets,
+            active_start: active_start,
+            active_end: active_end,
+            hot_bucket_name: strategy.method(:hot_bucket_partition_name),
+            bucket_end: ->(bucket) { [bucket + strategy.send(:current_band_size), active_end].min }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/partition_gardener/layout/sliding_window.rb

@@ -0,0 +1,28 @@
+module PartitionGardener
+  module Layout
+    class SlidingWindow
+      class << self
+        def active_end(active_start:, bucket: :month, active_span: nil)
+          span = active_span || DateBucket.default_active_span(bucket)
+          DateBucket.add_buckets(active_start, span, bucket)
+        end
+
+        def build_segments(config:, active_start:, active_end:, hot_months:)
+          strategy = Strategy::DateRange.new(config)
+          buckets = strategy.send(:each_bucket_in_range, active_start, active_end)
+          bucket = config.fetch(:bucket, :month)
+
+          ZoneSegments.build_filler_and_hot_segments(
+            table_name: config[:table_name],
+            buckets: buckets,
+            hot_buckets: hot_months,
+            active_start: active_start,
+            active_end: active_end,
+            hot_bucket_name: config[:partition_name_format],
+            bucket_end: ->(bucket_start) { DateBucket.end_of_bucket(bucket_start, bucket) }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/partition_gardener/layout/three_area.rb

@@ -0,0 +1,27 @@
+module PartitionGardener
+  module Layout
+    # Every partitioning strategy targets the same three zones on the key axis:
+    #
+    #   archive  — coldest data; fine-grained children, retention-friendly, rarely written
+    #   current  — hot active span; most reads/writes; may contain heat splits inside the zone
+    #   future   — beyond the active window; sparse, less hot than current, not yet archived
+    #
+    # Strategy plugins (date range, integer range, hash) only define how keys map to bounds.
+    # Heatmap collection and hot-bucket policy live on each strategy plugin.
+    # Executor cursor moves are identical: ORDER BY partition_key, conflict_key — strategy-agnostic.
+    module ThreeArea
+      ZONES = %i[archive current future].freeze
+
+      class << self
+        def zone_slot_name(table_name, zone)
+          case zone
+          when :current then Naming.current_partition_name(table_name)
+          when :future then Naming.future_partition_name(table_name)
+          else
+            raise ArgumentError, "archive zone uses strategy-specific bucket names, not a single slot"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/partition_gardener/layout/zone_segments.rb

@@ -0,0 +1,62 @@
+module PartitionGardener
+  module Layout
+    module ZoneSegments
+      module_function
+
+      def build_filler_and_hot_segments(table_name:, buckets:, hot_buckets:, active_start:, active_end:, hot_bucket_name:, bucket_end:)
+        hot_bucket_set = hot_buckets.to_set
+        segments = []
+        middle_filler_index = 0
+        index = 0
+
+        while index < buckets.length
+          bucket = buckets[index]
+
+          if hot_bucket_set.include?(bucket)
+            segments << Plan::Segment.new(
+              name: hot_bucket_name.call(bucket),
+              range_start: bucket,
+              range_end: bucket_end.call(bucket),
+              kind: :hot_bucket
+            )
+            index += 1
+            next
+          end
+
+          run_start = bucket
+          while index < buckets.length && !hot_bucket_set.include?(buckets[index])
+            index += 1
+          end
+          run_end = (index < buckets.length) ? buckets[index] : active_end
+
+          segment_name = if run_start == active_start
+            Naming.current_partition_name(table_name)
+          else
+            middle_filler_index += 1
+            if middle_filler_index == 1
+              Naming.open_partition_name(table_name)
+            else
+              "#{table_name}_open_#{middle_filler_index}"
+            end
+          end
+
+          segments << Plan::Segment.new(
+            name: segment_name,
+            range_start: run_start,
+            range_end: run_end,
+            kind: :filler
+          )
+        end
+
+        segments << Plan::Segment.new(
+          name: Naming.future_partition_name(table_name),
+          range_start: active_end,
+          range_end: :max,
+          kind: :future
+        )
+
+        segments
+      end
+    end
+  end
+end

data/lib/partition_gardener/lock_not_acquired.rb

@@ -0,0 +1,3 @@
+module PartitionGardener
+  class LockNotAcquired < StandardError; end
+end

data/lib/partition_gardener/maintenance_backend.rb

@@ -0,0 +1,73 @@
+module PartitionGardener
+  module MaintenanceBackend
+    GARDENER = :gardener
+    PG_PARTMAN = :pg_partman
+    HYBRID_LAYOUT_ONLY = :hybrid_layout_only
+
+    class ValidationError < ArgumentError; end
+
+    module_function
+
+    def normalize(backend)
+      backend&.to_sym || GARDENER
+    end
+
+    def gardener_owned?(config)
+      normalize(config[:maintenance_backend]) != PG_PARTMAN
+    end
+
+    def skipped?(config)
+      normalize(config[:maintenance_backend]) == PG_PARTMAN
+    end
+
+    def hybrid?(config)
+      normalize(config[:maintenance_backend]) == HYBRID_LAYOUT_ONLY
+    end
+
+    def partman_parent_configured?(table_name)
+      Connection.partman_parent_configured?(table_name)
+    rescue
+      false
+    end
+
+    def validate!(config)
+      violations = validation_messages(config)
+      return if violations.empty?
+
+      violations.each do |message|
+        if PartitionGardener.configuration.strict_maintenance_backend_validation
+          raise ValidationError, message
+        end
+
+        PartitionGardener.configuration.notify(
+          "[PartitionGardener] #{message}",
+          context: {
+            table_name: config[:table_name],
+            maintenance_backend: normalize(config[:maintenance_backend])
+          }
+        )
+      end
+    end
+
+    def validation_messages(config)
+      backend = normalize(config[:maintenance_backend])
+      table_name = config[:table_name]
+      partman_row = partman_parent_configured?(table_name)
+      messages = []
+
+      if backend == PG_PARTMAN && !partman_row
+        messages << "#{table_name} maintenance_backend is pg_partman but partman.part_config has no row"
+      end
+
+      if backend == GARDENER && partman_row
+        messages << "#{table_name} is registered for gardener but partman.part_config also lists this parent; pick one maintainer"
+      end
+
+      if hybrid?(config) && !partman_row
+        messages << "#{table_name} hybrid_layout_only expects partman premake on the same parent"
+      end
+
+      messages
+    end
+  end
+end

data/lib/partition_gardener/memory_run_record_store.rb

@@ -0,0 +1,19 @@
+module PartitionGardener
+  class MemoryRunRecordStore
+    def initialize
+      @records = {}
+    end
+
+    def load(table_name)
+      @records[table_name]
+    end
+
+    def save(table_name, attributes)
+      @records[table_name] = attributes
+    end
+
+    def clear(table_name)
+      @records.delete(table_name)
+    end
+  end
+end