exwiw 0.2.9 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e5d922e740407599ecb3fa3992e0de402434bacfb38ca817a189a53acf16ab3
-  data.tar.gz: 2a8919778bb9395434587ebb69f49f4d8445cb1890e0999cb065b5577d802532
+  metadata.gz: 55e0eecbd5d7117c263f00fb43c36e2bcc31c75eb4b7ef0255402bec2ac108dc
+  data.tar.gz: '0913f0804ad33023661b947f88cc86adfeb98ef6b047a93f0ba1f09cea52cec9'
 SHA512:
-  metadata.gz: e38a240087564c3e3909106268fba7ad3a8dce881924f8b210b1733d65f0bc12d3bb514af80be21e6f0ad39707f99e96edbaed3cc7c54e2d26677c3a0c7d203f
-  data.tar.gz: cca54067266034f8df074fce301623fd6c0c860e9fd1a13eac43d930b89f46a7b63d3e6230d155abcce3f6ab021c2299d518f8131d26ee5bcbe7c0a535093ee9
+  metadata.gz: bb152c10da5489d005660f458ee8cc526a199a15618e41a625694df6d8cca5df623916c14996f03df1ee969b1c51e43b12fc1b7a8676f2754ae01c7211deb251
+  data.tar.gz: 55ae136ec956f3a3e15d522e3d71388765ab206911e5662e653522d35e3126fb1d67711051bfd19d8cc2a7457194f84065ecc49dde38d7faaca67fddfb70da1f

data/CHANGELOG.md

@@ -2,11 +2,23 @@
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-05-31
+
+### Changed
+
+- **Breaking:** the `dump` subcommand is renamed to `export` to match the gem name (Export What I Want). Invoke `exwiw export ...` (or omit the subcommand, which now defaults to `export`) instead of `exwiw dump ...`. There is no `dump` alias.
+
+## [0.3.0] - 2026-05-31
+
+### Added
+
+- New `--ids-column=COLUMN` CLI option matches `--ids` against an arbitrary column on the target table instead of its primary key (e.g. `--target-table=users --ids=alice@example.com --ids-column=email`). This is the SQL-adapter (mysql2/postgresql/sqlite3) counterpart of the mongodb `--ids-field`; the two are mutually exclusive and each is rejected by the other adapter family (`--ids-field` is mongodb-only, `--ids-column` is sql-only), mirroring the existing `--target-table` / `--target-collection` split. Related tables are still extracted correctly: rather than propagating `--ids` directly onto foreign keys (which would be wrong when filtering on a non-primary-key column), each foreign key is resolved through the target via a subquery (`WHERE fk IN (SELECT pk FROM target WHERE COLUMN IN (...))`), so only the target table's filter column changes and direct / indirect / polymorphic relations all extract correctly. Note: if `COLUMN` is itself masked, re-running `delete-*` against an already-imported (masked) dump won't match, so prefer a stable natural key. ([#47](https://github.com/heyinc/exwiw/pull/47))
+
 ## [0.2.9] - 2026-05-31
 
 ### Added
 
-- New `--ids-field=FIELD` CLI option matches `--ids` against an arbitrary field on the target collection instead of its primary key (e.g. `--target-collection=users --ids=a@example.com --ids-field=email`). Only the target collection's filter changes — downstream foreign-key propagation still keys off the primary key. Unlike the primary-key path, the supplied ids are **not** type-coerced (a custom field's stored type is unknown, so values are passed through as-is). Currently **mongodb-only**: the SQL adapters (mysql2/postgresql/sqlite3) reject the flag at validation time, and threading `ids_field` through `QueryAstBuilder` for them is left as a TODO.
+- New `--ids-field=FIELD` CLI option matches `--ids` against an arbitrary field on the target collection instead of its primary key (e.g. `--target-collection=users --ids=a@example.com --ids-field=email`). Only the target collection's filter changes — downstream foreign-key propagation still keys off the primary key. Unlike the primary-key path, the supplied ids are **not** type-coerced (a custom field's stored type is unknown, so values are passed through as-is). This flag is **mongodb-only**.
 - New `--target-collection=COLLECTION` CLI option, a mongodb-only alias of `--target-table`. Specifying both, or using `--target-collection` with a non-mongodb adapter, is rejected at validation time.
 - New rake task `exwiw:schema:generate_mongoid` (backed by `Exwiw::MongoidSchemaGenerator`) generates `MongodbCollectionConfig` files by introspecting Mongoid document models — a separate task/class from the ActiveRecord `schema:generate` because the ORMs expose different metadata. It derives the collection name, the `_id` primary key, `fields` (including referenced `belongs_to` foreign keys), `belongs_tos` from referenced `belongs_to` associations, and `embedded_in` from `embedded_in` / `embeds_many` / `embeds_one` associations (each embedded config names its immediate parent collection and `store_as` document key; nested embedding is emitted as a chain — `comments` embedded_in `posts`, `posts` embedded_in `users` — so the adapter can recurse through both array and Hash subdocuments). Regeneration preserves hand-edited `replace_with` / `filter` / `skip` / `bulk_insert_chunk_size`. Polymorphic `belongs_to` is not yet expanded. Models in an inheritance hierarchy whose subclasses share the base's collection (Mongoid STI, `_type` discriminator) collapse into a single config: subclasses are discovered via `descendants` (Mongoid registers only the base in `Mongoid.models`) and every class's `fields` / `belongs_tos` are unioned, so subclass-only fields and associations are preserved. A referenced `belongs_to` declared on an *embedded* document (e.g. `Comment embedded_in :post, belongs_to :author`) is dropped from the embedded config's `belongs_tos` (cross-collection refs from inside embedded subdocuments are unsupported and rejected on load), while its foreign-key column is still kept as an ordinary field. A `has_and_belongs_to_many` association is likewise dropped from `belongs_tos` (its foreign keys are stored as an array field such as `tag_ids`, which exwiw cannot follow as a single-valued foreign key), while that `*_ids` array column is kept as an ordinary field. A *polymorphic* `embedded_in` (`embedded_in :addressable, polymorphic: true`) has no single embedding parent collection and cannot be expressed as an `embedded_in` config, so the generator raises a clear, actionable error rather than crashing on the unresolvable parent class. A *self-referential / cyclic* embedding (Mongoid's `recursively_embeds_many` / `recursively_embeds_one`) makes a collection both top-level and embedded inside documents of its own type; since exwiw represents a collection as either top-level or embedded (not both), the generator likewise raises a clear error rather than emit an `embedded_in` config that would silently make the collection undumpable. The `created_at` / `updated_at` columns added by `include Mongoid::Timestamps` are tracked as ordinary fields, and their BSON `ObjectId` / `Date` values (the shape a live `find` returns) serialize as MongoDB Extended JSON (`$oid` / `$date`) through the dump path — now covered end-to-end against the generated configs. An aliased field (`field :ctry, as: :country`) is emitted by its **stored** document key (`ctry`), never the Ruby accessor (`country`), so masking and projection target the key that actually appears in the document; the accessor is additionally surfaced as `mongoid_field_name` on that field so the otherwise cryptic short key stays understandable (association aliases such as `shop => shop_id` and the built-in `id => _id` are not field renames and are not annotated).
 

data/README.md

@@ -46,10 +46,10 @@ gem install exwiw
 
 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.
+- `export` (default) — generate INSERT/COPY SQL files. If the subcommand is omitted, `export` is assumed.
+- `explain` — print the compiled SQL and its `EXPLAIN` output for each query that `export` would run, without executing the SELECTs.
 
-### `exwiw dump`
+### `exwiw export`
 
 ```bash
 # dump & masking all records from database to dump.sql based on schema.json
@@ -67,6 +67,8 @@ exwiw \
   --log-level=info
 ```
 
+By default `--ids` are matched against the target table's primary key. `--ids-column=COLUMN` matches them against a different column instead (e.g. `--target-table=users --ids=alice@example.com --ids-column=email`). Related tables are still extracted correctly: their foreign keys are resolved through the target via a subquery (`WHERE fk IN (SELECT pk FROM target WHERE COLUMN IN (...))`), so only the target table's filter column changes. This is the SQL-adapter counterpart of the mongodb `--ids-field`; the two are mutually exclusive and each is rejected by the other adapter family. Note: if `COLUMN` is itself masked, re-running `delete-*` against an already-imported (masked) dump won't match, so prefer a stable natural key.
+
 When `--target-table` and `--ids` are omitted, exwiw dumps all tables defined in `--config-dir`:
 
 ```bash
@@ -412,7 +414,7 @@ The MongoDB adapter is experimental. To use it:
 - The MongoDB adapter consumes a separate config type, `MongodbCollectionConfig`, with MongoDB-native naming. Use `fields` (instead of the SQL adapters' `columns`), and set `"primary_key": "_id"`. Foreign keys (`shop_id`, `user_id`, ...) stay as ordinary fields.
 - `--ids` values are coerced to the type actually stored in `_id` before filtering: integer-looking ids become `Integer`, 24-char hex ids become `BSON::ObjectId` (Mongoid's default `_id` type — a plain String would never match an ObjectId), and any other string is left as-is.
 - `--target-collection=COLLECTION` is a mongodb-only alias of `--target-table` (use whichever reads better for MongoDB). Specifying both, or using `--target-collection` with a non-mongodb adapter, is an error.
-- `--ids-field=FIELD` matches `--ids` against `FIELD` on the target collection instead of its primary key (e.g. `--target-collection=users --ids=a@example.com --ids-field=email`). Downstream foreign-key propagation still keys off the primary key, so only the target collection's filter changes. Unlike the primary-key path, the supplied ids are **not** type-coerced (the stored type of a custom field is unknown), so pass values matching the field's actual type. This flag is currently **mongodb-only** (the SQL adapters reject it; supporting them is a TODO).
+- `--ids-field=FIELD` matches `--ids` against `FIELD` on the target collection instead of its primary key (e.g. `--target-collection=users --ids=a@example.com --ids-field=email`). Downstream foreign-key propagation still keys off the primary key, so only the target collection's filter changes. Unlike the primary-key path, the supplied ids are **not** type-coerced (the stored type of a custom field is unknown), so pass values matching the field's actual type. This flag is **mongodb-only**; the SQL adapters use `--ids-column` instead (see below).
 - Output is JSON Lines (`insert-{idx}-{collection}.jsonl`) using MongoDB Extended JSON (relaxed mode). Import with `mongoimport`:
   ```bash
   mongoimport --db app_dev --collection users --file dump/insert-002-users.jsonl

data/docs/plans/2026-05-31-ids-column-for-sql-adapters.md

@@ -0,0 +1,93 @@
+# `--ids-column` を SQL アダプタに実装
+
+## Context
+
+MongoDB アダプタには `--ids-field` フラグがあり、`--ids` を対象テーブルの主キー以外の
+フィールドにマッチさせられる（`lib/exwiw/adapter/mongodb_adapter.rb:48-65`）。一方で
+SQL アダプタ（mysql2 / postgresql / sqlite3）では未実装で、CLI が明示的に拒否している
+（`lib/exwiw/cli.rb:183-189` の TODO、`lib/exwiw/query_ast_builder.rb:109-118` の TODO）。
+
+このプランでは同等の機能を SQL アダプタにも提供する。命名・ゲーティングは既存の
+`--target-table` / `--target-collection` の分け方を踏襲し、**アダプタ別に厳密分離**する:
+
+- `--ids-field` … mongodb 専用（既存）
+- `--ids-column` … SQL アダプタ専用（新規）
+- 両方同時指定は拒否、不適合アダプタとの組み合わせも拒否
+
+内部的には双方とも `DumpTarget#ids_field` に集約される（`--target-collection` が
+`@target_table_name` に畳まれるのと同じパターン）。
+
+## 変更内容
+
+### 1. `lib/exwiw/cli.rb` — フラグ定義・畳み込み・バリデーション
+
+- **インスタンス変数追加**（`initialize`, 42行目付近）: `@ids_column = nil` を追加。
+- **フラグ定義**（`parser`, 309行目付近）: `--ids-field` の直後に追加。
+  ```ruby
+  opts.on("--ids-column=[COLUMN]", "Column on the target table that --ids is matched against. Defaults to the primary key. (sql adapters only)") { |v| @ids_column = v }
+  ```
+- **エイリアス畳み込み**: `resolve_target_collection_alias!`（210行目）に倣い
+  `resolve_ids_column_alias!` を新設し `validate_options!` の冒頭で呼ぶ。挙動:
+  - `--ids-field` と `--ids-column` の同時指定を拒否
+    （"Specify only one of --ids-field and --ids-column"）。
+  - `--ids-column` を mongodb で使った場合は拒否
+    （"--ids-column is only supported by the sql adapters (use --ids-field)"）。
+  - 問題なければ `@ids_field = @ids_column` に畳み込む。
+- **`--ids-field` の検証更新**（175-190行目）:
+  - `--target-table` 必須チェックは「`@ids_field` が立っていれば」で共通化されるため、
+    畳み込み後はそのまま両方をカバーする（メッセージは ids_field/ids_column を
+    使った側に合わせて出し分けるか、汎用文言にする — 実装時に調整）。
+  - mongodb 限定チェック（186-189行目）は `--ids-field` 用に維持
+    （"--ids-field is currently only supported by the mongodb adapter" のまま）。
+
+  実装方針: 畳み込み前にどちらのフラグが使われたかが分かる状態で
+  「target-table 必須」「アダプタ整合」を検証してから `@ids_field` に集約する。
+
+### 2. `lib/exwiw/query_ast_builder.rb` — WHERE 句に反映
+
+**当初の想定（1行変更）は関連テーブルで不正確になることが判明**したため、設計を変更した。
+SQL アダプタは単一クエリで `dump_target.ids` を外部キーに直接伝播する
+（`orders.user_id IN ids`）。これは `--ids` が主キーである前提のため、`--ids-column`
+で別カラムを指定すると関連テーブルが壊れる（mongodb は @state に主キーを溜めて伝播する
+ので正しい）。
+
+採用したアプローチ: **ターゲットを介すサブクエリ**。`ids_field` 指定時、外部キー制約を
+`fk IN (SELECT pk FROM target WHERE ids_field IN (ids))` に置き換える。direct /
+indirect / polymorphic を一律に正しく扱える。
+
+- `lib/exwiw/query_ast.rb`: `Subquery` 構造体を追加。`WhereClause` に
+  operator `:in_subquery`（value が `Subquery`）を導入し `to_h` を対応。
+- `lib/exwiw/query_ast_builder.rb`: `dump_target_fk_clause(foreign_key)` ヘルパーを新設。
+  `ids_field` 無しなら従来通り `eq`、有りなら `:in_subquery` を返す。
+  - `build_where_clauses`（direct belongs_to）と `build_join_clauses`
+    （indirect の `relation_to_dump_target` hop）の両方で利用。
+  - ターゲットテーブル自身のフィルタは `ids_field || primary_key` の `eq`（従来どおり）。
+- 各 SQL アダプタ（postgresql / mysql2 / sqlite3）の `compile_where_condition` に
+  `:in_subquery` 分岐と `compile_subquery` を追加。`is_a?(WhereClause)` のままなので
+  bulk_delete のサブクエリ生成・JoinClause.to_h もそのまま動く。
+
+補足: `--ids-column` がマスク対象カラムの場合、`delete-*` の冪等性が崩れる
+（README に注記済み）。
+
+## 検証
+
+- `bundle exec rspec spec/cli_spec.rb` — 既存の `--ids-field` validation を維持しつつ、
+  新規ケースを追加:
+  - `--ids-column` が `@ids_field`（畳み込み後）にパースされる
+  - `--ids-column` を mongodb で指定すると拒否される
+  - `--ids-field` と `--ids-column` の同時指定が拒否される
+  - `--ids-column` を target-table 無しで指定すると拒否される
+- `bundle exec rspec spec/query_ast_builder_spec.rb`（存在すれば）に
+  `ids_field` 指定時に対象テーブルの WHERE が主キーではなく当該カラムになることを確認する
+  ケースを追加。
+- `explain` サブコマンド（SQL のみ対応）で end-to-end 確認:
+  既存 scenario（例 `scenario/sqlite3-schema`）に対し
+  `--target-table=... --ids=... --ids-column=<col>` を渡し、出力 SQL の WHERE が
+  `<table>.<col> IN (...)` になることを目視確認。
+- `bundle exec rspec`（全体）でリグレッションが無いこと。
+
+## ドキュメント
+
+`README.md:415` の `--ids-field` 説明を更新し、SQL では `--ids-column` を使う旨と例
+（例: `--target-table=users --ids=a@example.com --ids-column=email`）を追記。
+「SQL adapters reject it / TODO」の記述を解消する。

data/lib/exwiw/adapter/mysql2_adapter.rb

@@ -138,10 +138,11 @@ module Exwiw
         subquery_sql = compile_ast(subquery_ast)
         sql += "\nWHERE #{select_query_ast.from_table_name}.#{foreign_key} IN (#{subquery_sql})"
 
-        # first_join.base_where_clauses は外側の削除対象テーブル
-        # (from_table_name) 上の条件 (polymorphic 型カラム等)。subquery には
-        # 含まれないため、外側の WHERE に追加する。これにより、別の
-        # polymorphic 型に属する行まで削除してしまうのを防ぐ。
+        # first_join.base_where_clauses holds conditions on the outer
+        # delete-target table (from_table_name), such as a polymorphic type
+        # column. They are not part of the subquery, so add them to the outer
+        # WHERE. This prevents deleting rows that belong to a different
+        # polymorphic type.
         first_join.base_where_clauses.each do |where|
           next unless where.is_a?(Exwiw::QueryAst::WhereClause)
 
@@ -171,8 +172,9 @@ module Exwiw
             sql += " AND #{compiled_where_condition}"
           end
 
-          # base_where_clauses は結合元テーブル (base_table_name) に対して
-          # コンパイルする。polymorphic な結合元テーブルの型カラム絞り込み等。
+          # base_where_clauses is compiled against the joined-from table
+          # (base_table_name), e.g. the type-column filter on a polymorphic
+          # source table.
           join.base_where_clauses.each do |where|
             compiled_where_condition = compile_where_condition(where, join.base_table_name)
             sql += " AND #{compiled_where_condition}"
@@ -201,11 +203,20 @@ module Exwiw
           else
             "#{key} IN (#{values.join(', ')})"
           end
+        elsif where_clause.operator == :in_subquery
+          "#{key} IN (#{compile_subquery(where_clause.value)})"
         else
           raise "Unsupported operator: #{where_clause.operator}"
         end
       end
 
+      private def compile_subquery(subquery)
+        inner_values = subquery.where_values.map { |v| escape_value(v) }
+        "SELECT #{subquery.table_name}.#{subquery.select_column} " \
+          "FROM #{subquery.table_name} " \
+          "WHERE #{subquery.table_name}.#{subquery.where_column} IN (#{inner_values.join(', ')})"
+      end
+
       private def escape_value(value)
         case value
         when nil

data/lib/exwiw/adapter/postgresql_adapter.rb

@@ -180,10 +180,11 @@ module Exwiw
         subquery_sql = compile_ast(subquery_ast)
         sql += "\nWHERE #{select_query_ast.from_table_name}.#{foreign_key} IN (#{subquery_sql})"
 
-        # first_join.base_where_clauses は外側の削除対象テーブル
-        # (from_table_name) 上の条件 (polymorphic 型カラム等)。subquery には
-        # 含まれないため、外側の WHERE に追加する。これにより、別の
-        # polymorphic 型に属する行まで削除してしまうのを防ぐ。
+        # first_join.base_where_clauses holds conditions on the outer
+        # delete-target table (from_table_name), such as a polymorphic type
+        # column. They are not part of the subquery, so add them to the outer
+        # WHERE. This prevents deleting rows that belong to a different
+        # polymorphic type.
         first_join.base_where_clauses.each do |where|
           next unless where.is_a?(Exwiw::QueryAst::WhereClause)
 
@@ -213,8 +214,9 @@ module Exwiw
             sql += " AND #{compiled_where_condition}"
           end
 
-          # base_where_clauses は結合元テーブル (base_table_name) に対して
-          # コンパイルする。polymorphic な結合元テーブルの型カラム絞り込み等。
+          # base_where_clauses is compiled against the joined-from table
+          # (base_table_name), e.g. the type-column filter on a polymorphic
+          # source table.
           join.base_where_clauses.each do |where|
             compiled_where_condition = compile_where_condition(where, join.base_table_name)
             sql += " AND #{compiled_where_condition}"
@@ -243,11 +245,20 @@ module Exwiw
           else
             "#{key} IN (#{values.join(', ')})"
           end
+        elsif where_clause.operator == :in_subquery
+          "#{key} IN (#{compile_subquery(where_clause.value)})"
         else
           raise "Unsupported operator: #{where_clause.operator}"
         end
       end
 
+      private def compile_subquery(subquery)
+        inner_values = subquery.where_values.map { |v| escape_value(v) }
+        "SELECT #{subquery.table_name}.#{subquery.select_column} " \
+          "FROM #{subquery.table_name} " \
+          "WHERE #{subquery.table_name}.#{subquery.where_column} IN (#{inner_values.join(', ')})"
+      end
+
       private def escape_value(value)
         case value
         when nil

data/lib/exwiw/adapter/sqlite3_adapter.rb

@@ -125,10 +125,11 @@ module Exwiw
         subquery_sql = compile_ast(subquery_ast)
         sql += "\nWHERE #{select_query_ast.from_table_name}.#{foreign_key} IN (#{subquery_sql})"
 
-        # first_join.base_where_clauses は外側の削除対象テーブル
-        # (from_table_name) 上の条件 (polymorphic 型カラム等)。subquery には
-        # 含まれないため、外側の WHERE に追加する。これにより、別の
-        # polymorphic 型に属する行まで削除してしまうのを防ぐ。
+        # first_join.base_where_clauses holds conditions on the outer
+        # delete-target table (from_table_name), such as a polymorphic type
+        # column. They are not part of the subquery, so add them to the outer
+        # WHERE. This prevents deleting rows that belong to a different
+        # polymorphic type.
         first_join.base_where_clauses.each do |where|
           next unless where.is_a?(Exwiw::QueryAst::WhereClause)
 
@@ -158,8 +159,9 @@ module Exwiw
             sql += " AND #{compiled_where_condition}"
           end
 
-          # base_where_clauses は結合元テーブル (base_table_name) に対して
-          # コンパイルする。polymorphic な結合元テーブルの型カラム絞り込み等。
+          # base_where_clauses is compiled against the joined-from table
+          # (base_table_name), e.g. the type-column filter on a polymorphic
+          # source table.
           join.base_where_clauses.each do |where|
             compiled_where_condition = compile_where_condition(where, join.base_table_name)
             sql += " AND #{compiled_where_condition}"
@@ -188,11 +190,20 @@ module Exwiw
           else
             "#{key} IN (#{values.join(', ')})"
           end
+        elsif where_clause.operator == :in_subquery
+          "#{key} IN (#{compile_subquery(where_clause.value)})"
         else
           raise "Unsupported operator: #{where_clause.operator}"
         end
       end
 
+      private def compile_subquery(subquery)
+        inner_values = subquery.where_values.map { |v| escape_value(v) }
+        "SELECT #{subquery.table_name}.#{subquery.select_column} " \
+          "FROM #{subquery.table_name} " \
+          "WHERE #{subquery.table_name}.#{subquery.where_column} IN (#{inner_values.join(', ')})"
+      end
+
       private def escape_value(value)
         case value
         when nil

data/lib/exwiw/belongs_to.rb

@@ -6,9 +6,10 @@ module Exwiw
 
     attribute :foreign_key, String
     attribute :table_name, String
-    # polymorphic 関連の場合のみ設定される。`foreign_type` は型を格納するカラム名
-    # (例: `reviewable_type`)、`type_value` はそのカラムに入る値 (例: `"Product"`)。
-    # 非 polymorphic の belongs_to では両方とも nil。
+    # Set only for a polymorphic association. `foreign_type` is the name of the
+    # column storing the type (e.g. `reviewable_type`), and `type_value` is the
+    # value held in that column (e.g. `"Product"`). Both are nil for a
+    # non-polymorphic belongs_to.
     attribute :foreign_type, optional(String), skip_serializing_if_nil: true
     attribute :type_value, optional(String), skip_serializing_if_nil: true
 

data/lib/exwiw/cli.rb

@@ -10,7 +10,7 @@ require 'exwiw'
 
 module Exwiw
   class CLI
-    KNOWN_SUBCOMMANDS = %w[dump explain].freeze
+    KNOWN_SUBCOMMANDS = %w[export explain].freeze
 
     def self.start(argv)
       new(argv).run
@@ -23,7 +23,7 @@ module Exwiw
         if !@argv.empty? && !@argv.first.start_with?("-") && KNOWN_SUBCOMMANDS.include?(@argv.first)
           @argv.shift
         else
-          "dump"
+          "export"
         end
 
       @help = @argv.empty?
@@ -40,6 +40,7 @@ module Exwiw
       @target_collection_name = nil
       @ids = []
       @ids_field = nil
+      @ids_column = nil
       @output_format = nil
       @insert_only = nil
       @after_insert_hook_path = nil
@@ -74,7 +75,7 @@ module Exwiw
       logger = build_logger
 
       case @subcommand
-      when "dump"
+      when "export"
         Runner.new(
           connection_config: connection_config,
           output_dir: @output_dir,
@@ -99,6 +100,7 @@ module Exwiw
 
     private def validate_options!
       resolve_target_collection_alias!
+      resolve_ids_column_alias!
 
       if @subcommand == "explain"
         validate_explain_only!
@@ -130,7 +132,7 @@ module Exwiw
         exit 1
       end
 
-      if @subcommand == "dump"
+      if @subcommand == "export"
         @output_dir ||= "dump"
         @output_format ||= "insert"
         @insert_only = @insert_only ? true : false
@@ -172,23 +174,6 @@ module Exwiw
         exit 1
       end
 
-      if @ids_field
-        # --ids-field overrides the field --ids filters against on the target
-        # table; it is meaningless without a target table to constrain.
-        if !@target_table_name
-          $stderr.puts "--target-table is required when --ids-field is specified"
-          exit 1
-        end
-
-        # TODO: support --ids-field for the sql adapters (mysql2/postgresql/
-        # sqlite3) by threading dump_target.ids_field through QueryAstBuilder's
-        # WHERE clause on the target table. For now it is mongodb-only.
-        if @database_adapter != "mongodb"
-          $stderr.puts "--ids-field is currently only supported by the mongodb adapter"
-          exit 1
-        end
-      end
-
       if @after_insert_hook_path
         unless File.file?(@after_insert_hook_path)
           $stderr.puts "--after-insert-hook file not found: #{@after_insert_hook_path}"
@@ -223,6 +208,43 @@ module Exwiw
       @target_table_name = @target_collection_name
     end
 
+    # `--ids-column` is the sql-adapter spelling of `--ids-field` (the mongodb
+    # spelling). Both override which column/field `--ids` is matched against on
+    # the target table; internally they fold into the single @ids_field carried
+    # by DumpTarget. Mirror the --target-table/--target-collection split: each
+    # flag is restricted to its adapter family and the two are mutually
+    # exclusive. Runs after resolve_target_collection_alias! so
+    # @target_table_name already reflects the collection alias.
+    private def resolve_ids_column_alias!
+      if @ids_field && @ids_column
+        $stderr.puts "Specify only one of --ids-field and --ids-column"
+        exit 1
+      end
+
+      if @ids_field && @database_adapter != "mongodb"
+        $stderr.puts "--ids-field is only supported by the mongodb adapter (use --ids-column)"
+        exit 1
+      end
+
+      if @ids_column
+        sql_adapters = ["mysql2", "postgresql", "sqlite3"]
+        unless sql_adapters.include?(@database_adapter)
+          $stderr.puts "--ids-column is only supported by the sql adapters (use --ids-field)"
+          exit 1
+        end
+
+        @ids_field = @ids_column
+      end
+
+      # --ids-field/--ids-column override the column --ids filters against on
+      # the target table; meaningless without a target table to constrain.
+      if @ids_field && !@target_table_name
+        flag = @ids_column ? "--ids-column" : "--ids-field"
+        $stderr.puts "--target-table is required when #{flag} is specified"
+        exit 1
+      end
+    end
+
     private def validate_explain_only!
       if @database_adapter == "mongodb"
         $stderr.puts "mongodb adapter is not yet supported by 'explain' subcommand"
@@ -284,7 +306,7 @@ module Exwiw
           Usage: exwiw [SUBCOMMAND] [options]
 
           Subcommands:
-            dump      Generate INSERT/COPY SQL files (default when omitted).
+            export    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
@@ -293,7 +315,7 @@ module Exwiw
         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/ (dump subcommand only)") do |v|
+        opts.on("-o", "--output-dir=[DUMP_DIR_PATH]", "Output file path. default is dump/ (export subcommand only)") do |v|
           v = v.end_with?("/") ? v[0..-2] : v
           @output_dir = File.expand_path(v)
         end
@@ -306,10 +328,11 @@ module Exwiw
         opts.on("--target-table=[TABLE]", "Target table for extraction. If omitted, dump all tables.") { |v| @target_table_name = v }
         opts.on("--target-collection=[COLLECTION]", "Alias of --target-table for the mongodb adapter.") { |v| @target_collection_name = v }
         opts.on("--ids=[IDS]", "Comma-separated list of identifiers. Required when --target-table is given.") { |v| @ids = v.split(',') }
-        opts.on("--ids-field=[FIELD]", "Field on the target table that --ids is matched against. Defaults to the primary key. (mongodb adapter only)") { |v| @ids_field = 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|
+        opts.on("--ids-field=[FIELD]", "Field on the target collection that --ids is matched against. Defaults to the primary key. (mongodb adapter only)") { |v| @ids_field = v }
+        opts.on("--ids-column=[COLUMN]", "Column on the target table that --ids is matched against. Defaults to the primary key. (sql adapters only)") { |v| @ids_column = v }
+        opts.on("--output-format=[FORMAT]", "Output format: insert (default) or copy (PostgreSQL only, export subcommand only)") { |v| @output_format = v }
+        opts.on("--insert-only", "Do not generate DELETE SQL files (export 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 (export 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/mongoid_schema_generator.rb

@@ -159,11 +159,13 @@ module Exwiw
         end
       end
 
-      # polymorphic belongs_to (`belongs_to :reviewable, polymorphic: true`) は
-      # 単一の対象コレクションを持たないため現状未対応。誤った FK を出力しないよう
-      # ここでは除外する (将来 ActiveRecord 版と同様に展開する余地を残す)。
+      # A polymorphic belongs_to (`belongs_to :reviewable, polymorphic: true`)
+      # has no single target collection, so it is not supported yet. Exclude it
+      # here to avoid emitting an incorrect FK (leaving room to expand it later,
+      # like the ActiveRecord version does).
       #
-      # 継承階層では基底クラスとサブクラスが同じ belongs_to を二重に持つため uniq する。
+      # In an inheritance hierarchy the base class and its subclasses carry the
+      # same belongs_to twice, so uniq them.
       belongs_to_assocs
         .reject(&:polymorphic?)
         .map { |assoc| { table_name: assoc.klass.collection_name.to_s, foreign_key: assoc.foreign_key } }

data/lib/exwiw/query_ast.rb

@@ -3,11 +3,11 @@
 module Exwiw
   module QueryAst
     class JoinClause
-      # `where_clauses` はこの join の join_table_name (= 結合先テーブル) に対して
-      # コンパイルされる。一方 `base_where_clauses` は base_table_name (= 結合元
-      # テーブル) に対してコンパイルされる。後者は、結合元テーブルが結合先へ
-      # polymorphic belongs_to していて型カラム (foreign_type) が結合元テーブル
-      # 側に存在するケースのために使う。
+      # `where_clauses` is compiled against this join's join_table_name (the
+      # joined-to table). `base_where_clauses`, on the other hand, is compiled
+      # against base_table_name (the joined-from table). The latter is used for
+      # the case where the source table polymorphically belongs_to the joined-to
+      # table and the type column (foreign_type) lives on the source table.
       attr_reader :base_table_name, :foreign_key, :join_table_name, :primary_key, :where_clauses, :base_where_clauses
 
       def initialize(base_table_name:, foreign_key:, join_table_name:, primary_key:, where_clauses: [], base_where_clauses: [])
@@ -41,7 +41,26 @@ module Exwiw
         {
           column_name: column_name,
           operator: operator,
-          value: value,
+          value: value.is_a?(Subquery) ? value.to_h : value,
+        }
+      end
+    end
+
+    # Resolves a set of values on `where_column` to the rows' `select_column`
+    # via a nested SELECT. Used as the `value` of a WhereClause whose operator
+    # is `:in_subquery`, so `--ids-column`/`--ids-field` can filter related
+    # tables through the target table's primary key:
+    #
+    #   <table>.<fk> IN (SELECT <table_name>.<select_column>
+    #                    FROM <table_name>
+    #                    WHERE <table_name>.<where_column> IN (<where_values>))
+    Subquery = Struct.new(:table_name, :select_column, :where_column, :where_values, keyword_init: true) do
+      def to_h
+        {
+          table_name: table_name,
+          select_column: select_column,
+          where_column: where_column,
+          where_values: where_values,
         }
       end
     end

data/lib/exwiw/query_ast_builder.rb

@@ -58,12 +58,12 @@ module Exwiw
           base_where_clauses: []
         )
 
-        # この hop 自体が polymorphic belongs_to の場合 (例: comments が
-        # commentable として posts へ polymorphic belongs_to)、型カラム
-        # (foreign_type) は結合元テーブル (from_table = base_table_name) 側に
-        # 存在する。外部キーだけでは reviewable_id=1 のような値が別モデルの
-        # 行と衝突しうるため、base_where_clauses に型条件を追加して結合元
-        # テーブルを絞り込む。
+        # When this hop itself is a polymorphic belongs_to (e.g. comments
+        # polymorphically belongs_to posts as commentable), the type column
+        # (foreign_type) lives on the source table (from_table = base_table_name).
+        # The foreign key alone is not enough — a value like reviewable_id=1 can
+        # collide with rows of another model — so add the type condition to
+        # base_where_clauses to narrow down the source table.
         if relation.polymorphic?
           join_clause.base_where_clauses.push QueryAst::WhereClause.new(
             column_name: relation.foreign_type,
@@ -73,16 +73,13 @@ module Exwiw
         end
         relation_to_dump_target = to_table.belongs_to(dump_target.table_name)
         if relation_to_dump_target
-          join_clause.where_clauses.push QueryAst::WhereClause.new(
-            column_name: relation_to_dump_target.foreign_key,
-            operator: :eq,
-            value: dump_target.ids
-          )
+          join_clause.where_clauses.push dump_target_fk_clause(relation_to_dump_target.foreign_key)
 
-          # 中間テーブルが dump target へ polymorphic belongs_to している場合は、
-          # 型カラム (foreign_type) も join 条件に追加する。型カラムは to_table
-          # (= join_table_name) 上に存在するため、JoinClause の where_clauses が
-          # join_table_name に対してコンパイルされる仕組みにそのまま乗せられる。
+          # When the intermediate table polymorphically belongs_to the dump
+          # target, also add the type column (foreign_type) to the join
+          # condition. The type column lives on to_table (= join_table_name), so
+          # it rides on the existing mechanism where a JoinClause's where_clauses
+          # are compiled against join_table_name.
           if relation_to_dump_target.polymorphic?
             join_clause.where_clauses.push QueryAst::WhereClause.new(
               column_name: relation_to_dump_target.foreign_type,
@@ -107,12 +104,12 @@ module Exwiw
       clauses = []
 
       if table.name == dump_target.table_name
-        # TODO: honor dump_target.ids_field here so `--ids` can match a non
-        # primary-key column on the target table (currently mongodb-only; the
-        # CLI rejects --ids-field for the sql adapters). When implemented, use
-        # `dump_target.ids_field || table.primary_key` as the column_name.
+        # `--ids-column` (folded into dump_target.ids_field by the CLI) lets
+        # `--ids` match a non primary-key column on the target table; otherwise
+        # fall back to the primary key. Only the target table's filter changes —
+        # downstream foreign-key propagation still keys off the primary key.
         clauses.push Exwiw::QueryAst::WhereClause.new(
-          column_name: table.primary_key,
+          column_name: dump_target.ids_field || table.primary_key,
           operator: :eq,
           value: dump_target.ids
         )
@@ -123,15 +120,11 @@ module Exwiw
       belongs_to = table.belongs_to(dump_target.table_name)
       return clauses if belongs_to.nil?
 
-      clauses.push Exwiw::QueryAst::WhereClause.new(
-        column_name: belongs_to.foreign_key,
-        operator: :eq,
-        value: dump_target.ids
-      )
+      clauses.push dump_target_fk_clause(belongs_to.foreign_key)
 
-      # polymorphic belongs_to の場合は外部キーだけでは型を区別できないため
-      # (例: reviewable_id=1 が Product なのか別モデルなのか判別できない)、
-      # 型カラム (foreign_type) を type_value で絞り込む条件を追加する。
+      # For a polymorphic belongs_to the foreign key alone cannot distinguish the
+      # type (e.g. reviewable_id=1 could be a Product or another model), so add a
+      # condition filtering the type column (foreign_type) by type_value.
       if belongs_to.polymorphic?
         clauses.push Exwiw::QueryAst::WhereClause.new(
           column_name: belongs_to.foreign_type,
@@ -147,6 +140,36 @@ module Exwiw
       clauses
     end
 
+    # Builds the WHERE clause that constrains a `foreign_key` pointing at the
+    # dump target. Normally `--ids` are the target's primary keys, so a plain
+    # `foreign_key IN (ids)` suffices. When `--ids-column`/`--ids-field` is set
+    # (dump_target.ids_field), `--ids` match a non primary-key column instead,
+    # so the foreign key must be resolved through the target table:
+    # `foreign_key IN (SELECT pk FROM target WHERE ids_field IN (ids))`.
+    # This keeps related-table extraction correct regardless of whether the
+    # relation is direct, indirect, or polymorphic.
+    private def dump_target_fk_clause(foreign_key)
+      unless dump_target.ids_field
+        return Exwiw::QueryAst::WhereClause.new(
+          column_name: foreign_key,
+          operator: :eq,
+          value: dump_target.ids
+        )
+      end
+
+      target = table_by_name.fetch(dump_target.table_name)
+      Exwiw::QueryAst::WhereClause.new(
+        column_name: foreign_key,
+        operator: :in_subquery,
+        value: Exwiw::QueryAst::Subquery.new(
+          table_name: target.name,
+          select_column: target.primary_key,
+          where_column: dump_target.ids_field,
+          where_values: dump_target.ids
+        )
+      )
+    end
+
     private def find_path_to_dump_target(table, table_by_name, dump_target)
       return [] if table.name == dump_target.table_name
 

data/lib/exwiw/schema_generator.rb

@@ -78,11 +78,12 @@ module Exwiw
         representative = model_group.first
         primary_key = representative.primary_key
 
-        # 複合主キー (`representative.primary_key` が Array) のテーブルは現状未対応。
-        # primary_key を省略し、type で非対応である旨を明示したうえで skip:true を
-        # 付与して出力する。type を付けておくことで将来対応する際の目印になる。
-        # 利用者が必要に応じて手動で skip を外して設定し直せるよう、設定ファイル
-        # 自体は生成しておく。
+        # Tables with a composite primary key (`representative.primary_key` is an
+        # Array) are not supported yet. Emit them with `primary_key` omitted,
+        # `skip: true`, and a `type` that marks them as unsupported — the `type`
+        # acts as a signpost for adding support later. The config file itself is
+        # still generated so a user can manually remove `skip` and wire it up when
+        # needed.
         if primary_key.is_a?(Array)
           TableConfig.from_symbol_keys(
             name: table_name,
@@ -110,12 +111,13 @@ module Exwiw
       @models.reject(&:abstract_class?).select(&:table_exists?)
     end
 
-    # rails-managed テーブル (`schema_migrations` / `ar_internal_metadata`) は
-    # モデルクラスを持たないため `ActiveRecord::Base.descendants` からは拾えない。
-    # multi-DB 構成では各 connection が独立した migration 履歴テーブルを持つので、
-    # 対象 connection を受け取り、その connection 上に該当テーブルが存在する場合のみ
-    # エントリを生成する。テーブル名そのものは prefix/suffix を含むグローバル設定
-    # (`ActiveRecord::Base.schema_migrations_table_name` 等) から得る。
+    # The rails-managed tables (`schema_migrations` / `ar_internal_metadata`)
+    # have no model class, so they cannot be picked up from
+    # `ActiveRecord::Base.descendants`. In a multi-DB setup each connection has
+    # its own migration history table, so we take the target connection and only
+    # emit an entry when the table actually exists on that connection. The table
+    # name itself (including any prefix/suffix) comes from the global settings
+    # (`ActiveRecord::Base.schema_migrations_table_name`, etc.).
     private def build_rails_managed_tables(conn)
       result = []
 
@@ -151,11 +153,11 @@ module Exwiw
         .reject(&:polymorphic?)
         .map { |assoc| { table_name: assoc.table_name, foreign_key: assoc.foreign_key } }
 
-      # polymorphic な belongs_to (`belongs_to :reviewable, polymorphic: true`) は
-      # 単一の対象テーブルを持たない。対象になりうるテーブルは、他モデルで
-      # `has_many/has_one ..., as: <association_name>` と宣言されている側から逆引き
-      # する。各候補テーブルごとに、型カラム (`foreign_type`) と格納される型の値
-      # (`type_value`) を添えた belongs_to を 1 件ずつ展開する。
+      # A polymorphic belongs_to (`belongs_to :reviewable, polymorphic: true`)
+      # has no single target table. The candidate tables are found by looking up
+      # the other models that declare `has_many/has_one ..., as: <association_name>`.
+      # For each candidate table, expand one belongs_to entry carrying the type
+      # column (`foreign_type`) and the stored type value (`type_value`).
       polymorphic = belongs_to_assocs
         .select(&:polymorphic?)
         .flat_map do |assoc|
@@ -172,11 +174,12 @@ module Exwiw
       (non_polymorphic + polymorphic).uniq
     end
 
-    # polymorphic 関連 `association_name` の対象となりうる具象モデルを、全モデルの
-    # `has_many` / `has_one` の `as:` オプションから逆引きして列挙する。
-    # `concrete_models` の並びは `ActiveRecord::Base.descendants` の順に依存し、
-    # Ruby バージョンによって変わりうるため、生成される belongs_to の並びが安定する
-    # よう `table_name` でソートして決定的に返す。
+    # Enumerate the concrete models that can be targets of the polymorphic
+    # association `association_name`, by looking them up from every model's
+    # `has_many` / `has_one` `as:` option. The order of `concrete_models` depends
+    # on `ActiveRecord::Base.descendants`, which can vary by Ruby version, so sort
+    # by `table_name` to return a deterministic order and keep the generated
+    # belongs_to ordering stable.
     private def polymorphic_target_models(association_name)
       concrete_models.select do |model|
         (model.reflect_on_all_associations(:has_many) +

data/lib/exwiw/table_config.rb

@@ -11,9 +11,10 @@ module Exwiw
       RAILS_MANAGED_INTERNAL_METADATA,
     ].freeze
 
-    # exwiw が現状サポートしていない複合主キーのテーブルを表す type。
-    # schema:generate が skip:true と併せて付与する。将来サポートする際の
-    # 目印になるよう、rails-managed とは異なり columns/belongs_tos は保持する。
+    # type marking a table with a composite primary key, which exwiw does not
+    # support yet. schema:generate attaches it together with skip:true. Unlike
+    # rails-managed tables, columns/belongs_tos are retained so it can serve as a
+    # signpost for adding support later.
     UNSUPPORTED_COMPOSITE_PRIMARY_KEY = "unsupported_composite_primary_key"
 
     attribute :name, String
@@ -143,8 +144,8 @@ module Exwiw
                 "Table '#{name}' has type=#{type}; columns must not be defined."
         end
       else
-        # skip:true のテーブルはデータ抽出を行わないため primary_key を要求しない。
-        # (例: exwiw 非対応の複合主キーテーブル)
+        # A skip:true table is not extracted, so primary_key is not required
+        # (e.g. a composite-primary-key table that exwiw does not support).
         if primary_key.nil? && !skip
           raise ArgumentError, "Table '#{name}' requires primary_key."
         end

data/lib/exwiw/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exwiw
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.3.1
 platform: ruby
 authors:
 - Shia
@@ -40,6 +40,7 @@ files:
 - docs/plans/2026-05-22-after-insert-hook.md
 - docs/plans/2026-05-22-postgres-copy-mode-scenario-test.md
 - docs/plans/2026-05-29-rails-managed-tables.md
+- docs/plans/2026-05-31-ids-column-for-sql-adapters.md
 - exe/exwiw
 - lib/exwiw.rb
 - lib/exwiw/adapter.rb