pcrd 0.1.0

data/lib/pcrd/cutover/sequences.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Pcrd
+  module Cutover
+    # Advances sequences on the target cluster to be safely ahead of the source.
+    #
+    # Called during cutover after writes on the source have stopped (maintenance
+    # mode active). At that point the source sequence is frozen and we can
+    # safely compute the correct target value.
+    #
+    # For each serial/bigserial/identity column in the migrated tables:
+    #   1. Read last_value + is_called from the source sequence
+    #   2. Read MAX(pk_col) from the source table (covers rolled-back transactions
+    #      that consumed sequence values without committing a row)
+    #   3. Take the maximum of both + safety_buffer
+    #   4. Call setval on the target sequence
+    #
+    # Returns an Array<SequenceResult> describing every setval performed.
+    class Sequences
+      SequenceResult = Data.define(
+        :table_name,
+        :column_name,
+        :source_seq_name,
+        :target_seq_name,
+        :source_last_value,
+        :source_max_id,
+        :target_value,
+        :safety_buffer
+      )
+
+      def initialize(source_pool:, target_pool:, safety_buffer: 1_000)
+        @source   = source_pool
+        @target   = target_pool
+        @buffer   = safety_buffer
+      end
+
+      # Advances sequences for all serial/identity columns in the given tables.
+      # Returns Array<SequenceResult>.
+      def advance(table_names)
+        results = []
+        table_names.each do |table_name|
+          sequences_for_table(table_name).each do |col_name, seq_name|
+            result = advance_one(table_name, col_name, seq_name)
+            results << result if result
+          end
+        end
+        results
+      end
+
+      private
+
+      # Returns Hash<column_name, qualified_sequence_name> for all owned sequences.
+      # Handles both SERIAL/BIGSERIAL columns and GENERATED ... AS IDENTITY columns.
+      def sequences_for_table(table_name)
+        result = @source.exec(<<~SQL, [table_name])
+          SELECT a.attname                               AS col_name,
+                 n.nspname || '.' || seq.relname         AS seq_name
+          FROM   pg_depend d
+          JOIN   pg_class seq ON seq.oid = d.objid AND seq.relkind = 'S'
+          JOIN   pg_namespace n ON n.oid = seq.relnamespace
+          JOIN   pg_attribute a
+                   ON  a.attrelid = d.refobjid
+                   AND a.attnum   = d.refobjsubid
+          JOIN   pg_class c ON c.oid = a.attrelid AND c.relname = $1
+          WHERE  d.classid    = 'pg_class'::regclass
+            AND  d.refclassid = 'pg_class'::regclass
+            AND  d.deptype   IN ('a', 'i')
+        SQL
+
+        result.each_with_object({}) do |row, h|
+          h[row["col_name"]] = row["seq_name"]
+        end
+      rescue Connection::Error
+        {}
+      end
+
+      def advance_one(table_name, col_name, source_seq_name)
+        # Read source sequence state
+        seq_row = @source.exec(
+          "SELECT last_value, is_called FROM #{source_seq_name}"
+        )[0]
+        source_last    = seq_row["last_value"].to_i
+        is_called      = seq_row["is_called"] == "t"
+        effective_last = is_called ? source_last : source_last - 1
+
+        # Read actual max value in table (accounts for rolled-back allocations)
+        quoted_col   = @source.quote_ident(col_name)
+        quoted_table = @source.quote_ident(table_name)
+        max_row    = @source.exec("SELECT COALESCE(MAX(#{quoted_col}), 0) AS m FROM #{quoted_table}")
+        source_max = max_row[0]["m"].to_i
+
+        target_value = [effective_last, source_max].max + @buffer
+
+        # Derive the target sequence name from the source (strip schema, use public.)
+        seq_base        = source_seq_name.split(".").last
+        target_seq_name = "public.#{seq_base}"
+
+        # Create the sequence on the target if it doesn't already exist.
+        # pcrd strips sequences from generated DDL by design; cutover creates them.
+        ensure_target_sequence(table_name, col_name, target_seq_name)
+
+        @target.exec("SELECT setval($1, $2)", [target_seq_name, target_value])
+
+        SequenceResult.new(
+          table_name:        table_name,
+          column_name:       col_name,
+          source_seq_name:   source_seq_name,
+          target_seq_name:   target_seq_name,
+          source_last_value: source_last,
+          source_max_id:     source_max,
+          target_value:      target_value,
+          safety_buffer:     @buffer
+        )
+      rescue Connection::Error => e
+        warn "  Warning: could not advance sequence for #{table_name}.#{col_name}: #{e.message}"
+        nil
+      end
+
+      def ensure_target_sequence(table_name, col_name, seq_name)
+        exists = @target.exec(
+          "SELECT 1 FROM pg_class c " \
+          "JOIN pg_namespace n ON n.oid = c.relnamespace " \
+          "WHERE n.nspname || '.' || c.relname = $1 AND c.relkind = 'S'",
+          [seq_name]
+        ).ntuples > 0
+        return if exists
+
+        qt  = @target.quote_ident(table_name)
+        qc  = @target.quote_ident(col_name)
+        @target.exec_sql(<<~SQL)
+          CREATE SEQUENCE #{seq_name};
+          ALTER TABLE #{qt} ALTER COLUMN #{qc} SET DEFAULT nextval('#{seq_name}');
+          ALTER SEQUENCE #{seq_name} OWNED BY #{qt}.#{qc};
+        SQL
+      end
+    end
+  end
+end

data/lib/pcrd/demo/generator.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module Pcrd
+  module Demo
+    # Generates realistic-looking fake data for the demo schema.
+    # Uses no external dependencies — all data is synthesized from built-in arrays.
+    class Generator
+      BATCH_SIZE = 500
+
+      FIRST_NAMES = %w[
+        James Mary Robert Patricia John Jennifer Michael Linda William Barbara
+        David Susan Richard Karen Joseph Lisa Thomas Betty Charles Margaret
+        Christopher Sandra Daniel Ashley Paul Emily Mark Donna George Carol
+        Steven Ruth Kenneth Sharon Edward Michelle Brian Cynthia Ronald Laura
+        Anthony Kimberly Kevin Deborah Jason Rebecca Jeffrey Sharon Gary Helen
+      ].freeze
+
+      LAST_NAMES = %w[
+        Smith Johnson Williams Brown Jones Garcia Miller Davis Wilson Anderson
+        Taylor Thomas Hernandez Moore Martin Jackson Thompson White Lopez Lee
+        Gonzalez Harris Clark Lewis Robinson Walker Perez Hall Young Allen
+        Sanchez Wright King Scott Green Baker Adams Nelson Hill Ramirez Campbell
+        Mitchell Roberts Carter Phillips Evans Turner Torres Parker Collins Edwards
+      ].freeze
+
+      EMAIL_DOMAINS = %w[gmail.com yahoo.com hotmail.com outlook.com icloud.com].freeze
+
+      CITIES_STATES = [
+        ["New York",      "NY"], ["Los Angeles",   "CA"], ["Chicago",       "IL"],
+        ["Houston",       "TX"], ["Phoenix",        "AZ"], ["Philadelphia",  "PA"],
+        ["San Antonio",   "TX"], ["San Diego",      "CA"], ["Dallas",        "TX"],
+        ["San Jose",      "CA"], ["Austin",         "TX"], ["Jacksonville",  "FL"],
+        ["Fort Worth",    "TX"], ["Columbus",       "OH"], ["Charlotte",     "NC"],
+        ["San Francisco", "CA"], ["Indianapolis",   "IN"], ["Seattle",       "WA"],
+        ["Denver",        "CO"], ["Nashville",      "TN"], ["Oklahoma City", "OK"],
+        ["El Paso",       "TX"], ["Boston",         "MA"], ["Portland",      "OR"],
+        ["Las Vegas",     "NV"], ["Memphis",        "TN"], ["Louisville",    "KY"],
+        ["Baltimore",     "MD"], ["Milwaukee",      "WI"], ["Albuquerque",   "NM"],
+        ["Tucson",        "AZ"], ["Fresno",         "CA"], ["Sacramento",    "CA"],
+        ["Mesa",          "AZ"], ["Kansas City",    "MO"], ["Atlanta",       "GA"],
+        ["Omaha",         "NE"], ["Colorado Springs","CO"],["Raleigh",       "NC"],
+        ["Long Beach",    "CA"], ["Virginia Beach",  "VA"], ["Minneapolis",  "MN"],
+      ].freeze
+
+      STREET_SUFFIXES = %w[St Ave Blvd Dr Rd Way Ln Ct Pl Ter Circle].freeze
+      STREET_NAMES    = %w[
+        Oak Maple Pine Cedar Elm Main Park Lake Hill River View Forest Sunset
+        Highland Meadow Ridge Valley Spring Garden Grove Willow Cherry Apple
+      ].freeze
+
+      DESCRIPTIONS = [
+        "Charming property in a desirable neighborhood.",
+        "Move-in ready home with modern upgrades throughout.",
+        "Spacious floor plan with abundant natural light.",
+        "Updated kitchen and baths, hardwood floors.",
+        "Corner lot with mature landscaping and privacy.",
+        "Open concept living with high-end finishes.",
+        "Well-maintained property close to top-rated schools.",
+        "Quiet cul-de-sac location, walking distance to parks.",
+        "Investor opportunity or perfect primary residence.",
+        "Stunning views and outdoor entertaining space.",
+        "Classic architecture with contemporary updates.",
+        "Energy-efficient with solar panels and smart features.",
+      ].freeze
+
+      def initialize(pool, seed: 42)
+        @pool = pool
+        @rng  = Random.new(seed)
+      end
+
+      # Generate users, agents, then listings in dependency order.
+      # Returns hash with row counts generated for each table.
+      def generate(listing_count:)
+        user_count  = [[(listing_count / 10).ceil, 50].max, 500].min
+        agent_count = [[(listing_count / 20).ceil, 10].max, 100].min
+
+        $stdout.puts "  Generating #{user_count} users..."
+        user_ids  = insert_users(user_count)
+
+        $stdout.puts "  Generating #{agent_count} agents..."
+        agent_ids = insert_agents(agent_count, user_ids: user_ids)
+
+        $stdout.puts "  Generating #{listing_count} listings..."
+        insert_listings(listing_count, agent_ids: agent_ids)
+
+        { users: user_count, agents: agent_count, listings: listing_count }
+      end
+
+      private
+
+      def insert_users(count)
+        ids = []
+        rows_batch(count) do |i|
+          first = FIRST_NAMES.sample(random: @rng)
+          last  = LAST_NAMES.sample(random: @rng)
+          email = "#{first.downcase}.#{last.downcase}#{i}@#{EMAIL_DOMAINS.sample(random: @rng)}"
+          [
+            "false",
+            email,
+            first,
+            last,
+            random_past_timestamp(years: 5)
+          ]
+        end.each_slice(BATCH_SIZE) do |batch|
+          result = @pool.exec(
+            "INSERT INTO users (is_admin, email, first_name, last_name, created_at) " \
+            "VALUES #{placeholders(batch, 5)} RETURNING id",
+            batch.flatten
+          )
+          ids.concat(result.column_values(0).map(&:to_i))
+        end
+        ids
+      end
+
+      def insert_agents(count, user_ids:)
+        ids = []
+        rows_batch(count) do |_i|
+          hired = random_past_date(years: 10)
+          [
+            user_ids.sample(random: @rng),
+            "LIC-#{@rng.rand(100_000..999_999)}",
+            "true",
+            format("%.4f", @rng.rand(0.020..0.065)),
+            hired,
+            random_past_timestamp(years: 5)
+          ]
+        end.each_slice(BATCH_SIZE) do |batch|
+          result = @pool.exec(
+            "INSERT INTO agents (user_id, license_number, active, commission_rate, hired_at, created_at) " \
+            "VALUES #{placeholders(batch, 6)} RETURNING id",
+            batch.flatten
+          )
+          ids.concat(result.column_values(0).map(&:to_i))
+        end
+        ids
+      end
+
+      def insert_listings(count, agent_ids:)
+        rows_batch(count) do |_i|
+          city, state = CITIES_STATES.sample(random: @rng)
+          sqft        = @rng.rand(500..7_500)
+          price       = (@rng.rand(80_000..4_500_000) / 1000.0 * 1000).round(2)
+          ppsf        = (price / sqft).round(4)
+          bedrooms    = @rng.rand(1..6)
+          bathrooms   = @rng.rand(1..4)
+          year_built  = @rng.rand(1920..2024)
+          lat         = @rng.rand(25.0..48.0).round(6)
+          lon         = @rng.rand(-124.0..-67.0).round(6)
+          listed_at   = random_past_timestamp(years: 3)
+          street_num  = @rng.rand(1..9_999)
+          street      = "#{street_num} #{STREET_NAMES.sample(random: @rng)} " \
+                        "#{STREET_SUFFIXES.sample(random: @rng)}"
+          zip         = format("%05d", @rng.rand(10_000..99_999))
+          [
+            "true",
+            price,
+            bedrooms,
+            "false",
+            listed_at,
+            sqft,
+            "false",
+            ppsf,
+            lon,
+            year_built,
+            listed_at,
+            bathrooms,
+            year_built > 2020 ? (@rng.rand < 0.5 ? "true" : "false") : "false",
+            lat,
+            DESCRIPTIONS.sample(random: @rng),
+            street,
+            city,
+            state,
+            zip,
+            agent_ids.sample(random: @rng)
+          ]
+        end.each_slice(BATCH_SIZE) do |batch|
+          @pool.exec(
+            "INSERT INTO listings (" \
+            "  active, list_price, bedrooms, has_garage, listed_at, square_feet," \
+            "  is_featured, price_per_sqft, longitude, year_built, created_at," \
+            "  bathrooms, is_new_construction, latitude, description," \
+            "  address_line1, city, state_code, zip_code, agent_id" \
+            ") VALUES #{placeholders(batch, 20)}",
+            batch.flatten
+          )
+        end
+      end
+
+      # Builds an array of rows by calling block(index) for each row.
+      def rows_batch(count, &block)
+        count.times.map(&block)
+      end
+
+      # Builds $1,$2,$3,... placeholder groups for multi-row insert.
+      def placeholders(rows, cols_per_row)
+        rows.each_with_index.map do |_, i|
+          base = i * cols_per_row + 1
+          "(#{(base..base + cols_per_row - 1).map { "$#{_1}" }.join(",")})"
+        end.join(",")
+      end
+
+      def random_past_timestamp(years:)
+        seconds_ago = @rng.rand(0..(years * 365 * 24 * 3600))
+        offset = Time.now.to_i - seconds_ago
+        Time.at(offset).strftime("%Y-%m-%d %H:%M:%S")
+      end
+
+      def random_past_date(years:)
+        days_ago = @rng.rand(0..(years * 365))
+        (Date.today - days_ago).to_s
+      end
+    end
+  end
+end

data/lib/pcrd/demo/schema.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Pcrd
+  module Demo
+    # DDL for the demo source database.
+    #
+    # The listings table is intentionally ordered to maximize padding waste —
+    # booleans and smallints are interleaved with 8-byte types (timestamps,
+    # double precision) throughout the column list. This creates a compelling
+    # before/after for `pcrd analyze`.
+    #
+    # The migration target will reorder columns optimally (bigint IDs,
+    # 8-byte types first, then 4-byte, then 2-byte, then 1-byte, then variable).
+    module Schema
+      DROP_SQL = <<~SQL.freeze
+        DROP TABLE IF EXISTS listings CASCADE;
+        DROP TABLE IF EXISTS agents   CASCADE;
+        DROP TABLE IF EXISTS users    CASCADE;
+      SQL
+
+      # Column ordering is deliberately poor to demonstrate padding analysis:
+      # booleans and smallints scattered among 8-byte types waste ~22 bytes/row.
+      # FK from listings → agents; executed after both tables are created.
+      LISTINGS_FK_DDL = <<~SQL.freeze
+        ALTER TABLE listings
+          ADD CONSTRAINT listings_agent_fk
+          FOREIGN KEY (agent_id) REFERENCES agents(id);
+      SQL
+
+      LISTINGS_DDL = <<~SQL.freeze
+        CREATE TABLE listings (
+          id                  integer           NOT NULL GENERATED ALWAYS AS IDENTITY,
+          active              boolean           NOT NULL DEFAULT true,
+          list_price          numeric(10,2)     NOT NULL,
+          bedrooms            smallint,
+          has_garage          boolean           NOT NULL DEFAULT false,
+          listed_at           timestamp         NOT NULL DEFAULT now(),
+          square_feet         integer,
+          is_featured         boolean           NOT NULL DEFAULT false,
+          price_per_sqft      real,
+          longitude           double precision,
+          year_built          smallint,
+          created_at          timestamp         NOT NULL DEFAULT now(),
+          bathrooms           smallint,
+          is_new_construction boolean           NOT NULL DEFAULT false,
+          latitude            double precision,
+          description         text,
+          address_line1       varchar(255)      NOT NULL,
+          city                varchar(100)      NOT NULL,
+          state_code          char(2)           NOT NULL,
+          zip_code            varchar(10),
+          agent_id            integer,
+          PRIMARY KEY (id)
+        );
+      SQL
+
+      USERS_DDL = <<~SQL.freeze
+        CREATE TABLE users (
+          id          integer       NOT NULL GENERATED ALWAYS AS IDENTITY,
+          is_admin    boolean       NOT NULL DEFAULT false,
+          email       varchar(255)  NOT NULL,
+          first_name  varchar(100),
+          last_name   varchar(100),
+          created_at  timestamp     NOT NULL DEFAULT now(),
+          PRIMARY KEY (id),
+          UNIQUE (email)
+        );
+      SQL
+
+      AGENTS_DDL = <<~SQL.freeze
+        CREATE TABLE agents (
+          id              integer       NOT NULL GENERATED ALWAYS AS IDENTITY,
+          user_id         integer       NOT NULL REFERENCES users(id),
+          license_number  varchar(50),
+          active          boolean       NOT NULL DEFAULT true,
+          commission_rate numeric(5,4)  NOT NULL DEFAULT 0.0300,
+          hired_at        date,
+          created_at      timestamp     NOT NULL DEFAULT now(),
+          PRIMARY KEY (id)
+        );
+      SQL
+
+      # A sample pcrd.config.yml that works with the demo schema.
+      # Written to disk by `pcrd demo setup` if no config exists.
+      SAMPLE_CONFIG = <<~YAML.freeze
+        # pcrd.config.yml — generated by `pcrd demo setup`
+        #
+        # Source: the original database (running demo schema)
+        # Target: the new cluster with the improved schema
+
+        source:
+          host: localhost
+          port: 5433
+          database: pcrd_source
+          user: postgres
+          password: postgres
+
+        target:
+          host: localhost
+          port: 5434
+          database: pcrd_target
+          user: postgres
+          password: postgres
+
+        migrate:
+          tables:
+            - name: users
+              columns:
+                id:
+                  type: bigint
+
+            - name: agents
+              columns:
+                id:
+                  type: bigint
+                user_id:
+                  type: bigint
+                commission_rate:
+                  type: numeric(7,4)
+
+            - name: listings
+              optimize_column_order: true
+              columns:
+                id:
+                  type: bigint
+                agent_id:
+                  type: bigint
+                list_price:
+                  type: numeric(18,4)
+                  rename: list_price_precise
+                listed_at:
+                  type: timestamptz
+                created_at:
+                  type: timestamptz
+              add_columns:
+                - name: updated_at
+                  type: timestamptz
+                  default: "now()"
+
+        analyze:
+          tables:
+            - listings
+            - users
+            - agents
+
+        verify:
+          sample_size: 1000
+
+        cutover:
+          sequence_buffer: 1000
+      YAML
+    end
+  end
+end

data/lib/pcrd/error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Pcrd
+  # Base class for every error pcrd raises on purpose. Catching Pcrd::Error at
+  # the CLI boundary turns expected failures into clean messages, while letting
+  # genuinely unexpected errors (real bugs) surface with their backtrace.
+  class Error < StandardError; end
+
+  # Raised when a command is given a config that lacks something it needs
+  # (e.g. no target connection, no tables).
+  class ConfigError < Error; end
+end