exwiw 0.4.11 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23b64ea4c8b3562427b3e605fc17dec1251cf6916f2be02aeed0b3a29e03a62d
-  data.tar.gz: ce8a51a31bb84c22abd164e3ec928065dff99f1dbd6eb83c72a9520e8c7e0737
+  metadata.gz: 2af5a1cc29946424a2b6498f19d7ad77714f108194575ddd6014c5fc2d829416
+  data.tar.gz: 3113e80b88ab11a95344140f819a9247eadc3706c45a9b2a665f946a88a945b7
 SHA512:
-  metadata.gz: 779684b310965b1f59a7d9bb20d20d61526435845c1c3c5d7b6a6e1c7febcb96ce82d12ebf22bcb894546d8dd9f876984d302a87a2e321a1fb3aa8de8aeb4447
-  data.tar.gz: e19d3931e974e09487e6a661e482cdeac9cf665e34d80dc82ed9fff6f099ffa7cf0a2a8fec2b7f682b301899f9121f3c6fd49680fe0a70fb300bb04d7b9c9f78
+  metadata.gz: 539f4ab428d75f97714475d607d91ae2870a2bf860ac8ab2f732d5a5709d5e0cf2fd085c0bc3bbdf9b095f969542eb866c1f3c3766cc5e3a8be0294cf3cfcf0f
+  data.tar.gz: 7b41f191e5e6d5ff60a1c927111d06f85b6c461a1dd63d5665b254338eafcde037233bb7f67027306258515e71aa1af3cf38e6aadf20b02ec9f6a91f05c7f2c4

data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-06-18
+
+### Added
+
+- **Scope-column extraction mode** (`--scope-column`, SQL adapters only). For schemas where many independent top-level tables share the same scope/tenant column instead of converging on a single `belongs_to` root, exwiw can now filter **every** table by that shared column (`--scope-column=COLUMN` with `--ids` as its values) rather than anchoring on one `--target-table`. A table that carries the column is filtered directly; a table that lacks it but `belongs_to` a table that has it is joined up to the nearest such table and filtered there. A table that `belongs_to` a parent which is itself scoped but carries no scope column of its own (e.g. a *hub* table scoped only because an extractable child references it) is constrained to the parent's in-scope ids via a subquery (`fk IN (SELECT parent.pk FROM <parent's scoped query>)`), so the hub's other children ride along to just the in-scope rows — limited to a single forward hop and a single unambiguous scopable parent. A table that cannot be scoped at all (no column and no path to one) makes the run **abort with a list of the offending tables**, so an unscoped table is never silently dumped in full. Two user-owned table-config keys support this and are preserved across `schema:generate` regeneration: **`scope_exempt: true`** exports a genuine reference/master table in full (rails-managed tables are treated as exempt automatically), and **`scope_column`** overrides the filtered column name for a table that stores the same scope value under a different name. `--scope-column` is mutually exclusive with `--target-table`, `--target-collection`, `--ids-column`, and `--ids-field`, can be set in `exwiw.yml`, and works with `exwiw explain`.
+
+## [0.5.0] - 2026-06-16
+
+### Added
+
+- A YAML **config file** (`exwiw.yml`) can now hold any option except the database connection settings, so they no longer have to be repeated on every invocation. Pass it with `--config=PATH`; when `--config` is omitted, `exwiw.yml` (or `exwiw.yaml`) is loaded automatically from the current directory if present. **Options passed on the CLI take precedence** over the file (the file only fills in options not given on the CLI). Connection settings — `host`, `port`, `user`, `database`, `uri`, `password` — are **rejected** in the file (they must come from the CLI/environment); `adapter` is the one connection-related key allowed. Relative paths in the file (`schema_dir`, `output_dir`, `after_insert_hook`) are resolved relative to the config file's own directory (so a root-level `exwiw.yml` with `schema_dir: exwiw/schema` reads naturally and an absolute `--config` works from any directory). Unknown keys are rejected to catch typos, and export-only keys (`output_dir`, `output_format`, `insert_only`, `after_insert_hook`) are ignored under `explain` so one file can be shared by both subcommands.
+
+### Changed
+
+- **BREAKING**: the `export`/`explain` CLI option `--config-dir` has been renamed to `--schema-dir` to distinguish the directory of schema JSON files from the new `--config` config file. Its short form `-c` is now `--config` (the config file); `--schema-dir` has no short form. The hook contract is renamed to match: the shell-hook environment variable `EXWIW_CONFIG_DIR` is now `EXWIW_SCHEMA_DIR`, and the Ruby-hook `cli_options[:config_dir]` is now `cli_options[:schema_dir]`. Update invocations, scripts, and hooks accordingly (`--config-dir` no longer exists). `--schema-dir` is still required and has no default unless `schema_dir` is set in the config file.
+- **BREAKING**: the env var that overrides where `schema:generate`, `schema:tidy`, and `schema:generate_mongoid` write their config has been renamed from `OUTPUT_DIR_PATH` to `EXWIW_SCHEMA_DIR_PATH`, and the default output directory is now `exwiw/schema` (previously `exwiw`). The new name disambiguates it from the dump-side `--output-dir`, and the dedicated `schema/` subdirectory leaves `exwiw/` free for other artifacts (hooks, dumps). `OUTPUT_DIR_PATH` is no longer read. Existing repositories should set `EXWIW_SCHEMA_DIR_PATH` (e.g. `EXWIW_SCHEMA_DIR_PATH=exwiw` to preserve the old flat layout) and/or move their config under `exwiw/schema/`; otherwise a `generate` run will write a fresh copy into `exwiw/schema/` and leave the old files stale. The `export`/`explain` CLI is unaffected, but examples now point at `exwiw/schema`.
+
 ## [0.4.11] - 2026-06-15
 
 ### Fixed

data/README.md

@@ -72,7 +72,7 @@ exwiw \
   --port=3306 \
   --user=reader \
   --database=app_production \
-  --config-dir=exwiw \
+  --schema-dir=exwiw/schema \
   --target-table=shops \
   --ids=1 \ # comma separated ids
   --output-dir=dump \
@@ -81,7 +81,7 @@ exwiw \
 
 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`:
+When `--target-table` and `--ids` are omitted, exwiw dumps all tables defined in `--schema-dir`:
 
 ```bash
 # dump all tables
@@ -91,7 +91,7 @@ exwiw \
   --port=5432 \
   --user=reader \
   --database=app_production \
-  --config-dir=exwiw \
+  --schema-dir=exwiw/schema \
   --output-dir=dump
 ```
 
@@ -123,25 +123,140 @@ exwiw explain \
   --adapter=postgresql \
   --host=localhost --port=5432 --user=reader \
   --database=app_production \
-  --config-dir=exwiw \
+  --schema-dir=exwiw/schema \
   --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`.
 
+### Scope-column mode (`--scope-column`)
+
+The default `--target-table` extraction assumes the schema converges on a single
+root: every table is reached by walking `belongs_to` toward that one table. Some
+schemas are not shaped that way — many independent top-level tables each carry the
+*same* scope/tenant column (e.g. `tenant_id`, `account_uuid`) and there is no
+single root. Choosing one of them as `--target-table` would leave the others
+unrelated to it, and an unrelated table is dumped in full — a problem if it holds
+personal data.
+
+`--scope-column` handles this shape: instead of one anchor table, **every table is
+filtered by a shared column** whose values are `--ids`.
+
+```bash
+exwiw \
+  --adapter=postgresql \
+  --host=localhost --port=5432 --user=reader \
+  --database=app_production \
+  --schema-dir=exwiw/schema \
+  --scope-column=tenant_id \
+  --ids=42,43 \
+  --output-dir=dump
+```
+
+Each table is resolved as follows:
+
+- **Carries the scope column** → `WHERE scope_column IN (ids)`.
+- **Lacks it but `belongs_to` reaches a table that has it** → exwiw joins up to the
+  nearest such table and applies the scope filter there (the same join machinery
+  the single-target mode uses).
+- **`belongs_to` a parent that is itself scoped but carries no scope column of its
+  own** → exwiw constrains this table to the parent's in-scope ids via a subquery
+  (`fk IN (SELECT parent.pk FROM <parent's scoped query>)`). This covers a *hub*
+  table that has no scope column and is scoped only because an extractable child
+  references it (see referenced-by below): the hub's other `belongs_to` children
+  ride along to just the in-scope rows instead of being dumped in full. Limited to
+  a single forward hop and a single unambiguous scopable parent.
+- **Cannot be scoped at all** (no scope column and no path to one) → exwiw
+  **aborts** and lists the offending tables, so an unscoped table is never silently
+  dumped in full. For each, either add a `belongs_to` path, set `ignore: true` to
+  skip it, or mark it `scope_exempt: true` (below) to export it in full.
+
+`--scope-column` is SQL-only (mysql / postgresql / sqlite) and mutually exclusive
+with `--target-table`, `--target-collection`, `--ids-column`, and `--ids-field`.
+It works with `exwiw explain` too, which is the recommended way to preview the
+queries before exporting.
+
+#### `scope_exempt` (intentional full dump)
+
+A genuine reference/master table (no personal data) that has no scope linkage can
+opt out of the strict check and be exported in full:
+
+```json
+{
+  "name": "countries",
+  "primary_key": "id",
+  "scope_exempt": true,
+  "columns": [{ "name": "id" }, { "name": "code" }]
+}
+```
+
+Rails-managed tables (`schema_migrations`, `ar_internal_metadata`) are treated as
+exempt automatically.
+
+#### Per-table `scope_column` override
+
+scope-column mode assumes a single shared **value** space — the same `--ids` apply
+to every scoped table. If a table stores that same value under a differently named
+column, override the column name for that table:
+
+```json
+{
+  "name": "legacy_orders",
+  "primary_key": "id",
+  "scope_column": "legacy_tenant_id",
+  "columns": [{ "name": "id" }, { "name": "legacy_tenant_id" }]
+}
+```
+
+Both `scope_exempt` and `scope_column` are user-maintained and preserved across
+`schema:generate` regeneration (the generators never emit them).
+
+### Config file (`exwiw.yml`)
+
+Options you would otherwise repeat on every run can be kept in a YAML config file. Pass it with `--config=PATH`; when `--config` is omitted, exwiw automatically loads `exwiw.yml` (or `exwiw.yaml`) from the current directory if present.
+
+**Options passed on the CLI always take precedence over the config file** — the config only fills in options you did not pass. This lets you commit the stable settings (which schema to read, output format, ...) while still varying the environment-specific connection details per invocation.
+
+```yaml
+# exwiw.yml — keep at the project root, alongside exwiw/schema/
+adapter: postgresql
+schema_dir: exwiw/schema
+output_dir: dump
+output_format: insert        # insert | copy
+insert_only: false
+after_insert_hook: hooks/seed.rb
+log_level: info              # debug | info
+# target_table / ids / ids_field / ids_column / scope_column may also be set here
+```
+
+With the file above, only the connection details need to be supplied on the CLI:
+
+```bash
+DATABASE_PASSWORD=... exwiw \
+  --host=localhost --port=5432 --user=reader --database=app_production \
+  --target-table=shops --ids=1
+```
+
+Notes:
+
+- **Database connection settings stay on the CLI/environment.** `host`, `port`, `user`, `database`, `uri`, and `password` are **rejected** in the config file (exwiw exits with an error). `adapter` is the one connection-related key that *is* allowed in the file.
+- **Relative paths in the config (`schema_dir`, `output_dir`, `after_insert_hook`) are resolved relative to the config file's own directory**, not the current working directory. So with the config at the project root, `schema_dir: exwiw/schema` reads naturally, and an absolute `--config=/path/to/exwiw.yml` works no matter where you run from. (CLI path flags remain relative to the current directory — each source resolves relative to where it is written.) Absolute paths are used as-is.
+- Unknown keys are rejected so a typo surfaces immediately.
+- Export-only keys (`output_dir`, `output_format`, `insert_only`, `after_insert_hook`) are ignored when running `explain`, so a single config file can be shared by both subcommands.
+
 ### Generator
 
 The config generator is provided as a Rake task.
 
 ```bash
-# generate table schema under exwiw/
+# generate table schema under exwiw/schema/
 bundle exec rake exwiw:schema:generate
 ```
 
-By default, the schema files will be saved in the `exwiw` directory. You can specify a different output directory by setting the `OUTPUT_DIR_PATH` environment variable:
+By default, the schema files will be saved in the `exwiw/schema` directory. You can specify a different output directory by setting the `EXWIW_SCHEMA_DIR_PATH` environment variable:
 
 ```sh
-OUTPUT_DIR_PATH=custom_directory bundle exec rake exwiw:schema:generate
+EXWIW_SCHEMA_DIR_PATH=custom_directory bundle exec rake exwiw:schema:generate
 ```
 
 #### Tidying stale config (`schema:tidy`)
@@ -159,14 +274,14 @@ bundle exec rake exwiw:schema:tidy
 
 Because it reads the database directly, a table that still exists in the database but has lost (or never had) an ActiveRecord model is **kept** — only a table that is genuinely gone is removed. (This is the deliberate counterpart to `generate`, which is model-driven and only ever adds what the models know about.)
 
-It respects `OUTPUT_DIR_PATH` and the per-database subdirectory layout in the same way as `schema:generate`. Unlike `generate`, `tidy` never adds or regenerates entries — every surviving table/column (including hand-edited `comment` / `ignore` / `replace_with`) is left untouched, so it is safe to run on a customized config. The task prints which tables and columns it removed (or that the config was already tidy). Stale `belongs_tos` are not pruned by `tidy`; rerun `schema:generate` to refresh those.
+It respects `EXWIW_SCHEMA_DIR_PATH` and the per-database subdirectory layout in the same way as `schema:generate`. Unlike `generate`, `tidy` never adds or regenerates entries — every surviving table/column (including hand-edited `comment` / `ignore` / `replace_with`) is left untouched, so it is safe to run on a customized config. The task prints which tables and columns it removed (or that the config was already tidy). Stale `belongs_tos` are not pruned by `tidy`; rerun `schema:generate` to refresh those.
 
 #### Multiple databases
 
 If the application uses Rails' multiple-database support (`connects_to`), `schema:generate` buckets models by the database they connect to and writes each database's config files into its own subdirectory of the output directory, named after the database config name (`primary`, `analytics`, ...):
 
 ```
-exwiw/
+exwiw/schema/
   primary/
     shops.json
     users.json
@@ -267,7 +382,7 @@ This is an example of the one table schema:
 }
 ```
 
-`--config-dir` will use all json files in the specified directory.
+`--schema-dir` will use all json files in the specified directory.
 
 ### Output format
 
@@ -307,7 +422,7 @@ SQL
 
 **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`
+- `EXWIW_OUTPUT_DIR`, `EXWIW_SCHEMA_DIR`
 - `EXWIW_DATABASE_ADAPTER`, `EXWIW_DATABASE_HOST`, `EXWIW_DATABASE_PORT`, `EXWIW_DATABASE_USER`, `EXWIW_DATABASE_NAME`
 - `EXWIW_TARGET_TABLE`, `EXWIW_IDS` (comma-separated), `EXWIW_OUTPUT_FORMAT`
 

data/lib/exwiw/after_insert_hook.rb

@@ -31,13 +31,14 @@ module Exwiw
     def self.run_shell(path:, cli_options:, output_dir:, logger:)
       env = {
         'EXWIW_OUTPUT_DIR'       => output_dir,
-        'EXWIW_CONFIG_DIR'       => cli_options[:config_dir].to_s,
+        'EXWIW_SCHEMA_DIR'       => cli_options[:schema_dir].to_s,
         'EXWIW_DATABASE_ADAPTER' => cli_options[:database_adapter].to_s,
         'EXWIW_DATABASE_HOST'    => cli_options[:database_host].to_s,
         'EXWIW_DATABASE_PORT'    => cli_options[:database_port].to_s,
         'EXWIW_DATABASE_USER'    => cli_options[:database_user].to_s,
         'EXWIW_DATABASE_NAME'    => cli_options[:database_name].to_s,
         'EXWIW_TARGET_TABLE'     => cli_options[:target_table].to_s,
+        'EXWIW_SCOPE_COLUMN'     => cli_options[:scope_column].to_s,
         'EXWIW_IDS'              => Array(cli_options[:ids]).join(','),
         'EXWIW_OUTPUT_FORMAT'    => cli_options[:output_format].to_s,
       }

data/lib/exwiw/cli.rb

@@ -5,6 +5,7 @@ require 'optparse'
 require 'pathname'
 
 require 'json'
+require 'yaml'
 
 require 'exwiw'
 
@@ -12,6 +13,40 @@ module Exwiw
   class CLI
     KNOWN_SUBCOMMANDS = %w[export explain].freeze
 
+    # Config file loaded automatically when --config is omitted, if one exists in
+    # the current directory. Kept at the project root (rather than under exwiw/)
+    # so that config-relative paths like `schema_dir: exwiw/schema` read naturally.
+    # Both extensions are accepted; .yml wins when both are present.
+    DEFAULT_CONFIG_PATHS = %w[exwiw.yml exwiw.yaml].freeze
+
+    # Keys accepted in the config file. Anything outside this set is rejected so
+    # a typo surfaces immediately instead of being silently ignored. These mirror
+    # the non-connection CLI options (plus `adapter`).
+    ALLOWED_CONFIG_KEYS = %w[
+      adapter
+      schema_dir
+      output_dir
+      output_format
+      insert_only
+      after_insert_hook
+      log_level
+      target_table
+      target_collection
+      ids
+      ids_field
+      ids_column
+      scope_column
+    ].freeze
+
+    # Database connection settings are environment-specific (and sometimes
+    # secret-adjacent), so they must be passed via CLI/env, never the committed
+    # config file. `adapter` is the one connection-ish key allowed in config.
+    REJECTED_CONNECTION_KEYS = %w[host port user database uri password].freeze
+
+    # Keys that only make sense for `export`. They are skipped when merging config
+    # for `explain` so a shared config file does not trip validate_explain_only!.
+    EXPORT_ONLY_CONFIG_KEYS = %w[output_dir output_format insert_only after_insert_hook].freeze
+
     def self.start(argv)
       new(argv).run
     end
@@ -34,7 +69,8 @@ module Exwiw
       @database_password = ENV["DATABASE_PASSWORD"]
       @connection_uri = nil
       @output_dir = nil
-      @config_dir = nil
+      @schema_dir = nil
+      @config_file_path = nil
       @database_adapter = nil
       @database_name = nil
       @target_table_name = nil
@@ -42,10 +78,13 @@ module Exwiw
       @ids = []
       @ids_field = nil
       @ids_column = nil
+      @scope_column = nil
       @output_format = nil
       @insert_only = nil
       @after_insert_hook_path = nil
-      @log_level = :info
+      # nil (not :info) so we can tell "user passed --log-level" from the default,
+      # letting a config-file value fill in; the :info default is applied later.
+      @log_level = nil
 
       parser.parse!(@argv)
     end
@@ -72,6 +111,7 @@ module Exwiw
         table_name: @target_table_name,
         ids: @ids,
         ids_field: @ids_field,
+        scope_column: @scope_column,
       )
 
       logger = build_logger
@@ -82,7 +122,7 @@ module Exwiw
         Runner.new(
           connection_config: connection_config,
           output_dir: @output_dir,
-          config_dir: @config_dir,
+          schema_dir: @schema_dir,
           dump_target: dump_target,
           output_format: @output_format,
           insert_only: @insert_only,
@@ -93,7 +133,7 @@ module Exwiw
       when "explain"
         ExplainRunner.new(
           connection_config: connection_config,
-          config_dir: @config_dir,
+          schema_dir: @schema_dir,
           dump_target: dump_target,
           logger: logger,
           io: $stdout,
@@ -102,6 +142,14 @@ module Exwiw
     end
 
     private def validate_options!
+      # Fill in any options not given on the CLI from the config file. Done first
+      # so a config-provided `adapter` is in place before normalization below.
+      # CLI values always win (the merge only fills nil/empty ivars).
+      apply_config_file!
+
+      # Default log level once CLI and config have both had their say.
+      @log_level ||= :info
+
       # Fold driver/Rails adapter spellings (mysql2, sqlite3) into exwiw's
       # canonical names up front, so every check below — and the
       # EXWIW_DATABASE_ADAPTER passed to hooks — sees the canonical name.
@@ -116,6 +164,7 @@ module Exwiw
       end
 
       resolve_target_collection_alias!
+      resolve_scope_column!
       resolve_ids_column_alias!
       resolve_uri_option!
 
@@ -163,18 +212,18 @@ module Exwiw
         end
       end
 
-      if @config_dir.nil?
-        $stderr.puts "Config dir is required"
+      if @schema_dir.nil?
+        $stderr.puts "Schema dir is required (pass --schema-dir or set schema_dir in the config file)"
         exit 1
       end
 
-      unless Dir.exist?(@config_dir)
-        $stderr.puts "Config dir does not exist: #{@config_dir}"
+      unless Dir.exist?(@schema_dir)
+        $stderr.puts "Schema dir does not exist: #{@schema_dir}"
         exit 1
       end
 
-      if Dir.glob(File.join(@config_dir, "*.json")).empty?
-        $stderr.puts "Config dir contains no .json files: #{@config_dir}"
+      if Dir.glob(File.join(@schema_dir, "*.json")).empty?
+        $stderr.puts "Schema dir contains no .json files: #{@schema_dir}"
         exit 1
       end
 
@@ -183,8 +232,13 @@ module Exwiw
         exit 1
       end
 
-      if !@target_table_name && @ids.any?
-        $stderr.puts "--target-table is required when --ids is specified"
+      if @scope_column && @ids.empty?
+        $stderr.puts "--ids is required when --scope-column is specified"
+        exit 1
+      end
+
+      if !@target_table_name && !@scope_column && @ids.any?
+        $stderr.puts "--target-table or --scope-column is required when --ids is specified"
         exit 1
       end
 
@@ -202,6 +256,79 @@ module Exwiw
       end
     end
 
+    # Merge settings from the config file (YAML) into any options the user did
+    # not pass on the CLI. The CLI always wins: every assignment below only fills
+    # an ivar that is still nil/empty after parsing ARGV. Connection settings
+    # (except `adapter`) are rejected here — they belong on the CLI/env.
+    private def apply_config_file!
+      path =
+        if @config_file_path
+          unless File.file?(@config_file_path)
+            $stderr.puts "Config file not found: #{@config_file_path}"
+            exit 1
+          end
+          @config_file_path
+        else
+          DEFAULT_CONFIG_PATHS.map { |p| File.expand_path(p) }.find { |p| File.file?(p) }
+        end
+      return if path.nil?
+
+      # Paths inside the config file are resolved relative to the file's own
+      # directory (not cwd), so `schema_dir: exwiw/schema` reads naturally with the
+      # config kept at the project root, and an absolute --config works from any
+      # cwd. (CLI path flags stay cwd-relative — each source resolves relative to
+      # where it is written.) `path` is always absolute here.
+      base = File.dirname(path)
+
+      config = YAML.safe_load(File.read(path)) || {}
+      unless config.is_a?(Hash)
+        $stderr.puts "Config file must be a YAML mapping (key: value): #{path}"
+        exit 1
+      end
+
+      config.each_key do |key|
+        if REJECTED_CONNECTION_KEYS.include?(key)
+          $stderr.puts "'#{key}' is a database connection setting and must be passed via the CLI/environment, not the config file (#{path})"
+          exit 1
+        end
+        unless ALLOWED_CONFIG_KEYS.include?(key)
+          $stderr.puts "Unknown config key '#{key}' in #{path}. Allowed keys: #{ALLOWED_CONFIG_KEYS.join(', ')}"
+          exit 1
+        end
+      end
+
+      # For `explain`, drop export-only keys so a config shared with `export`
+      # does not make validate_explain_only! reject the run.
+      config = config.reject { |k, _| EXPORT_ONLY_CONFIG_KEYS.include?(k) } if @subcommand == "explain"
+
+      @database_adapter ||= config["adapter"]
+      @schema_dir ||= expand_dir(config["schema_dir"], base)
+      @output_dir ||= expand_dir(config["output_dir"], base)
+      @after_insert_hook_path ||= (File.expand_path(config["after_insert_hook"], base) if config["after_insert_hook"])
+      @output_format ||= config["output_format"]
+      @insert_only = config["insert_only"] if @insert_only.nil? && config.key?("insert_only")
+      @log_level ||= config["log_level"]&.to_sym
+      @target_table_name ||= config["target_table"]
+      @target_collection_name ||= config["target_collection"]
+      if @ids.empty? && config.key?("ids")
+        raw = config["ids"]
+        # Accept either a YAML list or a "1,2" string; coerce to strings to match
+        # the CLI's `--ids=1,2` -> ["1", "2"] shape.
+        @ids = (raw.is_a?(String) ? raw.split(",") : Array(raw)).map(&:to_s)
+      end
+      @ids_field ||= config["ids_field"]
+      @ids_column ||= config["ids_column"]
+      @scope_column ||= config["scope_column"]
+    end
+
+    # Strip a trailing slash (like the CLI's dir options) and expand relative to
+    # `base` (the config file's directory). Returns nil for a nil value.
+    private def expand_dir(value, base)
+      return nil if value.nil?
+      value = value.end_with?("/") ? value[0..-2] : value
+      File.expand_path(value, base)
+    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
@@ -259,6 +386,33 @@ module Exwiw
       end
     end
 
+    # `--scope-column` switches to scope-column mode: every table is filtered by a
+    # shared column (`--ids` are its values) instead of anchoring on one
+    # `--target-table`. It is SQL-only and mutually exclusive with the single-target
+    # flags. Runs after resolve_target_collection_alias! (so --target-collection is
+    # already folded into @target_table_name) and before resolve_ids_column_alias!
+    # so the clearer "cannot combine" message wins over the generic ids-column one.
+    private def resolve_scope_column!
+      return if @scope_column.nil?
+
+      sql_adapters = ["mysql", "postgresql", "sqlite"]
+      unless sql_adapters.include?(@database_adapter)
+        $stderr.puts "--scope-column is only supported by the sql adapters"
+        exit 1
+      end
+
+      if @target_table_name
+        $stderr.puts "--scope-column cannot be combined with --target-table/--target-collection"
+        exit 1
+      end
+
+      if @ids_field || @ids_column
+        flag = @ids_column ? "--ids-column" : "--ids-field"
+        $stderr.puts "--scope-column cannot be combined with #{flag}"
+        exit 1
+      end
+    end
+
     # `--uri` supplies a full connection string (e.g. `mongodb+srv://...`) and is
     # mongodb-only — the SQL adapters shell out to their own client binaries with
     # discrete host/port/user flags and have no equivalent. Runs after the
@@ -319,12 +473,13 @@ module Exwiw
         database_user: @database_user,
         database_password: @database_password,
         output_dir: @output_dir,
-        config_dir: @config_dir,
+        schema_dir: @schema_dir,
         database_adapter: @database_adapter,
         database_name: @database_name,
         target_table: @target_table_name,
         ids: @ids.dup.freeze,
         ids_field: @ids_field,
+        scope_column: @scope_column,
         output_format: @output_format,
         insert_only: @insert_only,
         log_level: @log_level,
@@ -368,9 +523,12 @@ module Exwiw
           v = v.end_with?("/") ? v[0..-2] : v
           @output_dir = File.expand_path(v)
         end
-        opts.on("-c", "--config-dir=CONFIG_DIR_PATH", "Config dir path.") do |v|
+        opts.on("--schema-dir=SCHEMA_DIR_PATH", "Directory of schema JSON files. (or set schema_dir in the config file)") do |v|
           v = v.end_with?("/") ? v[0..-2] : v
-          @config_dir = File.expand_path(v)
+          @schema_dir = File.expand_path(v)
+        end
+        opts.on("-c", "--config=CONFIG_FILE_PATH", "Path to the exwiw config YAML. Defaults to ./#{DEFAULT_CONFIG_PATHS.first} (or .#{File.extname(DEFAULT_CONFIG_PATHS.last)}) when present. CLI options take precedence; paths inside the file are resolved relative to the file.") do |v|
+          @config_file_path = File.expand_path(v)
         end
         opts.on("-a", "--adapter=ADAPTER", "Database adapter: mysql, sqlite, postgresql, mongodb (aliases: mysql2, sqlite3)") { |v| @database_adapter = v }
         opts.on("--uri=URI", "Full MongoDB connection URI (mongodb:// or mongodb+srv://). mongodb adapter only; takes precedence over --host/--port/--user. TLS, replicaSet, authSource and credentials are read from the URI.") { |v| @connection_uri = v }
@@ -380,6 +538,7 @@ module Exwiw
         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("--scope-column=[COLUMN]", "Filter every table by this shared column (--ids are its values) instead of a single --target-table. Tables lacking it are reached via belongs_to. SQL adapters only; mutually exclusive with --target-table.") { |v| @scope_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|

data/lib/exwiw/explain_runner.rb

@@ -4,13 +4,13 @@ module Exwiw
   class ExplainRunner
     def initialize(
       connection_config:,
-      config_dir:,
+      schema_dir:,
       dump_target:,
       logger:,
       io: $stdout
     )
       @connection_config = connection_config
-      @config_dir = config_dir
+      @schema_dir = schema_dir
       @dump_target = dump_target
       @logger = logger
       @io = io
@@ -26,8 +26,11 @@ module Exwiw
       target = table_by_name[@dump_target.table_name]
       adapter.validate_as_dump_target!(target) if target
 
+      dumpable_configs = configs.select { |c| adapter.dumpable?(c) }
+      QueryAstBuilder.validate_scope!(dumpable_configs, table_by_name, @dump_target, @logger)
+
       @logger.debug("Determining table processing order...")
-      ordered_table_names = DetermineTableProcessingOrder.run(configs.select { |c| adapter.dumpable?(c) })
+      ordered_table_names = DetermineTableProcessingOrder.run(dumpable_configs)
 
       total_size = ordered_table_names.size
       ordered_table_names.each_with_index do |table_name, idx|
@@ -53,7 +56,7 @@ module Exwiw
     end
 
     private def load_table_config(klass)
-      Dir[File.join(@config_dir, "*.json")].map do |file|
+      Dir[File.join(@schema_dir, "*.json")].map do |file|
         json = JSON.parse(File.read(file))
         klass.from(json).reject_ignored_members!
       end

data/lib/exwiw/query_ast_builder.rb

@@ -2,23 +2,58 @@
 
 module Exwiw
   class QueryAstBuilder
-    def self.run(table_name, table_by_name, dump_target, logger, allow_reverse: true)
-      new(table_name, table_by_name, dump_target, logger, allow_reverse: allow_reverse).run
+    def self.run(table_name, table_by_name, dump_target, logger, allow_reverse: true, allow_forward: true)
+      new(table_name, table_by_name, dump_target, logger, allow_reverse: allow_reverse, allow_forward: allow_forward).run
+    end
+
+    # Scope-column mode classification for a single table. One of
+    # :exempt / :direct / :via_path / :referenced_by / :via_scoped_parent / :unscopable.
+    def self.scope_category(table_name, table_by_name, dump_target, logger)
+      new(table_name, table_by_name, dump_target, logger).scope_category
+    end
+
+    # Strict pre-flight for scope-column mode: abort if any extractable table
+    # cannot be scoped, so an unscoped (potentially sensitive) table is never
+    # silently dumped in full. No-op outside scope mode. `tables` is the set of
+    # dumpable configs (ignore:true tables are skipped — they are not extracted).
+    def self.validate_scope!(tables, table_by_name, dump_target, logger)
+      return if dump_target.scope_column.nil?
+
+      unscopable =
+        tables.reject(&:ignore).select do |table|
+          scope_category(table.name, table_by_name, dump_target, logger) == :unscopable
+        end
+      return if unscopable.empty?
+
+      names = unscopable.map(&:name).sort.join(", ")
+      raise ArgumentError,
+            "scope-column mode: #{unscopable.size} table(s) cannot be scoped by " \
+            "'#{dump_target.scope_column}': #{names}. For each, add `scope_exempt: true` " \
+            "to export it in full, set `ignore: true` to skip it, or add a belongs_to path " \
+            "to a table that carries the scope column (use a per-table `scope_column` if the " \
+            "column name differs on that table)."
     end
 
     attr_reader :table_name, :table_by_name, :dump_target
 
-    def initialize(table_name, table_by_name, dump_target, logger, allow_reverse: true)
+    def initialize(table_name, table_by_name, dump_target, logger, allow_reverse: true, allow_forward: true)
       @table_name = table_name
       @table_by_name = table_by_name
       @dump_target = dump_target
       @logger = logger
       @allow_reverse = allow_reverse
+      # @allow_forward gates the "scope via an indirectly-scoped belongs_to
+      # parent" rescue (build_belongs_to_scoped_clause). Disabled while building a
+      # parent/child subquery so a single forward hop never recurses into another
+      # (which could loop on a belongs_to cycle).
+      @allow_forward = allow_forward
     end
 
     def run
       table = table_by_name.fetch(table_name)
 
+      return build_scoped(table) if scope_mode?
+
       where_clauses = build_where_clauses(table, dump_target)
       join_clauses = build_join_clauses(table, table_by_name, dump_target)
 
@@ -130,8 +165,10 @@ module Exwiw
         next if relation.nil? || relation.polymorphic?
 
         # Build the child's own extraction query. allow_reverse:false stops a
-        # chain of FK-less tables from recursing back into each other.
-        child_query = self.class.run(other.name, table_by_name, dump_target, @logger, allow_reverse: false)
+        # chain of FK-less tables from recursing back into each other;
+        # allow_forward:false stops the child from forward-scoping back through
+        # this very table (which would loop).
+        child_query = self.class.run(other.name, table_by_name, dump_target, @logger, allow_reverse: false, allow_forward: false)
 
         # Only an *already constrained* child narrows anything; an unconstrained
         # child would select every fk value (i.e. dump all) and not help.
@@ -169,6 +206,64 @@ module Exwiw
       )
     end
 
+    # Scope-column mode. Builds a `fk IN (SELECT parent.pk FROM <parent
+    # extraction query>)` clause for a table whose belongs_to parent is itself
+    # scopable but carries no scope column of its own — so find_path_to_scoped
+    # cannot terminate on it (via_path fails) and nothing references this table
+    # (referenced_by fails). The classic shape is a hub scoped only via
+    # referenced_by (e.g. CDP `customer_accounts`, scoped by the `customers` that
+    # reference it) with sibling detail tables (`customer_account_details`, ...)
+    # hanging off it. Constraining those siblings to the hub's in-scope ids keeps
+    # them out of a full dump. Returns nil when there is no single, unambiguous
+    # scopable parent, leaving the caller on the unscopable path.
+    private def build_belongs_to_scoped_clause(table)
+      candidates = table.belongs_tos.filter_map do |relation|
+        # A polymorphic belongs_to points at several parent tables through one
+        # column, so it cannot project to a single parent id set; skip it.
+        next if relation.polymorphic?
+
+        parent = table_by_name[relation.table_name]
+        next if parent.nil?
+
+        # Build the parent's own scoped query. allow_reverse stays true so the
+        # parent may be scoped via referenced_by; allow_forward:false bounds this
+        # to a single forward hop so a belongs_to cycle cannot loop.
+        parent_query = self.class.run(parent.name, table_by_name, dump_target, @logger, allow_reverse: true, allow_forward: false)
+
+        # Only a constrained parent narrows anything; an unconstrained parent
+        # would select every pk (i.e. dump all) and not help.
+        next unless parent_query.where_clauses.any? || parent_query.join_clauses.any?
+
+        [relation, parent, parent_query]
+      end
+
+      # Only the unambiguous single-parent case. Multiple scopable parents would
+      # need their subqueries combined (not supported); fall back to unscopable.
+      if candidates.size != 1
+        if candidates.size > 1
+          @logger.debug("  #{table.name} has multiple scopable parents; skipping forward scope (unscopable).")
+        end
+        return nil
+      end
+
+      relation, parent, parent_query = candidates.first
+
+      # Project the parent's extraction query down to just its primary key — the
+      # column this table's foreign key points at.
+      pk_column = TableColumn.from_symbol_keys(name: parent.primary_key)
+      projected = QueryAst::Select.new
+      projected.from(parent_query.from_table_name)
+      projected.select([pk_column])
+      parent_query.join_clauses.each { |j| projected.join(j) }
+      parent_query.where_clauses.each { |w| projected.where(w) }
+
+      QueryAst::WhereClause.new(
+        column_name: relation.foreign_key,
+        operator: :in_subquery,
+        value: QueryAst::SelectSubquery.new(query: projected)
+      )
+    end
+
     private def build_where_clauses(table, dump_target)
       clauses = []
 
@@ -264,5 +359,208 @@ module Exwiw
 
       queue
     end
+
+    # ------------------------------------------------------------------
+    # Scope-column mode (Exwiw::DumpTarget#scope_column).
+    #
+    # The single-target machinery above anchors everything on one named table.
+    # Scope mode instead filters every table by a shared column. The relationship
+    # walk is the same idea — the *terminus* is just "any table carrying the
+    # scope column" rather than "the one named target".
+    # ------------------------------------------------------------------
+
+    private def scope_mode?
+      !dump_target.scope_column.nil?
+    end
+
+    # Classifier used by validate_scope! and mirrored by build_scoped below.
+    def scope_category
+      table = table_by_name.fetch(table_name)
+      return :exempt if scope_exempt?(table)
+      return :direct if directly_scoped?(table)
+      return :via_path if build_join_clauses_scoped(table).any?
+      return :referenced_by if @allow_reverse && build_referenced_by_clause(table)
+      return :via_scoped_parent if @allow_forward && build_belongs_to_scoped_clause(table)
+
+      :unscopable
+    end
+
+    private def build_scoped(table)
+      ast = QueryAst::Select.new
+      ast.from(table.name)
+      if table.rails_managed?
+        ast.select_all!
+      else
+        ast.select(table.columns)
+      end
+
+      # Reference/master (or rails-managed) table: export every row.
+      return ast if scope_exempt?(table)
+
+      # Carries the scope column itself: filter on it directly.
+      if directly_scoped?(table)
+        ast.where(scope_where_clause(table))
+        ast.where(table.filter) if table.filter
+        return ast
+      end
+
+      # Reachable via belongs_to: join up to the scoped ancestor (the scope
+      # filter is applied at the terminal join inside build_join_clauses_scoped).
+      join_clauses = build_join_clauses_scoped(table)
+      unless join_clauses.empty?
+        join_clauses.each { |join_clause| ast.join(join_clause) }
+        ast.where(table.filter) if table.filter
+        return ast
+      end
+
+      if @allow_reverse
+        # Referenced by an extractable (scoped) child: constrain via subquery.
+        reverse_clause = build_referenced_by_clause(table)
+        if reverse_clause
+          ast.where(reverse_clause)
+          return ast
+        end
+      end
+
+      if @allow_forward
+        # Belongs_to a parent that is itself scoped but carries no scope column of
+        # its own (so via_path cannot terminate on it) — e.g. a hub table scoped
+        # only via referenced_by. Constrain this table to that parent's in-scope
+        # ids so its rows ride along instead of being dumped in full.
+        parent_clause = build_belongs_to_scoped_clause(table)
+        if parent_clause
+          ast.where(parent_clause)
+          return ast
+        end
+      end
+
+      # Only the genuine top-level build (no rescue disabled) is allowed to fail
+      # hard. The Runner/ExplainRunner pre-flight (validate_scope!) rejects
+      # unscopable tables before extraction, so a top-level build never
+      # legitimately lands here; if it does, raise rather than emit an unfiltered
+      # (potential full PII) dump.
+      if @allow_reverse && @allow_forward
+        raise ArgumentError, scope_unscopable_message(table)
+      end
+
+      # Unscopable during a reverse/forward subquery build (a rescue is disabled):
+      # return the unconstrained AST so the caller's "constrained only" check
+      # filters this candidate out (it never becomes a real dump query).
+      ast
+    end
+
+    # The shared column this table is filtered on: a per-table `scope_column`
+    # override when present, otherwise the global `--scope-column`.
+    private def resolved_scope_column(table)
+      table.scope_column || dump_target.scope_column
+    end
+
+    private def scope_exempt?(table)
+      table.scope_exempt || table.rails_managed?
+    end
+
+    private def directly_scoped?(table)
+      column = resolved_scope_column(table)
+      table.columns.any? { |c| c.name == column }
+    end
+
+    private def scope_where_clause(table)
+      Exwiw::QueryAst::WhereClause.new(
+        column_name: resolved_scope_column(table),
+        operator: :eq,
+        value: dump_target.ids
+      )
+    end
+
+    # BFS over belongs_tos to the nearest *directly scoped* ancestor. Unlike the
+    # target-mode walk, the returned path INCLUDES that ancestor: the scope column
+    # lives on the ancestor itself (not on a foreign key of the child), so the
+    # ancestor must be joined and then filtered.
+    private def find_path_to_scoped(table)
+      visited = {}
+      queue = [[table.name, [table.name]]]
+
+      until queue.empty?
+        current_table_name, path = queue.shift
+        next if visited[current_table_name]
+        visited[current_table_name] = true
+
+        current_table = table_by_name[current_table_name]
+        next if current_table.nil?
+
+        current_table.belongs_tos.each do |relation|
+          next_table_name = relation.table_name
+          next_table = table_by_name[next_table_name]
+          next if next_table.nil?
+
+          next_path = path + [next_table_name]
+          return next_path if directly_scoped?(next_table)
+
+          queue.push([next_table_name, next_path])
+        end
+      end
+
+      []
+    end
+
+    private def build_join_clauses_scoped(table)
+      path_tables = find_path_to_scoped(table)
+      @logger.debug("  Join path from #{table.name} to a scoped table: #{path_tables}")
+
+      return [] if path_tables.size < 2
+
+      path_tables.each_cons(2).map do |from_table_name, to_table_name|
+        from_table = table_by_name[from_table_name]
+        to_table = table_by_name[to_table_name]
+
+        join_clause = build_scoped_join_clause(from_table, to_table)
+
+        # Only the final hop's to_table is directly scoped (the BFS stops there),
+        # so the scope filter rides on that join's where_clauses, compiled against
+        # join_table_name = the scoped ancestor.
+        if directly_scoped?(to_table)
+          join_clause.where_clauses.push scope_where_clause(to_table)
+        end
+
+        if to_table.filter
+          join_clause.where_clauses.push to_table.filter
+        end
+
+        join_clause
+      end
+    end
+
+    # One belongs_to hop as a JoinClause, with the polymorphic type condition
+    # placed on the source table (base_where_clauses) when the hop is polymorphic
+    # — mirroring the target-mode loop in build_join_clauses.
+    private def build_scoped_join_clause(from_table, to_table)
+      relation = from_table.belongs_to(to_table.name)
+
+      join_clause = QueryAst::JoinClause.new(
+        base_table_name: from_table.name,
+        foreign_key: relation.foreign_key,
+        join_table_name: to_table.name,
+        primary_key: to_table.primary_key,
+        where_clauses: [],
+        base_where_clauses: []
+      )
+
+      if relation.polymorphic?
+        join_clause.base_where_clauses.push QueryAst::WhereClause.new(
+          column_name: relation.foreign_type,
+          operator: :eq,
+          value: [relation.type_value]
+        )
+      end
+
+      join_clause
+    end
+
+    private def scope_unscopable_message(table)
+      "Table '#{table.name}' cannot be scoped in scope-column mode: it has no " \
+        "'#{dump_target.scope_column}' column (nor a per-table scope_column override) and no " \
+        "belongs_to path to a table that does. Add `scope_exempt: true` to export it in full, " \
+        "set `ignore: true` to skip it, or add the missing belongs_to."
+    end
   end
 end

data/lib/exwiw/runner.rb

@@ -7,7 +7,7 @@ module Exwiw
     def initialize(
       connection_config:,
       output_dir:,
-      config_dir:,
+      schema_dir:,
       dump_target:,
       logger:,
       output_format: 'insert',
@@ -17,7 +17,7 @@ module Exwiw
     )
       @connection_config = connection_config
       @output_dir = output_dir
-      @config_dir = config_dir
+      @schema_dir = schema_dir
       @dump_target = dump_target
       @output_format = output_format
       @insert_only = insert_only
@@ -38,8 +38,13 @@ module Exwiw
       target = table_by_name[@dump_target.table_name]
       adapter.validate_as_dump_target!(target) if target
 
+      dumpable_configs = configs.select { |c| adapter.dumpable?(c) }
+      # Scope-column mode: abort if any extractable table cannot be scoped (no-op
+      # otherwise). Done before extraction so nothing is dumped if it would leak.
+      QueryAstBuilder.validate_scope!(dumpable_configs, table_by_name, @dump_target, @logger)
+
       @logger.info("Determining table processing order...")
-      ordered_table_names = DetermineTableProcessingOrder.run(configs.select { |c| adapter.dumpable?(c) })
+      ordered_table_names = DetermineTableProcessingOrder.run(dumpable_configs)
 
       clean_output_dir!
 
@@ -159,7 +164,7 @@ module Exwiw
     end
 
     private def load_table_config(klass)
-      Dir[File.join(@config_dir, "*.json")].map do |file|
+      Dir[File.join(@schema_dir, "*.json")].map do |file|
         json = JSON.parse(File.read(file))
         # Drop belongs_tos/columns(fields) flagged ignore:true so they are not
         # considered during extraction. Done here (after loading from file)

data/lib/exwiw/table_config.rb

@@ -26,6 +26,18 @@ module Exwiw
     attribute :columns, array(TableColumn), default: []
     attribute :bulk_insert_chunk_size, optional(Integer), skip_serializing_if_nil: true
     attribute :ignore, Serdes::OptionalType.new(Serdes::ConcreteType.new(Boolean)), skip_serializing_if_nil: true
+    # Scope-column mode only (see Exwiw::DumpTarget#scope_column). Both are
+    # user-configured and never emitted by the schema generators.
+    #
+    # `scope_exempt: true` exports the whole table without scope filtering — the
+    # explicit, auditable escape hatch for genuine reference/master tables under
+    # the strict "every table must be scopable" rule.
+    #
+    # `scope_column` overrides the physical column this table is filtered on when
+    # it differs from the global `--scope-column` name (same scope value, just a
+    # different column name on this table).
+    attribute :scope_exempt, Serdes::OptionalType.new(Serdes::ConcreteType.new(Boolean)), skip_serializing_if_nil: true
+    attribute :scope_column, optional(String), skip_serializing_if_nil: true
 
     def self.from(hash)
       config = super
@@ -137,6 +149,9 @@ module Exwiw
         merged_table.filter = filter
         merged_table.bulk_insert_chunk_size = passed_table.bulk_insert_chunk_size
         merged_table.ignore = ignore
+        # User-owned, never regenerated: carry over from the existing config.
+        merged_table.scope_exempt = scope_exempt
+        merged_table.scope_column = scope_column
 
         # Structural facts of each belongs_to come from the freshly generated
         # config, but the user-owned `comment`/`ignore`/`references` carry over

data/lib/exwiw/version.rb

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

data/lib/exwiw.rb

@@ -39,7 +39,13 @@ module Exwiw
   # `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)
+  #
+  # `scope_column` switches the extraction to scope-column mode: instead of a
+  # single `table_name` anchor, every table is filtered by a shared column
+  # (`scope_column IN ids`) and tables lacking it are reached by walking
+  # belongs_to up to the nearest table that has it. When set, `table_name` is
+  # nil. SQL adapters only.
+  DumpTarget = Struct.new(:table_name, :ids, :ids_field, :scope_column, keyword_init: true)
   # `uri` is an optional full connection string (currently only honored by the
   # mongodb adapter, e.g. `mongodb+srv://...`). When present it is the source of
   # truth for the connection — host/port/user/password are ignored — so TLS,

data/lib/tasks/exwiw.rake

@@ -7,7 +7,7 @@ namespace :exwiw do
       require "exwiw"
 
       Exwiw::SchemaGenerator.from_rails_application(
-        output_dir: ENV["OUTPUT_DIR_PATH"] || "exwiw",
+        output_dir: ENV["EXWIW_SCHEMA_DIR_PATH"] || "exwiw/schema",
       ).generate!
     end
 
@@ -16,7 +16,7 @@ namespace :exwiw do
       require "exwiw"
 
       result = Exwiw::SchemaGenerator.from_rails_application(
-        output_dir: ENV["OUTPUT_DIR_PATH"] || "exwiw",
+        output_dir: ENV["EXWIW_SCHEMA_DIR_PATH"] || "exwiw/schema",
       ).tidy!
 
       if result.empty?
@@ -47,7 +47,7 @@ namespace :exwiw do
       require "exwiw"
 
       Exwiw::MongoidSchemaGenerator.from_rails_application(
-        output_dir: ENV["OUTPUT_DIR_PATH"] || "exwiw",
+        output_dir: ENV["EXWIW_SCHEMA_DIR_PATH"] || "exwiw/schema",
         skip_unsupported: ENV["EXWIW_SKIP_UNSUPPORTED"] == "1",
       ).generate!
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exwiw
 version: !ruby/object:Gem::Version
-  version: 0.4.11
+  version: 0.5.1
 platform: ruby
 authors:
 - Shia