pcrd 0.1.0

data/lib/pcrd/migration/orchestrator.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+module Pcrd
+  module Migration
+    # Drives the full migrate flow: setup, concurrent backfill + WAL apply, and
+    # the streaming monitor, with cleanup guaranteed. Extracted from the CLI so
+    # the orchestration is testable on its own and free of Thor.
+    #
+    # The CLI stays a thin adapter: it runs preflight, confirms with the
+    # operator, installs signal traps that call #request_stop, and renders the
+    # result. All progress output goes through an injected Reporter.
+    #
+    # #run assumes preflight has passed and the operator has confirmed; it
+    # returns an outcome symbol (:completed | :interrupted | :backfill_only) and
+    # raises Pcrd::Error subclasses (Replication::Error, Connection::Error, ...)
+    # for the CLI to translate.
+    class Orchestrator
+      LAG_CHECK_INTERVAL = 2 # seconds between lag readings in streaming mode
+
+      def initialize(config:, options: {}, reporter: Reporter::Console.new)
+        @config   = config
+        @options  = Options.normalize(options)
+        @reporter = reporter
+        @mutex    = Mutex.new
+        @stop     = false
+      end
+
+      # Safe to call from a signal handler / another thread.
+      def request_stop
+        @mutex.synchronize { @stop = true }
+        @backfill_engine&.stop!
+        @reporter.info("\nStopping...")
+      end
+
+      def run
+        @source_pool = Connection::Client.new(@config.source)
+        @target_pool = Connection::Client.new(@config.target)
+        @checkpoint  = Checkpoint::Store.new(@config.migrate.checkpoint_db)
+        setup        = Schema::Setup.new(source_pool: @source_pool, target_pool: @target_pool, config: @config)
+
+        report_session_settings
+        acquire_lock!
+
+        start_lsn = prepare_replication(setup)
+        start_streaming(start_lsn) unless backfill_only?
+
+        return :interrupted if run_backfill == :interrupted
+
+        if backfill_only?
+          @reporter.info("Run `pcrd verify` to check row counts, then `pcrd cutover` when ready.")
+          return :backfill_only
+        end
+
+        stream_until_stopped
+      ensure
+        cleanup
+      end
+
+      private
+
+      def stopped?
+        @mutex.synchronize { @stop }
+      end
+
+      def backfill_only?
+        @options[:"backfill-only"]
+      end
+
+      def report_session_settings
+        s = @source_pool.session_settings
+        @reporter.info(
+          "Session: application_name=#{s['application_name']}, lock_timeout=#{s['lock_timeout']}, " \
+          "idle_in_transaction=#{s['idle_in_transaction_session_timeout']}, " \
+          "statement_timeout=#{s['statement_timeout']}"
+        )
+      end
+
+      def acquire_lock!
+        @migration_lock = AdvisoryLock.new(pool: @source_pool, name: @config.migrate.replication_slot)
+        return if @migration_lock.try_acquire
+
+        raise Pcrd::Error,
+              "Another pcrd migration is already running against slot " \
+              "'#{@config.migrate.replication_slot}'. Wait for it to finish, or stop it before retrying."
+      end
+
+      # Ensures (or, on resume, validates) the slot/publication and target
+      # tables, returning the LSN streaming should start from.
+      def prepare_replication(setup)
+        if @options[:resume]
+          unless backfill_only?
+            setup.validate_resumable!(
+              pub_name: @config.migrate.publication, slot_name: @config.migrate.replication_slot
+            )
+          end
+          start_lsn = @checkpoint.backfill_start_lsn || "0/0"
+          @reporter.info("\nResuming migration from LSN #{start_lsn}...")
+          return start_lsn
+        end
+
+        start_lsn = "0/0"
+        unless backfill_only?
+          @reporter.info("\nCreating publication and replication slot...")
+          start_lsn = setup.create_publication_and_slot(
+            pub_name: @config.migrate.publication, slot_name: @config.migrate.replication_slot
+          )
+          @checkpoint.set_backfill_start_lsn(start_lsn)
+          @checkpoint.set_publication(@config.migrate.publication)
+          @checkpoint.set_replication_slot(@config.migrate.replication_slot)
+          @reporter.success("  Slot created at LSN #{start_lsn}.")
+        end
+
+        @reporter.info("\nCreating target tables...")
+        setup.create_target_tables(force_overwrite: @options[:"force-overwrite"])
+        @reporter.success("  Target tables created.")
+        start_lsn
+      end
+
+      # Starts the WAL consumer and the apply worker on its own target
+      # connection (Connection::Client is single-connection and unsafe to share
+      # with backfill's writes).
+      def start_streaming(start_lsn)
+        repl_conn = Connection::Replication.new(@config.source)
+        @parser   = Replication::Pgoutput::Parser.new
+        @consumer = Replication::Consumer.new(
+          repl_conn: repl_conn, parser: @parser,
+          slot_name: @config.migrate.replication_slot,
+          pub_name:  @config.migrate.publication, start_lsn: start_lsn
+        )
+        @reporter.info("\nStarting WAL consumer...")
+        @consumer.start
+        @reporter.success("  Streaming from #{start_lsn}.")
+
+        @apply_pool  = Connection::Client.new(@config.target)
+        apply_engine = Apply::Engine.new(
+          target_pool: @apply_pool, config: @config, parser: @parser,
+          source_schema: read_source_schema
+        )
+        @apply_worker = Apply::Worker.new(
+          engine: apply_engine, queue: @consumer.queue,
+          # Acknowledge to the source only after the txn is durably applied and
+          # checkpointed, so WAL is not released prematurely.
+          on_committed: lambda { |lsn|
+            @checkpoint.set_lsn(lsn)
+            @consumer.advance_lsn(lsn)
+          }
+        )
+        @apply_worker.start
+        @reporter.success("  Applying WAL concurrently with backfill.")
+      end
+
+      # Runs backfill concurrently with the apply worker. Returns :interrupted
+      # if it stopped early, otherwise nil.
+      def run_backfill
+        @backfill_engine = Backfill::Engine.new(
+          source_pool: @source_pool, target_pool: @target_pool,
+          config: @config, checkpoint: @checkpoint
+        )
+
+        if (rps = @config.migrate.max_rows_per_second)
+          @reporter.info("\nStarting backfill (throttled to #{format_count(rps)} rows/s)...")
+        else
+          @reporter.info("\nStarting backfill...")
+        end
+
+        results = @backfill_engine.run(on_batch: method(:report_batch))
+        @reporter.info("")
+
+        results.each do |r|
+          status = r.stopped_early ? " (interrupted)" : ""
+          @reporter.success("  #{r.table_name}: #{format_count(r.rows_copied)} rows " \
+                            "in #{r.batch_count} batches#{status}")
+        end
+
+        raise_if_streaming_failed
+
+        if results.any?(&:stopped_early) || stopped?
+          @reporter.warn("\nInterrupted. Resume with --resume.")
+          return :interrupted
+        end
+
+        @reporter.success("\nBackfill complete.")
+        nil
+      end
+
+      # Surfaces a dead apply worker or WAL consumer as a Replication::Error so
+      # a failure during backfill (e.g. a TRUNCATE or a dropped connection)
+      # aborts promptly instead of being noticed only once streaming begins.
+      def raise_if_streaming_failed
+        if @apply_worker&.failed?
+          raise Replication::Error, "Apply worker stopped: #{@apply_worker.error.message}"
+        end
+        return unless @consumer&.failed?
+
+        raise Replication::Error, "WAL consumer stopped: #{@consumer.last_error.message}"
+      end
+
+      def stream_until_stopped
+        @reporter.info("Entering streaming mode. Press Ctrl-C to stop.\n")
+        lag_monitor    = Monitor::Lag.new(source_pool: @source_pool, slot_name: @config.migrate.replication_slot)
+        last_lag_check = 0.0
+
+        loop do
+          break if stopped?
+
+          if @apply_worker.failed?
+            raise Replication::Error, "Apply worker stopped: #{@apply_worker.error.message}"
+          end
+          if @consumer.failed? && @consumer.queue.empty?
+            raise Replication::Error, "WAL consumer stopped: #{@consumer.last_error.message}"
+          end
+
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if now - last_lag_check >= LAG_CHECK_INTERVAL
+            render_lag(lag_monitor)
+            last_lag_check = now
+          end
+          sleep 0.1
+        end
+
+        @reporter.info("")
+        if stopped?
+          @reporter.warn("Migration interrupted. Resume with:")
+          @reporter.warn("  pcrd migrate --config #{@options[:config] || Config::DEFAULT_CONFIG_FILE} --resume")
+        end
+        :completed
+      end
+
+      def render_lag(lag_monitor)
+        lag       = lag_monitor.lag_bytes
+        threshold = @config.migrate.lag_threshold_bytes
+        metrics   = "queue: #{@consumer.queue_depth}  applied: #{@apply_worker.last_applied_lsn || '—'}"
+        ready     = lag && lag <= threshold ? "  #{@reporter.green('✓ Ready for cutover')}" : ""
+        @reporter.status("  Lag: #{lag_monitor.summary}  |  #{metrics}#{ready}   ")
+      end
+
+      def read_source_schema
+        reader = Schema::Reader.new(@source_pool)
+        (@config.migrate&.tables || []).each_with_object({}) do |table, h|
+          h[table.name] = {
+            columns:    reader.read(table.name),
+            pk_columns: reader.primary_key_columns(table.name)
+          }
+        end
+      end
+
+      def report_batch(stats)
+        rps = stats[:duration_ms] > 0 ? (stats[:row_count] * 1000.0 / stats[:duration_ms]).round : 0
+        @reporter.status(
+          "  #{stats[:table]}  batch #{stats[:batch_num]}  " \
+          "#{format_count(stats[:rows_so_far])} rows  #{format_count(rps)} rows/s    "
+        )
+      end
+
+      # Stop the producer first so the queue is finite, then let the worker
+      # drain what's left before closing its connection.
+      def cleanup
+        @consumer&.stop rescue nil
+        @apply_worker&.stop rescue nil
+        @apply_pool&.close rescue nil
+        @checkpoint&.close rescue nil
+        @migration_lock&.release rescue nil
+        @source_pool&.close rescue nil
+        @target_pool&.close rescue nil
+      end
+
+      def format_count(n)
+        n.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+      end
+    end
+  end
+end

data/lib/pcrd/monitor/lag.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Pcrd
+  module Monitor
+    # Queries the source database for replication lag on a named slot.
+    #
+    # Lag is reported in bytes (WAL bytes the slot has not yet confirmed).
+    # A rolling window of recent readings is maintained so callers can
+    # compute rate-of-change and estimated time to zero.
+    class Lag
+      WINDOW_SIZE = 10  # readings to keep for trend analysis
+
+      Reading = Data.define(:bytes, :taken_at)
+
+      def initialize(source_pool:, slot_name:)
+        @pool      = source_pool
+        @slot_name = slot_name
+        @history   = []
+      end
+
+      # Queries the current lag in bytes. Returns nil if the slot is not found.
+      def lag_bytes
+        result = @pool.exec(<<~SQL, [@slot_name])
+          SELECT pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn)::bigint AS lag
+          FROM   pg_replication_slots
+          WHERE  slot_name = $1
+        SQL
+
+        return nil if result.ntuples.zero?
+
+        bytes = result[0]["lag"].to_i
+        record(bytes)
+        bytes
+      rescue Connection::Error
+        nil
+      end
+
+      # Returns the confirmed_flush_lsn for the slot as a "X/Y" string.
+      def confirmed_lsn
+        result = @pool.exec(<<~SQL, [@slot_name])
+          SELECT confirmed_flush_lsn FROM pg_replication_slots WHERE slot_name = $1
+        SQL
+        result.ntuples > 0 ? result[0]["confirmed_flush_lsn"] : nil
+      rescue Connection::Error
+        nil
+      end
+
+      # Returns bytes/second rate of lag change (negative = lag is shrinking).
+      # Returns nil if fewer than 2 readings available.
+      def trend_bytes_per_sec
+        return nil if @history.size < 2
+
+        oldest = @history.first
+        newest = @history.last
+        elapsed = newest.taken_at - oldest.taken_at
+        return nil if elapsed <= 0
+
+        (newest.bytes - oldest.bytes) / elapsed
+      end
+
+      # Estimated seconds until lag reaches zero at current trend.
+      # Returns nil if trend is not converging (positive or unknown).
+      def eta_seconds
+        trend = trend_bytes_per_sec
+        return nil unless trend&.negative?
+
+        current = @history.last&.bytes
+        return nil unless current
+
+        -(current / trend).ceil
+      end
+
+      # Human-readable lag summary string.
+      def summary
+        bytes = lag_bytes
+        return "unknown (slot not found)" if bytes.nil?
+
+        parts = ["#{format_bytes(bytes)} behind"]
+        eta   = eta_seconds
+        parts << "ETA ~#{format_duration(eta)}" if eta
+        parts.join("  ")
+      end
+
+      private
+
+      def record(bytes)
+        @history << Reading.new(bytes: bytes, taken_at: Time.now.to_f)
+        @history = @history.last(WINDOW_SIZE)
+      end
+
+      def format_bytes(n)
+        return "#{n} B" if n < 1024
+        return "#{(n / 1024.0).round(1)} KB" if n < 1_048_576
+        return "#{(n / 1_048_576.0).round(1)} MB" if n < 1_073_741_824
+
+        "#{(n / 1_073_741_824.0).round(2)} GB"
+      end
+
+      def format_duration(secs)
+        return "#{secs}s" if secs < 60
+        return "#{(secs / 60.0).ceil}m" if secs < 3600
+
+        "#{(secs / 3600.0).ceil}h"
+      end
+    end
+  end
+end

data/lib/pcrd/options.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pcrd
+  # Normalizes the options hash once at the boundary so commands can use symbol
+  # keys consistently, instead of guarding every read with
+  # `options["x"] || options[:"x"]`. Accepts Thor's string-keyed options, a
+  # plain symbol hash, or nil.
+  module Options
+    module_function
+
+    def normalize(opts)
+      (opts || {}).to_h.transform_keys(&:to_sym)
+    end
+  end
+end

data/lib/pcrd/output/analyze_printer.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "tty-table"
+require "tty-screen"
+require "pastel"
+
+module Pcrd
+  module Output
+    class AnalyzePrinter
+      PASTEL = Pastel.new
+
+      STATUS_COLORS = {
+        unchanged:        ->(s) { s },
+        type_changed:     ->(s) { PASTEL.yellow(s) },
+        renamed:          ->(s) { PASTEL.cyan(s) },
+        type_and_renamed: ->(s) { PASTEL.yellow(s) },
+        dropped:          ->(s) { PASTEL.red(s) },
+        added:            ->(s) { PASTEL.green(s) }
+      }.freeze
+
+      def initialize(output: $stdout)
+        @out = output
+      end
+
+      # Single-cluster padding analysis: current layout vs. optimal reordering.
+      def print_table_report(table_name:, schema_name: "public", row_count:, report:)
+        heading = "Table: #{schema_name}.#{table_name}"
+        heading += "  (#{format_count(row_count)} rows)" if row_count > 0
+        @out.puts
+        @out.puts PASTEL.bold(heading)
+        @out.puts
+
+        if report[:already_optimal]
+          @out.puts PASTEL.green("  ✓ Column order is already optimal. No padding waste detected.")
+          @out.puts
+          print_layout_table(report[:current_layout], title: "Current layout")
+          return
+        end
+
+        print_layout_table(report[:current_layout], title: "Current layout",
+                           highlight_padding: true)
+        @out.puts
+        print_savings_summary(report, row_count)
+        @out.puts
+        print_layout_table(report[:optimal_layout], title: "Suggested layout (optimal packing)")
+      end
+
+      # Cross-cluster diff: source schema vs. target (live or synthesized from spec).
+      def print_diff_report(table_name:, schema_name: "public", row_count:,
+                            diff_entries:, packer:, target_is_live: false)
+        heading = "Table: #{schema_name}.#{table_name}"
+        heading += "  (#{format_count(row_count)} rows)" if row_count > 0
+        heading += target_is_live ? "  — live source vs. live target" \
+                                  : "  — source vs. proposed target (synthesized from spec)"
+        @out.puts
+        @out.puts PASTEL.bold(heading)
+        @out.puts
+
+        print_diff_table(diff_entries)
+        @out.puts
+        print_diff_padding_summary(diff_entries, packer, row_count)
+      end
+
+      private
+
+      def print_layout_table(layout_entries, title:, highlight_padding: false)
+        @out.puts "  #{PASTEL.bold(title)}:"
+        @out.puts
+
+        rows = layout_entries.map do |entry|
+          col     = entry.column
+          padding = entry.padding_before
+
+          padding_cell = if padding > 0 && highlight_padding
+                          PASTEL.yellow("← #{padding} wasted")
+                        elsif padding > 0
+                          "#{padding} bytes"
+                        else
+                          "—"
+                        end
+
+          [col.name, col.display_type, col.display_alignment, col.display_size, padding_cell]
+        end
+
+        render_table(["Column", "Type", "Align", "Size", "Padding before"], rows)
+      end
+
+      def print_savings_summary(report, row_count)
+        saved = report[:saved_bytes]
+        pct   = report[:savings_pct]
+        curr  = report[:current_size]
+        opt   = report[:optimal_size]
+
+        @out.puts "  #{PASTEL.bold("Padding analysis:")}"
+        @out.puts "    Current row overhead (fixed cols + padding):  #{curr} bytes"
+        @out.puts "    Optimal row overhead (fixed cols only):        #{opt} bytes"
+        @out.puts "    #{PASTEL.yellow("Wasted padding:")}  #{PASTEL.bold("#{saved} bytes/row")}  (#{pct}%)"
+
+        return unless row_count > 0
+
+        total_mb = (saved * row_count) / (1024.0 * 1024.0)
+        scale    = scale_label(total_mb)
+        @out.puts "    At #{format_count(row_count)} rows:  #{PASTEL.bold("~#{scale} reclaimed")} by reordering columns"
+      end
+
+      def print_diff_table(diff_entries)
+        @out.puts "  #{PASTEL.bold("Schema diff")}  " \
+                  "(#{PASTEL.yellow("■")} type changed  " \
+                  "#{PASTEL.cyan("■")} renamed  " \
+                  "#{PASTEL.red("■")} dropped  " \
+                  "#{PASTEL.green("■")} added)"
+        @out.puts
+
+        rows = diff_entries.map do |entry|
+          colorize = STATUS_COLORS[entry.status]
+          src_name = entry.source_column ? colorize.call(entry.source_column.name)         : PASTEL.dim("—")
+          src_type = entry.source_column ? colorize.call(entry.source_column.display_type) : PASTEL.dim("—")
+          tgt_name = entry.target_column ? colorize.call(entry.target_column.name)         : PASTEL.dim("—")
+          tgt_type = entry.target_column ? colorize.call(entry.target_column.display_type) : PASTEL.dim("—")
+          [src_name, src_type, tgt_name, tgt_type, colorize.call(entry.status_label)]
+        end
+
+        render_table(["Source column", "Source type", "Target column", "Target type", "Change"], rows)
+      end
+
+      def print_diff_padding_summary(diff_entries, packer, row_count)
+        source_cols = diff_entries.reject(&:added?).map(&:source_column).compact
+        target_cols = diff_entries.reject(&:dropped?).map(&:target_column).compact
+
+        src_size    = packer.estimated_row_size(source_cols)
+        tgt_size    = packer.estimated_row_size(target_cols)
+        src_padding = packer.total_padding(source_cols)
+        tgt_padding = packer.total_padding(target_cols)
+        delta       = src_size - tgt_size
+        delta_pct   = src_size > 0 ? (delta.to_f / src_size * 100).abs.round(1) : 0.0
+
+        @out.puts "  #{PASTEL.bold("Row size comparison (fixed columns + padding):")}"
+        @out.puts "    Source: #{src_size} bytes  (#{src_padding} bytes padding)"
+
+        size_line = "    Target: #{tgt_size} bytes  (#{tgt_padding} bytes padding)"
+        if delta > 0
+          @out.puts size_line + "  #{PASTEL.green("▼ #{delta} bytes smaller  (#{delta_pct}%)")}"
+        elsif delta < 0
+          @out.puts size_line + "  #{PASTEL.yellow("▲ #{delta.abs} bytes larger  (#{delta_pct}%)")}"
+        else
+          @out.puts size_line + "  (no change)"
+        end
+
+        return unless row_count > 0 && delta != 0
+
+        total_mb = (delta.abs * row_count) / (1024.0 * 1024.0)
+        verb     = delta > 0 ? "saved" : "added"
+        @out.puts "    At #{format_count(row_count)} rows:  #{PASTEL.bold("~#{scale_label(total_mb)} #{verb}")}"
+      end
+
+      def render_table(headers, rows)
+        table    = TTY::Table.new(header: headers, rows: rows)
+        rendered = table.render(:unicode, padding: [0, 1]) do |r|
+          r.border.separator = :each_row
+        end
+        rendered.each_line { @out.puts "  #{_1.chomp}" }
+      end
+
+      def scale_label(mb)
+        mb >= 1024 ? "#{(mb / 1024).round(1)} GB" : "#{mb.round(1)} MB"
+      end
+
+      def format_count(n)
+        n.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+      end
+    end
+  end
+end

data/lib/pcrd/output/cutover_printer.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "pastel"
+
+module Pcrd
+  module Output
+    class CutoverPrinter
+      PASTEL = Pastel.new
+
+      def initialize(output: $stdout)
+        @out = output
+      end
+
+      def print(result)
+        @out.puts
+        @out.puts PASTEL.bold("Cutover report")
+        @out.puts PASTEL.dim("─" * 70)
+        @out.puts
+
+        print_row_counts(result.row_counts)
+        print_sequences(result.sequence_results)
+        print_warnings(result.warnings)
+        print_summary(result)
+      end
+
+      def print_verify(result)
+        @out.puts
+        @out.puts PASTEL.bold("Verify results")
+        @out.puts PASTEL.dim("─" * 70)
+        @out.puts
+
+        result.tables.each do |t|
+          src = t.source_count
+          tgt = t.target_count
+
+          if src.nil?
+            @out.puts "  #{PASTEL.red("✗")}  #{t.table_name}  #{PASTEL.red(t.mismatches.first)}"
+            next
+          end
+
+          if src == tgt
+            suffix = t.mismatches.empty? ? "" : PASTEL.yellow("  (#{t.mismatches.length} spot-check mismatch(es))")
+            @out.puts "  #{PASTEL.green("✓")}  #{t.table_name}  " \
+                      "#{PASTEL.dim("#{format_count(src)} rows match")}#{suffix}"
+          else
+            @out.puts "  #{PASTEL.red("✗")}  #{t.table_name}  " \
+                      "source=#{format_count(src)}  target=#{format_count(tgt)}  " \
+                      "#{PASTEL.red("count mismatch")}"
+          end
+        end
+
+        @out.puts
+        if result.passed
+          @out.puts "  #{PASTEL.green("✓")}  #{PASTEL.bold("All tables verified.")}"
+        else
+          @out.puts "  #{PASTEL.red("✗")}  #{PASTEL.bold(PASTEL.red("Verification failed."))}"
+        end
+        @out.puts
+      end
+
+      private
+
+      def print_row_counts(row_counts)
+        @out.puts "  #{PASTEL.bold("Row counts:")}"
+        row_counts.each do |table, counts|
+          src = counts[:source]
+          tgt = counts[:target]
+
+          if src == tgt
+            @out.puts "    #{PASTEL.green("✓")}  #{table}  #{format_count(src)} rows"
+          else
+            @out.puts "    #{PASTEL.red("✗")}  #{table}  " \
+                      "source=#{format_count(src)}  target=#{format_count(tgt)}  " \
+                      "#{PASTEL.red("MISMATCH")}"
+          end
+        end
+        @out.puts
+      end
+
+      def print_sequences(seq_results)
+        return if seq_results.empty?
+
+        @out.puts "  #{PASTEL.bold("Sequence advancement:")}"
+        seq_results.each do |r|
+          @out.puts "    #{PASTEL.green("✓")}  #{r.table_name}.#{r.column_name}  " \
+                    "#{PASTEL.dim("setval(#{r.target_seq_name}, #{r.target_value})")}"
+          @out.puts "         #{PASTEL.dim("source last_value=#{r.source_last_value}  " \
+                    "source max=#{r.source_max_id}  buffer=+#{r.safety_buffer}")}"
+        end
+        @out.puts
+      end
+
+      def print_warnings(warnings)
+        return if warnings.empty?
+
+        warnings.each do |w|
+          @out.puts "  #{PASTEL.yellow("⚠")}  #{PASTEL.yellow(w)}"
+        end
+        @out.puts
+      end
+
+      def print_summary(result)
+        @out.puts PASTEL.dim("─" * 70)
+        @out.puts
+
+        if result.passed
+          @out.puts "  #{PASTEL.green("✓")}  #{PASTEL.bold("Cutover complete.")}"
+          @out.puts
+          @out.puts "  #{PASTEL.bold("Next steps:")}"
+          @out.puts "    1. Update DATABASE_URL to point at the target cluster"
+          @out.puts "    2. Restart the application"
+          @out.puts "    3. Run `pcrd verify` to confirm row counts"
+          @out.puts "    4. End maintenance mode"
+          @out.puts "    5. Run `pcrd cleanup` (days later, when confident)"
+        else
+          @out.puts "  #{PASTEL.red("✗")}  #{PASTEL.bold("Cutover check failed.")} " \
+                    "Review the issues above before switching connection strings."
+        end
+        @out.puts
+      end
+
+      def format_count(n)
+        return "?" if n.nil?
+        n.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+      end
+    end
+  end
+end