exwiw 0.9.0 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 171e3c591c208afcb89c2a9330c2c80d67f8f86ab370858b4690d03c799d28bc
-  data.tar.gz: f913a31f6f8e2a29a9e4b2a296926c1266c17cc8655fd4cf33110899f2b468fd
+  metadata.gz: 1856ad12991806b66ecce4a9fa6d85bc89c9e371f38c90da14168367b99e4f5b
+  data.tar.gz: 0fe953311f016847e4b4adf27c8b82ff94d3012d8d896406200b4d94080e442e
 SHA512:
-  metadata.gz: a8d6e99e0881f4cdaa8d6d737cfbd0107382a6585f119df7d3068007ebb768a976b47fd59f78fb2d931ed95147c707523b3c8e5d1e9af0507584de93796e1ec1
-  data.tar.gz: f1cbada5c1adb8892cc297a5e864051da3bdc0b7447cbe1c386b32dde4020cbf1ac6be94935d7bb547c2ec7f4482ebf79b3e1df796bb526db7fd7d5fb42ce662
+  metadata.gz: bb984601846145d7e542bdaddfecfb836a393926f3cd985f879bdabd3a5c28a37b190de443ae881faf2adec384429746dd1816b2d5c5ad0d11d4f570dbc94e80
+  data.tar.gz: 492316c915507618455644f2f4ff2073479db979a6e18b70aa8e2ff1efeb4df76562770be3bf760b3ab628c863ac3bb3b5a70806bc029730bda29df0bdb90ec2

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.9.2] - 2026-06-30
+
+### Added
+
+- **The mongodb adapter accepts a server-enforced query timeout, globally and per collection.** A global `--mongodb-query-timeout-ms=N` (also `mongodb_query_timeout_ms:` in the config file) sets the MongoDB driver's CSOT `timeout_ms` on the client, so every operation — the find cursor's whole lifetime (initial batch and every `getMore` the streaming dump walks), the document count, and an executing `explain` — is bounded; past the deadline the server aborts the operation and exwiw fails the run, so an accidentally heavy or unscoped query cannot keep pinning the (often production) source. A per-collection `query_timeout_ms` key in the schema config overrides the global for that collection's find/count (give a known-large collection more headroom, or cap a runaway one); like `bulk_insert_chunk_size`, it is user-maintained and preserved across Mongoid schema regeneration. Both are **mongodb-only** (the SQL adapters shell out to their own clients) and must be positive integers; the default is no timeout. The fork-parallel dump inherits both automatically (workers rebuild the client from the same connection config and run the same per-collection queries).
+
+## [0.9.1] - 2026-06-30
+
+### Fixed
+
+- **The `reverse_scope` satellite cascade now fires in single-target (`--target-table`) mode, not only scope-column mode.** A table that `belongs_to` a `reverse_scope`'d hub (a "satellite") is scoped by constraining it to the hub's in-scope ids — the multi-hop forward (`via_scoped_parent`) cascade. That cascade ran only in scope-column mode: in single-target / PK-anchor mode the hub itself was scoped via `reverse_scope`, but its `belongs_to` children fell through to a full dump — a silent cross-tenant export in a multi-tenant schema, despite the README promising the cascade works in "both single-target and scope-column mode." The single-target build now runs the same `build_belongs_to_scoped_clause` cascade for a non-target table that has no `belongs_to` path to the dump target, so satellites tighten to the kept ids (multi-hop, keeping the single-unambiguous-parent rule, polymorphic skip, and forward-path cycle guard); it can only narrow such a table's output, never widen it. Scope-column mode is unchanged — the cascade logic is reused as-is. Because single-target mode has no `validate_scope!` pre-flight, a satellite the cascade cannot resolve to a single scopable parent (e.g. it `belongs_to` two scopable hubs) is still dumped in full but now logs a warning. The README also documents that `referenced_by` scoping takes precedence over the hub cascade (which can under-scope) and how to force the hub cascade. SQL adapters only.
+
 ## [0.9.0] - 2026-06-30
 
 ### Added

data/README.md

@@ -220,6 +220,13 @@ Each table is resolved as follows:
   path, set `ignore: true` to skip it, or mark it `scope_exempt: true` (below) to
   export it in full.
 
+> **Note — referenced-by is preferred over the hub cascade.** A table that is
+> *both* `belongs_to` a scoped hub *and* referenced-by a constrained child is
+> scoped to the (narrower) referenced-by id-set, not the hub cascade, so the hub's
+> other children the child does not reference are dropped (under-scoping). To force
+> the broader hub cascade, set `ignore: true` on the child's `belongs_to` edge that
+> points at this table.
+
 Scope-column mode is SQL-only (mysql / postgresql / sqlite). It works with `exwiw
 explain` too, which is the recommended way to preview the queries before exporting.
 
@@ -293,6 +300,7 @@ insert_only: false
 after_insert_hook: hooks/seed.rb
 log_level: info              # debug | info
 # target_table / ids / ids_field / scope_column may also be set here
+# mongodb_query_timeout_ms: 30000   # global query timeout (mongodb only)
 ```
 
 With the file above, only the connection details need to be supplied on the CLI:
@@ -310,6 +318,7 @@ Notes:
 - 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.
 - `explain_verbosity` sets the mongodb `explain` verbosity (`queryPlanner` | `executionStats` | `allPlansExecution`, default `queryPlanner`); the `EXWIW_MONGODB_EXPLAIN_VERBOSITY` env var overrides it. Ignored by the SQL adapters and by `export`. See [`exwiw explain`](#mongodb-explain-verbosity).
+- `mongodb_query_timeout_ms` sets the global, server-enforced query timeout (mongodb only); the `--mongodb-query-timeout-ms` CLI flag overrides it. Ignored by the SQL adapters. See [MongoDB notes](#mongodb-notes).
 
 ### Generator
 
@@ -388,7 +397,7 @@ It is a distinct task and class (`Exwiw::MongoidSchemaGenerator`) from the Activ
 
 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`, `ignore`, 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.
+Regeneration preserves hand-edited `replace_with`, `filter`, `ignore`, `bulk_insert_chunk_size`, and `query_timeout_ms` 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.
 
 By default the task **aborts** when a model uses a construct exwiw cannot represent: a `belongs_to` whose target class can no longer be resolved (a stale relation left behind after its model was removed), or a polymorphic / self-referential-cyclic / ambiguous / unresolvable-parent `embedded_in` (see the cases above).
 
@@ -658,7 +667,7 @@ Notes:
 - **Only scoped referencers belong in `via`.** Each arm's query must come out constrained; an unconstrained referencer (e.g. a `scope_exempt` table, or one with no path to a scope) would project *every* id and union the whole table back — so such an arm is **skipped with a warning** rather than silently widening the dump. An unknown table is likewise skipped with a warning. If no arm survives, the table stays unscopable and (in [scope-column mode](#scope-column-mode)) the run aborts via `validate_scope!`.
 - **NULLs are excluded** per arm (`IS NOT NULL`).
 - **Satellites need no config.** A table that `belongs_to` the reverse-scoped table (e.g. `end_users.id → users.id`, or `identities.user_id → users.id`) tightens to the kept ids automatically through the normal cascade — only the reverse-scoped table itself declares `reverse_scope`. The cascade is **multi-hop**, so a table several `belongs_to` hops below the reverse-scoped table (e.g. `end_user_profiles → end_users → users`) also tightens automatically, with no config of its own.
-- Works in both single-target and scope-column mode. Polymorphic foreign keys are not eligible as anchors (the named `column` is always a concrete column).
+- Works in both single-target and scope-column mode. In single-target mode there is no scope-column pre-flight (`validate_scope!`), so a satellite the cascade cannot resolve to a single scopable parent (e.g. it `belongs_to` two scopable hubs) is dumped in full with a warning rather than aborting. Polymorphic foreign keys are not eligible as anchors (the named `column` is always a concrete column).
 
 ### Why a JOIN, not `IN (subquery)`
 
@@ -793,6 +802,7 @@ The MongoDB adapter is experimental. To use it:
 - `--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 have no equivalent).
 - Large or embedded-document-heavy dumps are streamed automatically: the adapter reads the collection through a lazy cursor (not `.to_a`) and writes JSONL in chunks, so peak memory is bounded by the chunk size rather than the collection size — no flag to set. Encoding each document to MongoDB Extended JSON is accelerated by an **optional native (C) extension** that compiles automatically on `gem install`; where it cannot compile, exwiw falls back to a byte-identical pure-Ruby encoder. See [`docs/optimization-notes.md`](docs/optimization-notes.md) for the performance investigation and [`docs/optimize-mongodb-export-with-native-ext.md`](docs/optimize-mongodb-export-with-native-ext.md) for the native encoder's design. Benchmark your own data with `script/bench_mongodb_dump.rb`.
+- `--mongodb-query-timeout-ms=N` sets a global, **server-enforced** timeout (in milliseconds) on every query exwiw issues — the find cursor's whole lifetime (the initial batch and every `getMore` the streaming dump walks), the count, and an executing `explain`. Past the deadline the server aborts the operation and exwiw fails the run, so an accidentally heavy or unscoped query cannot keep pinning the (often production) source. It is **mongodb-only** (the SQL adapters shell out to their own clients) and may also be set as `mongodb_query_timeout_ms:` in the config file. The default is no timeout. A single collection can opt to a different limit with a `query_timeout_ms` key in its schema config (a sibling of `bulk_insert_chunk_size`), which overrides the global for that collection's find/count — use it to give a known-large collection more headroom, or to cap one that tends to run away. Hand-edited `query_timeout_ms` values are preserved across schema regeneration.
 - `--parallel-workers=N` (opt-in, `export` only) forks `N` worker processes that decode whole collections in parallel — the dominant cost on a large dump is the driver's BSON→Ruby decode, and each worker decodes its own collections in their natural order, so the output stays **byte-identical** to a serial run (same filenames and content). It needs a dump target (the schedule is built around the scoped DAG) and a `fork`-capable runtime (CRuby on POSIX), falling back to the serial path otherwise; it also accepts `parallel_workers:` in the config file. The speedup needs real cores to spend — it reaches ~2× from 4 workers and saturates there. The default is serial. See [`docs/mongodb-dump-parallelism-2x-notes.md`](docs/mongodb-dump-parallelism-2x-notes.md) for the schedule and measurements.
 - Output is JSON Lines (`insert-{idx}-{collection}.jsonl`) using MongoDB Extended JSON (relaxed mode). Import with `mongoimport`:
   ```bash

data/lib/exwiw/adapter/mongodb_adapter.rb

@@ -40,15 +40,20 @@ module Exwiw
       class StreamingResult
         include Enumerable
 
-        def initialize(view:, collection:, keys:, state:)
+        def initialize(view:, collection:, keys:, state:, timeout_ms: nil)
           @view = view
           @collection = collection
           @keys = keys
           @state = state
+          @timeout_ms = timeout_ms
         end
 
         def size
-          @size ||= @view.count_documents
+          # count_documents reads :timeout_ms only from the opts passed here (it
+          # does not inherit the find view's per-op timeout), so the per-collection
+          # value must be threaded in explicitly. When nil it falls back to the
+          # client-wide global timeout, like every other operation.
+          @size ||= @timeout_ms ? @view.count_documents(timeout_ms: @timeout_ms) : @view.count_documents
         end
         alias length size
 
@@ -172,6 +177,7 @@ module Exwiw
           primary_key: config.primary_key,
           filter: filter,
           projection: build_projection(config, @propagation_keys),
+          timeout_ms: config.query_timeout_ms,
         )
       end
 
@@ -179,7 +185,7 @@ module Exwiw
         @logger.debug("  Executing Mongo find on '#{query.collection}': filter=#{query.filter.inspect} projection=#{query.projection.inspect}")
 
         view = db[query.collection]
-          .find(query.filter)
+          .find(query.filter, find_timeout_opts(query))
           .projection(query.projection)
           .comment(query_comment_text("collection=#{query.collection}"))
 
@@ -195,7 +201,7 @@ module Exwiw
         # large / embed-heavy collections — the dump's dominant memory cost. The
         # propagation-key values are captured as the cursor streams and published
         # into @state once the pass completes (see StreamingResult).
-        StreamingResult.new(view: view, collection: query.collection, keys: keys, state: @state)
+        StreamingResult.new(view: view, collection: query.collection, keys: keys, state: @state, timeout_ms: query.timeout_ms)
       end
 
       # NOTE: relies on @embedded_children_by_parent set by a prior build_query
@@ -233,7 +239,7 @@ module Exwiw
         @logger.debug("  Running explain (verbosity=#{verbosity}) on '#{query.collection}': filter=#{query.filter.inspect}")
 
         result = db[query.collection]
-          .find(query.filter)
+          .find(query.filter, find_timeout_opts(query))
           .projection(query.projection)
           .comment(query_comment_text("collection=#{query.collection}"))
           .explain(verbosity: verbosity)
@@ -360,6 +366,16 @@ module Exwiw
         false
       end
 
+      # Per-operation find options carrying the collection's CSOT timeout. An
+      # empty hash when the query has none, so the operation inherits the
+      # client-wide global timeout (or runs untimed if that is also unset). The
+      # find view's :timeout_ms governs the whole cursor lifetime — initial batch
+      # plus every getMore the streaming dump walks — which is what makes it the
+      # right cap for an accidentally heavy/unscoped extraction.
+      private def find_timeout_opts(query)
+        query.timeout_ms ? { timeout_ms: query.timeout_ms } : {}
+      end
+
       private def reject_filter!(config)
         return if config.filter.nil? || config.filter.to_s.empty?
 
@@ -670,14 +686,14 @@ module Exwiw
               # given, overrides the database in the URI path; otherwise the
               # URI's own database is used. The URI is never logged (it may carry
               # credentials).
-              client_options = {}
+              client_options = global_timeout_options
               if @connection_config.database_name && !@connection_config.database_name.to_s.empty?
                 client_options[:database] = @connection_config.database_name
               end
               Mongo::Client.new(@connection_config.uri, **client_options)
             else
               address = "#{@connection_config.host}:#{@connection_config.port}"
-              options = { database: @connection_config.database_name }
+              options = global_timeout_options.merge(database: @connection_config.database_name)
               if @connection_config.user && !@connection_config.user.to_s.empty?
                 options[:user] = @connection_config.user
                 options[:password] = @connection_config.password
@@ -690,6 +706,15 @@ module Exwiw
       private def uri_connection?
         !@connection_config.uri.nil? && !@connection_config.uri.to_s.empty?
       end
+
+      # Client-level CSOT default applied to every operation on this connection
+      # (find cursor lifetime, count, executing explain). nil when no global
+      # timeout is configured, leaving the client untimed; a per-collection
+      # `query_timeout_ms` still overrides this per find/count.
+      private def global_timeout_options
+        timeout = @connection_config.mongodb_query_timeout_ms
+        timeout ? { timeout_ms: timeout } : {}
+      end
     end
   end
 end

data/lib/exwiw/cli.rb

@@ -37,6 +37,7 @@ module Exwiw
       scope_column
       parallel_workers
       explain_verbosity
+      mongodb_query_timeout_ms
     ].freeze
 
     # MongoDB explain verbosity levels (passed through to the server's explain
@@ -89,6 +90,7 @@ module Exwiw
       @insert_only = nil
       @after_insert_hook_path = nil
       @parallel_workers = nil
+      @mongodb_query_timeout_ms = nil
       @explain_verbosity = nil
       # 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.
@@ -113,6 +115,7 @@ module Exwiw
         password: @database_password,
         database_name: @database_name,
         uri: @connection_uri,
+        mongodb_query_timeout_ms: @mongodb_query_timeout_ms,
       )
 
       dump_target = DumpTarget.new(
@@ -178,6 +181,7 @@ module Exwiw
       resolve_ids_field!
       resolve_uri_option!
       resolve_parallel_workers!
+      resolve_mongodb_query_timeout_ms!
 
       if @subcommand == "explain"
         validate_explain_only!
@@ -331,6 +335,7 @@ module Exwiw
       @ids_field ||= config["ids_field"]
       @scope_column ||= config["scope_column"]
       @parallel_workers ||= parse_parallel_workers(config["parallel_workers"]) if config.key?("parallel_workers")
+      @mongodb_query_timeout_ms ||= parse_mongodb_query_timeout_ms(config["mongodb_query_timeout_ms"]) if config.key?("mongodb_query_timeout_ms")
       @explain_verbosity ||= config["explain_verbosity"]
     end
 
@@ -457,6 +462,38 @@ module Exwiw
       exit 1
     end
 
+    # `--mongodb-query-timeout-ms` sets the global, server-enforced CSOT timeout
+    # applied to every MongoDB query (find cursor lifetime, count, executing
+    # explain). It is mongodb-only (the SQL adapters shell out to their own
+    # clients) and must be a positive integer. A per-collection `query_timeout_ms`
+    # in the schema config overrides it. Runs after the adapter name is normalized
+    # so the family check is reliable.
+    private def resolve_mongodb_query_timeout_ms!
+      return if @mongodb_query_timeout_ms.nil?
+
+      if @database_adapter != "mongodb"
+        $stderr.puts "--mongodb-query-timeout-ms is only supported by the mongodb adapter"
+        exit 1
+      end
+
+      if @mongodb_query_timeout_ms < 1
+        $stderr.puts "--mongodb-query-timeout-ms must be a positive integer (got #{@mongodb_query_timeout_ms})"
+        exit 1
+      end
+    end
+
+    # Coerce a config-file `mongodb_query_timeout_ms` (YAML scalar) to Integer,
+    # matching the CLI flag's Integer coercion. A non-integer value is a config
+    # typo, so fail fast rather than silently dropping it.
+    private def parse_mongodb_query_timeout_ms(value)
+      return nil if value.nil?
+
+      Integer(value)
+    rescue ArgumentError, TypeError
+      $stderr.puts "config 'mongodb_query_timeout_ms' must be an integer (got #{value.inspect})"
+      exit 1
+    end
+
     private def validate_explain_only!
       rejected = []
       rejected << "--output-dir" unless @output_dir.nil?
@@ -591,6 +628,7 @@ module Exwiw
           @after_insert_hook_path = File.expand_path(v)
         end
         opts.on("--parallel-workers=N", Integer, "Fork N workers for the MongoDB dump's parallel schedule (mongodb + export only; N>=2 enables it, default is serial). Output is byte-identical to serial; falls back to serial where fork is unavailable.") { |v| @parallel_workers = v }
+        opts.on("--mongodb-query-timeout-ms=N", Integer, "Global server-enforced timeout (ms) for every MongoDB query (mongodb only). Aborts an accidentally heavy/unscoped query past the deadline. Overridden per collection by `query_timeout_ms` in the schema config.") { |v| @mongodb_query_timeout_ms = v }
         opts.on("--log-level=LEVEL", "Log level (debug, info). default is info") { |v| @log_level = v.to_sym }
 
         opts.on("--help", "Print this help") do

data/lib/exwiw/mongo_query.rb

@@ -2,14 +2,19 @@
 
 module Exwiw
   module MongoQuery
-    Find = Struct.new(:collection, :primary_key, :filter, :projection, keyword_init: true) do
+    # `timeout_ms` is the per-collection, server-enforced operation timeout (CSOT)
+    # applied when this query runs; nil falls back to the client-wide global
+    # (ConnectionConfig#mongodb_query_timeout_ms) or, if that is also unset, no
+    # timeout. Omitted from #to_h when nil so the historical 4-key query shape is
+    # unchanged for collections without a timeout.
+    Find = Struct.new(:collection, :primary_key, :filter, :projection, :timeout_ms, keyword_init: true) do
       def to_h
         {
           collection: collection,
           primary_key: primary_key,
           filter: filter,
           projection: projection,
-        }
+        }.tap { |h| h[:timeout_ms] = timeout_ms unless timeout_ms.nil? }
       end
     end
   end

data/lib/exwiw/mongodb_collection_config.rb

@@ -13,6 +13,13 @@ module Exwiw
     attribute :belongs_tos, array(BelongsTo)
     attribute :fields, array(MongodbField)
     attribute :bulk_insert_chunk_size, optional(Integer), skip_serializing_if_nil: true
+    # Per-collection server-enforced query timeout in milliseconds (CSOT). Applied
+    # to this collection's find (whole cursor lifetime), count, and an executing
+    # explain; overrides the global ConnectionConfig#mongodb_query_timeout_ms. Use
+    # it to give a known-large collection more headroom than the global default
+    # (or, conversely, to cap one that tends to run away). User-maintained — the
+    # generator never emits it, so #merge carries it forward across regeneration.
+    attribute :query_timeout_ms, optional(Integer), skip_serializing_if_nil: true
     attribute :ignore, Serdes::OptionalType.new(Serdes::ConcreteType.new(Boolean)), skip_serializing_if_nil: true
     # Free-form note. Purely informational — exwiw never reads it — and preserved
     # across `MongoidSchemaGenerator` regeneration like the field / belongs_to
@@ -62,7 +69,8 @@ module Exwiw
     # - structural facts come from the freshly generated config: primary_key,
     #   belongs_tos, embedded_in.
     # - user customizations are kept from the receiver: filter, ignore,
-    #   bulk_insert_chunk_size, and each field's `replace_with` masking rule.
+    #   bulk_insert_chunk_size, query_timeout_ms, 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)
@@ -73,6 +81,7 @@ module Exwiw
         merged.primary_key = passed.primary_key
         merged.filter = filter
         merged.bulk_insert_chunk_size = bulk_insert_chunk_size
+        merged.query_timeout_ms = query_timeout_ms
         merged.ignore = ignore
         merged.ignore_type = ignore_type
         # A freshly generated comment (e.g. the skip_unsupported marker) wins so

data/lib/exwiw/query_ast_builder.rb

@@ -86,6 +86,28 @@ module Exwiw
         where_clauses.push(reverse_clause) if reverse_clause
       end
 
+      # Forward cascade. A satellite of a reverse_scope'd (or referenced-by-scoped)
+      # hub has no belongs_to path to the dump target, so the clauses above stay
+      # empty and it would dump every row. When its belongs_to parent is itself
+      # scoped, constrain this table to the parent's in-scope ids — the same
+      # multi-hop cascade scope-column mode performs in build_scoped.
+      if table.name != dump_target.table_name &&
+         where_clauses.empty? && join_clauses.empty? &&
+         forward_scope_allowed?(table)
+        parent_clause = build_belongs_to_scoped_clause(table)
+        if parent_clause
+          where_clauses.push(parent_clause)
+        elsif @allow_reverse && @forward_path.empty? && !scope_exempt?(table) &&
+              scopable_parent_candidates(table).size > 1
+          @logger.warn(
+            "  #{table.name} belongs_to multiple scopable parents; the cascade cannot " \
+            "pick one unambiguously, so it is dumped in full. If this is intended, set " \
+            "`scope_exempt: true`. Otherwise, scope it through a single parent (e.g. ignore one belongs_to edge), " \
+            "or switch to scope-column mode to scope it directly."
+          )
+        end
+      end
+
       QueryAst::Select.new.tap do |ast|
         ast.from(table.name)
         if table.rails_managed?
@@ -290,48 +312,18 @@ 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.
+    # 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. Used by both scope-column and single-target mode.
     private def build_belongs_to_scoped_clause(table)
-      # This table plus every ancestor currently being forward-resolved. A
-      # candidate parent already on this path would close a belongs_to cycle, so
-      # it is skipped; threading the grown path into the parent build lets the
-      # cascade recurse N hops (users -> end_users -> end_user_profiles -> ...)
-      # and terminate only when a table reappears.
-      forward_path = @forward_path + [table.name]
-
-      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?
-
-        # Cycle guard: descending into a parent already on the forward path would
-        # loop (a -> b -> a). Stop, leaving this table on the :unscopable path.
-        next if forward_path.include?(parent.name)
-
-        # Build the parent's own scoped query. allow_reverse stays true so the
-        # parent may be scoped via referenced_by, and forward scoping stays
-        # enabled so a parent that is itself scoped via *its* parent resolves
-        # too — this is what makes the cascade multi-hop.
-        parent_query = self.class.run(parent.name, table_by_name, dump_target, @logger, allow_reverse: true, forward_path: forward_path)
-
-        # 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
+      candidates = scopable_parent_candidates(table)
 
       # Only the unambiguous single-parent case. Multiple scopable parents would
       # need their subqueries combined (not supported); fall back to unscopable.
@@ -360,6 +352,45 @@ module Exwiw
       )
     end
 
+    # The scopable belongs_to parents of `table`: each non-polymorphic parent
+    # whose own extraction query comes out constrained, paired with the relation
+    # and that query. Shared by build_belongs_to_scoped_clause (which requires
+    # exactly one) and the single-target full-dump warning (which flags two or
+    # more, since the cascade then cannot disambiguate).
+    private def scopable_parent_candidates(table)
+      # Memoized: #run can resolve this twice for the same table (once via
+      # build_belongs_to_scoped_clause, once for the ambiguous-parent warning),
+      # and each pass recursively builds every parent's query.
+      (@scopable_parent_candidates ||= {})[table.name] ||= begin
+        # This table plus every ancestor currently being forward-resolved; a
+        # candidate parent already on this path would close a belongs_to cycle, so
+        # it is skipped. Threading the grown path into the parent build lets the
+        # cascade recurse N hops and terminate only when a table reappears.
+        forward_path = @forward_path + [table.name]
+
+        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.
+          next if relation.polymorphic?
+
+          parent = table_by_name[relation.table_name]
+          next if parent.nil?
+          next if forward_path.include?(parent.name)
+
+          # allow_reverse and forward scoping stay enabled so the parent may itself
+          # be scoped via referenced_by or via *its* parent — this is what makes the
+          # cascade multi-hop.
+          parent_query = self.class.run(parent.name, table_by_name, dump_target, @logger, allow_reverse: true, forward_path: forward_path)
+
+          # 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
+      end
+    end
+
     private def build_where_clauses(table, dump_target)
       clauses = []
 

data/lib/exwiw/version.rb

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

data/lib/exwiw.rb

@@ -56,5 +56,13 @@ module Exwiw
   # 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,
   # replica_set, auth_source, etc. can be expressed via the URI's query string.
-  ConnectionConfig = Struct.new(:adapter, :host, :port, :user, :password, :database_name, :uri, keyword_init: true)
+  #
+  # `mongodb_query_timeout_ms` is the global, server-enforced operation timeout
+  # (CSOT `timeout_ms`) applied to every MongoDB query exwiw issues — the find
+  # cursor's whole lifetime, the count, and an executing `explain`. It guards
+  # against an accidentally heavy/unscoped query pinning the (often production)
+  # source: the server aborts the operation past the deadline. nil leaves it
+  # unset (no timeout). A per-collection `query_timeout_ms` overrides it.
+  # mongodb adapter only.
+  ConnectionConfig = Struct.new(:adapter, :host, :port, :user, :password, :database_name, :uri, :mongodb_query_timeout_ms, keyword_init: true)
 end

metadata

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