exwiw 0.2.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21a9432692220a23b0109497b0ffcb3f1c7f0fc360248c3590f730a4a98452ec
-  data.tar.gz: bf0847f90a24c8da3cf078f1c18e5d22f9827b705bc13945ddfc28f8e42460f1
+  metadata.gz: e62483afc43054ae026c232502f40f6c1a92381a9c2c833ef1f7d603f6b845ae
+  data.tar.gz: 660a006272b9156bbc98af2a0c288f7943bdd40523adffc45de713b36a5d0426
 SHA512:
-  metadata.gz: c59e201f1180e2fb6191506647b78a82c43d7d124117c0d87e2cdcbfd8fa68ff30653accc9a22d82434d7e680496eed41d91c7b150b8b884b3b545b344b91d72
-  data.tar.gz: 600e4a3b8d134d43182b81017b8b4ad9a352824a76a351300ca3fc22ee4942ceccf6f8404eb6e04e2a2320a79849ddc6b3cacf0c3510c7b8acca0c06820eaa22
+  metadata.gz: 988813923c5e8a2aa1fd499c3af3a2d5467fc9a77b60664b1cd8d245ed1837a1cf43dc88a872bbbcfb7951902624e6b61fb50d290af6716a06c1fe8bb376ae6a
+  data.tar.gz: d8f751b794c20658c643ab2aeca769b01f7b50e9acc46c9605a4d7121d0d5fa8041bfbdad8021ede6bbfefc8cb36a937509120f25b7bdd059aaf6989f4c94e00

data/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-31
+
+## [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 `--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).
+
+### Fixed
+
+- MongoDB adapter: `--ids` filtering against an `ObjectId` `_id` now works. `--ids` arrives as text and MongoDB compares types strictly, so a 24-char hex id is coerced to `BSON::ObjectId` (a plain String would never match). Integer-looking ids are still coerced to `Integer` and other strings (e.g. a String/UUID `_id`) are left as-is. This makes the `MongoidSchemaGenerator`-emitted `"primary_key": "_id"` configs usable end-to-end for the common case where `_id` is Mongoid's default `ObjectId`.
+
 ## [0.2.8] - 2026-05-31
 
 ### Added

data/README.md

@@ -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
@@ -148,6 +150,25 @@ Each database keeps its own Rails migration history, so a `schema_migrations` (a
 
 - The rails-managed table *names* are resolved from the global `ActiveRecord::Base.schema_migrations_table_name` / `internal_metadata_table_name` accessors, which are shared across all connections. A per-database override of these names is not detected, so such a table will be missing from that database's generated configs.
 
+#### Mongoid applications
+
+For MongoDB applications backed by [Mongoid](https://www.mongodb.com/docs/mongoid/), a separate rake task introspects Mongoid document models and emits `MongodbCollectionConfig` files (the `fields` / `_id` / `embedded_in` shape described under [MongoDB notes](#mongodb-notes)):
+
+```bash
+bundle exec rake exwiw:schema:generate_mongoid
+```
+
+It is a distinct task and class (`Exwiw::MongoidSchemaGenerator`) from the ActiveRecord generator because the two ORMs expose entirely different metadata. From each model it derives:
+
+- the collection name and the `_id` primary key,
+- `fields` from the declared Mongoid fields (referenced `belongs_to` foreign keys such as `shop_id`, and the `created_at` / `updated_at` columns added by `Mongoid::Timestamps`, are ordinary fields — their BSON `ObjectId` / `Date` values serialize as MongoDB Extended JSON at dump time). For an aliased field (`field :ctry, as: :country`), the generator emits the **stored** document key (`ctry`), never the Ruby accessor (`country`), so masking and projection target the key that actually appears in the document, and additionally records the accessor as `mongoid_field_name` on that field so the 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),
+- `belongs_tos` from referenced `belongs_to` associations (`{ table_name, foreign_key }`). A referenced `belongs_to` declared on an *embedded* document is dropped (cross-collection refs from inside embedded subdocuments are unsupported — see [MongoDB notes](#mongodb-notes)), but its foreign-key column is still kept as an ordinary field. A `has_and_belongs_to_many` association is also dropped (its foreign keys are stored as an array field, e.g. `tag_ids`, which exwiw cannot follow as a single-valued foreign key), while that `*_ids` array column is kept as an ordinary field,
+- `embedded_in` from `embedded_in` / `embeds_many` / `embeds_one` associations. Each embedded config names its *immediate* parent collection and the document key it lives under (`store_as`, defaulting to the relation name); nested embedding is represented as a chain (`comments` → `embedded_in` `posts`, `posts` → `embedded_in` `users`) rather than a flattened dot-path, matching how the adapter recurses through array and Hash subdocuments. A *polymorphic* `embedded_in` (`embedded_in :addressable, polymorphic: true`) has no single embedding parent collection and so cannot be expressed as an `embedded_in` config; the generator raises a clear error pointing you to define that collection's config by hand. A *self-referential / cyclic* embedding (Mongoid's `recursively_embeds_many` / `recursively_embeds_one`) makes a collection both a top-level document and embedded inside documents of its own type; exwiw represents a collection as either top-level or embedded, not both, so the generator likewise raises a clear error rather than emit a config that would silently make the collection undumpable.
+
+Models in an inheritance hierarchy whose subclasses share the base's collection (Mongoid STI, distinguished by the auto-added `_type` discriminator) collapse into a single config: the generator discovers the subclasses via `descendants` (Mongoid registers only the base class in `Mongoid.models`) and unions every class's `fields` and `belongs_tos` into the collection config, so subclass-only fields and associations are not lost.
+
+Regeneration preserves hand-edited `replace_with`, `filter`, `skip`, and `bulk_insert_chunk_size` values, like the ActiveRecord generator. Indexes are not written to the config — they are introspected from the live database at dump time (see [MongoDB notes](#mongodb-notes)). Polymorphic `belongs_to` is not yet expanded by this task.
+
 ### Configuration
 
 This is an example of the one table schema:
@@ -391,6 +412,9 @@ The MongoDB adapter is experimental. To use it:
 - Add `gem "mongo"` to your Gemfile in addition to `exwiw` (it is not declared as a runtime dependency of the gem).
 - Set `--adapter=mongodb`. `--user` / `DATABASE_PASSWORD` are optional and only needed when your MongoDB requires authentication.
 - 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 **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/mongodb_adapter.rb

@@ -47,7 +47,22 @@ module Exwiw
 
         filter =
           if config.name == dump_target.table_name
-            { config.primary_key => { "$in" => coerce_ids(dump_target.ids) } }
+            # `--ids-field` may override which field --ids is matched against;
+            # otherwise fall back to the primary key. Note this only changes the
+            # WHERE filter on the target collection — downstream foreign-key
+            # propagation still keys off `primary_key` (see #execute, which
+            # stashes doc[primary_key] into @state).
+            #
+            # Type coercion is only applied to the primary key (`_id`), whose
+            # stored type we know (Mongoid's default ObjectId). For a custom
+            # `ids_field` the stored type is unknown, so the textual --ids are
+            # left as Strings rather than guessed at — the caller passes values
+            # matching the field's actual type.
+            if dump_target.ids_field
+              { dump_target.ids_field => { "$in" => dump_target.ids } }
+            else
+              { config.primary_key => { "$in" => coerce_ids(dump_target.ids) } }
+            end
           else
             constrained = config.belongs_tos.select do |relation|
               @state.key?(relation.table_name) && !@state[relation.table_name].empty?
@@ -155,18 +170,42 @@ module Exwiw
       end
 
       # `--ids` from the CLI arrives as Strings. Mongo compares types strictly,
-      # so integer-looking ids are coerced to Integer. Other strings (e.g. ObjectId
-      # hex) are left as-is.
+      # so the textual ids must be coerced to the type actually stored in `_id`:
+      #
+      # - integer-looking ids -> Integer
+      # - 24-char hex ids -> BSON::ObjectId (Mongoid's default `_id` type; a
+      #   plain String would never match an ObjectId in a `$in` filter)
+      # - anything else (e.g. a String/UUID `_id`) is left as-is
+      #
+      # Only used for the primary-key filter; a custom `--ids-field` skips this
+      # because its stored type is unknown (see build_query).
       private def coerce_ids(ids)
-        Array(ids).map do |id|
-          if id.is_a?(String) && id.match?(/\A-?\d+\z/)
-            id.to_i
-          else
-            id
-          end
+        Array(ids).map { |id| coerce_id(id) }
+      end
+
+      private def coerce_id(id)
+        return id unless id.is_a?(String)
+
+        if id.match?(/\A-?\d+\z/)
+          id.to_i
+        elsif object_id_hex?(id)
+          BSON::ObjectId.from_string(id)
+        else
+          id
         end
       end
 
+      # True when `str` is a canonical 24-char hex ObjectId. `bson` ships with
+      # `mongo`/`mongoid` but may not be loaded yet when build_query runs before
+      # any db access, so require it lazily; if it is genuinely unavailable we
+      # fall back to leaving the id as a String.
+      private def object_id_hex?(str)
+        require 'bson' unless defined?(::BSON::ObjectId)
+        ::BSON::ObjectId.legal?(str)
+      rescue LoadError
+        false
+      end
+
       private def reject_filter!(config)
         return if config.filter.nil? || config.filter.to_s.empty?
 

data/lib/exwiw/adapter/mysql2_adapter.rb

@@ -201,11 +201,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

@@ -243,11 +243,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

@@ -188,11 +188,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/cli.rb

@@ -37,7 +37,10 @@ module Exwiw
       @database_adapter = nil
       @database_name = nil
       @target_table_name = nil
+      @target_collection_name = nil
       @ids = []
+      @ids_field = nil
+      @ids_column = nil
       @output_format = nil
       @insert_only = nil
       @after_insert_hook_path = nil
@@ -66,6 +69,7 @@ module Exwiw
       dump_target = DumpTarget.new(
         table_name: @target_table_name,
         ids: @ids,
+        ids_field: @ids_field,
       )
 
       logger = build_logger
@@ -95,6 +99,9 @@ module Exwiw
     end
 
     private def validate_options!
+      resolve_target_collection_alias!
+      resolve_ids_column_alias!
+
       if @subcommand == "explain"
         validate_explain_only!
       end
@@ -181,6 +188,63 @@ module Exwiw
       end
     end
 
+    # `--target-collection` is a mongodb-only alias of `--target-table`. Fold it
+    # into @target_table_name (the single field the rest of the CLI/runner uses)
+    # after rejecting the misuses: combining it with --target-table, or using it
+    # with a non-mongodb adapter.
+    private def resolve_target_collection_alias!
+      return if @target_collection_name.nil?
+
+      if @target_table_name
+        $stderr.puts "Specify only one of --target-table and --target-collection"
+        exit 1
+      end
+
+      if @database_adapter != "mongodb"
+        $stderr.puts "--target-collection is only supported by the mongodb adapter (use --target-table)"
+        exit 1
+      end
+
+      @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"
@@ -211,6 +275,7 @@ module Exwiw
         database_name: @database_name,
         target_table: @target_table_name,
         ids: @ids.dup.freeze,
+        ids_field: @ids_field,
         output_format: @output_format,
         insert_only: @insert_only,
         log_level: @log_level,
@@ -261,7 +326,10 @@ module Exwiw
         opts.on("-a", "--adapter=ADAPTER", "Database adapter") { |v| @database_adapter = v }
         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("--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 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, 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|

data/lib/exwiw/mongodb_collection_config.rb

@@ -35,6 +35,39 @@ module Exwiw
       !embedded_in.nil?
     end
 
+    # Merge an auto-generated config (`passed`) into this user-maintained one so
+    # that `MongoidSchemaGenerator` regenerations preserve hand-edited values.
+    #
+    # - structural facts come from the freshly generated config: primary_key,
+    #   belongs_tos, embedded_in.
+    # - user customizations are kept from the receiver: filter, skip,
+    #   bulk_insert_chunk_size, and each field's `replace_with` masking rule.
+    # - generated fields drive the field list (so added/removed fields track the
+    #   model), but a matching receiver field wins to retain its masking.
+    def merge(passed)
+      return passed if passed.to_hash == to_hash
+
+      MongodbCollectionConfig.new.tap do |merged|
+        merged.name = name
+        merged.primary_key = passed.primary_key
+        merged.filter = filter
+        merged.belongs_tos = passed.belongs_tos
+        merged.bulk_insert_chunk_size = bulk_insert_chunk_size
+        merged.skip = skip
+        merged.embedded_in = passed.embedded_in
+
+        # Take each field from the freshly generated config (so structural facts
+        # like `mongoid_field_name` track the model) but carry over the user's
+        # hand-edited `replace_with` masking when the field still exists.
+        receiver_field_by_name = fields.each_with_object({}) { |f, h| h[f.name] = f }
+        merged.fields = passed.fields.map do |pf|
+          receiver = receiver_field_by_name[pf.name]
+          pf.replace_with = receiver.replace_with if receiver&.replace_with
+          pf
+        end
+      end
+    end
+
     private def validate_embedded!
       return unless embedded?
       return if belongs_tos.empty?

data/lib/exwiw/mongodb_field.rb

@@ -6,6 +6,11 @@ module Exwiw
 
     attribute :name, String
     attribute :replace_with, optional(String), skip_serializing_if_nil: true
+    # The Mongoid model's Ruby accessor when the stored document key (`name`)
+    # was renamed via `field :ctry, as: :country`. Purely informational — exwiw
+    # masks/projects by `name` (the storage key) — but surfacing the accessor
+    # keeps an otherwise cryptic short key understandable in the config.
+    attribute :mongoid_field_name, optional(String), skip_serializing_if_nil: true
 
     def self.from_symbol_keys(hash)
       from(hash.transform_keys(&:to_s))

data/lib/exwiw/mongoid_schema_generator.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Exwiw
+  # Generates exwiw `MongodbCollectionConfig` files by introspecting Mongoid
+  # document models. This is the MongoDB/Mongoid counterpart of
+  # `SchemaGenerator` (which targets ActiveRecord); it is intentionally a
+  # separate class and rake task because the two ORMs expose entirely
+  # different metadata APIs.
+  #
+  # Introspection relies only on class-level Mongoid metadata
+  # (`fields`, `relations`, `collection_name`), so it does not require a live
+  # MongoDB connection.
+  class MongoidSchemaGenerator
+    def self.from_rails_application(output_dir:)
+      Rails.application.eager_load!
+      new(models: ::Mongoid.models, output_dir: output_dir)
+    end
+
+    def initialize(models:, output_dir:)
+      @models = models
+      @output_dir = output_dir
+    end
+
+    def generate!
+      collections = build_collections
+      write_files(@output_dir, collections)
+      collections
+    end
+
+    # Returns an array of `MongodbCollectionConfig`, one per *collection*
+    # (top-level collections and embedded subdocument configs alike).
+    #
+    # Models are grouped by `collection_name` so an inheritance hierarchy whose
+    # subclasses share the base's collection (Mongoid STI, discriminated by the
+    # auto-added `_type` field) collapses into a single config that aggregates
+    # every class's fields and associations. See `expand_with_descendants`.
+    def build_collections
+      models = expand_with_descendants(concrete_models)
+      models
+        .group_by { |model| model.collection_name.to_s }
+        .map { |collection_name, group| build_collection_for(collection_name, group) }
+    end
+
+    def write_files(dir, collections)
+      FileUtils.mkdir_p(dir)
+
+      collections.each do |collection|
+        path = File.join(dir, "#{collection.name}.json")
+        config_to_write =
+          if File.exist?(path)
+            MongodbCollectionConfig.from(JSON.parse(File.read(path))).merge(collection)
+          else
+            collection
+          end
+        File.write(path, JSON.pretty_generate(config_to_write.to_hash) + "\n")
+      end
+    end
+
+    # Builds one config for the collection shared by `models` (usually a single
+    # model, but an inheritance hierarchy contributes several). Fields and
+    # belongs_tos are unioned across the group; processing least-derived first
+    # keeps the base's fields leading the list and the output deterministic
+    # regardless of input order or sibling subclasses.
+    private def build_collection_for(collection_name, models)
+      ordered = models.sort_by { |model| [model.fields.size, model.name] }
+
+      attrs = {
+        name: collection_name,
+        primary_key: "_id",
+        fields: aggregate_fields(ordered),
+      }
+
+      if ordered.any?(&:embedded?)
+        # Cross-collection references from inside an embedded array are not
+        # supported (MongodbCollectionConfig rejects them), so embedded configs
+        # always carry an empty belongs_tos and instead declare where they live.
+        attrs[:belongs_tos] = []
+        attrs[:embedded_in] = embedded_in_for(ordered.find(&:embedded?))
+      else
+        attrs[:belongs_tos] = aggregate_belongs_tos(ordered)
+      end
+
+      MongodbCollectionConfig.from_symbol_keys(attrs)
+    end
+
+    # Mongoid registers only the base class of an inheritance hierarchy in
+    # `Mongoid.models`; subclasses that store into the base's collection
+    # (STI-style, distinguished by the auto-added `_type` discriminator) are
+    # reachable only via `descendants`, and the base's own metadata does NOT
+    # include subclass-only fields or associations. Expand the model set with
+    # descendants so each collection's config aggregates every class that
+    # stores into it. (A subclass that overrides `store_in` to a different
+    # collection naturally falls into its own group via the `collection_name`
+    # grouping in `build_collections`.)
+    private def expand_with_descendants(models)
+      concrete((models + models.flat_map(&:descendants)).uniq)
+    end
+
+    # Mongoid registers internal helper classes (e.g. the discriminator key
+    # host) in `Mongoid.models`; those have no usable `collection_name`. Keep
+    # only application documents.
+    private def concrete_models
+      concrete(@models)
+    end
+
+    private def concrete(models)
+      models.select do |model|
+        model.respond_to?(:collection_name) &&
+          model.name &&
+          !model.name.start_with?("Mongoid::")
+      end
+    end
+
+    # Unions the declared field names across `models`, preserving first-seen
+    # order. A subclass's `fields` already includes everything it inherits, so
+    # the base's fields lead and each subclass appends only its own.
+    private def aggregate_fields(models)
+      seen = {}
+      models.each_with_object([]) do |model, fields|
+        accessor_by_storage = aliased_field_accessors(model)
+        model.fields.keys.each do |name|
+          next if seen[name]
+
+          seen[name] = true
+          field = { name: name }
+          # When `field :ctry, as: :country` renamed the storage key, surface the
+          # Ruby accessor so the short key is not cryptic in the config.
+          accessor = accessor_by_storage[name]
+          field[:mongoid_field_name] = accessor if accessor
+          fields << field
+        end
+      end
+    end
+
+    # Maps a stored document key -> its Mongoid Ruby accessor, but ONLY for
+    # genuine `field ..., as:` renames. `Model.aliased_fields` also contains the
+    # built-in `id => _id` and one entry per association (e.g. `shop => shop_id`,
+    # `profile => user_profile`); those are not field renames, so exclude any
+    # accessor that names a relation, the `_id` storage key, or a no-op alias.
+    private def aliased_field_accessors(model)
+      relation_names = model.relations.keys
+      model.aliased_fields.each_with_object({}) do |(accessor, storage), acc|
+        next if accessor == storage
+        next if storage == "_id"
+        next if relation_names.include?(accessor)
+        next unless model.fields.key?(storage)
+
+        acc[storage] = accessor
+      end
+    end
+
+    private def aggregate_belongs_tos(models)
+      belongs_to_assocs = models.flat_map do |model|
+        model.relations.values.select do |assoc|
+          assoc.is_a?(::Mongoid::Association::Referenced::BelongsTo)
+        end
+      end
+
+      # polymorphic belongs_to (`belongs_to :reviewable, polymorphic: true`) は
+      # 単一の対象コレクションを持たないため現状未対応。誤った FK を出力しないよう
+      # ここでは除外する (将来 ActiveRecord 版と同様に展開する余地を残す)。
+      #
+      # 継承階層では基底クラスとサブクラスが同じ belongs_to を二重に持つため uniq する。
+      belongs_to_assocs
+        .reject(&:polymorphic?)
+        .map { |assoc| { table_name: assoc.klass.collection_name.to_s, foreign_key: assoc.foreign_key } }
+        .uniq
+    end
+
+    # Resolves the `embedded_in` config for an embedded model. Each embedded
+    # model points at its *immediate* embedding parent: the parent's collection
+    # name plus the single document key (`store_as`, defaulting to the relation
+    # name) the subdocuments live under within that parent.
+    #
+    # Multi-level nesting is represented one link at a time, NOT flattened into
+    # a dot-separated path. For `User embeds_many :posts` and
+    # `Post embeds_many :comments`, the Post config resolves to
+    # `{ collection_name: "users", path: "posts" }` and the Comment config to
+    # `{ collection_name: "posts", path: "comments" }`. `MongodbAdapter` walks
+    # this chain recursively (masking each `posts` subdocument, then its
+    # `comments`), which is the only form that correctly traverses both array
+    # (`embeds_many`) and Hash (`embeds_one`) intermediates — a flattened
+    # `posts.comments` path would stop at the `posts` array boundary.
+    private def embedded_in_for(model)
+      assoc = embedded_in_association(model)
+
+      # A polymorphic `embedded_in` (`embedded_in :addressable, polymorphic: true`)
+      # can live inside several different parent collections, so it has no single
+      # embedding parent and `assoc.klass` would raise a cryptic NameError
+      # (uninitialized constant) trying to resolve one. exwiw's `embedded_in`
+      # names exactly one parent collection + path, so this shape cannot be
+      # represented; fail loudly with an actionable message instead of crashing.
+      if assoc.polymorphic?
+        raise ArgumentError,
+              "MongoidSchemaGenerator: '#{model.name}' (collection '#{model.collection_name}') " \
+              "declares a polymorphic `embedded_in :#{assoc.name}`, which has no single embedding " \
+              "parent collection and cannot be expressed as an exwiw `embedded_in` config. " \
+              "Define the collection's config by hand, or make the relation non-polymorphic."
+      end
+
+      parent = assoc.klass
+
+      # A self-referential / cyclic `embedded_in` — Mongoid's
+      # `recursively_embeds_many` / `recursively_embeds_one` (which declare a
+      # `cyclic: true` `embedded_in`/`embeds_*` pair pointing at the same model),
+      # or any hand-rolled self-embedding — makes a collection BOTH a top-level
+      # document AND embedded inside documents of its own type. exwiw represents
+      # a collection as either top-level (dumpable on its own) or embedded
+      # (masked through its parent at `path`), never both: emitting an
+      # `embedded_in` here would mark the whole collection embedded, so
+      # `MongodbAdapter#dumpable?` (`!embedded?`) would silently never dump the
+      # collection's root documents. Fail loudly instead.
+      if parent.collection_name.to_s == model.collection_name.to_s
+        raise ArgumentError,
+              "MongoidSchemaGenerator: '#{model.name}' (collection '#{model.collection_name}') " \
+              "declares a self-referential (cyclic) `embedded_in :#{assoc.name}` that embeds the " \
+              "collection inside documents of its own type (e.g. `recursively_embeds_many` / " \
+              "`recursively_embeds_one`). " \
+              "exwiw represents a collection as either top-level or embedded, not both, so this " \
+              "cannot be expressed as an exwiw `embedded_in` config. Define the collection's config " \
+              "by hand."
+      end
+
+      # `store_as` defaults to the relation name and is the actual document key
+      # the subdocuments are stored under inside the immediate parent.
+      parent_relation = parent.relations[assoc.inverse.to_s]
+
+      { collection_name: parent.collection_name.to_s, path: parent_relation.store_as }
+    end
+
+    private def embedded_in_association(model)
+      model.relations.values.find do |assoc|
+        assoc.is_a?(::Mongoid::Association::Embedded::EmbeddedIn)
+      end
+    end
+  end
+end

data/lib/exwiw/query_ast.rb

@@ -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

@@ -73,11 +73,7 @@ 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
@@ -107,8 +103,12 @@ module Exwiw
       clauses = []
 
       if table.name == dump_target.table_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
         )
@@ -119,11 +119,7 @@ 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 なのか別モデルなのか判別できない)、
@@ -143,6 +139,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/version.rb

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

data/lib/exwiw.rb

@@ -25,6 +25,7 @@ require_relative "exwiw/after_insert_hook"
 require_relative "exwiw/runner"
 require_relative "exwiw/explain_runner"
 require_relative "exwiw/schema_generator"
+require_relative "exwiw/mongoid_schema_generator"
 
 begin
   require 'rails'
@@ -34,6 +35,9 @@ else
 end
 
 module Exwiw
-  DumpTarget = Struct.new(:table_name, :ids, keyword_init: true)
+  # `ids_field` optionally overrides which field `--ids` is matched against on
+  # the target table. When nil the table's primary key is used (the historical
+  # behavior). Currently only honored by the mongodb adapter.
+  DumpTarget = Struct.new(:table_name, :ids, :ids_field, keyword_init: true)
   ConnectionConfig = Struct.new(:adapter, :host, :port, :user, :password, :database_name, keyword_init: true)
 end

data/lib/tasks/exwiw.rake

@@ -10,5 +10,14 @@ namespace :exwiw do
         output_dir: ENV["OUTPUT_DIR_PATH"] || "exwiw",
       ).generate!
     end
+
+    desc "Generate schema from a Mongoid application"
+    task generate_mongoid: :environment do
+      require "exwiw"
+
+      Exwiw::MongoidSchemaGenerator.from_rails_application(
+        output_dir: ENV["OUTPUT_DIR_PATH"] || "exwiw",
+      ).generate!
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exwiw
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.3.0
 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
@@ -57,6 +58,7 @@ files:
 - lib/exwiw/mongo_query.rb
 - lib/exwiw/mongodb_collection_config.rb
 - lib/exwiw/mongodb_field.rb
+- lib/exwiw/mongoid_schema_generator.rb
 - lib/exwiw/query_ast.rb
 - lib/exwiw/query_ast_builder.rb
 - lib/exwiw/railtie.rb