exwiw 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72265c12853dbc7a70b44d81aca646870f23a2964e8433e0799edd6d6228c494
-  data.tar.gz: ea442e301f04910083c5ac39d35fdeba81cc8078a7cabae44f03defa40cdaf5b
+  metadata.gz: 4855b3fc49afc6cc69606579eb15c0cf430c4123024ec8e9b26a5215989292d3
+  data.tar.gz: 1ee99545e00cb43292c59b918dc24d3b4f764427f8708fca773c0b507f6c1e2d
 SHA512:
-  metadata.gz: 23d468a3a8ef2900856d7bc2730e3708d2443980bd086e69912ce4e77a3b9cd500cb67032405d2db119a39059b55b78545a34dbd9f16204d64676a73687d2045
-  data.tar.gz: dc77ea5d357863e55556615537e095216c2c5cf5bbd3e3bd98de6b359e33e8bbe7ab92b27c3745c52a9723f068303e29859bebfe46a4dacd4bd673f8ad9b82ca
+  metadata.gz: fcbe518ae634e294bd48e61088dd4bd0f1012b317b08d921bcbd7ee95e4e595c69c9df59ad18593dbcee35b017c1fa6a198102f27757183b804218920ff64cbb
+  data.tar.gz: 48475293bc58a6f32ec9edc68c3bdc0bdd1427233ec4cd2366fb656e5fdd1e050a260056fc69e73c5735eeb8cb6b457ef7244a13589946430f138359cc050911

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-05-23
+
+### Added
+
+- `skip: true` table config attribute to explicitly exclude a table from the dump. Skipped tables produce no schema entry, no `insert-*` file, and no `delete-*` file. Using a skipped table as `--target-table`, or having another non-skipped table reference it via `belongs_to`, raises `ArgumentError` on load. Available for both SQL adapters (`TableConfig`) and the MongoDB adapter (`MongodbCollectionConfig`). ([#26](https://github.com/heyinc/exwiw/pull/26))
+- `dump` / `explain` subcommands. `dump` is the default and preserves the existing behavior when no subcommand is given. `explain` prints the compiled SQL and its `EXPLAIN` output (estimate-only — `EXPLAIN QUERY PLAN` on SQLite) for each extraction query to stdout without executing the SELECTs. Supported for `mysql2`, `postgresql`, and `sqlite3`; `mongodb` is not yet supported. ([#28](https://github.com/heyinc/exwiw/pull/28))
+
 ## [0.2.0] - 2026-05-22
 
 ### Added

data/README.md

@@ -44,7 +44,12 @@ gem install exwiw
 
 ## Usage
 
-### Command
+exwiw has two subcommands:
+
+- `dump` (default) — generate INSERT/COPY SQL files. This is the existing behavior; if the subcommand is omitted, `dump` is assumed for backwards compatibility.
+- `explain` — print the compiled SQL and its `EXPLAIN` output for each query that `dump` would run, without executing the SELECTs.
+
+### `exwiw dump`
 
 ```bash
 # dump & masking all records from database to dump.sql based on schema.json
@@ -92,6 +97,22 @@ you need to delete the records before importing the dump,
 This sql will delete "all" related records to the extract targets.
 idx meaning is the same as insert sql.
 
+### `exwiw explain`
+
+Print the compiled SQL and its `EXPLAIN` output (estimate-only; `EXPLAIN QUERY PLAN` on SQLite) for each query that `dump` would run, to stdout. No SELECT is executed. Supported for `mysql2`, `postgresql`, and `sqlite3`. The `mongodb` adapter is not yet supported.
+
+```bash
+# preview the queries exwiw would run, without executing the SELECTs
+exwiw explain \
+  --adapter=postgresql \
+  --host=localhost --port=5432 --user=reader \
+  --database=app_production \
+  --config-dir=exwiw \
+  --target-table=shops --ids=1
+```
+
+The `--output-dir`, `--output-format`, `--insert-only`, and `--after-insert-hook` options are dump-specific and rejected when used with `explain`.
+
 ### Generator
 
 The config generator is provided as a Rake task.
@@ -136,21 +157,7 @@ This is an example of the one table schema:
 
 ### Output format
 
-By default, exwiw generates `INSERT` statements. For PostgreSQL, you can use `--output-format=copy` to generate `COPY FROM stdin` format instead, which is significantly faster for bulk loading:
-
-```bash
-exwiw \
-  --adapter=postgresql \
-  --host=localhost \
-  --port=5432 \
-  --user=reader \
-  --database=app_production \
-  --config-dir=exwiw \
-  --target-table=shops \
-  --ids=1 \
-  --output-dir=dump \
-  --output-format=copy
-```
+By default, exwiw generates `INSERT` statements. For PostgreSQL, you can pass `--output-format=copy` to generate `COPY FROM stdin` format instead, which is significantly faster for bulk loading.
 
 The generated file uses tab-separated values with PostgreSQL's text-format escaping (`\N` for NULL, `\\` for backslash, etc.). Import with `psql`:
 
@@ -162,21 +169,7 @@ psql -d app_dev -f dump/insert-001-shops.sql
 
 ### Skip DELETE SQL output
 
-By default, exwiw generates `delete-*.sql` files alongside the `insert-*.sql` files so that an existing dataset can be cleared before re-inserting. Pass `--insert-only` when you only need the insert files:
-
-```bash
-exwiw \
-  --adapter=mysql2 \
-  --host=localhost \
-  --port=3306 \
-  --user=reader \
-  --database=app_production \
-  --config-dir=exwiw \
-  --target-table=shops \
-  --ids=1 \
-  --output-dir=dump \
-  --insert-only
-```
+By default, exwiw generates `delete-*.sql` files alongside the `insert-*.sql` files so that an existing dataset can be cleared before re-inserting. Pass `--insert-only` when you only need the insert files.
 
 ### After-insert hook
 
@@ -198,17 +191,6 @@ insert_sql <<~SQL
 SQL
 ```
 
-Run with:
-
-```bash
-exwiw \
-  --adapter=mysql2 --host=localhost --port=3306 --user=reader \
-  --database=app_production --config-dir=exwiw \
-  --target-table=shops --ids=1,2 \
-  --output-dir=dump \
-  --after-insert-hook=hooks/seed_default_users.rb
-```
-
 **Shell hook**: anything other than `.rb` is exec'd as a child process. It is a pure side-effect hook — exwiw does not capture its stdout. The hook receives these env vars and inherits `DATABASE_PASSWORD` from the parent:
 
 - `EXWIW_OUTPUT_DIR`, `EXWIW_CONFIG_DIR`
@@ -219,6 +201,26 @@ A non-zero exit code from the shell hook aborts exwiw.
 
 Note: Ruby hooks are evaluated via `instance_eval` inside the exwiw process — only pass paths you trust.
 
+### Skip a table
+
+Set `"skip": true` on a table's config JSON to explicitly exclude it from the dump. The table is omitted from `insert-000-schema.{sql,js}`, and no `insert-*` / `delete-*` files are generated for it. Skipped tables are also not queried at all.
+
+```json
+{
+  "name": "audit_logs",
+  "primary_key": "id",
+  "skip": true,
+  "belongs_tos": [],
+  "columns": [{ "name": "id" }]
+}
+```
+
+Constraints:
+
+- If another non-skipped table has a `belongs_to` entry pointing at a skipped table, exwiw raises `ArgumentError` on load. Remove the `belongs_to` entry on the referencing table, or unset `skip` on the referenced table.
+- Specifying a skipped table as `--target-table` raises `ArgumentError`.
+- `skip: true` is preserved by `exwiw:schema:generate` regenerations (the receiver value wins over the auto-generated config).
+
 ### Bulk insert chunk size
 
 `bulk_insert_chunk_size` splits the generated `INSERT` statement into multiple statements, each containing at most the specified number of rows. This is useful when the number of records per table is large enough to hit limits like MySQL's `max_allowed_packet`.

data/docs/plans/2026-05-22-postgres-copy-mode-scenario-test.md

@@ -0,0 +1,91 @@
+# PostgreSQL COPY モードの SQL 妥当性を検証する scenario_test 追加
+
+## Context
+
+`exwiw` の PostgreSQL アダプターは `--output-format=copy` で `COPY ... FROM stdin;` 形式の出力に切り替えられる（`lib/exwiw/adapter/postgresql_adapter.rb:77-85`）。既存のテストでは:
+
+- 単体テスト（`spec/adapter/postgresql_adapter_spec.rb:256-305`）が文字列フォーマットを検証
+- ランナー統合テスト（`spec/runner_spec.rb:236-286`）がファイル構造を検証
+
+しかし **生成された COPY-mode SQL を実際に `psql -f` で取り込めるかを検証する end-to-end テストが存在しない**。ユーザーは COPY モードで invalid な SQL が出ているのではと疑っており、それを実DBに対して検証したい。
+
+既存の INSERT モードは `scenario/test_with_postgresql.sh` が `psql -f` での再取込まで含めて検証している。これに対応する COPY モード版が無い状態。
+
+ゴール: COPY モード出力を実際に psql に食わせる E2E シナリオ + スナップショット回帰テストを追加し、潜在的な invalid SQL を表面化する。
+
+## 変更ファイル
+
+1. **新規** `scenario/test_with_postgresql_copy.sh` — E2E シェル
+2. **修正** `spec/insert_output_snapshot_spec.rb` — COPY 用の SCENARIOS エントリと `snapshot_subdir` 対応
+3. **修正** `.github/workflows/scenario.yml` — `with_postgres` ジョブに新ステップ
+4. **新規** `spec/insert_output_snapshots/postgresql-copy/insert-*.sql` — `UPDATE_SNAPSHOTS=1` で自動生成
+
+## 詳細
+
+### 1. `scenario/test_with_postgresql_copy.sh`
+
+`scenario/test_with_postgresql.sh` を雛形にして以下のみ差し替え:
+
+- `FROM_DATABASE_NAME="exwiw_scenario_prod_db_copy"`
+- `TO_DATABASE_NAME="exwiw_scenario_dev_db_copy"`（並列実行されても既存シナリオと衝突しない名前）
+- `exe/exwiw` に `--output-format=copy` を追加
+- `--output-dir=tmp/postgresql-copy` に変更
+- `delete-*.sql` / `insert-*.sql` のループも `tmp/postgresql-copy/` を参照
+
+`set -e` により、psql が COPY ブロックの構文/データエラーで終了したら即時失敗する。これがユーザーが疑う「invalid SQL」の検出ポイント。
+
+末尾の検証（`INSERT INTO shops ... ` がオートインクリメントで通るか）はそのまま流用 — `to_copy_from_stdin` の後ろに付く `post_insert_sql`（sequence の setval）まで含めて検証される。
+
+実行権限 `chmod +x` を付与（兄弟スクリプトに合わせる）。
+
+### 2. `spec/insert_output_snapshot_spec.rb`
+
+- 78 行目の `snapshot_dir` を `scenario[:snapshot_subdir] || scenario[:adapter]` に変更し、同一 adapter で複数シナリオを持てるようにする
+- 76 行目の context ラベルに `output_format` がある場合のサフィックスを足して、rspec 出力で区別可能にする
+- `SCENARIOS` 配列に以下を追加:
+
+```ruby
+{
+  adapter: "postgresql",
+  config_dir: "scenario/postgresql-schema",
+  output_format: "copy",
+  snapshot_subdir: "postgresql-copy",
+  connection: { adapter: "postgresql", database_name: "exwiw_test",
+                host: "127.0.0.1", port: 5432,
+                user: "postgres", password: "test_password" },
+},
+```
+
+86 行目の `scenario.fetch(:output_format, "insert")` は既に存在するので追加変更不要。`insert-000-schema.sql` の pg_dump 正規化（21-25 行）も同 adapter なのでそのまま効く。
+
+### 3. `.github/workflows/scenario.yml`
+
+`with_postgres` ジョブの「Run exwiw (from clean target DB)」ステップ（115 行目）の後に追加:
+
+```yaml
+      - name: Run exwiw (copy mode)
+        run: scenario/test_with_postgresql_copy.sh
+```
+
+`postgres:17-alpine` サービスと `postgresql-client-17` インストールは既存ステップで完了済みなので追加不要。
+
+### 4. スナップショット生成
+
+```
+UPDATE_SNAPSHOTS=1 bundle exec rspec spec/insert_output_snapshot_spec.rb
+```
+
+`spec/insert_output_snapshots/postgresql-copy/` 配下に `insert-000-schema.sql` + `insert-001-shops.sql` ... `insert-007-transactions.sql` 相当が生成される。これを git に含める。
+
+## 検証手順
+
+1. ローカルで `docker compose up -d postgres` を起動
+2. `bash scenario/test_with_postgresql_copy.sh` を実行 — exit 0 ならば COPY モード SQL は psql 経由で valid。non-zero なら invalid SQL が表面化（その時点で原因を特定して別途修正）
+3. `UPDATE_SNAPSHOTS=1 bundle exec rspec spec/insert_output_snapshot_spec.rb` でスナップショットを生成
+4. `bundle exec rspec spec/insert_output_snapshot_spec.rb` を `UPDATE_SNAPSHOTS` 無しで再実行し、全シナリオ（sqlite3 / mysql2 / postgresql / postgresql-copy / mongodb）が通ることを確認
+5. CI 上で `with_postgres` ジョブの新ステップ `Run exwiw (copy mode)` が通る（または invalid SQL を検出する）ことを確認
+
+## 想定される結果の分岐
+
+- **テストが通った場合**: ユーザーの疑いは（少なくとも seed データの範囲では）杞憂。回帰テストとして残り、今後 COPY モード周りの改修で SQL を壊した時に早期検出できる
+- **テストが落ちた場合**: 落ち方（psql のエラーメッセージ）から原因を特定。修正は本プランの範囲外として別タスクで対応する（ユーザーに報告 → 方針決定 → 実装）

data/lib/exwiw/adapter/mongodb_adapter.rb

@@ -97,6 +97,10 @@ module Exwiw
         raise NotImplementedError, "MongodbAdapter does not support bulk delete"
       end
 
+      def explain(_query)
+        raise NotImplementedError, "MongodbAdapter does not support explain yet"
+      end
+
       def output_extension
         'jsonl'
       end

data/lib/exwiw/adapter/mysql2_adapter.rb

@@ -14,6 +14,17 @@ module Exwiw
         connection.query(sql, cast: false, as: :array).to_a
       end
 
+      def explain(query_ast)
+        sql = compile_ast(query_ast)
+
+        @logger.debug("  Executing EXPLAIN: \n#{sql}")
+        rows = connection.query("EXPLAIN #{sql}", cast: false).to_a
+        rows.each_with_index.flat_map do |row, i|
+          ["*************************** #{i + 1}. row ***************************"] +
+            row.map { |k, v| "#{k}: #{v}" }
+        end.join("\n")
+      end
+
       def dump_schema(ordered_tables, output_path)
         require 'open3'
 

data/lib/exwiw/adapter/postgresql_adapter.rb

@@ -14,6 +14,13 @@ module Exwiw
         connection.exec(sql).values
       end
 
+      def explain(query_ast)
+        sql = compile_ast(query_ast)
+
+        @logger.debug("  Executing EXPLAIN: \n#{sql}")
+        connection.exec("EXPLAIN #{sql}").values.map(&:first).join("\n")
+      end
+
       def dump_schema(ordered_tables, output_path)
         require 'open3'
 

data/lib/exwiw/adapter/sqlite3_adapter.rb

@@ -14,6 +14,14 @@ module Exwiw
         connection.execute(sql)
       end
 
+      def explain(query_ast)
+        sql = compile_ast(query_ast)
+
+        @logger.debug("  Executing EXPLAIN QUERY PLAN: \n#{sql}")
+        rows = connection.execute("EXPLAIN QUERY PLAN #{sql}")
+        rows.map { |row| row[3] }.join("\n")
+      end
+
       def dump_schema(ordered_tables, output_path)
         @logger.debug("  Reading schema from sqlite_master...")
         target_names = ordered_tables.map(&:name)

data/lib/exwiw/adapter.rb

@@ -74,6 +74,13 @@ module Exwiw
       def to_copy_from_stdin(_results, _table)
         raise NotImplementedError, "COPY format is not supported by #{self.class.name}"
       end
+
+      # Run the database-specific EXPLAIN for the given query and return the
+      # output as a single string for `explain` subcommand to print.
+      # SQL adapters override; MongodbAdapter currently raises.
+      def explain(_query_ast)
+        raise NotImplementedError, "#{self.class.name} does not implement #explain"
+      end
     end
 
     # @params [Exwiw::QueryAst] query_ast

data/lib/exwiw/cli.rb

@@ -10,26 +10,36 @@ require 'exwiw'
 
 module Exwiw
   class CLI
+    KNOWN_SUBCOMMANDS = %w[dump explain].freeze
+
     def self.start(argv)
       new(argv).run
     end
 
     def initialize(argv)
       @argv = argv.dup
-      @help = argv.empty?
+
+      @subcommand =
+        if !@argv.empty? && !@argv.first.start_with?("-") && KNOWN_SUBCOMMANDS.include?(@argv.first)
+          @argv.shift
+        else
+          "dump"
+        end
+
+      @help = @argv.empty?
 
       @database_host = nil
       @database_port = nil
       @database_user = nil
       @database_password = ENV["DATABASE_PASSWORD"]
-      @output_dir = "dump"
+      @output_dir = nil
       @config_dir = nil
       @database_adapter = nil
       @database_name = nil
       @target_table_name = nil
       @ids = []
-      @output_format = 'insert'
-      @insert_only = false
+      @output_format = nil
+      @insert_only = nil
       @after_insert_hook_path = nil
       @log_level = :info
 
@@ -39,25 +49,29 @@ module Exwiw
     def run
       if @help
         puts parser.help
-      else
-        validate_options!
+        return
+      end
 
-        connection_config = ConnectionConfig.new(
-          adapter: @database_adapter,
-          host: @database_host,
-          port: @database_port,
-          user: @database_user,
-          password: @database_password,
-          database_name: @database_name,
-        )
+      validate_options!
 
-        dump_target = DumpTarget.new(
-          table_name: @target_table_name,
-          ids: @ids,
-        )
+      connection_config = ConnectionConfig.new(
+        adapter: @database_adapter,
+        host: @database_host,
+        port: @database_port,
+        user: @database_user,
+        password: @database_password,
+        database_name: @database_name,
+      )
+
+      dump_target = DumpTarget.new(
+        table_name: @target_table_name,
+        ids: @ids,
+      )
 
-        logger = build_logger
+      logger = build_logger
 
+      case @subcommand
+      when "dump"
         Runner.new(
           connection_config: connection_config,
           output_dir: @output_dir,
@@ -69,10 +83,22 @@ module Exwiw
           cli_options: build_cli_options_hash,
           logger: logger,
         ).run
+      when "explain"
+        ExplainRunner.new(
+          connection_config: connection_config,
+          config_dir: @config_dir,
+          dump_target: dump_target,
+          logger: logger,
+          io: $stdout,
+        ).run
       end
     end
 
     private def validate_options!
+      if @subcommand == "explain"
+        validate_explain_only!
+      end
+
       if @database_adapter != "sqlite3"
         required_options = {
           "Target database host" => @database_host,
@@ -99,15 +125,21 @@ module Exwiw
         exit 1
       end
 
-      valid_output_formats = ["insert", "copy"]
-      unless valid_output_formats.include?(@output_format)
-        $stderr.puts "Invalid output format '#{@output_format}'. Available options are: #{valid_output_formats.join(', ')}"
-        exit 1
-      end
+      if @subcommand == "dump"
+        @output_dir ||= "dump"
+        @output_format ||= "insert"
+        @insert_only = @insert_only ? true : false
 
-      if @output_format == "copy" && @database_adapter != "postgresql"
-        $stderr.puts "--output-format=copy is only supported with the postgresql adapter"
-        exit 1
+        valid_output_formats = ["insert", "copy"]
+        unless valid_output_formats.include?(@output_format)
+          $stderr.puts "Invalid output format '#{@output_format}'. Available options are: #{valid_output_formats.join(', ')}"
+          exit 1
+        end
+
+        if @output_format == "copy" && @database_adapter != "postgresql"
+          $stderr.puts "--output-format=copy is only supported with the postgresql adapter"
+          exit 1
+        end
       end
 
       if @config_dir.nil?
@@ -149,6 +181,24 @@ module Exwiw
       end
     end
 
+    private def validate_explain_only!
+      if @database_adapter == "mongodb"
+        $stderr.puts "mongodb adapter is not yet supported by 'explain' subcommand"
+        exit 1
+      end
+
+      rejected = []
+      rejected << "--output-dir" unless @output_dir.nil?
+      rejected << "--output-format" unless @output_format.nil?
+      rejected << "--insert-only" unless @insert_only.nil?
+      rejected << "--after-insert-hook" unless @after_insert_hook_path.nil?
+
+      unless rejected.empty?
+        $stderr.puts "The following options are not applicable in 'explain' subcommand: #{rejected.join(', ')}"
+        exit 1
+      end
+    end
+
     private def build_cli_options_hash
       {
         database_host: @database_host,
@@ -185,13 +235,22 @@ module Exwiw
 
     private def parser
       @parser ||= OptionParser.new do |opts|
-        opts.banner = "exwiw #{Exwiw::VERSION}"
+        opts.banner = <<~BANNER
+          exwiw #{Exwiw::VERSION}
+
+          Usage: exwiw [SUBCOMMAND] [options]
+
+          Subcommands:
+            dump      Generate INSERT/COPY SQL files (default when omitted).
+            explain   Print EXPLAIN output for each extraction query to stdout.
+                      (not yet supported for the mongodb adapter)
+        BANNER
         opts.version = Exwiw::VERSION
 
         opts.on("-h", "--host=HOST", "Target database host") { |v| @database_host = v }
         opts.on("-p", "--port=PORT", "Target database port") { |v| @database_port = v }
         opts.on("-u", "--user=USERNAME", "Target database user") { |v| @database_user = v }
-        opts.on("-o", "--output-dir=[DUMP_DIR_PATH]", "Output file path. default is dump/") do |v|
+        opts.on("-o", "--output-dir=[DUMP_DIR_PATH]", "Output file path. default is dump/ (dump subcommand only)") do |v|
           v = v.end_with?("/") ? v[0..-2] : v
           @output_dir = File.expand_path(v)
         end
@@ -203,9 +262,9 @@ module Exwiw
         opts.on("--database=DATABASE", "Target database name") { |v| @database_name = v }
         opts.on("--target-table=[TABLE]", "Target table for extraction. If omitted, dump all tables.") { |v| @target_table_name = v }
         opts.on("--ids=[IDS]", "Comma-separated list of identifiers. Required when --target-table is given.") { |v| @ids = v.split(',') }
-        opts.on("--output-format=[FORMAT]", "Output format: insert (default) or copy (PostgreSQL only)") { |v| @output_format = v }
-        opts.on("--insert-only", "Do not generate DELETE SQL files") { @insert_only = true }
-        opts.on("--after-insert-hook=PATH", "Path to a .rb or .sh post-processing hook executed after all insert/delete files are written") do |v|
+        opts.on("--output-format=[FORMAT]", "Output format: insert (default) or copy (PostgreSQL only, dump subcommand only)") { |v| @output_format = v }
+        opts.on("--insert-only", "Do not generate DELETE SQL files (dump subcommand only)") { @insert_only = true }
+        opts.on("--after-insert-hook=PATH", "Path to a .rb or .sh post-processing hook executed after all insert/delete files are written (dump subcommand only)") do |v|
           @after_insert_hook_path = File.expand_path(v)
         end
         opts.on("--log-level=LEVEL", "Log level (debug, info). default is info") { |v| @log_level = v.to_sym }

data/lib/exwiw/explain_runner.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Exwiw
+  class ExplainRunner
+    def initialize(
+      connection_config:,
+      config_dir:,
+      dump_target:,
+      logger:,
+      io: $stdout
+    )
+      @connection_config = connection_config
+      @config_dir = config_dir
+      @dump_target = dump_target
+      @logger = logger
+      @io = io
+    end
+
+    def run
+      adapter = Adapter.build(@connection_config, @logger)
+      configs = load_table_config(adapter.class.table_config_class)
+      configs = reject_and_validate_skipped(configs)
+
+      table_by_name = configs.each_with_object({}) { |config, hash| hash[config.name] = config }
+
+      target = table_by_name[@dump_target.table_name]
+      adapter.validate_as_dump_target!(target) if target
+
+      @logger.debug("Determining table processing order...")
+      ordered_table_names = DetermineTableProcessingOrder.run(configs.select { |c| adapter.dumpable?(c) })
+
+      total_size = ordered_table_names.size
+      ordered_table_names.each_with_index do |table_name, idx|
+        @logger.debug("Explaining '#{table_name}'... (#{idx + 1}/#{total_size})")
+        table = table_by_name.fetch(table_name)
+
+        query_ast = adapter.build_query(table, @dump_target, table_by_name)
+        sql = adapter.compile_ast(query_ast)
+        explain_text = adapter.explain(query_ast)
+
+        @io.puts "-- [#{idx + 1}/#{total_size}] #{table_name}"
+        @io.puts sql
+        @io.puts
+        @io.puts "-- EXPLAIN:"
+        @io.puts explain_text
+        @io.puts
+      end
+    end
+
+    private def load_table_config(klass)
+      Dir[File.join(@config_dir, "*.json")].map do |file|
+        json = JSON.parse(File.read(file))
+        klass.from(json)
+      end
+    end
+
+    private def reject_and_validate_skipped(configs)
+      skipped_names = configs.select { |c| c.skip }.map(&:name).to_set
+      return configs if skipped_names.empty?
+
+      configs.each do |config|
+        next if config.skip
+        next unless config.respond_to?(:belongs_tos)
+
+        dangling = config.belongs_tos.select { |rel| skipped_names.include?(rel.table_name) }
+        next if dangling.empty?
+
+        raise ArgumentError,
+              "Table '#{config.name}' has belongs_to references to skipped table(s): " \
+              "#{dangling.map(&:table_name).join(', ')}. " \
+              "Remove the belongs_to entries or unset `skip` on the referenced table."
+      end
+
+      if @dump_target.table_name && skipped_names.include?(@dump_target.table_name)
+        raise ArgumentError,
+              "--target-table '#{@dump_target.table_name}' is marked skip:true and cannot be used as a dump target."
+      end
+
+      skipped_names.each { |n| @logger.info("Skipping table '#{n}' (skip:true)") }
+      configs.reject { |c| c.skip }
+    end
+  end
+end

data/lib/exwiw/mongodb_collection_config.rb

@@ -13,6 +13,7 @@ module Exwiw
     attribute :belongs_tos, array(BelongsTo)
     attribute :fields, array(MongodbField)
     attribute :bulk_insert_chunk_size, optional(Integer), skip_serializing_if_nil: true
+    attribute :skip, Serdes::OptionalType.new(Serdes::ConcreteType.new(Boolean)), skip_serializing_if_nil: true
 
     # Marks this config as physically embedded inside another collection's
     # documents. When set, this config is not processed as a standalone dump

data/lib/exwiw/runner.rb

@@ -30,6 +30,8 @@ module Exwiw
       adapter = Adapter.build(@connection_config, @logger)
       configs = load_table_config(adapter.class.table_config_class)
 
+      configs = reject_and_validate_skipped(configs)
+
       table_by_name = configs.each_with_object({}) { |config, hash| hash[config.name] = config }
 
       target = table_by_name[@dump_target.table_name]
@@ -120,5 +122,31 @@ module Exwiw
         klass.from(json)
       end
     end
+
+    private def reject_and_validate_skipped(configs)
+      skipped_names = configs.select { |c| c.skip }.map(&:name).to_set
+      return configs if skipped_names.empty?
+
+      configs.each do |config|
+        next if config.skip
+        next unless config.respond_to?(:belongs_tos)
+
+        dangling = config.belongs_tos.select { |rel| skipped_names.include?(rel.table_name) }
+        next if dangling.empty?
+
+        raise ArgumentError,
+              "Table '#{config.name}' has belongs_to references to skipped table(s): " \
+              "#{dangling.map(&:table_name).join(', ')}. " \
+              "Remove the belongs_to entries or unset `skip` on the referenced table."
+      end
+
+      if @dump_target.table_name && skipped_names.include?(@dump_target.table_name)
+        raise ArgumentError,
+              "--target-table '#{@dump_target.table_name}' is marked skip:true and cannot be used as a dump target."
+      end
+
+      skipped_names.each { |n| @logger.info("Skipping table '#{n}' (skip:true)") }
+      configs.reject { |c| c.skip }
+    end
   end
 end

data/lib/exwiw/table_config.rb

@@ -10,6 +10,7 @@ module Exwiw
     attribute :belongs_tos, array(BelongsTo)
     attribute :columns, array(TableColumn)
     attribute :bulk_insert_chunk_size, optional(Integer), skip_serializing_if_nil: true
+    attribute :skip, Serdes::OptionalType.new(Serdes::ConcreteType.new(Boolean)), skip_serializing_if_nil: true
 
     def self.from_symbol_keys(hash)
       from(JSON.parse(hash.to_json))
@@ -76,6 +77,7 @@ module Exwiw
         merged_table.filter = filter
         merged_table.belongs_tos = passed_table.belongs_tos
         merged_table.bulk_insert_chunk_size = passed_table.bulk_insert_chunk_size
+        merged_table.skip = skip
 
         receiver_column_by_name = columns.each_with_object({}) { |column, hash| hash[column.name] = column }
 

data/lib/exwiw/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Exwiw
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/exwiw.rb

@@ -23,6 +23,7 @@ require_relative "exwiw/query_ast"
 require_relative "exwiw/query_ast_builder"
 require_relative "exwiw/after_insert_hook"
 require_relative "exwiw/runner"
+require_relative "exwiw/explain_runner"
 require_relative "exwiw/schema_generator"
 
 begin

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exwiw
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Shia
@@ -38,6 +38,7 @@ files:
 - docs/plans/2026-05-15-insert-000-schema-file.md
 - docs/plans/2026-05-16-mongodb-from-clean-scenario.md
 - docs/plans/2026-05-22-after-insert-hook.md
+- docs/plans/2026-05-22-postgres-copy-mode-scenario-test.md
 - exe/exwiw
 - lib/exwiw.rb
 - lib/exwiw/adapter.rb
@@ -51,6 +52,7 @@ files:
 - lib/exwiw/ddl_postprocessor.rb
 - lib/exwiw/determine_table_processing_order.rb
 - lib/exwiw/embedded_in.rb
+- lib/exwiw/explain_runner.rb
 - lib/exwiw/mongo_query.rb
 - lib/exwiw/mongodb_collection_config.rb
 - lib/exwiw/mongodb_field.rb