pcrd 0.1.0

data/lib/pcrd/schema/differ.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Pcrd
+  module Schema
+    # Computes the diff between source and target schemas, optionally guided
+    # by a migration spec (Config::Table).
+    #
+    # Two modes:
+    #
+    #   Synthesis mode (target_columns: nil)
+    #     The target schema is synthesized by applying the migration spec to the
+    #     source columns. Use this to preview what the target will look like before
+    #     the migration has run.
+    #
+    #   Real-target mode (target_columns: [...])
+    #     The target schema comes from a live database query. The spec is used
+    #     to understand source→target column name mappings; without a spec,
+    #     columns are matched by name.
+    class Differ
+      # Returns Array<DiffEntry> in source-column order, added columns last.
+      #
+      # source_columns: Array<Schema::Column>
+      # table_config:   Config::Table or nil
+      # target_columns: Array<Schema::Column> or nil (triggers synthesis)
+      def diff(source_columns:, table_config: nil, target_columns: nil)
+        if target_columns.nil?
+          synthesize_diff(source_columns, table_config)
+        else
+          real_diff(source_columns, table_config, target_columns)
+        end
+      end
+
+      # Extracts target-side columns from a diff for use in padding analysis.
+      def target_columns_from_diff(entries)
+        entries
+          .reject(&:dropped?)
+          .map(&:target_column)
+          .compact
+      end
+
+      private
+
+      # -----------------------------------------------------------------------
+      # Synthesis path: build target columns from source + spec
+      # -----------------------------------------------------------------------
+
+      def synthesize_diff(source_columns, table_config)
+        spec_columns = table_config&.columns || {}
+        entries      = []
+
+        source_columns.each do |src|
+          col_spec = spec_columns[src.name]
+
+          if col_spec&.drop
+            entries << DiffEntry.new(status: :dropped, source_column: src, target_column: nil)
+          else
+            target = synthesize_column(src, col_spec)
+            status = compute_status(src, target, col_spec)
+            entries << DiffEntry.new(status: status, source_column: src, target_column: target)
+          end
+        end
+
+        # Added columns come last.
+        (table_config&.add_columns || []).each do |add_col|
+          target = build_added_column(add_col)
+          entries << DiffEntry.new(status: :added, source_column: nil, target_column: target)
+        end
+
+        entries
+      end
+
+      def synthesize_column(source_col, col_spec)
+        new_name = col_spec&.rename || source_col.name
+        new_type = col_spec&.type
+
+        if new_type
+          info = TypeRegistry.lookup(new_type)
+          Column.new(
+            attnum:         source_col.attnum,
+            name:           new_name,
+            type_name:      info.canonical_name,
+            formatted_type: new_type,
+            alignment:      info.alignment,
+            fixed_size:     info.fixed_size,
+            nullable:       source_col.nullable,
+            default_expr:   source_col.default_expr
+          )
+        else
+          Column.new(
+            attnum:         source_col.attnum,
+            name:           new_name,
+            type_name:      source_col.type_name,
+            formatted_type: source_col.formatted_type,
+            alignment:      source_col.alignment,
+            fixed_size:     source_col.fixed_size,
+            nullable:       source_col.nullable,
+            default_expr:   source_col.default_expr
+          )
+        end
+      end
+
+      def build_added_column(add_col)
+        info = TypeRegistry.lookup(add_col.type)
+        Column.new(
+          attnum:         nil,
+          name:           add_col.name,
+          type_name:      info.canonical_name,
+          formatted_type: add_col.type,
+          alignment:      info.alignment,
+          fixed_size:     info.fixed_size,
+          nullable:       true,
+          default_expr:   add_col.default
+        )
+      end
+
+      def compute_status(src, target, col_spec)
+        type_changed   = src.type_name != target.type_name ||
+                         src.formatted_type.downcase != target.formatted_type.downcase
+        name_changed   = src.name != target.name
+
+        if type_changed && name_changed
+          :type_and_renamed
+        elsif type_changed
+          :type_changed
+        elsif name_changed
+          :renamed
+        else
+          :unchanged
+        end
+      end
+
+      # -----------------------------------------------------------------------
+      # Real-target path: match live source and target columns
+      # -----------------------------------------------------------------------
+
+      def real_diff(source_columns, table_config, target_columns)
+        spec_columns  = table_config&.columns || {}
+        target_by_name = target_columns.each_with_object({}) { |c, h| h[c.name] = c }
+        entries = []
+        matched_targets = Set.new
+
+        source_columns.each do |src|
+          col_spec    = spec_columns[src.name]
+          target_name = col_spec&.rename || src.name
+
+          if col_spec&.drop
+            entries << DiffEntry.new(status: :dropped, source_column: src, target_column: nil)
+            next
+          end
+
+          tgt = target_by_name[target_name]
+          if tgt
+            matched_targets << tgt.name
+            status = compute_status(src, tgt, col_spec)
+            entries << DiffEntry.new(status: status, source_column: src, target_column: tgt)
+          else
+            # Column expected on target but not found — treat as dropped.
+            entries << DiffEntry.new(status: :dropped, source_column: src, target_column: nil)
+          end
+        end
+
+        # Columns present on target but not matched from source are additions.
+        target_columns.each do |tgt|
+          next if matched_targets.include?(tgt.name)
+
+          entries << DiffEntry.new(status: :added, source_column: nil, target_column: tgt)
+        end
+
+        entries
+      end
+    end
+  end
+end

data/lib/pcrd/schema/object_reader.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Pcrd
+  module Schema
+    # Reads the "secondary" schema objects that the load DDL deliberately omits
+    # (Schema::DDL creates only the table + primary key). Used by the
+    # target-readiness manifest to report and regenerate what must exist on the
+    # target before cutover.
+    #
+    # Works against either cluster — point it at the source to discover objects,
+    # at the target to see what already exists.
+    class ObjectReader
+      Index      = Data.define(:name, :definition, :unique, :columns)
+      Constraint = Data.define(:name, :kind, :definition, :columns) # kind: f|u|c
+      IdentityColumn = Data.define(:column, :kind) # kind: "identity" | "serial"
+      Grant      = Data.define(:grantee, :privileges)
+
+      def initialize(pool)
+        @pool = pool
+      end
+
+      # Non-PK indexes that are not backing a unique/PK constraint (those are
+      # reported under #constraints instead, to avoid double-counting).
+      def indexes(table_name, schema_name: "public")
+        @pool.exec(INDEXES_SQL, [table_name, schema_name]).map do |r|
+          Index.new(
+            name:       r["index_name"],
+            definition: r["definition"],
+            unique:     r["indisunique"] == "t",
+            columns:    split_list(r["columns"])
+          )
+        end
+      end
+
+      # Foreign-key, unique, and check constraints (not the primary key).
+      def constraints(table_name, schema_name: "public")
+        @pool.exec(CONSTRAINTS_SQL, [table_name, schema_name]).map do |r|
+          Constraint.new(
+            name:       r["conname"],
+            kind:       r["contype"],
+            definition: r["definition"],
+            columns:    split_list(r["columns"])
+          )
+        end
+      end
+
+      # Identity (GENERATED ... AS IDENTITY) and serial (nextval default) columns.
+      def identity_columns(table_name, schema_name: "public")
+        @pool.exec(IDENTITY_SQL, [table_name, schema_name]).map do |r|
+          IdentityColumn.new(
+            column: r["attname"],
+            kind:   r["attidentity"].to_s.empty? ? "serial" : "identity"
+          )
+        end
+      end
+
+      # The table's owner role name.
+      def owner(table_name, schema_name: "public")
+        row = @pool.exec(OWNER_SQL, [table_name, schema_name])
+        row.ntuples.zero? ? nil : row[0]["owner"]
+      end
+
+      # Explicit table privileges (the owner's implicit grant is excluded), one
+      # Grant per grantee with its sorted privilege list.
+      def grants(table_name, schema_name: "public")
+        owner_name = owner(table_name, schema_name: schema_name)
+        by_grantee = Hash.new { |h, k| h[k] = [] }
+
+        @pool.exec(GRANTS_SQL, [table_name, schema_name]).each do |r|
+          next if r["grantee"] == owner_name # owner already has everything
+
+          by_grantee[r["grantee"]] << r["privilege_type"]
+        end
+
+        by_grantee.map { |grantee, privs| Grant.new(grantee: grantee, privileges: privs.sort) }
+      end
+
+      # The table's COMMENT, or nil.
+      def table_comment(table_name, schema_name: "public")
+        row = @pool.exec(TABLE_COMMENT_SQL, [table_name, schema_name])
+        row.ntuples.zero? ? nil : row[0]["comment"]
+      end
+
+      # Hash<column_name, comment> for columns that have a COMMENT.
+      def column_comments(table_name, schema_name: "public")
+        @pool.exec(COLUMN_COMMENTS_SQL, [table_name, schema_name])
+             .each_with_object({}) { |r, h| h[r["attname"]] = r["comment"] }
+      end
+
+      private
+
+      def split_list(str)
+        str.to_s.empty? ? [] : str.split(",")
+      end
+
+      OWNER_SQL = <<~SQL.freeze
+        SELECT pg_get_userbyid(c.relowner) AS owner
+        FROM   pg_class c
+        JOIN   pg_namespace n ON n.oid = c.relnamespace
+        WHERE  c.relname = $1 AND n.nspname = $2
+      SQL
+
+      GRANTS_SQL = <<~SQL.freeze
+        SELECT CASE WHEN g.grantee = 0 THEN 'PUBLIC'
+                    ELSE pg_get_userbyid(g.grantee) END AS grantee,
+               g.privilege_type
+        FROM   pg_class c
+        JOIN   pg_namespace n ON n.oid = c.relnamespace
+        CROSS  JOIN LATERAL aclexplode(c.relacl) AS g
+        WHERE  c.relname = $1 AND n.nspname = $2
+      SQL
+
+      TABLE_COMMENT_SQL = <<~SQL.freeze
+        SELECT obj_description(c.oid, 'pg_class') AS comment
+        FROM   pg_class c
+        JOIN   pg_namespace n ON n.oid = c.relnamespace
+        WHERE  c.relname = $1 AND n.nspname = $2
+      SQL
+
+      COLUMN_COMMENTS_SQL = <<~SQL.freeze
+        SELECT a.attname, col_description(a.attrelid, a.attnum) AS comment
+        FROM   pg_attribute a
+        JOIN   pg_class c     ON c.oid = a.attrelid
+        JOIN   pg_namespace n ON n.oid = c.relnamespace
+        WHERE  c.relname = $1 AND n.nspname = $2
+          AND  a.attnum > 0 AND NOT a.attisdropped
+          AND  col_description(a.attrelid, a.attnum) IS NOT NULL
+        ORDER  BY a.attnum
+      SQL
+
+      INDEXES_SQL = <<~SQL.freeze
+        SELECT i.relname AS index_name,
+               pg_get_indexdef(ix.indexrelid) AS definition,
+               ix.indisunique,
+               array_to_string(ARRAY(
+                 SELECT a.attname
+                 FROM   unnest(ix.indkey) WITH ORDINALITY AS k(attnum, ord)
+                 JOIN   pg_attribute a ON a.attrelid = ix.indrelid AND a.attnum = k.attnum
+                 WHERE  k.attnum <> 0
+                 ORDER  BY k.ord
+               ), ',') AS columns
+        FROM   pg_index ix
+        JOIN   pg_class i     ON i.oid = ix.indexrelid
+        JOIN   pg_class t     ON t.oid = ix.indrelid
+        JOIN   pg_namespace n ON n.oid = t.relnamespace
+        WHERE  t.relname = $1 AND n.nspname = $2
+          AND  NOT ix.indisprimary
+          AND  ix.indexrelid NOT IN (
+                 SELECT conindid FROM pg_constraint
+                 WHERE  conrelid = t.oid AND conindid <> 0
+               )
+        ORDER  BY i.relname
+      SQL
+
+      CONSTRAINTS_SQL = <<~SQL.freeze
+        SELECT c.conname,
+               c.contype,
+               pg_get_constraintdef(c.oid) AS definition,
+               array_to_string(ARRAY(
+                 SELECT a.attname
+                 FROM   unnest(c.conkey) WITH ORDINALITY AS k(attnum, ord)
+                 JOIN   pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.attnum
+                 ORDER  BY k.ord
+               ), ',') AS columns
+        FROM   pg_constraint c
+        JOIN   pg_class t     ON t.oid = c.conrelid
+        JOIN   pg_namespace n ON n.oid = t.relnamespace
+        WHERE  t.relname = $1 AND n.nspname = $2
+          AND  c.contype IN ('f', 'u', 'c')
+        ORDER  BY c.conname
+      SQL
+
+      IDENTITY_SQL = <<~SQL.freeze
+        SELECT a.attname, a.attidentity
+        FROM   pg_attribute a
+        JOIN   pg_class t     ON t.oid = a.attrelid
+        JOIN   pg_namespace n ON n.oid = t.relnamespace
+        LEFT   JOIN pg_attrdef ad ON ad.adrelid = a.attrelid AND ad.adnum = a.attnum
+        WHERE  t.relname = $1 AND n.nspname = $2
+          AND  a.attnum > 0 AND NOT a.attisdropped
+          AND  (a.attidentity IN ('a', 'd')
+                OR pg_get_expr(ad.adbin, ad.adrelid) LIKE 'nextval(%')
+        ORDER  BY a.attnum
+      SQL
+    end
+  end
+end

data/lib/pcrd/schema/packer.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Pcrd
+  module Schema
+    # Analyzes column alignment and computes optimal ordering to minimize padding waste.
+    #
+    # PostgreSQL stores columns in definition order. Each column must start at an
+    # address aligned to its type's natural alignment boundary. When a small-aligned
+    # column (e.g. bool, 1 byte) precedes a large-aligned column (e.g. timestamp,
+    # 8 bytes), PostgreSQL inserts padding bytes to satisfy the alignment requirement
+    # of the larger type. Reordering columns largest-alignment-first eliminates this
+    # waste entirely for fixed-size columns.
+    #
+    # Variable-length columns (text, varchar, numeric, etc.) have a 4-byte aligned
+    # varlena header. Their actual content length is not predictable, so we count only
+    # the header for padding estimates and place them last where they contribute no
+    # cross-column alignment overhead.
+    class Packer
+      # A single entry in a layout: the column plus the padding bytes inserted
+      # before it to satisfy its alignment requirement.
+      LayoutEntry = Data.define(:column, :offset, :padding_before)
+
+      # Returns columns in optimal order: 8-byte → 4-byte → 2-byte → 1-byte → variable.
+      # Within each alignment tier, preserves the original column order.
+      def optimize(columns)
+        fixed    = columns.select(&:fixed?)
+        variable = columns.select(&:variable?)
+        sorted_fixed = fixed.sort_by.with_index { |c, i| [-c.alignment, -c.fixed_size, i] }
+        sorted_fixed + variable
+      end
+
+      # Computes the per-column layout (offset and padding before each column).
+      # Returns Array<LayoutEntry>.
+      def layout(columns)
+        offset  = 0
+        entries = []
+
+        columns.each do |col|
+          align   = col.fixed? ? col.alignment : 4  # varlena header is 4-byte aligned
+          padding = padding_needed(offset, align)
+          entries << LayoutEntry.new(column: col, offset: offset + padding, padding_before: padding)
+          offset  += padding + (col.fixed? ? col.fixed_size : 4)  # count header only for varlena
+        end
+
+        entries
+      end
+
+      # Estimated bytes consumed by fixed-length columns plus alignment padding.
+      # Variable-length columns contribute 4 bytes each (header only).
+      def estimated_row_size(columns)
+        layout(columns).sum do |e|
+          e.padding_before + (e.column.fixed? ? e.column.fixed_size : 4)
+        end
+      end
+
+      # Total wasted padding bytes across all columns.
+      def total_padding(columns)
+        layout(columns).sum(&:padding_before)
+      end
+
+      # Returns a report hash comparing current vs optimal layout.
+      def report(columns)
+        optimal_order = optimize(columns)
+
+        current_size  = estimated_row_size(columns)
+        optimal_size  = estimated_row_size(optimal_order)
+        saved_bytes   = current_size - optimal_size
+        pct           = current_size > 0 ? (saved_bytes.to_f / current_size * 100).round(1) : 0.0
+
+        {
+          current_columns:  columns,
+          optimal_columns:  optimal_order,
+          current_layout:   layout(columns),
+          optimal_layout:   layout(optimal_order),
+          current_size:     current_size,
+          optimal_size:     optimal_size,
+          saved_bytes:      saved_bytes,
+          savings_pct:      pct,
+          already_optimal:  saved_bytes.zero?
+        }
+      end
+
+      private
+
+      def padding_needed(offset, alignment)
+        (alignment - (offset % alignment)) % alignment
+      end
+    end
+  end
+end

data/lib/pcrd/schema/reader.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Pcrd
+  module Schema
+    class Reader
+      TYPALIGN_BYTES = { "c" => 1, "s" => 2, "i" => 4, "d" => 8 }.freeze
+
+      def initialize(pool)
+        @pool = pool
+      end
+
+      def read(table_name, schema_name: "public")
+        rows = @pool.exec(COLUMNS_QUERY, [table_name, schema_name])
+        raise TableNotFound, "Table #{schema_name}.#{table_name} not found" if rows.ntuples.zero?
+
+        rows.map { build_column(_1) }
+      end
+
+      def table_exists?(table_name, schema_name: "public")
+        result = @pool.exec(<<~SQL, [table_name, schema_name])
+          SELECT 1
+          FROM   pg_class c
+          JOIN   pg_namespace n ON n.oid = c.relnamespace
+          WHERE  c.relname = $1
+            AND  n.nspname = $2
+            AND  c.relkind = 'r'
+        SQL
+        result.ntuples > 0
+      end
+
+      # Returns an array of column names that form the primary key, in key order.
+      def primary_key_columns(table_name, schema_name: "public")
+        result = @pool.exec(<<~SQL, [table_name, schema_name])
+          SELECT a.attname
+          FROM   pg_index i
+          JOIN   pg_attribute a ON a.attrelid = i.indrelid
+                               AND a.attnum = ANY(i.indkey)
+          JOIN   pg_class c     ON c.oid = i.indrelid
+          JOIN   pg_namespace n ON n.oid = c.relnamespace
+          WHERE  c.relname = $1
+            AND  n.nspname = $2
+            AND  i.indisprimary
+          ORDER BY array_position(i.indkey, a.attnum)
+        SQL
+        result.column_values(0)
+      end
+
+      # Returns the table's replica identity setting as a single char:
+      #   'd' default (primary key)   'n' nothing
+      #   'f' full (whole row)        'i' a specific unique index
+      # Returns nil if the table is not found. This governs whether UPDATE/DELETE
+      # WAL records carry the old-row key columns the apply engine needs.
+      def replica_identity(table_name, schema_name: "public")
+        result = @pool.exec(<<~SQL, [table_name, schema_name])
+          SELECT c.relreplident
+          FROM   pg_class c
+          JOIN   pg_namespace n ON n.oid = c.relnamespace
+          WHERE  c.relname = $1
+            AND  n.nspname = $2
+        SQL
+        result.ntuples > 0 ? result[0]["relreplident"] : nil
+      end
+
+      # Returns the estimated live row count from pg_class statistics.
+      def estimated_row_count(table_name, schema_name: "public")
+        result = @pool.exec(<<~SQL, [table_name, schema_name])
+          SELECT c.reltuples::bigint
+          FROM   pg_class c
+          JOIN   pg_namespace n ON n.oid = c.relnamespace
+          WHERE  c.relname = $1
+            AND  n.nspname = $2
+        SQL
+        result.ntuples > 0 ? result[0]["reltuples"].to_i : 0
+      end
+
+      private
+
+      COLUMNS_QUERY = <<~SQL.freeze
+        SELECT
+          a.attnum,
+          a.attname,
+          t.typname,
+          format_type(a.atttypid, a.atttypmod) AS formatted_type,
+          t.typalign,
+          t.typlen,
+          NOT a.attnotnull         AS nullable,
+          pg_get_expr(d.adbin, d.adrelid) AS default_expr
+        FROM   pg_attribute a
+        JOIN   pg_class c     ON c.oid = a.attrelid
+        JOIN   pg_namespace n ON n.oid = c.relnamespace
+        JOIN   pg_type t      ON t.oid = a.atttypid
+        LEFT   JOIN pg_attrdef d
+               ON  d.adrelid = a.attrelid AND d.adnum = a.attnum
+        WHERE  c.relname = $1
+          AND  n.nspname = $2
+          AND  a.attnum > 0
+          AND  NOT a.attisdropped
+        ORDER  BY a.attnum
+      SQL
+
+      def build_column(row)
+        typlen    = row["typlen"].to_i
+        fixed_size = typlen > 0 ? typlen : nil  # -1 = varlena, -2 = C string
+
+        Column.new(
+          attnum:         row["attnum"].to_i,
+          name:           row["attname"],
+          type_name:      row["typname"],
+          formatted_type: row["formatted_type"],
+          alignment:      TYPALIGN_BYTES.fetch(row["typalign"], 4),
+          fixed_size:     fixed_size,
+          nullable:       row["nullable"] == "t",
+          default_expr:   row["default_expr"]
+        )
+      end
+    end
+  end
+end