pcrd 0.1.0

data/lib/pcrd/schema/setup.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Pcrd
+  module Schema
+    # Creates target tables from the migration spec.
+    # Called at the start of `pcrd migrate` (after preflight passes).
+    #
+    # In the full streaming flow (Phase 9+), Setup also creates the publication
+    # and replication slot on source. For --backfill-only those are skipped.
+    class Setup
+      def initialize(source_pool:, target_pool:, config:)
+        @source_pool = source_pool
+        @target_pool = target_pool
+        @config      = config
+      end
+
+      # Creates the publication and replication slot on the source.
+      # Returns the slot's starting LSN as a "X/Y" string — pass this to the
+      # consumer so streaming begins from a point that covers all of backfill.
+      # Idempotently ensures the publication and replication slot exist for a
+      # fresh migration, returning the slot's starting LSN ("X/Y").
+      #
+      # A leftover publication from a partial prior run is reused if it covers
+      # exactly the configured tables (it is just a definition). A leftover
+      # slot is NOT reused: its WAL position is unknown relative to backfill, so
+      # we refuse and point the operator at --resume or `pcrd cleanup`.
+      def create_publication_and_slot(pub_name:, slot_name:)
+        ensure_publication(pub_name)
+
+        if slot_exists?(slot_name)
+          raise SetupError, "Replication slot '#{slot_name}' already exists. Resume the existing " \
+                            "migration with --resume, or remove it with `pcrd cleanup` to start over."
+        end
+
+        result = @source_pool.exec(
+          "SELECT lsn FROM pg_create_logical_replication_slot($1, 'pgoutput')",
+          [slot_name]
+        )
+        result[0]["lsn"]
+      end
+
+      # Validates that a --resume run has the slot and publication it needs.
+      # Raises with a clear message if either is missing.
+      def validate_resumable!(pub_name:, slot_name:)
+        unless slot_exists?(slot_name)
+          raise SetupError, "Cannot resume: replication slot '#{slot_name}' does not exist on the source. " \
+                            "Start a fresh migration (without --resume)."
+        end
+
+        unless publication_exists?(pub_name)
+          raise SetupError, "Cannot resume: publication '#{pub_name}' does not exist on the source. " \
+                            "Start a fresh migration (without --resume)."
+        end
+      end
+
+      # Drops the publication and replication slot (cleanup phase).
+      def drop_publication_and_slot(pub_name:, slot_name:)
+        @source_pool.exec_sql(
+          "DROP PUBLICATION IF EXISTS #{@source_pool.quote_ident(pub_name)}"
+        )
+        @source_pool.exec(
+          "SELECT pg_drop_replication_slot($1) WHERE EXISTS (" \
+          "  SELECT 1 FROM pg_replication_slots WHERE slot_name = $1)",
+          [slot_name]
+        )
+      end
+
+      # Creates all target tables and returns a Hash<table_name, ddl_string>.
+      # Raises if a target table already exists (use --force-overwrite to drop first).
+      def create_target_tables(force_overwrite: false)
+        reader = Reader.new(@source_pool)
+        ddls   = {}
+
+        @config.migrate.tables.each do |table_config|
+          name        = table_config.name
+          source_cols = reader.read(name)
+          pk_cols     = reader.primary_key_columns(name)
+
+          ddl = DDL.generate(
+            source_columns:      source_cols,
+            table_config:        table_config,
+            primary_key_columns: pk_cols
+          )
+
+          target_reader = Reader.new(@target_pool)
+          if target_reader.table_exists?(name)
+            if force_overwrite
+              @target_pool.exec_sql("DROP TABLE IF EXISTS #{Sql.quote_table(name)} CASCADE")
+            else
+              raise SetupError, "Table '#{name}' already exists on target. " \
+                                "Pass --force-overwrite to drop and recreate."
+            end
+          end
+
+          @target_pool.exec_sql("#{ddl};")
+          ddls[name] = ddl
+        end
+
+        ddls
+      end
+
+      private
+
+      # Creates the publication if absent; reuses it if it already covers exactly
+      # the configured tables; raises if it exists but covers a different set.
+      def ensure_publication(pub_name)
+        configured = @config.migrate.tables.map(&:name).sort
+
+        if publication_exists?(pub_name)
+          existing = publication_tables(pub_name).sort
+          return if existing == configured
+
+          raise SetupError, "Publication '#{pub_name}' already exists but covers #{existing.inspect}, " \
+                            "not the configured tables #{configured.inspect}. " \
+                            "Drop it with `pcrd cleanup` or reconcile the config."
+        end
+
+        table_list = @config.migrate.tables.map { |t| Sql.quote_table(t.name) }.join(", ")
+        @source_pool.exec_sql(
+          "CREATE PUBLICATION #{@source_pool.quote_ident(pub_name)} FOR TABLE #{table_list}"
+        )
+      end
+
+      def publication_exists?(pub_name)
+        @source_pool.exec(
+          "SELECT 1 FROM pg_publication WHERE pubname = $1", [pub_name]
+        ).ntuples.positive?
+      end
+
+      def publication_tables(pub_name)
+        @source_pool.exec(
+          "SELECT tablename FROM pg_publication_tables WHERE pubname = $1", [pub_name]
+        ).column_values(0)
+      end
+
+      def slot_exists?(slot_name)
+        @source_pool.exec(
+          "SELECT 1 FROM pg_replication_slots WHERE slot_name = $1", [slot_name]
+        ).ntuples.positive?
+      end
+    end
+  end
+end

data/lib/pcrd/schema/setup_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Pcrd
+  module Schema
+    # Raised when replication/target setup cannot proceed safely — an existing
+    # slot, a mismatched publication, or a target table that already exists.
+    class SetupError < Pcrd::Error; end
+  end
+end

data/lib/pcrd/schema/table_not_found.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Pcrd
+  module Schema
+    # Raised when a configured table is not present on the source.
+    class TableNotFound < Pcrd::Error; end
+  end
+end

data/lib/pcrd/schema/type_registry.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Pcrd
+  module Schema
+    # Maps PostgreSQL type name strings (as they appear in migration specs)
+    # to the physical storage properties needed for padding analysis and
+    # synthetic column construction.
+    #
+    # Used when building target Schema::Column objects from a migration spec
+    # without a real target DB connection.
+    module TypeRegistry
+      TypeInfo = Data.define(:canonical_name, :alignment, :fixed_size)
+
+      # Fixed-size types with exact mappings.
+      FIXED = {
+        # 8-byte, 8-byte aligned
+        "bigint"                       => TypeInfo.new(canonical_name: "bigint",            alignment: 8, 
+fixed_size: 8),
+        "int8"                         => TypeInfo.new(canonical_name: "bigint",            alignment: 8, 
+fixed_size: 8),
+        "double precision"             => TypeInfo.new(canonical_name: "double precision",  alignment: 8, 
+fixed_size: 8),
+        "float8"                       => TypeInfo.new(canonical_name: "double precision",  alignment: 8, 
+fixed_size: 8),
+        "timestamp"                    => TypeInfo.new(canonical_name: "timestamp",         alignment: 8, 
+fixed_size: 8),
+        "timestamp without time zone"  => TypeInfo.new(canonical_name: "timestamp",         alignment: 8, 
+fixed_size: 8),
+        "timestamptz"                  => TypeInfo.new(canonical_name: "timestamptz",       alignment: 8, 
+fixed_size: 8),
+        "timestamp with time zone"     => TypeInfo.new(canonical_name: "timestamptz",       alignment: 8, 
+fixed_size: 8),
+        "interval"                     => TypeInfo.new(canonical_name: "interval",          alignment: 8, 
+fixed_size: 16),
+        "money"                        => TypeInfo.new(canonical_name: "money",             alignment: 8, 
+fixed_size: 8),
+        # 4-byte, 4-byte aligned
+        "integer"                      => TypeInfo.new(canonical_name: "integer",           alignment: 4, 
+fixed_size: 4),
+        "int4"                         => TypeInfo.new(canonical_name: "integer",           alignment: 4, 
+fixed_size: 4),
+        "int"                          => TypeInfo.new(canonical_name: "integer",           alignment: 4, 
+fixed_size: 4),
+        "real"                         => TypeInfo.new(canonical_name: "real",              alignment: 4, 
+fixed_size: 4),
+        "float4"                       => TypeInfo.new(canonical_name: "real",              alignment: 4, 
+fixed_size: 4),
+        "date"                         => TypeInfo.new(canonical_name: "date",              alignment: 4, 
+fixed_size: 4),
+        "time"                         => TypeInfo.new(canonical_name: "time",              alignment: 4, 
+fixed_size: 8),
+        "time without time zone"       => TypeInfo.new(canonical_name: "time",              alignment: 4, 
+fixed_size: 8),
+        "oid"                          => TypeInfo.new(canonical_name: "oid",               alignment: 4, 
+fixed_size: 4),
+        # 2-byte, 2-byte aligned
+        "smallint"                     => TypeInfo.new(canonical_name: "smallint",          alignment: 2, 
+fixed_size: 2),
+        "int2"                         => TypeInfo.new(canonical_name: "smallint",          alignment: 2, 
+fixed_size: 2),
+        # 1-byte, 1-byte aligned
+        "boolean"                      => TypeInfo.new(canonical_name: "boolean",           alignment: 1, 
+fixed_size: 1),
+        "bool"                         => TypeInfo.new(canonical_name: "boolean",           alignment: 1, 
+fixed_size: 1),
+        "\"char\""                     => TypeInfo.new(canonical_name: "\"char\"",          alignment: 1, 
+fixed_size: 1),
+      }.freeze
+
+      # Variable-length types (varlena): 4-byte aligned header, variable content.
+      VARIABLE = %w[
+        text varchar character\ varying bytea json jsonb xml
+        numeric decimal cidr inet macaddr tsvector tsquery
+        character char
+      ].freeze
+
+      # Prefixes that indicate a parameterized variable-length type,
+      # e.g. "varchar(255)", "numeric(10,2)", "char(2)".
+      VARIABLE_PREFIXES = %w[
+        varchar character\ varying numeric decimal char character
+        bit varying varbit
+      ].freeze
+
+      # Returns a TypeInfo for the given type string, or a safe variable-length
+      # default if the type is unknown. Never raises.
+      def self.lookup(type_str)
+        normalized = type_str.to_s.strip.downcase
+
+        # Exact match first.
+        return FIXED[normalized] if FIXED.key?(normalized)
+
+        # Parameterized variable-length types: varchar(N), numeric(P,S), etc.
+        VARIABLE_PREFIXES.each do |prefix|
+          if normalized.start_with?(prefix)
+            return TypeInfo.new(canonical_name: type_str, alignment: 4, fixed_size: nil)
+          end
+        end
+
+        # Plain variable-length names.
+        VARIABLE.each do |name|
+          return TypeInfo.new(canonical_name: type_str, alignment: 4, fixed_size: nil) if normalized == name
+        end
+
+        # Unknown type: assume variable-length (safest for padding analysis).
+        TypeInfo.new(canonical_name: type_str, alignment: 4, fixed_size: nil)
+      end
+
+      def self.known?(type_str)
+        normalized = type_str.to_s.strip.downcase
+        return true if FIXED.key?(normalized)
+        VARIABLE_PREFIXES.any? { |p| normalized.start_with?(p) } ||
+          VARIABLE.include?(normalized)
+      end
+    end
+  end
+end

data/lib/pcrd/sql.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Pcrd
+  # Centralized SQL identifier rendering. Every place that builds SQL (DDL,
+  # setup, apply, verify, validation) goes through here so quoting and schema
+  # qualification are consistent instead of three different conventions —
+  # some of which interpolated identifiers raw and broke on mixed-case,
+  # reserved-word, or non-public names.
+  #
+  # Quoting follows PostgreSQL's own quote_ident(): an identifier that is a
+  # safe lowercase word and not a reserved keyword is emitted bare (so normal
+  # DDL stays readable), otherwise it is double-quoted with internal quotes
+  # doubled. The reserved set is the common subset most likely to appear as a
+  # column or table name; anything not lowercase-simple is always quoted, so
+  # the only risk from an incomplete set is an unnecessary quote, never a
+  # broken statement.
+  module Sql
+    SAFE_IDENT = /\A[a-z_][a-z0-9_$]*\z/
+
+    RESERVED = %w[
+      all analyse analyze and any array as asc asymmetric authorization
+      between binary both case cast check collate column constraint create
+      cross current_catalog current_date current_role current_time
+      current_timestamp current_user default deferrable desc distinct do else
+      end except false fetch for foreign from grant group having ilike in
+      initially inner intersect into is isnull join lateral leading left like
+      limit localtime localtimestamp natural not notnull null offset on only or
+      order outer overlaps placing primary references returning right select
+      session_user similar some symmetric table tablesample then to trailing
+      true union unique user using variadic verbose when where window with
+    ].to_set.freeze
+
+    module_function
+
+    # Quotes an identifier only when PostgreSQL would require it.
+    def quote_ident(name)
+      str = name.to_s
+      return str if str.match?(SAFE_IDENT) && !RESERVED.include?(str)
+
+      %("#{str.gsub('"', '""')}")
+    end
+
+    # Fully-qualified, quoted "schema.table".
+    def quote_table(name, schema: "public")
+      "#{quote_ident(schema)}.#{quote_ident(name)}"
+    end
+
+    # Comma-joined list of quoted column identifiers.
+    def quote_columns(names)
+      names.map { |n| quote_ident(n) }.join(", ")
+    end
+  end
+end

data/lib/pcrd/transform/row_transformer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Pcrd
+  module Transform
+    # Applies a Config::Table migration spec to a single row hash.
+    #
+    # Handles the structural changes: drops (exclude column), renames (change key),
+    # and pass-through for unchanged columns. Does NOT perform Ruby-level type
+    # conversion — PostgreSQL coerces values on INSERT/COPY, so string values from
+    # the source pass through as-is.
+    #
+    # Added columns (from add_columns) are NOT included in the transformer output.
+    # They are omitted from the INSERT column list so the target database applies
+    # their DEFAULT expressions directly.
+    #
+    # Usage:
+    #   transformer = RowTransformer.new(table_config, source_columns)
+    #   target_row  = transformer.transform(source_row_hash)
+    #   columns     = transformer.target_column_names
+    class RowTransformer
+      def initialize(table_config, source_columns)
+        @source_names = source_columns.map(&:name)
+        @drops        = build_drop_set(table_config)
+        @renames      = build_rename_map(table_config)
+        @target_names = build_target_names
+      end
+
+      # Returns a hash of {target_column_name => value} for all non-dropped columns.
+      # Values are whatever the pg gem returned (typically String or nil).
+      def transform(row_hash)
+        @target_names.each_with_object({}).with_index do |(tgt_name, result), i|
+          result[tgt_name] = row_hash[@source_names_kept[i]]
+        end
+      end
+
+      # Ordered list of target column names produced by #transform.
+      # Pass this to the backfill engine when constructing INSERT/COPY statements.
+      def target_column_names
+        @target_names
+      end
+
+      # Ordered list of source column names that survive (not dropped).
+      def source_column_names_kept
+        @source_names_kept
+      end
+
+      private
+
+      def build_drop_set(config)
+        (config.columns || {}).each_with_object(Set.new) do |(name, spec), set|
+          set << name.to_s if spec.drop
+        end
+      end
+
+      def build_rename_map(config)
+        (config.columns || {}).each_with_object({}) do |(name, spec), map|
+          map[name.to_s] = spec.rename if spec.rename
+        end
+      end
+
+      def build_target_names
+        @source_names_kept = @source_names.reject { |n| @drops.include?(n) }
+        @source_names_kept.map { |n| @renames[n] || n }
+      end
+    end
+  end
+end

data/lib/pcrd/transform/type_map.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Pcrd
+  module Transform
+    # Registry of known PostgreSQL type transitions and their safety classification.
+    #
+    # Works with pg's internal type_name values (int4, int8, bool, etc.) for the
+    # source side, and normalizes user-facing spec strings (bigint, timestamptz)
+    # to the same internal names for matching.
+    #
+    # Safety levels:
+    #   :no_op        — source and target are the same type; nothing to do
+    #   :always_safe  — widening cast; no possible data loss; no validation needed
+    #   :validated    — cast may lose data; Validator must run a pre-migration check
+    #   :unsupported  — pcrd cannot handle this cast; user must provide a custom transform
+    module TypeMap
+      # Maps user-facing type strings in migration specs to pg internal type names.
+      SPEC_TO_PG = {
+        "bigint"                       => "int8",
+        "int8"                         => "int8",
+        "integer"                      => "int4",
+        "int4"                         => "int4",
+        "int"                          => "int4",
+        "smallint"                     => "int2",
+        "int2"                         => "int2",
+        "real"                         => "float4",
+        "float4"                       => "float4",
+        "double precision"             => "float8",
+        "float8"                       => "float8",
+        "boolean"                      => "bool",
+        "bool"                         => "bool",
+        "text"                         => "text",
+        "date"                         => "date",
+        "timestamp"                    => "timestamp",
+        "timestamp without time zone"  => "timestamp",
+        "timestamptz"                  => "timestamptz",
+        "timestamp with time zone"     => "timestamptz",
+        "time"                         => "time",
+        "time without time zone"       => "time",
+        "timetz"                       => "timetz",
+        "time with time zone"          => "timetz",
+        "numeric"                      => "numeric",
+        "decimal"                      => "numeric",
+        "money"                        => "money",
+        "uuid"                         => "uuid",
+        "json"                         => "json",
+        "jsonb"                        => "jsonb",
+        "bytea"                        => "bytea",
+        "oid"                          => "oid",
+      }.freeze
+
+      # Always-safe casts: pure widening, no possible data loss.
+      # Keys are [pg_source_type, pg_target_type].
+      ALWAYS_SAFE_PAIRS = Set.new([
+        %w[int2 int4],
+        %w[int2 int8],
+        %w[int4 int8],
+        %w[int2 float4],
+        %w[int4 float4],
+        %w[int2 float8],
+        %w[int4 float8],
+        %w[int8 float8],
+        %w[float4 float8],
+        %w[int2 numeric],
+        %w[int4 numeric],
+        %w[int8 numeric],
+        %w[float4 numeric],
+        %w[float8 numeric],
+        %w[date timestamp],
+        %w[date timestamptz],
+        %w[timestamp timestamptz],
+        %w[bpchar text],    # char(n)    → text
+        %w[varchar text],   # varchar(n) → text
+        %w[bpchar varchar], # char(n)    → varchar(m) — validated below if m < n
+        %w[name text],
+        %w[json jsonb],
+      ]).freeze
+
+      # Validated casts: may lose data; Validator generates SQL to check.
+      # Values include: :description, :check_expr (a Proc → SQL fragment), :warn_only.
+      VALIDATED_RULES = [
+        {
+          from: "int8", to: "int4",
+          description: "values must fit in integer range [-2,147,483,648 … 2,147,483,647]",
+          check_expr: ->(col) { "#{col} NOT BETWEEN -2147483648 AND 2147483647" },
+          warn_only: false
+        },
+        {
+          from: "int8", to: "int2",
+          description: "values must fit in smallint range [-32,768 … 32,767]",
+          check_expr: ->(col) { "#{col} NOT BETWEEN -32768 AND 32767" },
+          warn_only: false
+        },
+        {
+          from: "int4", to: "int2",
+          description: "values must fit in smallint range [-32,768 … 32,767]",
+          check_expr: ->(col) { "#{col} NOT BETWEEN -32768 AND 32767" },
+          warn_only: false
+        },
+        {
+          from: "float8", to: "float4",
+          description: "precision will be reduced (double precision → real); some values may differ",
+          check_expr: nil,
+          warn_only: true
+        },
+        {
+          from: "timestamptz", to: "timestamp",
+          description: "timezone information will be discarded",
+          check_expr: nil,
+          warn_only: true
+        },
+        {
+          from: "numeric", to: "int8",
+          description: "fractional parts will be truncated; values must be whole numbers",
+          check_expr: ->(col) { "#{col} <> floor(#{col})" },
+          warn_only: false
+        },
+        {
+          from: "numeric", to: "int4",
+          description: "fractional parts truncated; values must fit in integer range",
+          check_expr: ->(col) { "floor(#{col}) NOT BETWEEN -2147483648 AND 2147483647 OR #{col} <> floor(#{col})" },
+          warn_only: false
+        },
+        # text/varchar → varchar(n): length check — handled separately via varchar_length_check
+        {
+          from: "text",    to: "varchar",  description: "all values must fit within target length", check_expr: :varchar_length_check, warn_only: false },
+        {
+          from: "varchar", to: "varchar",  description: "all values must fit within target length", check_expr: :varchar_length_check, warn_only: false },
+        {
+          from: "varchar", to: "bpchar",   description: "all values must fit within target length", check_expr: :varchar_length_check, warn_only: false },
+        {
+          from: "text",    to: "bpchar",   description: "all values must fit within target length", check_expr: :varchar_length_check, warn_only: false },
+      ].freeze
+
+      # Returns the safety classification for a source→target type transition.
+      #
+      # source_pg_type:    pg internal type name from Schema::Column#type_name
+      # target_type_str:   type string from the migration spec (e.g. "bigint", "varchar(255)")
+      def self.cast_safety(source_pg_type, target_type_str)
+        src = source_pg_type.to_s.strip
+        tgt_pg, tgt_base = normalize_target(target_type_str)
+
+        # Same base type: usually no-op, but with special cases for parameterized types.
+        if src == tgt_pg || (src == tgt_base && tgt_pg.nil?)
+          # varchar/char → varchar/char with a length constraint needs validation.
+          if %w[bpchar varchar].include?(src) && extract_length(target_type_str)
+            return :validated
+          end
+          # numeric → numeric with any parameterization is always safe (precision can
+          # only be widened without validation — pcrd doesn't restrict to widening only,
+          # but narrowing numeric is caught by the validated rule below).
+          return :no_op
+        end
+
+        return :always_safe if ALWAYS_SAFE_PAIRS.include?([src, tgt_base])
+
+        # varchar → varchar(m): validated (length comparison handled by Validator)
+        if %w[bpchar varchar].include?(src) && %w[varchar bpchar].include?(tgt_base)
+          tgt_len = extract_length(target_type_str)
+          return :always_safe if tgt_len.nil?   # → text (already covered above)
+          return :validated
+        end
+
+        validated = VALIDATED_RULES.find { |r| r[:from] == src && r[:to] == tgt_base }
+        return :validated if validated
+
+        :unsupported
+      end
+
+      # Returns the validated rule for a source→target pair, or nil.
+      def self.validated_rule(source_pg_type, target_type_str)
+        _, tgt_base = normalize_target(target_type_str)
+        VALIDATED_RULES.find { |r| r[:from] == source_pg_type && r[:to] == tgt_base }
+      end
+
+      # Returns true if a target type string refers to a known type.
+      def self.known_target?(type_str)
+        _, base = normalize_target(type_str)
+        SPEC_TO_PG.value?(base) || %w[varchar bpchar].include?(base)
+      end
+
+      # Extracts the length parameter from a varchar(N) / char(N) type string.
+      # Returns nil if not parameterized.
+      def self.extract_length(type_str)
+        return nil unless type_str
+        m = type_str.match(/\((\d+)/)
+        m ? m[1].to_i : nil
+      end
+
+      private_class_method def self.normalize_target(type_str) # rubocop:disable Metrics/MethodLength
+        s = type_str.to_s.strip.downcase
+        base = s.split("(").first.strip
+
+        # Parameterized varchar/char: keep base separate
+        if s.start_with?("character varying", "varchar")
+          return [nil, "varchar"]
+        end
+        if s.start_with?("character(", "char(", "bpchar")
+          return [nil, "bpchar"]
+        end
+
+        pg = SPEC_TO_PG[s] || SPEC_TO_PG[base]
+        [pg, pg || base]
+      end
+    end
+  end
+end