exwiw 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 224bdc1d3b0f94e08463ad9e42a6e67d0592d902388b5873f5840226dbdbd3fe
-  data.tar.gz: de9ddd4a625565e0bcd28ff3f74df8da06092c443ad1f170d41c5858a24c4802
+  metadata.gz: 2af5a1cc29946424a2b6498f19d7ad77714f108194575ddd6014c5fc2d829416
+  data.tar.gz: 3113e80b88ab11a95344140f819a9247eadc3706c45a9b2a665f946a88a945b7
 SHA512:
-  metadata.gz: '08f564c07c09561a4b9b825bb7f6ca43a076df5b8262f165addad471639084fa5b5074330215edd36951ce0c427f510533f39d03e0632c1306ba4e9054391b33'
-  data.tar.gz: 2c161f236a676a15774fb097a7a2c4d66f95f38be8c465dfc29788b4c45165aa3b13dee2b1da771e317672e63f089d2496e10cf4fe2ebf16f97885e0e1c49c76
+  metadata.gz: 539f4ab428d75f97714475d607d91ae2870a2bf860ac8ab2f732d5a5709d5e0cf2fd085c0bc3bbdf9b095f969542eb866c1f3c3766cc5e3a8be0294cf3cfcf0f
+  data.tar.gz: 7b41f191e5e6d5ff60a1c927111d06f85b6c461a1dd63d5665b254338eafcde037233bb7f67027306258515e71aa1af3cf38e6aadf20b02ec9f6a91f05c7f2c4

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [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

data/README.md

@@ -129,6 +129,88 @@ exwiw explain \
 
 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.
@@ -144,7 +226,7 @@ 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 may also be set here
+# 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:

data/lib/exwiw/after_insert_hook.rb

@@ -38,6 +38,7 @@ module Exwiw
         '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

@@ -35,6 +35,7 @@ module Exwiw
       ids
       ids_field
       ids_column
+      scope_column
     ].freeze
 
     # Database connection settings are environment-specific (and sometimes
@@ -77,6 +78,7 @@ module Exwiw
       @ids = []
       @ids_field = nil
       @ids_column = nil
+      @scope_column = nil
       @output_format = nil
       @insert_only = nil
       @after_insert_hook_path = nil
@@ -109,6 +111,7 @@ module Exwiw
         table_name: @target_table_name,
         ids: @ids,
         ids_field: @ids_field,
+        scope_column: @scope_column,
       )
 
       logger = build_logger
@@ -161,6 +164,7 @@ module Exwiw
       end
 
       resolve_target_collection_alias!
+      resolve_scope_column!
       resolve_ids_column_alias!
       resolve_uri_option!
 
@@ -228,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
 
@@ -309,6 +318,7 @@ module Exwiw
       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
@@ -376,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
@@ -442,6 +479,7 @@ module Exwiw
         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,
@@ -500,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

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

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

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

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.5.0"
+  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,

metadata

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