pcrd 0.1.0

data/lib/pcrd/output/preflight_printer.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "pastel"
+
+module Pcrd
+  module Output
+    class PreflightPrinter
+      PASTEL = Pastel.new
+
+      ICONS = {
+        pass: PASTEL.green("✓"),
+        fail: PASTEL.red("✗"),
+        warn: PASTEL.yellow("⚠"),
+        info: PASTEL.dim("·")
+      }.freeze
+
+      def initialize(output: $stdout)
+        @out = output
+      end
+
+      def print(result)
+        @out.puts
+        @out.puts PASTEL.bold("Preflight check")
+        @out.puts PASTEL.dim("─" * 70)
+        @out.puts
+
+        result.items.each { |item| print_item(item) }
+
+        @out.puts
+        print_ddl_section(result.ddl_map) if result.ddl_map.any?
+        print_estimate_section(result.row_counts, result) if result.row_counts.any?
+        print_summary(result)
+      end
+
+      private
+
+      def print_item(item)
+        icon  = ICONS[item.status]
+        label = case item.status
+                when :fail then PASTEL.red(item.label)
+                when :warn then PASTEL.yellow(item.label)
+                else item.label
+                end
+
+        if item.detail&.include?("\n")
+          @out.puts "  #{icon}  #{label}"
+          item.detail.each_line do |line|
+            @out.puts "     #{PASTEL.dim(line.chomp)}"
+          end
+        elsif item.detail
+          @out.puts "  #{icon}  #{label}  #{PASTEL.dim(item.detail)}"
+        else
+          @out.puts "  #{icon}  #{label}"
+        end
+      end
+
+      def print_ddl_section(ddl_map)
+        @out.puts PASTEL.dim("─" * 70)
+        @out.puts
+        @out.puts PASTEL.bold("  Target DDL:")
+        @out.puts
+        ddl_map.each do |_table, ddl|
+          ddl.each_line { @out.puts "    #{_1.chomp}" }
+          @out.puts "    ;"
+          @out.puts
+        end
+      end
+
+      def print_estimate_section(row_counts, result)
+        return unless result.respond_to?(:passed)
+
+        batch_size = 10_000  # default; real config batch size used by migrate
+
+        @out.puts PASTEL.dim("─" * 70)
+        @out.puts
+        @out.puts PASTEL.bold("  Estimated backfill:")
+        @out.puts
+
+        row_counts.each do |table, count|
+          next if count.zero?
+
+          batches   = (count.to_f / batch_size).ceil
+          est_mins  = (batches / 100.0).round(1)
+          est_label = est_mins >= 60 ? "~#{(est_mins / 60).round(1)}h" : "~#{est_mins}m"
+
+          @out.puts "    #{table}:  #{format_count(count)} rows / " \
+                    "#{format_count(batch_size)} per batch = " \
+                    "#{format_count(batches)} batches  (#{est_label} at 100 batches/min)"
+        end
+        @out.puts
+      end
+
+      def print_summary(result)
+        @out.puts PASTEL.dim("─" * 70)
+        @out.puts
+
+        fail_count = result.items.count { |i| i.status == :fail }
+        warn_count = result.items.count { |i| i.status == :warn }
+
+        if result.passed
+          if warn_count > 0
+            @out.puts "  #{PASTEL.green("✓")}  #{PASTEL.bold("All checks passed")}  " \
+                      "(#{PASTEL.yellow("#{warn_count} warning(s)")} — review before proceeding)"
+          else
+            @out.puts "  #{PASTEL.green("✓")}  #{PASTEL.bold("All checks passed.")}"
+          end
+        else
+          @out.puts "  #{PASTEL.red("✗")}  #{PASTEL.bold(PASTEL.red("#{fail_count} check(s) failed."))}  " \
+                    "Fix the issue(s) above before running migrate."
+        end
+        @out.puts
+      end
+
+      def format_count(n)
+        n.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+      end
+    end
+  end
+end

data/lib/pcrd/output/readiness_printer.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "pastel"
+
+module Pcrd
+  module Output
+    # Renders a Readiness::Manifest::Result: a per-table checklist of secondary
+    # objects, followed by a single block of DDL to run on the target before
+    # cutover.
+    class ReadinessPrinter
+      PASTEL = Pastel.new
+
+      ICONS = {
+        present:      PASTEL.green("✓"),
+        missing:      PASTEL.yellow("+"),
+        needs_review: PASTEL.red("!"),
+        info:         PASTEL.dim("·")
+      }.freeze
+
+      def initialize(output: $stdout)
+        @out = output
+      end
+
+      def print(result)
+        @out.puts
+        @out.puts PASTEL.bold("Target readiness")
+        @out.puts PASTEL.dim("─" * 70)
+
+        result.tables.each { |table| print_table(table) }
+
+        print_ddl_section(result)
+        print_legend
+      end
+
+      private
+
+      def print_table(table)
+        @out.puts
+        @out.puts PASTEL.bold("  #{table.table_name}")
+        if table.entries.empty?
+          @out.puts "    #{PASTEL.dim('no secondary objects on source')}"
+          return
+        end
+
+        table.entries.each do |e|
+          @out.puts "    #{ICONS[e.status]}  #{e.category.ljust(10)} " \
+                    "#{e.name.ljust(28)} #{PASTEL.dim(e.detail)}"
+        end
+      end
+
+      def print_ddl_section(result)
+        ddl = result.tables.flat_map { |t| t.entries }.filter_map(&:ddl)
+        return if ddl.empty?
+
+        @out.puts
+        @out.puts PASTEL.dim("─" * 70)
+        @out.puts
+        @out.puts PASTEL.bold("  DDL to run on the target before cutover:")
+        @out.puts
+        ddl.each { |stmt| @out.puts "    #{stmt}" }
+        @out.puts
+      end
+
+      def print_legend
+        @out.puts PASTEL.dim("─" * 70)
+        @out.puts "  #{ICONS[:present]} present   #{ICONS[:missing]} will create   " \
+                  "#{ICONS[:needs_review]} needs review   #{ICONS[:info]} handled at cutover"
+        @out.puts
+      end
+    end
+  end
+end

data/lib/pcrd/preflight.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+module Pcrd
+  # Runs all pre-migration safety checks and generates the target DDL.
+  #
+  # Checks are grouped and run top-to-bottom. Connection failures are hard
+  # stops (subsequent checks that need a connection are skipped). All table
+  # checks run even when earlier tables fail, so the operator sees all
+  # problems at once.
+  #
+  # Returns a Result that includes all check items and a DDL map for display.
+  class Preflight
+    # Individual check result.
+    Item = Data.define(:status, :label, :detail)
+    # status: :pass | :fail | :warn | :info
+
+    # Overall preflight result.
+    Result = Data.define(:passed, :items, :ddl_map, :row_counts)
+    # ddl_map:    Hash<table_name, String>  — generated CREATE TABLE SQL per table
+    # row_counts: Hash<table_name, Integer> — estimated row counts
+
+    HARD_FAIL = :fail  # any :fail in items means Result#passed = false
+
+    def initialize(config, options = {})
+      @config  = config
+      @options = Options.normalize(options)
+      @items   = []
+      @ddl_map = {}
+      @row_counts = {}
+    end
+
+    def run
+      @source_pool = open_pool(@config.source)
+      @target_pool = @config.target ? open_pool(@config.target) : nil
+
+      check_source_connection
+      check_target_connection
+      check_wal_level
+      check_replication_slots
+      check_replication_objects
+
+      (@config.migrate&.tables || []).each { |t| check_table(t) }
+
+      Result.new(
+        passed:     @items.none? { |i| i.status == :fail },
+        items:      @items,
+        ddl_map:    @ddl_map,
+        row_counts: @row_counts
+      )
+    ensure
+      @source_pool&.close
+      @target_pool&.close
+    end
+
+    private
+
+    # ── connection & server checks ──────────────────────────────────────────
+
+    def check_source_connection
+      @source_pool.exec("SELECT 1")
+      @source_ok = true
+      pass("source connection",
+           "#{@config.source.host}:#{@config.source.port}/#{@config.source.database}")
+    rescue Connection::Error => e
+      @source_ok = false
+      fail!("source connection", e.message)
+    end
+
+    def check_target_connection
+      return info("target connection", "not configured — skipping") unless @target_pool
+
+      @target_pool.exec("SELECT 1")
+      @target_ok = true
+      pass("target connection",
+           "#{@config.target.host}:#{@config.target.port}/#{@config.target.database}")
+    rescue Connection::Error => e
+      @target_ok = false
+      fail!("target connection", e.message)
+    end
+
+    def check_wal_level
+      return skip("wal_level", "source not reachable") unless @source_ok
+
+      result = @source_pool.exec("SELECT setting FROM pg_settings WHERE name = 'wal_level'")
+      level  = result[0]["setting"]
+
+      if level == "logical"
+        pass("wal_level", "logical")
+      else
+        fail!("wal_level",
+              "#{level.inspect} — must be 'logical'; " \
+              "set wal_level = logical in postgresql.conf and restart PostgreSQL")
+      end
+    end
+
+    def check_replication_slots
+      return skip("replication slots", "source not reachable") unless @source_ok
+
+      max_row   = @source_pool.exec("SELECT setting::int FROM pg_settings WHERE name = 'max_replication_slots'")
+      used_row  = @source_pool.exec("SELECT count(*)::int FROM pg_replication_slots")
+      max_slots = max_row[0]["setting"].to_i
+      used      = used_row[0]["count"].to_i
+      free      = max_slots - used
+      # pcrd creates one logical slot per migration covering all tables (via a
+      # single publication), not one slot per table.
+      needed    = 1
+
+      if free >= needed
+        pass("replication slots", "#{used} used / #{max_slots} max  (#{free} free, #{needed} needed)")
+      else
+        fail!("replication slots",
+              "#{used} used / #{max_slots} max — need #{needed} free; " \
+              "increase max_replication_slots in postgresql.conf")
+      end
+    end
+
+    # Checks whether the slot/publication already exist, interpreted against
+    # --resume: a fresh run must not collide with leftovers, and a resume must
+    # have something to resume. This catches the conflict before any work.
+    def check_replication_objects
+      return unless @source_ok
+      return unless @config.migrate
+
+      slot   = @config.migrate.replication_slot
+      resume = @options[:resume]
+      present = @source_pool.exec(
+        "SELECT 1 FROM pg_replication_slots WHERE slot_name = $1", [slot]
+      ).ntuples.positive?
+
+      if resume && !present
+        fail!("replication slot state",
+              "--resume given but slot '#{slot}' does not exist; " \
+              "run a fresh migration without --resume")
+      elsif resume
+        pass("replication slot state", "slot '#{slot}' present — will resume")
+      elsif present
+        fail!("replication slot state",
+              "slot '#{slot}' already exists from a previous run; resume it with --resume, " \
+              "or remove it with `pcrd cleanup` to start over")
+      else
+        pass("replication slot state", "no existing slot — will be created")
+      end
+    end
+
+    # ── per-table checks ────────────────────────────────────────────────────
+
+    def check_table(table_config)
+      return unless @source_ok
+
+      name   = table_config.name
+      reader = Schema::Reader.new(@source_pool)
+
+      # 1. Source table exists
+      unless reader.table_exists?(name)
+        fail!("#{name}: source table", "table '#{name}' not found on source")
+        return
+      end
+
+      source_cols = reader.read(name)
+      row_count   = reader.estimated_row_count(name)
+      pk_cols     = reader.primary_key_columns(name)
+      @row_counts[name] = row_count
+
+      pass("#{name}: source table", "#{format_count(row_count)} rows")
+
+      # 2. Primary key required
+      if pk_cols.empty?
+        fail!("#{name}: primary key",
+              "no primary key found — pcrd requires a primary key for upsert " \
+              "semantics during the backfill/streaming overlap window")
+      else
+        pass("#{name}: primary key", pk_cols.join(", "))
+        check_pk_not_dropped(name, table_config, pk_cols)
+        check_replica_identity(name)
+      end
+
+      # 3. Target table must not exist (unless --force-overwrite)
+      check_target_table(name, table_config)
+
+      # 4. All spec columns exist on source
+      check_spec_columns_exist(name, table_config, source_cols)
+
+      # 5. All type casts are known + run data validation
+      check_type_casts(name, table_config, source_cols)
+
+      # 6. Generate DDL for display
+      @ddl_map[name] = Schema::DDL.generate(
+        source_columns:      source_cols,
+        table_config:        table_config,
+        primary_key_columns: pk_cols,
+        schema_name:         "public"
+      )
+    rescue Connection::Error => e
+      fail!("#{name}", "database error: #{e.message}")
+    end
+
+    # A primary-key column cannot be dropped: the apply engine matches replayed
+    # UPDATE/DELETE events by primary key, so dropping one breaks streaming.
+    def check_pk_not_dropped(name, table_config, pk_cols)
+      dropped = pk_cols.select do |col|
+        spec = table_config.columns&.[](col) || table_config.columns&.[](col.to_sym)
+        spec&.drop
+      end
+      return if dropped.empty?
+
+      fail!("#{name}: primary key",
+            "primary key column(s) cannot be dropped: #{dropped.join(', ')} — " \
+            "they are required to match replicated updates and deletes")
+    end
+
+    # The source table's replica identity must carry key columns on UPDATE/DELETE
+    # or the apply engine cannot locate the target row to update/delete.
+    def check_replica_identity(name)
+      ident = Schema::Reader.new(@source_pool).replica_identity(name)
+
+      case ident
+      when "d" then pass("#{name}: replica identity", "default (primary key)")
+      when "f" then pass("#{name}: replica identity", "full")
+      when "i" then pass("#{name}: replica identity", "index")
+      when "n"
+        fail!("#{name}: replica identity",
+              "REPLICA IDENTITY NOTHING — UPDATE/DELETE WAL records carry no key " \
+              "columns, so replicated updates and deletes cannot be applied. " \
+              "Run: ALTER TABLE #{Sql.quote_table(name)} REPLICA IDENTITY DEFAULT (or FULL).")
+      else
+        warn("#{name}: replica identity", "unrecognized setting #{ident.inspect}")
+      end
+    end
+
+    def check_target_table(name, _table_config)
+      return unless @target_ok
+
+      reader = Schema::Reader.new(@target_pool)
+      if reader.table_exists?(name)
+        if @options[:"force-overwrite"]
+          warn("#{name}: target table", "already exists — will be dropped and recreated (--force-overwrite)")
+        else
+          fail!("#{name}: target table",
+                "table '#{name}' already exists on target; " \
+                "pass --force-overwrite to drop and recreate it")
+        end
+      else
+        pass("#{name}: target table", "does not exist — will be created")
+      end
+    end
+
+    def check_spec_columns_exist(name, table_config, source_cols)
+      source_names = source_cols.map(&:name)
+      missing = (table_config.columns || {}).keys.map(&:to_s) - source_names
+      if missing.any?
+        fail!("#{name}: column spec",
+              "column(s) in spec not found on source: #{missing.join(', ')}")
+      else
+        pass("#{name}: column spec", "all spec columns found on source")
+      end
+    end
+
+    def check_type_casts(name, table_config, source_cols)
+      col_index = source_cols.each_with_object({}) { |c, h| h[c.name] = c }
+      unknown   = []
+      safe_changes = []
+      validator = Transform::Validator.new(@source_pool)
+      failures  = validator.validate(table_config, source_cols)
+
+      (table_config.columns || {}).each do |src_name, col_spec|
+        next if col_spec.drop || col_spec.type.nil?
+
+        src_col = col_index[src_name.to_s]
+        next unless src_col
+
+        safety = Transform::TypeMap.cast_safety(src_col.type_name, col_spec.type)
+
+        if safety == :unsupported
+          unknown << "#{src_name}: #{src_col.display_type} → #{col_spec.type}"
+        else
+          label = [col_spec.rename ? "rename" : nil,
+                   col_spec.type  ? "#{src_col.display_type} → #{col_spec.type}" : nil,
+                   "(#{safety.to_s.tr('_', ' ')})"].compact.join("  ")
+          safe_changes << "#{src_name}: #{label}"
+        end
+      end
+
+      if unknown.any?
+        fail!("#{name}: type casts",
+              "unsupported type transition(s):\n" +
+              unknown.map { "      #{_1}" }.join("\n"))
+        return
+      end
+
+      if safe_changes.any?
+        pass("#{name}: type casts", safe_changes.join("\n" + " " * 6))
+      end
+
+      hard_fails = failures.reject(&:warn_only)
+      warnings   = failures.select(&:warn_only)
+
+      if hard_fails.any?
+        msgs = hard_fails.map do |f|
+          "#{f.column_name} (#{f.source_type} → #{f.target_type}): " \
+          "#{f.failing_count} row(s) would fail — #{f.description}"
+        end
+        fail!("#{name}: data validation",
+              "#{hard_fails.length} cast(s) failed validation:\n" +
+              msgs.map { "      #{_1}" }.join("\n"))
+      else
+        pass("#{name}: data validation", "all casts validated")
+      end
+
+      warnings.each do |w|
+        warn("#{name}: #{w.column_name}",
+             "#{w.source_type} → #{w.target_type}: #{w.description}")
+      end
+    end
+
+    # ── helpers ─────────────────────────────────────────────────────────────
+
+    def open_pool(conn_config)
+      Connection::Client.new(conn_config)
+    end
+
+    def pass(label, detail = nil)  @items << Item.new(status: :pass, label: label, detail: detail) end
+    def fail!(label, detail)       @items << Item.new(status: :fail, label: label, detail: detail) end
+    def warn(label, detail)        @items << Item.new(status: :warn, label: label, detail: detail) end
+    def info(label, detail = nil)  @items << Item.new(status: :info, label: label, detail: detail) end
+    def skip(label, reason)        @items << Item.new(status: :info, label: label, detail: "skipped — #{reason}") end
+
+    def format_count(n)
+      n.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+    end
+  end
+end