exwiw 0.5.1 → 0.5.3

data/lib/exwiw/adapter/mongodb_adapter.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'set'
 
 # NOTE: This adapter consumes MongodbCollectionConfig (`fields` instead of
 # `columns`, plus `embedded_in`). Top-level collections are dumped as one
@@ -13,6 +14,57 @@ module Exwiw
         Exwiw::MongodbCollectionConfig
       end
 
+      # A lazy, streaming stand-in for the materialized result array #execute
+      # used to return. Wrapping the Mongo cursor (instead of `.to_a`) keeps the
+      # dump's dominant memory cost — the full result set — off the heap: the
+      # Runner pulls documents through `each_slice`, so at most one chunk of
+      # documents (plus the small propagation-key arrays) is resident at a time,
+      # even for large or embed-heavy collections.
+      #
+      # It satisfies the two things the Runner asks of an execute result:
+      #   - #size: the record count, used to skip empty collections and to log.
+      #     Answered with a `count_documents` query (which only walks index
+      #     entries, far cheaper than fetching every document) rather than by
+      #     draining the cursor.
+      #   - #each (via Enumerable / each_slice): a single streaming pass over the
+      #     cursor. While streaming it captures — per propagation key, BEFORE
+      #     handing the document to the caller's masking — the values downstream
+      #     children will `$in`-match against, publishing them into @state once
+      #     the pass completes.
+      #
+      # Contract note: unlike the old `.to_a` execute, which populated @state
+      # eagerly, this defers state capture until the result is consumed. The
+      # Runner always fully consumes a non-empty result before any child
+      # collection is processed, so propagation is unaffected; a caller that only
+      # needs @state must iterate the result (e.g. `.to_a`).
+      class StreamingResult
+        include Enumerable
+
+        def initialize(view:, collection:, keys:, state:)
+          @view = view
+          @collection = collection
+          @keys = keys
+          @state = state
+        end
+
+        def size
+          @size ||= @view.count_documents
+        end
+        alias length size
+
+        def each
+          return enum_for(:each) { size } unless block_given?
+
+          captured = @keys.each_with_object({}) { |key, acc| acc[key] = [] }
+          @view.each do |doc|
+            @keys.each { |key| captured[key] << doc[key] }
+            yield doc
+          end
+          @state[@collection] = captured
+          self
+        end
+      end
+
       def initialize(connection_config, logger)
         super
         @state = {}
@@ -71,16 +123,7 @@ module Exwiw
               { config.primary_key => { "$in" => coerce_ids(dump_target.ids) } }
             end
           else
-            config.belongs_tos.each_with_object({}) do |relation, acc|
-              # Constrain by the parent field this FK actually references
-              # (`relation.references`, default the parent primary_key). The
-              # values were captured from that field's documents in #execute, so
-              # their BSON type already matches the stored FK — no coercion.
-              values = parent_state_for(relation, config_by_name)
-              next if values.nil? || values.empty?
-
-              acc[relation.foreign_key] = { "$in" => values }
-            end
+            related_collection_filter(config, config_by_name)
           end
 
         Exwiw::MongoQuery::Find.new(
@@ -94,22 +137,24 @@ module Exwiw
       def execute(query)
         @logger.debug("  Executing Mongo find on '#{query.collection}': filter=#{query.filter.inspect} projection=#{query.projection.inspect}")
 
-        docs = db[query.collection]
+        view = db[query.collection]
           .find(query.filter)
           .projection(query.projection)
           .comment(query_comment_text("collection=#{query.collection}"))
-          .to_a
 
-        # Stash, per referenced field, the values children will `$in`-match
-        # against. @propagation_keys is set by the build_query call for this same
+        # Per referenced field, the values children will `$in`-match against.
+        # @propagation_keys is set by the build_query call for this same
         # collection; fall back to the primary key if execute is driven without a
         # preceding build_query (e.g. in isolation from a test).
         keys = @propagation_keys || [query.primary_key]
-        @state[query.collection] = keys.each_with_object({}) do |key, acc|
-          acc[key] = docs.map { |doc| doc[key] }
-        end
 
-        docs
+        # Return a streaming view of the result set rather than `.to_a`-ing the
+        # whole collection into memory. The Runner pulls documents through
+        # `each_slice`, so only one chunk's worth is resident at a time even for
+        # 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)
       end
 
       # NOTE: relies on @embedded_children_by_parent set by a prior build_query
@@ -118,9 +163,9 @@ module Exwiw
       # to_bulk_insert (SQL adapters don't need it). Safe in Runner, fragile in
       # tests — call build_query first.
       def to_bulk_insert(rows, config)
+        plan = mask_plan(config)
         rows.map do |doc|
-          apply_replace_with!(doc, config)
-          apply_embedded_masking!(doc, config)
+          apply_mask_plan!(doc, plan)
           JSON.generate(extended_json(doc))
         end.join("\n")
       end
@@ -143,6 +188,20 @@ module Exwiw
         'jsonl'
       end
 
+      # Bound how many documents are serialized at once when a collection config
+      # carries no explicit bulk_insert_chunk_size. A MongoDB dump is one JSONL
+      # line per document and, without chunking, the Runner would materialize the
+      # entire collection's output as a single giant string while the full
+      # in-memory result set is still alive — doubling peak memory on large or
+      # embed-heavy collections. Chunking lets the Runner stream each slice to the
+      # file and release its serialized string (and the transient extended-JSON
+      # trees) before building the next.
+      DEFAULT_BULK_INSERT_CHUNK_SIZE = 1_000
+
+      def default_bulk_insert_chunk_size
+        DEFAULT_BULK_INSERT_CHUNK_SIZE
+      end
+
       def schema_output_extension
         'js'
       end
@@ -160,6 +219,14 @@ module Exwiw
 
         collections = ordered_tables.reject(&:embedded?)
 
+        # Index listing targets a specific collection, and MongoDB raises
+        # NamespaceNotFound (code 26) for one that does not exist. The schema may
+        # declare collections absent from this database (schema/DB drift, or a
+        # sparse dev DB), so resolve the set that actually exists up front and emit
+        # indexes only for those. `createCollection` is still emitted for every
+        # config below, so the target schema is created in full regardless.
+        existing_collections = db.database.collection_names.to_set
+
         File.open(output_path, 'w') do |file|
           file.puts("// Auto-generated by exwiw. Apply with: mongosh \"$MONGODB_URI\" #{File.basename(output_path)}")
           file.puts
@@ -172,6 +239,11 @@ module Exwiw
 
           collections.each do |config|
             name = config.name
+            unless existing_collections.include?(name)
+              @logger.debug("  Collection '#{name}' is not present in the source database; emitting no indexes.")
+              next
+            end
+
             indexes = db[name].indexes.to_a.reject { |idx| idx['name'] == '_id_' }
             indexes.each do |idx|
               key = idx['key']
@@ -274,6 +346,39 @@ module Exwiw
         ([config.primary_key] + referenced).uniq
       end
 
+      # Build the scoping filter for a non-target collection from its belongs_to
+      # parents' captured ids. Each belongs_to is constrained by the parent field
+      # the FK references (`relation.references`, default the parent primary_key);
+      # the values were captured from that field in #execute, so their BSON type
+      # already matches the stored FK — no coercion.
+      #
+      # A belongs_to whose parent produced no ids contributes no constraint:
+      # either the parent matched nothing, or it is not dumped here (e.g. an
+      # embedded collection, or one excluded from the run). If that leaves the
+      # filter empty even though the collection HAS belongs_to, the collection
+      # cannot be scoped from the dump target — and falling back to an empty `{}`
+      # filter would scan and dump the ENTIRE collection across every scope. That
+      # is never what a scoped extraction wants, so constrain it to match nothing
+      # and warn instead. (A collection with no belongs_to at all is genuine
+      # reference/master data and is still dumped in full via `{}`.)
+      private def related_collection_filter(config, config_by_name)
+        filter = config.belongs_tos.each_with_object({}) do |relation, acc|
+          values = parent_state_for(relation, config_by_name)
+          next if values.nil? || values.empty?
+
+          acc[relation.foreign_key] = { "$in" => values }
+        end
+
+        return filter unless filter.empty? && config.belongs_tos.any?
+
+        @logger.warn(
+          "  Collection '#{config.name}' has belongs_to but no parent produced ids to scope by " \
+          "(parents matched nothing, or are not dumped on their own such as embedded collections). " \
+          "Constraining it to match no rows to avoid an unscoped full-collection dump."
+        )
+        { config.primary_key => { "$in" => [] } }
+      end
+
       # The captured parent-collection values a child belongs_to should be
       # constrained by: the values of the parent field the FK references
       # (`relation.references`, default the parent primary_key). nil when the
@@ -287,41 +392,101 @@ module Exwiw
         parent_fields[reference_field]
       end
 
-      private def apply_replace_with!(doc, config)
-        config.fields.each do |field|
+      # A masking plan compiled once per collection config and reused for every
+      # document of that collection. `masked_fields` is `[field_name,
+      # template_segments]` for each field carrying a `replace_with`;
+      # `embedded` is one EmbeddedMask per embedded child.
+      MaskPlan = Struct.new(:masked_fields, :embedded)
+
+      # A pre-resolved embedded-child mask: the parent path split once into
+      # `prefix` (the containers to descend into) and `last` (the field holding
+      # the subdocument(s)), plus the child's own MaskPlan.
+      EmbeddedMask = Struct.new(:prefix, :last, :plan)
+
+      # Build (or fetch) the cached MaskPlan for `config`. Masking runs over every
+      # document AND every embedded subdocument, so for an embed-heavy collection
+      # the same per-config decisions — which fields carry a `replace_with`, how
+      # each template splits into segments, where the embedded children live —
+      # were previously recomputed tens of times per document. Compiling them once
+      # per config lets #apply_mask_plan! do nothing but the work that actually
+      # varies per document (rendering templates, descending into subdocuments),
+      # so the saved per-subdocument overhead scales down with embedding count.
+      #
+      # Cached by config name: names are unique within a run and the configs do
+      # not mutate mid-dump. Relies on @embedded_children_by_parent, set by the
+      # build_query call that always precedes to_bulk_insert (see #to_bulk_insert).
+      private def mask_plan(config)
+        (@mask_plans ||= {})[config.name] ||= build_mask_plan(config)
+      end
+
+      private def build_mask_plan(config)
+        masked_fields = config.fields.each_with_object([]) do |field, acc|
           next unless field.replace_with
 
-          doc[field.name] = field.replace_with.gsub(/\{([^{}]+)\}/) do
-            ref = Regexp.last_match(1)
-            (doc.key?(ref) ? doc[ref] : nil).to_s
-          end
+          acc << [field.name, compile_template(field.replace_with)]
+        end
+        embedded = embedded_children_of(config).map do |child|
+          *prefix, last = child.embedded_in.path.split(".")
+          EmbeddedMask.new(prefix, last, build_mask_plan(child))
         end
+        MaskPlan.new(masked_fields, embedded)
       end
 
-      private def apply_embedded_masking!(doc, parent_config)
-        embedded_children_of(parent_config).each do |child|
-          walk(doc, child.embedded_in.path) do |subdoc|
-            apply_replace_with!(subdoc, child)
-            apply_embedded_masking!(subdoc, child)
+      # Apply a precompiled MaskPlan to a document in place: render each masked
+      # field, then descend into each embedded child (recursing into its own
+      # plan). Equivalent to the old apply_replace_with! + apply_embedded_masking!
+      # pair, with all per-config lookups hoisted into the plan.
+      private def apply_mask_plan!(doc, plan)
+        plan.masked_fields.each do |name, segments|
+          doc[name] = render_template(segments, doc)
+        end
+        plan.embedded.each do |child|
+          container = child.prefix.reduce(doc) { |acc, seg| acc.is_a?(Hash) ? acc[seg] : nil }
+          next unless container.is_a?(Hash)
+
+          case (value = container[child.last])
+          when Array then value.each { |sub| apply_mask_plan!(sub, child.plan) if sub.is_a?(Hash) }
+          when Hash  then apply_mask_plan!(value, child.plan)
           end
         end
       end
 
-      private def embedded_children_of(parent_config)
-        @embedded_children_by_parent.fetch(parent_config.name, [])
+      PLACEHOLDER_PATTERN = /\{([^{}]+)\}/
+
+      # Split a `replace_with` template into a flat list of segments (called once
+      # per masked field at plan-build time, see #build_mask_plan). A segment is
+      # either a literal String or a 1-element Array `[ref]` marking a `{ref}`
+      # placeholder. #render_template then concatenates them, skipping the regex
+      # scan / block / `Regexp.last_match` a per-document `gsub` would repeat (~2.5x
+      # faster per field). The segment walk reproduces the old gsub byte-for-byte
+      # (missing keys render as "", literals pass through unchanged).
+      private def compile_template(template)
+        segments = []
+        pos = 0
+        while (md = PLACEHOLDER_PATTERN.match(template, pos))
+          segments << template[pos...md.begin(0)] if md.begin(0) > pos
+          segments << [md[1]]
+          pos = md.end(0)
+        end
+        segments << template[pos..] if pos < template.length
+        segments
       end
 
-      private def walk(doc, dotted_path)
-        segments = dotted_path.split(".")
-        *prefix, last = segments
-        container = prefix.reduce(doc) { |acc, seg| acc.is_a?(Hash) ? acc[seg] : nil }
-        return unless container.is_a?(Hash)
-
-        value = container[last]
-        case value
-        when Array then value.each { |sub| yield sub if sub.is_a?(Hash) }
-        when Hash  then yield value
+      private def render_template(segments, doc)
+        out = +''
+        segments.each do |seg|
+          if seg.is_a?(Array)
+            ref = seg[0]
+            out << (doc.key?(ref) ? doc[ref] : nil).to_s
+          else
+            out << seg
+          end
         end
+        out
+      end
+
+      private def embedded_children_of(parent_config)
+        @embedded_children_by_parent.fetch(parent_config.name, [])
       end
 
       private def extended_json(doc)

data/lib/exwiw/adapter/postgresql_adapter.rb

@@ -65,7 +65,18 @@ module Exwiw
           ext_ddl = extensions.map do |extname, schema|
             stmt = "CREATE EXTENSION IF NOT EXISTS #{connection.quote_ident(extname)}"
             stmt += " SCHEMA #{connection.quote_ident(schema)}" unless schema == "public"
-            "DO $$ BEGIN #{stmt}; EXCEPTION WHEN feature_not_supported THEN NULL; END $$;"
+            # Best-effort prepend: a restore target that genuinely cannot create the
+            # extension should not abort the whole restore. Two such cases are caught:
+            #   feature_not_supported (0A000) -- the extension's binaries are unavailable
+            #   invalid_schema_name   (3F000) -- the extension's required schema is absent
+            # insufficient_privilege (42501) is deliberately NOT caught: a restore role
+            # lacking CREATE privilege is a misconfiguration to fix, not to skip silently.
+            # The skip is re-raised as a WARNING so it surfaces in the restore logs
+            # instead of vanishing.
+            warning = connection.escape_literal("exwiw: skipped CREATE EXTENSION #{extname} (SQLSTATE %): %")
+            "DO $$ BEGIN #{stmt}; " \
+              "EXCEPTION WHEN feature_not_supported OR invalid_schema_name THEN " \
+              "RAISE WARNING #{warning}, SQLSTATE, SQLERRM; END $$;"
           end.join("\n") + "\n\n"
           @logger.debug("  Found #{extensions.size} extension(s) to prepend.")
           stdout = ext_ddl + stdout
@@ -382,11 +393,17 @@ module Exwiw
       end
 
       private def query_extensions
+        # Skip plpgsql (always present) and managed-platform bookkeeping extensions
+        # (google_*/rds_*/aiven_*). pglogical is also skipped: it is a logical-
+        # replication mechanism of the source, not part of the data being copied,
+        # and its dedicated `pglogical` schema is typically absent on the restore
+        # target — so prepending CREATE EXTENSION for it only breaks the restore.
         sql = <<~SQL
           SELECT e.extname, n.nspname
           FROM pg_extension e
           JOIN pg_namespace n ON n.oid = e.extnamespace
           WHERE e.extname != 'plpgsql'
+            AND e.extname != 'pglogical'
             AND e.extname NOT LIKE 'google\\_%' ESCAPE '\\'
             AND e.extname NOT LIKE 'rds\\_%' ESCAPE '\\'
             AND e.extname NOT LIKE 'aiven\\_%' ESCAPE '\\'

data/lib/exwiw/adapter.rb

@@ -113,6 +113,16 @@ module Exwiw
         raise NotImplementedError, "COPY format is not supported by #{self.class.name}"
       end
 
+      # Default bulk-insert chunk size when a table config does not set one.
+      # The Runner streams each chunk straight to the output file, so a non-nil
+      # value here bounds how much serialized output (and how many transient
+      # intermediate objects) live in memory at once. SQL adapters keep nil
+      # (one statement per table, as before); adapters whose output is large
+      # and built per-row (e.g. MongoDB JSONL) override with a positive value.
+      def default_bulk_insert_chunk_size
+        nil
+      end
+
       # Run the database-specific EXPLAIN for the given query and return the
       # output as a single string for `explain` subcommand to print.
       # SQL adapters override; MongodbAdapter currently raises.

data/lib/exwiw/determine_table_processing_order.rb

@@ -1,35 +1,58 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Exwiw
   module DetermineTableProcessingOrder
     module_function
 
     # @param tables [Array<Exwiw::TableConfig>] tables
+    # @param logger [Logger, nil] receives a warning when a cycle has to be broken
     # @return [Array<String>] sorted table names
-    def run(tables)
+    def run(tables, logger: nil)
       return tables.map(&:name) if tables.size < 2
 
       ordered_table_names = []
+      ordered = Set.new
 
       table_by_name = tables.each_with_object({}) do |table, acc|
         acc[table.name] = table
       end
 
+      # Only belongs_to relations whose target is also in this run constrain the
+      # order. A belongs_to pointing at a table that is not being processed here
+      # — e.g. an embedded MongoDB collection (masked through its parent, never
+      # dumped on its own) or any table excluded from the run — is not something
+      # we can or need to order against, so it must never block resolution.
+      # Without this, such a dependency would stay unresolved forever and
+      # masquerade as a circular dependency, freezing every table that
+      # (transitively) references it.
+      present_names = table_by_name.keys.to_set
+
       loop do
         break if table_by_name.empty?
 
-        tables_with_no_dependencies = table_by_name.values.select do |table|
-          not_resolved_names = compute_table_dependencies(table) - ordered_table_names - [table.name]
-
-          not_resolved_names.empty?
+        resolvable = table_by_name.values.select do |table|
+          unresolved_dependencies(table, present_names, ordered).empty?
         end
 
-        if tables_with_no_dependencies.empty?
-          raise ArgumentError, build_cycle_error_message(table_by_name, ordered_table_names)
+        if resolvable.empty?
+          # No table has all its (in-run) dependencies satisfied, yet tables
+          # remain: the belongs_to graph has a genuine cycle and no strict
+          # topological order exists. Rather than aborting the whole export, break
+          # the cycle by emitting one cycle member; see pick_cycle_victim for how
+          # the member is chosen. Warn so the dropped constraint is visible.
+          victim = pick_cycle_victim(table_by_name.values, present_names, ordered)
+          warn_cycle_break(logger, victim, unresolved_dependencies(victim, present_names, ordered))
+          resolvable = [victim]
         end
 
-        tables_with_no_dependencies.each do |table|
+        # In the normal (acyclic) path, emit every currently-resolvable table in
+        # insertion order — preserving the historical ordering the snapshot specs
+        # depend on. The cycle-break path emits exactly its single chosen victim.
+        resolvable.each do |table|
           ordered_table_names << table.name
+          ordered << table.name
           table_by_name.delete(table.name)
         end
       end
@@ -37,30 +60,124 @@ module Exwiw
       ordered_table_names
     end
 
+    # The belongs_to target table names of `table`. A polymorphic belongs_to is
+    # expanded into one entry per concrete target by schema generation, so each
+    # entry is a plain table name here.
     def compute_table_dependencies(table)
-      table.belongs_tos.each_with_object([]) do |relation, acc|
-        acc << relation.table_name
+      table.belongs_tos.map(&:table_name)
+    end
+
+    # The dependencies still blocking `table`: belongs_to targets that are part
+    # of this run, not yet ordered, and not the table itself (a self-referential
+    # belongs_to never blocks).
+    private_class_method def unresolved_dependencies(table, present_names, ordered)
+      compute_table_dependencies(table).uniq.select do |dep|
+        present_names.include?(dep) && !ordered.include?(dep) && dep != table.name
       end
     end
 
-    # When no table can be resolved but some remain, the belongs_to graph
-    # contains a cycle (e.g. A belongs_to B and B belongs_to A). A topological
-    # order cannot exist, so report the offending tables instead of looping
-    # forever.
-    private_class_method def cycle_diagnostics(table_by_name, ordered_table_names)
-      table_by_name.values.map do |table|
-        unresolved = (compute_table_dependencies(table) - ordered_table_names - [table.name]).uniq
-        "  #{table.name} -> #{unresolved.join(', ')}"
+    # Choose the next table to emit when the order is stuck in a cycle. Only
+    # genuine cycle members are eligible — a table in a non-trivial
+    # strongly-connected component of the unresolved-dependency subgraph — so an
+    # acyclic table that merely waits on a cycle is never reordered ahead of its
+    # parent. Among the members, prefer one that still has at least one
+    # already-ordered parent, so its extraction stays constrained instead of
+    # collapsing to "match every row" (a cross-scope over-extraction risk for the
+    # mongodb adapter); break remaining ties by fewest unresolved dependencies,
+    # then by name, for determinism.
+    private_class_method def pick_cycle_victim(remaining, present_names, ordered)
+      adjacency = remaining.each_with_object({}) do |table, acc|
+        acc[table.name] = unresolved_dependencies(table, present_names, ordered)
+      end
+      cyclic_names = strongly_connected_members(adjacency)
+
+      candidates = remaining.select { |table| cyclic_names.include?(table.name) }
+      candidates = remaining if candidates.empty? # defensive; a stall implies a cycle
+
+      anchored = candidates.select { |table| ordered_parent?(table, present_names, ordered) }
+      pool = anchored.empty? ? candidates : anchored
+
+      pool.min_by { |table| [unresolved_dependencies(table, present_names, ordered).size, table.name] }
+    end
+
+    # True when `table` has a belongs_to whose target was already ordered, so its
+    # extraction filter will be constrained rather than an unscoped full scan.
+    private_class_method def ordered_parent?(table, present_names, ordered)
+      compute_table_dependencies(table).any? do |dep|
+        dep != table.name && present_names.include?(dep) && ordered.include?(dep)
       end
     end
 
-    private_class_method def build_cycle_error_message(table_by_name, ordered_table_names)
-      "Circular belongs_to dependency detected among tables: " \
-        "#{table_by_name.keys.sort.join(', ')}. " \
-        "A processing order cannot be determined. " \
-        "Remove one of the belongs_to entries forming the cycle.\n" \
-        "Unresolved dependencies:\n" \
-        "#{cycle_diagnostics(table_by_name, ordered_table_names).join("\n")}"
+    # Names belonging to a non-trivial strongly-connected component (size > 1) of
+    # `adjacency` (table name -> unresolved dependency names), i.e. the genuine
+    # cycle participants. Iterative Tarjan; nodes and edges are visited in name
+    # order so the result is deterministic. Self-edges are already excluded from
+    # the adjacency, so a size-1 component is never a cycle.
+    private_class_method def strongly_connected_members(adjacency)
+      index = {}
+      low = {}
+      on_stack = {}
+      stack = []
+      counter = 0
+      members = Set.new
+      neighbors = adjacency.each_with_object({}) { |(name, deps), acc| acc[name] = deps.sort }
+
+      adjacency.keys.sort.each do |start|
+        next if index.key?(start)
+
+        work = [[start, 0]]
+        until work.empty?
+          node, edge_i = work.last
+          if edge_i.zero?
+            index[node] = counter
+            low[node] = counter
+            counter += 1
+            stack.push(node)
+            on_stack[node] = true
+          end
+
+          adj = neighbors[node] || []
+          if edge_i < adj.size
+            work.last[1] += 1
+            w = adj[edge_i]
+            next unless adjacency.key?(w) # ignore edges leaving the remaining set
+
+            if index.key?(w)
+              low[node] = [low[node], index[w]].min if on_stack[w]
+            else
+              work.push([w, 0])
+            end
+          else
+            if low[node] == index[node]
+              component = []
+              loop do
+                w = stack.pop
+                on_stack[w] = false
+                component << w
+                break if w == node
+              end
+              members.merge(component) if component.size > 1
+            end
+            work.pop
+            low[work.last[0]] = [low[work.last[0]], low[node]].min unless work.empty?
+          end
+        end
+      end
+
+      members
+    end
+
+    private_class_method def warn_cycle_break(logger, victim, dropped)
+      return if logger.nil?
+
+      logger.warn(
+        "Circular belongs_to dependency detected. Breaking it by ordering " \
+        "'#{victim.name}' before its parent table(s): #{dropped.join(', ')}. The dropped " \
+        "relationship is not enforced while ordering, so '#{victim.name}' is extracted " \
+        "without that parent constraint (the mongodb adapter may then match a superset of " \
+        "rows; SQL output may not load in foreign-key order). To break the cycle explicitly " \
+        "instead, mark one of the belongs_to entries forming it with `ignore: true`."
+      )
     end
   end
 end

data/lib/exwiw/explain_runner.rb

@@ -30,7 +30,7 @@ module Exwiw
       QueryAstBuilder.validate_scope!(dumpable_configs, table_by_name, @dump_target, @logger)
 
       @logger.debug("Determining table processing order...")
-      ordered_table_names = DetermineTableProcessingOrder.run(dumpable_configs)
+      ordered_table_names = DetermineTableProcessingOrder.run(dumpable_configs, logger: @logger)
 
       total_size = ordered_table_names.size
       ordered_table_names.each_with_index do |table_name, idx|