partition_gardener 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ad4860950aedb375b6703ededf1602006203f1defa7406465f6f87b5d38083b
-  data.tar.gz: 0af3c3dadfe7c123c5193e9aa1b78b3d8fb5dc1a294a3819c790ad20b18a4d53
+  metadata.gz: 4be8b78232ba13211d0baad009dea43f6320b96dd9b82398c8a4e86ed6008b3d
+  data.tar.gz: acb6c02d0192c07e3b8c9f959b6ada44e44014f9f5c144906e6649ebb1309e87
 SHA512:
-  metadata.gz: 68c44b5b9851c2f167801c26f33b9050f5ba684a0355820ea8738f7309ceebaf35ed3ab2ef3ee8a87830a145c9593b8a994f06ae7b3625901fb7b92963cec2d7
-  data.tar.gz: 8026d9241cf10f037655ded5999cae214dafe6658b6d3c66a5d336561e87d20b078a63a82321bed1d0b74d0b9b513579196dbe3d3d31235a61c10aedb6d864ab
+  metadata.gz: f387a844418342ef9f4ff644faf1ca2431f8259e3f26e9220bab9ce225ae5f1606ceb4651a94cb39f0e7929a7a0b7c2eae779c6aa7d079a8ad4355901f39a63f
+  data.tar.gz: a659acdb2ed364d72f44a9ecb0aab7ac925b27b77f8365e9da36582416145c9db9bbe6a1e9da279be036eab0cb4eda3d4a865d5a86a22741564bbcbf87145d32

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.3.4 (2026-09-02)
+
+- Align LIKE and detached children with additive parent columns before `ATTACH PARTITION`, preserving type, collation, default, and `NOT NULL` atomically. Audit warns when a managed child still lags. Set `align_child_columns: false` to fail fast instead.
+
 ## 0.3.3 (2026-08-13)
 
 - Roll the sliding-window current partition before attaching the prior month's archive so a month rollover detaches the old current span and attaches that month as its own child

data/SECURITY.md

@@ -2,26 +2,24 @@
 
 ## Reporting a Vulnerability
 
-Do not open a public issue for security vulnerabilities.
-
 Email security details to: security@kiskolabs.com
 
-Include: description, steps to reproduce, potential impact, and suggested fix (if available).
+Send the report only to that address. Include description, steps to reproduce, potential impact, and a suggested fix when you have one.
 
 ### Response Timeline
 
-- We will acknowledge receipt of your report
-- We will provide an initial assessment
-- We will keep you informed of our progress and resolution timeline
+- We will acknowledge receipt of your report.
+- We will provide an initial assessment.
+- We will keep you informed of our progress and resolution timeline.
 
 ### Disclosure Policy
 
-- We will work with you to understand and resolve the issue
-- We will credit you for the discovery (unless you prefer to remain anonymous)
-- We will publish a security advisory after the vulnerability is patched
-- We will coordinate public disclosure with you
+- We will work with you to understand and resolve the issue.
+- We will credit you for the discovery unless you prefer to remain anonymous.
+- We will publish a security advisory after the vulnerability is patched.
+- We will coordinate public disclosure with you.
 
 ## Automation Security
 
-- Context Isolation: It is strictly forbidden to include production credentials, API keys, or Personally Identifiable Information (PII) in prompts sent to third-party LLMs or automation services.
-- Supply Chain: All automated dependencies must be verified.
+- Keep production credentials, API keys, and personal data out of prompts sent to third-party models or automation services.
+- Verify automated dependencies.

data/docs/THIRD_PARTY_LICENSE_MANIFEST.tsv

@@ -19,16 +19,16 @@ root	logger	1.7.0	Ruby|BSD-2-Clause
 root	minitest	6.0.6	MIT
 root	parallel	2.1.0	MIT
 root	parser	3.3.12.0	MIT
-root	partition_gardener	0.3.3	MIT
+root	partition_gardener	0.3.4	MIT
 root	pg	1.6.3	BSD-2-Clause
-root	polyrun	2.2.2	MIT
+root	polyrun	2.2.3	MIT
 root	prism	1.9.0	MIT
 root	prosopite	2.2.0	Apache-2.0
 root	racc	1.8.1	Ruby|BSD-2-Clause
 root	rack	3.2.6	MIT
 root	rainbow	3.1.1	MIT
 root	rake	13.4.2	MIT
-root	rbs	4.1.2	BSD-2-Clause|Ruby
+root	rbs	4.2.0	BSD-2-Clause|Ruby
 root	regexp_parser	2.12.0	MIT
 root	rspec	3.13.2	MIT
 root	rspec-core	3.13.6	MIT

data/docs/audit_reference.md

@@ -36,6 +36,8 @@ Horizon warning threshold: 30 days (`Audit::HORIZON_WARNING_DAYS`). High child c
 
 `partition gap: no attached tail partition extends to MAXVALUE` — missing future/open tail. `apply` to attach `_future`.
 
+`child {name} is missing column {columns} from parent {table}` — a managed LIKE or detached child lacks ordinary columns added on the parent later. `apply` adds those columns atomically then attaches (default). Set `align_child_columns: false` to fail fast. Built-in naming schemes exclude unrelated prefixed tables; custom partition name formatters retain prefix discovery.
+
 Gap objects include `range_start`, `range_end`, and `message`.
 
 ## Plan report

data/docs/configuration.md

@@ -53,6 +53,8 @@ When the gem loads inside Rails, the railtie sets `connection_resolver` and `tod
 
 `retention_detach_concurrently` (default: `false`) — detach dropped archive partitions with `CONCURRENTLY` (global default).
 
+`align_child_columns` (default: `true`) — before `ATTACH PARTITION`, add ordinary parent columns that a LIKE or detached child is missing. Audit warns when a child still lags. Set `false` to fail fast when a child is missing those columns.
+
 ### Advisory locks
 
 Each table run acquires `pg_advisory_lock(hashtext('partition_gardener'), hashtext(table_name))` (or the transaction-scoped variant).
@@ -164,6 +166,8 @@ All templates accept shared options passed through to the registry hash:
 
 `retention_detach_concurrently` (default: global default) — per-table override for concurrent detach.
 
+`align_child_columns` (default: global default) — per-table override. Additive only: add missing ordinary columns in one statement (skip identity and generated), preserving type, non-default collation, default, and `NOT NULL`. If existing rows cannot satisfy `NOT NULL`, PostgreSQL rejects the complete alignment and leaves the child unchanged. Existing types, extra child columns, and other constraints stay as they are.
+
 `maintenance_backend` (default: `:gardener`) — `:gardener`, `:pg_partman`, or `:hybrid_layout_only`.
 
 `incremental_rebalance` (default: global default) — per-table override.

data/docs/schemas/partition_garden.schema.json

@@ -92,6 +92,10 @@
     "retention_detach_concurrently": {
       "type": "boolean"
     },
+    "align_child_columns": {
+      "type": "boolean",
+      "description": "When true (default), atomically add missing ordinary parent columns with their collation, default, and NOT NULL contract on a LIKE or detached child before ATTACH PARTITION"
+    },
     "hash_modulus": {
       "type": "integer",
       "minimum": 2,

data/lib/partition_gardener/audit.rb

@@ -61,6 +61,10 @@ module PartitionGardener
         warnings << "partition gap: #{gap.message}"
       end
 
+      warning_options = {}
+      warning_options[:candidate_table] = method(:managed_child_table?) if @config
+      warnings.concat(ChildColumnAlign.lagging_child_warnings(@table_name, **warning_options))
+
       AuditResult.new(
         table_name: @table_name,
         partitioned: true,
@@ -74,6 +78,18 @@ module PartitionGardener
 
     private
 
+    def managed_child_table?(child_table)
+      return true if @config[:partition_name_format_is_custom] || @config[:archive_partition_name_format]
+      return true if child_table == Naming.rebalance_staging_partition_name(@table_name)
+
+      strategy = (@strategy ||= Strategy.for(@config))
+      return true if strategy.respond_to?(:tail_slot_name?) && strategy.tail_slot_name?(child_table)
+
+      !strategy.archive_bucket_from_partition_name(child_table).nil?
+    rescue Date::Error
+      false
+    end
+
     def compute_horizon_days(partitions)
       today = PartitionGardener.configuration.today
       finite_ends = partitions.filter_map do |partition|

data/lib/partition_gardener/child_column_align.rb

@@ -0,0 +1,165 @@
+module PartitionGardener
+  class ChildColumnAlign
+    Column = Data.define(
+      :name,
+      :type,
+      :not_null,
+      :default_expression,
+      :collation_schema,
+      :collation_name
+    )
+
+    def self.lagging_child_warnings(parent_table, connection: Connection.connection, candidate_table: nil)
+      new(connection: connection).lagging_child_warnings(parent_table, candidate_table: candidate_table)
+    end
+
+    def initialize(connection: Connection.connection)
+      @connection = connection
+    end
+
+    def align!(parent_table, child_table)
+      missing = missing_ordinary_columns(parent_table, child_table)
+      add_columns!(child_table, missing) if missing.any?
+    end
+
+    def lagging_child_warnings(parent_table, candidate_table: nil)
+      child_tables = unattached_child_tables(parent_table)
+      child_tables.select!(&candidate_table) if candidate_table
+      columns_by_table = ordinary_columns_by_table([parent_table, *child_tables])
+      parent_columns = columns_by_table.fetch(parent_table, [])
+
+      child_tables.filter_map do |child_table|
+        missing = missing_columns(parent_columns, columns_by_table.fetch(child_table, []))
+        next if missing.empty?
+
+        missing_columns_warning(child_table, parent_table, missing)
+      end
+    end
+
+    def missing_ordinary_columns(parent_table, child_table)
+      columns_by_table = ordinary_columns_by_table([parent_table, child_table])
+      missing_columns(
+        columns_by_table.fetch(parent_table, []),
+        columns_by_table.fetch(child_table, [])
+      )
+    end
+
+    private
+
+    def add_columns!(child_table, columns)
+      actions = columns.map { |column| add_column_action(column) }.join(",\n  ")
+      @connection.execute(<<~SQL)
+        ALTER TABLE #{quoted_table(child_table)}
+          #{actions}
+      SQL
+    end
+
+    def add_column_action(column)
+      clauses = ["ADD COLUMN #{quoted_column(column.name)} #{column.type}"]
+      if column.collation_name
+        clauses << "COLLATE #{quoted_column(column.collation_schema)}.#{quoted_column(column.collation_name)}"
+      end
+      clauses << "DEFAULT #{column.default_expression}" if usable_default?(column.default_expression)
+      clauses << "NOT NULL" if column.not_null
+      clauses.join(" ")
+    end
+
+    def ordinary_columns_by_table(table_names)
+      names = table_names.uniq
+      quoted_names = names.map { |table_name| @connection.quote(table_name) }.join(", ")
+      sql = <<~SQL
+        SELECT
+          table_class.relname AS table_name,
+          attribute.attname AS name,
+          pg_catalog.format_type(attribute.atttypid, attribute.atttypmod) AS type,
+          attribute.attnotnull AS not_null,
+          pg_get_expr(column_default.adbin, column_default.adrelid) AS default_expression,
+          attribute.attidentity AS identity,
+          attribute.attgenerated AS generated,
+          collation_namespace.nspname AS collation_schema,
+          column_collation.collname AS collation_name
+        FROM pg_attribute attribute
+        LEFT JOIN pg_attrdef column_default
+          ON column_default.adrelid = attribute.attrelid
+          AND column_default.adnum = attribute.attnum
+        JOIN pg_class table_class ON table_class.oid = attribute.attrelid
+        JOIN pg_namespace table_namespace ON table_namespace.oid = table_class.relnamespace
+        JOIN pg_type attribute_type ON attribute_type.oid = attribute.atttypid
+        LEFT JOIN pg_collation column_collation
+          ON column_collation.oid = attribute.attcollation
+          AND attribute.attcollation <> attribute_type.typcollation
+        LEFT JOIN pg_namespace collation_namespace
+          ON collation_namespace.oid = column_collation.collnamespace
+        WHERE table_namespace.nspname = #{@connection.quote(schema_name)}
+          AND table_class.relname IN (#{quoted_names})
+          AND attribute.attnum > 0
+          AND NOT attribute.attisdropped
+        ORDER BY table_class.relname, attribute.attnum
+      SQL
+      @connection.execute(sql).each_with_object({}) do |row, columns_by_table|
+        next if Blank.present?(row["identity"]) || Blank.present?(row["generated"])
+
+        column = Column.new(
+          name: row["name"],
+          type: row["type"],
+          not_null: flag?(row["not_null"]),
+          default_expression: row["default_expression"],
+          collation_schema: row["collation_schema"],
+          collation_name: row["collation_name"]
+        )
+        (columns_by_table[row["table_name"]] ||= []) << column
+      end
+    end
+
+    def missing_columns(parent_columns, child_columns)
+      child_names = child_columns.to_h { |column| [column.name, true] }
+      parent_columns.reject { |column| child_names.key?(column.name) }
+    end
+
+    def unattached_child_tables(parent_table)
+      sql = <<~SQL
+        SELECT child.relname
+        FROM pg_class child
+        JOIN pg_namespace child_namespace ON child_namespace.oid = child.relnamespace
+        WHERE child_namespace.nspname = #{@connection.quote(schema_name)}
+          AND child.relkind = 'r'
+          AND starts_with(child.relname, #{@connection.quote("#{parent_table}_")})
+          AND NOT EXISTS (
+            SELECT 1
+            FROM pg_inherits inheritance
+            WHERE inheritance.inhrelid = child.oid
+          )
+        ORDER BY child.relname
+      SQL
+      @connection.execute(sql).map { |row| row["relname"] }
+    end
+
+    def missing_columns_warning(child_table, parent_table, missing)
+      names = missing.map(&:name).join(", ")
+      noun = (missing.size == 1) ? "column" : "columns"
+      "child #{child_table} is missing #{noun} #{names} from parent #{parent_table}"
+    end
+
+    def usable_default?(expression)
+      return false if Blank.blank?(expression)
+
+      !expression.strip.match?(/\ANULL(::[\w.]+)?\z/i)
+    end
+
+    def flag?(value)
+      value == true || value.to_s == "t" || value.to_s == "true"
+    end
+
+    def quoted_table(name)
+      @connection.quote_table_name(name)
+    end
+
+    def quoted_column(name)
+      @connection.quote_column_name(name)
+    end
+
+    def schema_name
+      PartitionGardener.configuration.schema_name
+    end
+  end
+end

data/lib/partition_gardener/config_document.rb

@@ -22,6 +22,7 @@ module PartitionGardener
       retention_apply
       retention_keep_table
       retention_detach_concurrently
+      align_child_columns
       hash_modulus
       maintenance_backend
       incremental_rebalance
@@ -173,6 +174,7 @@ module PartitionGardener
       validate_registry_conflict_key!(document)
       validate_registry_optional_bucket!(document)
       validate_registry_optional_maintenance_backend!(document)
+      validate_registry_optional_boolean!(document, "align_child_columns")
       document
     end
 
@@ -233,6 +235,13 @@ module PartitionGardener
       raise ArgumentError, "maintenance_backend must be gardener, pg_partman, or hybrid_layout_only"
     end
 
+    def validate_registry_optional_boolean!(document, key)
+      return unless document.key?(key)
+      return if document.fetch(key) == true || document.fetch(key) == false
+
+      raise ArgumentError, "#{key} must be true or false"
+    end
+
     def register_validated_document!(document)
       Registry.register(from_hash(validate_registry_document!(document)))
     end

data/lib/partition_gardener/configuration.rb

@@ -11,6 +11,7 @@ module PartitionGardener
       :incremental_rebalance,
       :run_record_enabled,
       :retention_detach_concurrently,
+      :align_child_columns,
       :strict_maintenance_backend_validation,
       :current_run_metrics
 
@@ -29,6 +30,7 @@ module PartitionGardener
       @run_record_enabled = true
       @run_record_store = nil
       @retention_detach_concurrently = false
+      @align_child_columns = true
       @strict_maintenance_backend_validation = false
       @current_run_metrics = nil
     end

data/lib/partition_gardener/executor.rb

@@ -5,16 +5,26 @@ module PartitionGardener
     def self.for_config(config, connection: Connection.connection)
       new(
         connection: connection,
-        batch_size: config.fetch(:move_batch_size, MOVE_BATCH_SIZE)
+        batch_size: config.fetch(:move_batch_size, MOVE_BATCH_SIZE),
+        align_child_columns: config.fetch(
+          :align_child_columns,
+          PartitionGardener.configuration.align_child_columns
+        )
       )
     end
 
-    def initialize(connection: Connection.connection, batch_size: MOVE_BATCH_SIZE)
+    def initialize(
+      connection: Connection.connection,
+      batch_size: MOVE_BATCH_SIZE,
+      align_child_columns: PartitionGardener.configuration.align_child_columns
+    )
       @connection = connection
       @batch_size = batch_size
+      @align_child_columns = align_child_columns
     end
 
     def attach_partition(table_name, partition_name, for_values_clause)
+      align_child_columns!(table_name, partition_name)
       sql = <<~SQL
         ALTER TABLE #{quoted_table(table_name)} ATTACH PARTITION #{quoted_table(partition_name)}
         FOR VALUES #{for_values_clause}
@@ -23,6 +33,7 @@ module PartitionGardener
     end
 
     def attach_default_partition(table_name, partition_name)
+      align_child_columns!(table_name, partition_name)
       sql = <<~SQL
         ALTER TABLE #{quoted_table(table_name)} ATTACH PARTITION #{quoted_table(partition_name)} DEFAULT
       SQL
@@ -59,6 +70,7 @@ module PartitionGardener
         )
       SQL
       @connection.execute(sql)
+      align_child_columns!(table_name, partition_name)
 
       conflict_columns = conflict_key.map { |column| @connection.quote_column_name(column) }.join(", ")
       sql = <<~SQL
@@ -141,6 +153,12 @@ module PartitionGardener
 
     private
 
+    def align_child_columns!(parent_table, child_table)
+      return unless @align_child_columns
+
+      ChildColumnAlign.new(connection: @connection).align!(parent_table, child_table)
+    end
+
     def quoted_table(name)
       @connection.quote_table_name(name)
     end

data/lib/partition_gardener/templates.rb

@@ -4,6 +4,9 @@ module PartitionGardener
 
     def normalize(config)
       config = config.dup
+      unless config.key?(:partition_name_format_is_custom)
+        config[:partition_name_format_is_custom] = config.key?(:partition_name_format)
+      end
       config[:layout] ||= :sliding_window
       config[:bucket] ||= :month if date_layout?(config[:layout])
       config
@@ -106,6 +109,7 @@ module PartitionGardener
         conflict_key: conflict_key,
         premake_months: premake_months,
         maintenance_backend: options.fetch(:maintenance_backend, :gardener),
+        partition_name_format_is_custom: options.key?(:partition_name_format),
         partition_name_format: options.fetch(:partition_name_format) {
           ->(identifier) { DateBucket.partition_name(table_name, identifier, :month) }
         },
@@ -128,6 +132,7 @@ module PartitionGardener
         partition_key_column: partition_key_column,
         conflict_key: conflict_key,
         active_years: active_years,
+        partition_name_format_is_custom: options.key?(:partition_name_format),
         partition_name_format: options.fetch(:partition_name_format) {
           ->(identifier) { DateBucket.partition_name(table_name, identifier, :year) }
         },
@@ -301,6 +306,7 @@ module PartitionGardener
         :partition_key_column => partition_key_column,
         :conflict_key => conflict_key,
         active_key => active_value,
+        :partition_name_format_is_custom => options.key?(:partition_name_format),
         :partition_name_format => options.fetch(:partition_name_format) {
           ->(identifier) { DateBucket.partition_name(table_name, identifier, bucket) }
         },

data/lib/partition_gardener/version.rb

@@ -1,3 +1,3 @@
 module PartitionGardener
-  VERSION = "0.3.3"
+  VERSION = "0.3.4"
 end

data/lib/partition_gardener.rb

@@ -14,6 +14,7 @@ require_relative "partition_gardener/configuration"
 require_relative "partition_gardener/naming"
 require_relative "partition_gardener/plan"
 require_relative "partition_gardener/connection"
+require_relative "partition_gardener/child_column_align"
 require_relative "partition_gardener/executor"
 require_relative "partition_gardener/default_partition"
 require_relative "partition_gardener/strategy/requires_default_partition"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: partition_gardener
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
 platform: ruby
 authors:
 - Andrei Makarov
@@ -303,6 +303,7 @@ files:
 - lib/partition_gardener/archive_retention.rb
 - lib/partition_gardener/audit.rb
 - lib/partition_gardener/blank.rb
+- lib/partition_gardener/child_column_align.rb
 - lib/partition_gardener/cli.rb
 - lib/partition_gardener/config_document.rb
 - lib/partition_gardener/configuration.rb