exwiw 0.9.24 → 1.1.0

data/lib/exwiw/adapter/sqlite_adapter.rb

@@ -137,64 +137,6 @@ module Exwiw
         end
       end
 
-      def to_bulk_delete(select_query_ast, table)
-        raise NotImplementedError unless select_query_ast.is_a?(Exwiw::QueryAst::Select)
-
-        sql = "DELETE FROM #{quote_table_name(select_query_ast.from_table_name)}"
-
-        if select_query_ast.join_clauses.empty?
-          # Ignore filter option, because bulk delete is for cleaning before import,
-          # so it should delete all records to avoid foreign key violation & data consistancy.
-          compiled_where_conditions = select_query_ast.
-            where_clauses.
-            select { |where| where.is_a?(Exwiw::QueryAst::WhereClause) }.
-            map do |where|
-            compile_where_condition(where, select_query_ast.from_table_name)
-          end
-
-          if compiled_where_conditions.size > 0
-            sql += "\nWHERE "
-            sql += compiled_where_conditions.join(' AND ')
-          end
-          sql += ";"
-
-          return sql
-        end
-
-        subquery_ast = Exwiw::QueryAst::Select.new
-        first_join = select_query_ast.join_clauses.first.clone
-
-        subquery_ast.from(first_join.join_table_name)
-        primay_key_col = table.columns.find { |col| col.name == table.primary_key }
-        subquery_ast.select([primay_key_col])
-        select_query_ast.join_clauses[1..].each do |join|
-          subquery_ast.join(join)
-        end
-        first_join.where_clauses.each do |where|
-          # Ignore filter option, because bulk delete is for cleaning before import,
-          # so it should delete all records to avoid foreign key violation & data consistancy.
-          subquery_ast.where(where) if where.is_a?(Exwiw::QueryAst::WhereClause)
-        end
-
-        foreign_key = first_join.foreign_key
-        subquery_sql = compile_ast(subquery_ast)
-        sql += "\nWHERE #{qualified_name(select_query_ast.from_table_name, foreign_key)} IN (#{subquery_sql})"
-
-        # first_join.base_where_clauses holds conditions on the outer
-        # delete-target table (from_table_name), such as a polymorphic type
-        # column. They are not part of the subquery, so add them to the outer
-        # WHERE. This prevents deleting rows that belong to a different
-        # polymorphic type.
-        first_join.base_where_clauses.each do |where|
-          next unless where.is_a?(Exwiw::QueryAst::WhereClause)
-
-          sql += " AND #{compile_where_condition(where, select_query_ast.from_table_name)}"
-        end
-        sql += ";"
-
-        sql
-      end
-
       # @param count_only [Boolean] emit `SELECT COUNT(*)` instead of the
       #   projected columns (used by StreamingResult#size). Safe because exwiw's
       #   extraction queries have no DISTINCT/GROUP BY/LIMIT, so the count does

data/lib/exwiw/adapter.rb

@@ -82,11 +82,6 @@ module Exwiw
       def dump_schema(ordered_tables, output_path)
       end
 
-      # Whether this adapter emits delete-NNN-*.sql files.
-      def supports_bulk_delete?
-        true
-      end
-
       # Whether the given config produces its own dump output and needs an
       # independent processing pass. SQL adapters always do; non-SQL adapters
       # may exclude e.g. embedded subdocument configs.
@@ -339,12 +334,6 @@ module Exwiw
       raise NotImplementedError
     end
 
-    # @params [Exwiw::QueryAst] select_query_ast
-    # @params [Exwiw::TableConfig] table
-    def to_bulk_delete(select_query_ast, table)
-      raise NotImplementedError
-    end
-
     def self.build(connection_config, logger)
       case normalize_name(connection_config.adapter)
       when 'sqlite'

data/lib/exwiw/cli.rb

@@ -39,7 +39,6 @@ module Exwiw
       schema_dir
       output_dir
       output_format
-      insert_only
       after_insert_hook
       log_level
       target_table
@@ -58,6 +57,11 @@ module Exwiw
     EXPLAIN_VERBOSITIES = %w[queryPlanner executionStats allPlansExecution].freeze
     DEFAULT_EXPLAIN_VERBOSITY = "queryPlanner"
 
+    # Keys that configured behavior that no longer exists (insert_only toggled
+    # the removed delete-*.sql generation). Accepted so a committed config file
+    # keeps working across the upgrade, warned about so it gets cleaned up.
+    OBSOLETE_CONFIG_KEYS = %w[insert_only].freeze
+
     # Database connection settings are environment-specific (and sometimes
     # secret-adjacent), so they must be passed via CLI/env, never the committed
     # config file. `adapter` is the one connection-ish key allowed in config.
@@ -66,7 +70,7 @@ module Exwiw
     # Keys that only make sense for `export`. They are skipped when merging config
     # for `explain` so a shared config file does not trip validate_explain_only!,
     # and for `schema`, which performs no export at all.
-    EXPORT_ONLY_CONFIG_KEYS = %w[output_dir output_format insert_only after_insert_hook parallel_workers].freeze
+    EXPORT_ONLY_CONFIG_KEYS = %w[output_dir output_format after_insert_hook parallel_workers].freeze
 
     def self.start(argv)
       new(argv).run
@@ -111,11 +115,14 @@ module Exwiw
       @ids_field = nil
       @scope_column = nil
       @output_format = nil
-      @insert_only = nil
       @after_insert_hook_path = nil
       @parallel_workers = nil
       @mongodb_query_timeout_ms = nil
       @explain_verbosity = nil
+      # `schema check` only: which part of the report drives the exit code.
+      # nil (not "any") so validation can tell "user passed --fail-on" apart
+      # from the default when rejecting it on the other verbs.
+      @fail_on = 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.
       @log_level = nil
@@ -160,7 +167,6 @@ module Exwiw
           schema_dir: @schema_dir,
           dump_target: dump_target,
           output_format: @output_format,
-          insert_only: @insert_only,
           after_insert_hook_path: @after_insert_hook_path,
           parallel_workers: @parallel_workers,
           cli_options: build_cli_options_hash,
@@ -250,9 +256,33 @@ module Exwiw
 
       return if SchemaCheck.clean?(report)
 
-      $stderr.puts "exwiw: the schema config is out of date or has undecided masking; " \
-                   "run `exwiw schema generate --from-db` (then `exwiw schema tidy --from-db`) " \
-                   "and resolve every `needs_mask_decision` column."
+      # --fail-on=stale: a pre-extraction gate stops only on the drift that
+      # would break the export itself; the report above still carries the rest.
+      if @fail_on == "stale" && !SchemaCheck.stale?(report)
+        $stderr.puts "exwiw: the schema config has drifted, but nothing the extraction reads is stale " \
+                     "(--fail-on=stale); run `exwiw schema generate --from-db` at your leisure."
+        return
+      end
+
+      if SchemaCheck.stale?(report)
+        # Name what blocks the export, capped — a migration can drop dozens of
+        # columns, and the full list is in the report above.
+        stale = SchemaCheck::STALE_CATEGORIES.flat_map { |category| report.fetch(category, []) }
+        listed = stale.first(10)
+        listed << "and #{stale.size - listed.size} more (see the report)" if stale.size > listed.size
+        $stderr.puts "exwiw: the config still references #{listed.join(', ')} — gone from the database, " \
+                     "so an extraction SELECT would fail on them; " \
+                     "run `exwiw schema generate --from-db` (then `exwiw schema tidy --from-db`) to drop them."
+        # The default (CI) mode is a one-shot report; the gate deliberately
+        # stays quiet about mask decisions.
+        if @fail_on != "stale" && report.fetch("needs_mask_decision", []).any?
+          $stderr.puts "exwiw: the report also lists `needs_mask_decision` columns; resolve those too."
+        end
+      else
+        $stderr.puts "exwiw: the schema config is out of date or has undecided masking; " \
+                     "run `exwiw schema generate --from-db` (then `exwiw schema tidy --from-db`) " \
+                     "and resolve every `needs_mask_decision` column."
+      end
       exit SCHEMA_CHECK_DIRTY_EXIT
     end
 
@@ -333,7 +363,6 @@ module Exwiw
       if @subcommand == "export"
         @output_dir ||= "dump"
         @output_format ||= "insert"
-        @insert_only = @insert_only ? true : false
 
         valid_output_formats = ["insert", "copy"]
         unless valid_output_formats.include?(@output_format)
@@ -426,6 +455,10 @@ module Exwiw
           $stderr.puts "'#{key}' is a database connection setting and must be passed via the CLI/environment, not the config file (#{path})"
           exit 1
         end
+        if OBSOLETE_CONFIG_KEYS.include?(key)
+          $stderr.puts "warning: config key '#{key}' in #{path} is obsolete and ignored (exwiw no longer generates delete-*.sql files); remove it from the config file"
+          next
+        end
         unless ALLOWED_CONFIG_KEYS.include?(key)
           $stderr.puts "Unknown config key '#{key}' in #{path}. Allowed keys: #{ALLOWED_CONFIG_KEYS.join(', ')}"
           exit 1
@@ -443,7 +476,6 @@ module Exwiw
       @output_dir ||= expand_dir(config["output_dir"], base)
       @after_insert_hook_path ||= (File.expand_path(config["after_insert_hook"], base) if config["after_insert_hook"])
       @output_format ||= config["output_format"]
-      @insert_only = config["insert_only"] if @insert_only.nil? && config.key?("insert_only")
       @log_level ||= config["log_level"]&.to_sym
       @target_table_name ||= config["target_table"]
       @target_collection_name ||= config["target_collection"]
@@ -635,6 +667,15 @@ module Exwiw
         exit 1
       end
 
+      if @fail_on && @schema_verb != "check"
+        $stderr.puts "--fail-on only applies to `exwiw schema check` (got `exwiw schema #{@schema_verb}`)."
+        exit 1
+      end
+      if @fail_on && !%w[any stale].include?(@fail_on)
+        $stderr.puts "--fail-on must be 'any' or 'stale' (got '#{@fail_on}')."
+        exit 1
+      end
+
       unless DbIntrospector::SUPPORTED_ADAPTERS.include?(@database_adapter)
         $stderr.puts "--from-db supports the #{DbIntrospector::SUPPORTED_ADAPTERS.join(' and ')} adapters only " \
                      "(got '#{@database_adapter}'). sqlite and mongodb schemas are not read this way."
@@ -679,7 +720,6 @@ module Exwiw
       rejected = []
       rejected << "--output-dir" unless @output_dir.nil?
       rejected << "--output-format" unless @output_format.nil?
-      rejected << "--insert-only" unless @insert_only.nil?
       rejected << "--after-insert-hook" unless @after_insert_hook_path.nil?
       rejected << "--parallel-workers" unless @parallel_workers.nil?
 
@@ -744,7 +784,6 @@ module Exwiw
         ids_field: @ids_field,
         scope_column: @scope_column,
         output_format: @output_format,
-        insert_only: @insert_only,
         log_level: @log_level,
         after_insert_hook: @after_insert_hook_path,
       }.freeze
@@ -816,12 +855,15 @@ module Exwiw
         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("--scope-column=[COLUMN]", "DEPRECATED. Filter every table by this shared global column (--ids are its values) instead of a single --target-table. SQL adapters only; mutually exclusive with --target-table. Prefer declaring a per-table `scope_column:` in the schema config and running 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|
+        opts.on("--insert-only", "DEPRECATED: ignored. exwiw no longer generates delete-*.sql files, so every export is insert-only.") do
+          $stderr.puts "warning: --insert-only is obsolete and ignored (exwiw no longer generates delete-*.sql files); remove the flag"
+        end
+        opts.on("--after-insert-hook=PATH", "Path to a .rb or .sh post-processing hook executed after all insert files are written (export subcommand only)") do |v|
           @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("--fail-on=CATEGORY", "schema check only: what makes the exit code non-zero. 'any' (default) fails on any drift or undecided masking; 'stale' fails only when the committed config references tables/columns the schema no longer has - the drift that would break an export. The full report is printed either way.") { |v| @fail_on = 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/ddl_postprocessor.rb

@@ -58,10 +58,50 @@ module Exwiw
       end
     end
 
-    # pg_dump --table includes triggers but not the referenced function
-    # definitions, causing UndefinedFunction errors on the target DB.
-    def strip_triggers(sql)
-      sql.gsub(/^[ \t]*CREATE\s+(?:OR\s+REPLACE\s+)?(?:CONSTRAINT\s+)?TRIGGER\b[^;]*;\r?\n?/i, "")
+    # One trigger as pg_dump writes it: its header comment block ($1) followed by
+    # the `CREATE TRIGGER` statement ($2).
+    #
+    #   --
+    #   -- Name: users set_timestamp; Type: TRIGGER; Schema: public; Owner: -
+    #   --
+    #
+    #   CREATE TRIGGER set_timestamp BEFORE UPDATE ON public.users ...;
+    #
+    # The header is what keeps the pass off a `CREATE TRIGGER` line inside a
+    # dollar-quoted function body — a function that installs a trigger itself,
+    # whose meaning a rewrite would change. pg_dump never writes a header block
+    # inside a body, so requiring one limits the match to top-level statements.
+    # (The stripping pass this replaced matched the bare form and deleted such a
+    # line, leaving a function that compiled but installed nothing.)
+    #
+    # The statement ends at the first semicolon outside a single-quoted string, so
+    # a `;` in a WHEN clause or an argument (`EXECUTE FUNCTION f('a;b')`) does not
+    # truncate it. A trigger definition has no body, so no dollar quoting either.
+    CREATE_TRIGGER_RE = /
+      (^--\r?\n
+       --[ \t]+Name:[^\n]*;[ \t]*Type:[ \t]*TRIGGER;[^\n]*\r?\n
+       --\r?\n
+       (?:[ \t]*\r?\n)*)
+      ([ \t]*CREATE\s+(?:OR\s+REPLACE\s+)?(?:CONSTRAINT\s+)?TRIGGER\b
+       (?:[^;']|'(?:[^']|'')*')*;)
+    /xi.freeze
+
+    # A bare `CREATE TRIGGER ...;` is not idempotent (a second restore raises
+    # `duplicate_object`, 42710), so each statement goes into a DO block that
+    # swallows that error, in the form #wrap_add_constraint_in_do_block uses; the
+    # header is left as written. `CREATE OR REPLACE TRIGGER` would be shorter but
+    # is PostgreSQL 14+ only and pg_dump never emits it.
+    def wrap_create_trigger_in_do_block(sql)
+      sql.gsub(CREATE_TRIGGER_RE) do
+        header = Regexp.last_match(1)
+        stmt = Regexp.last_match(2).strip
+        <<~SQL.chomp
+          #{header}DO $exwiw$ BEGIN
+            #{stmt}
+          EXCEPTION WHEN duplicate_object THEN NULL;
+          END $exwiw$;
+        SQL
+      end
     end
 
     # A user@host pair as mysqldump writes it. Each side is independently a

data/lib/exwiw/query_ast_builder.rb

@@ -2,8 +2,8 @@
 
 module Exwiw
   class QueryAstBuilder
-    def self.run(table_name, table_by_name, dump_target, logger, allow_reverse: true, forward_path: [], batch_ids: nil)
-      new(table_name, table_by_name, dump_target, logger, allow_reverse: allow_reverse, forward_path: forward_path, batch_ids: batch_ids).run
+    def self.run(table_name, table_by_name, dump_target, logger, allow_reverse: true, allow_declared_reverse: true, forward_path: [], reverse_path: [], deep_chain_warned: nil, batch_ids: nil)
+      new(table_name, table_by_name, dump_target, logger, allow_reverse: allow_reverse, allow_declared_reverse: allow_declared_reverse, forward_path: forward_path, reverse_path: reverse_path, deep_chain_warned: deep_chain_warned, batch_ids: batch_ids).run
     end
 
     # Scope-column mode classification for a single table. One of
@@ -34,15 +34,25 @@ module Exwiw
       # Unscopable is reported before a bad batch_scope shape — it is the more
       # fundamental problem.
       if scope_mode?(table_by_name, dump_target)
+        # Keep each table's builder: classification records ambiguous_referencers,
+        # and this pre-flight message is what an operator actually reads.
         unscopable =
-          tables.reject(&:ignore).select do |table|
-            scope_category(table.name, table_by_name, dump_target, logger) == :unscopable
+          tables.reject(&:ignore).filter_map do |table|
+            builder = new(table.name, table_by_name, dump_target, logger)
+            next unless builder.scope_category == :unscopable
+
+            if builder.ambiguous_referencers
+              "#{table.name} (referenced by multiple constrained tables: " \
+                "#{builder.ambiguous_referencers} — declaring `reverse_scope` on it " \
+                "to union their ids is likely the fix)"
+            else
+              table.name
+            end
           end
 
         if unscopable.any?
-          names = unscopable.map(&:name).sort.join(", ")
           raise ArgumentError,
-                "scope-column mode: #{unscopable.size} table(s) cannot be scoped: #{names}. " \
+                "scope-column mode: #{unscopable.size} table(s) cannot be scoped: #{unscopable.sort.join(', ')}. " \
                 "For each, declare `scope_column: <column>` on the table to filter it directly, " \
                 "add a belongs_to path to a table that carries the scope column, mark it " \
                 "`scope_exempt: true` to export it in full, or set `ignore: true` to skip it."
@@ -58,7 +68,11 @@ module Exwiw
 
     attr_reader :table_name, :table_by_name, :dump_target
 
-    def initialize(table_name, table_by_name, dump_target, logger, allow_reverse: true, forward_path: [], batch_ids: nil)
+    # The multiple constrained referencers (comma-joined) that made the
+    # automatic reverse detection step aside, when it did.
+    attr_reader :ambiguous_referencers
+
+    def initialize(table_name, table_by_name, dump_target, logger, allow_reverse: true, allow_declared_reverse: true, forward_path: [], reverse_path: [], deep_chain_warned: nil, batch_ids: nil)
       @table_name = table_name
       @table_by_name = table_by_name
       @dump_target = dump_target
@@ -76,6 +90,19 @@ module Exwiw
       # table already on the path is not re-resolved, falling through to
       # :unscopable instead of looping forever.
       @forward_path = forward_path
+      # @reverse_path is the reverse counterpart: the chain of tables whose
+      # reverse resolution is in progress up the stack. It bounds the declared
+      # reverse_scope recursion — a table already being reverse-resolved is not
+      # resolved again, so a cycle of declarations terminates.
+      @reverse_path = reverse_path
+      # Whether this build may honor an explicit `reverse_scope` even though
+      # @allow_reverse is off: true for a reverse_scope arm build, false for the
+      # auto-detection's child builds (widening those would change the detection's
+      # candidate count and could bail a scoped table into a full dump).
+      @allow_declared_reverse = allow_declared_reverse
+      # Deep-chain warnings already emitted, keyed by chain path and shared (the
+      # same Hash) across every recursive build under one top-level run.
+      @deep_chain_warned = deep_chain_warned || {}
     end
 
     def run
@@ -91,9 +118,12 @@ module Exwiw
       # every row (see the "no relation -> dump all" case). If an extractable
       # child table references it via a foreign key (e.g. active_storage_blobs is
       # referenced by active_storage_attachments.blob_id), constrain it to just
-      # the referenced ids instead. Disabled (@allow_reverse=false) while building
-      # a child's subquery, so this never recurses.
-      if @allow_reverse && table.name != dump_target.table_name &&
+      # the referenced ids instead. The automatic detection is disabled
+      # (@allow_reverse=false) while building a child's subquery, so it never
+      # recurses; an explicit `reverse_scope` still applies inside a reverse_scope
+      # arm build (@allow_declared_reverse), with @reverse_path cutting cycles.
+      if (@allow_reverse || (@allow_declared_reverse && explicit_reverse_scope?(table))) &&
+         table.name != dump_target.table_name &&
          where_clauses.empty? && join_clauses.empty?
         reverse_clause = build_referenced_by_clause(table)
         where_clauses.push(reverse_clause) if reverse_clause
@@ -121,6 +151,19 @@ module Exwiw
         end
       end
 
+      # The reverse detection stepped aside on an ambiguity and nothing else
+      # scoped the table: at the top level of single-target mode that is a full
+      # dump, which must not happen at debug volume. Only the final outcome
+      # warns — a table the cascade rescued stays quiet.
+      if @ambiguous_referencers && where_clauses.empty? && join_clauses.empty? &&
+         @forward_path.empty? && @reverse_path.empty? && !scope_exempt?(table)
+        @logger.warn(
+          "  #{table.name} is referenced by multiple constrained tables (#{@ambiguous_referencers}), " \
+          "which the automatic reverse extraction cannot pick between, and nothing else scopes it — " \
+          "it is dumped in full. Declare `reverse_scope` on it to union their ids."
+        )
+      end
+
       QueryAst::Select.new.tap do |ast|
         ast.from(table.name)
         if table.rails_managed?
@@ -210,11 +253,20 @@ module Exwiw
       # the schema author has enumerated the referencers explicitly, constrain
       # the table to the UNION of those referencers' scoped queries instead of
       # the single-referencer auto-detection below (which bails to a full dump
-      # once two or more tables reference the table).
-      if table.reverse_scope && table.reverse_scope.via.any?
+      # once two or more tables reference the table). Unlike the auto-detection,
+      # this branch also runs during a reverse_scope arm build
+      # (@allow_declared_reverse); @reverse_path bounds the recursion.
+      if explicit_reverse_scope?(table)
+        return nil unless @allow_reverse || @allow_declared_reverse
+
         return build_reverse_scope_via_clause(table)
       end
 
+      # The automatic single-referencer detection is top-level only: during a
+      # subquery build it could recurse through a chain of FK-less tables that
+      # reference each other.
+      return nil unless @allow_reverse
+
       candidates = table_by_name.each_value.filter_map do |other|
         next if other.name == table.name
 
@@ -225,11 +277,12 @@ 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; adding this
-        # table to forward_path stops the child from forward-scoping back through
-        # it (which would loop) while still letting the child forward-scope
-        # through other tables.
-        child_query = self.class.run(other.name, table_by_name, dump_target, @logger, allow_reverse: false, forward_path: @forward_path + [table.name])
+        # chain of FK-less tables from recursing back into each other; the grown
+        # forward_path/reverse_path stop the child from scoping back through this
+        # table. allow_declared_reverse is OFF: a child scoped only by its own
+        # reverse_scope must stay unconstrained here, or it would widen the
+        # candidate set and could bail this detection out of a scope it had.
+        child_query = self.class.run(other.name, table_by_name, dump_target, @logger, allow_reverse: false, allow_declared_reverse: false, forward_path: @forward_path + [table.name], reverse_path: @reverse_path + [table.name], deep_chain_warned: @deep_chain_warned)
 
         # Only an *already constrained* child narrows anything; an unconstrained
         # child would select every fk value (i.e. dump all) and not help.
@@ -239,11 +292,14 @@ module Exwiw
       end
 
       # Scope: only the unambiguous single-referencer case. Multiple referencers
-      # would need their subqueries OR'd together (not yet supported); falling
-      # back to dump-all preserves today's behavior for those.
+      # would need `reverse_scope` to union them; falling back preserves today's
+      # behavior for those.
       if candidates.size != 1
         if candidates.size > 1
-          @logger.debug("  #{table.name} has multiple referencing tables; skipping reverse extraction (dump all).")
+          # Whether the ambiguity deserves a warning depends on the outcome —
+          # the forward cascade may still scope the table — so `run` decides.
+          @ambiguous_referencers = candidates.map { |_, query| query.from_table_name }.sort.join(', ')
+          @logger.debug("  #{table.name} has multiple referencing tables; skipping reverse extraction.")
         end
         return nil
       end
@@ -279,7 +335,33 @@ module Exwiw
     # every row's id and union the whole table back, silently defeating the
     # prune. Returns nil when no arm survives, leaving the caller to fall back to
     # the dump-all behavior (which validate_scope! then rejects in scope mode).
+    #
+    # A referencer that is itself scoped only by its own `reverse_scope` still
+    # resolves, so declared chains nest, with @reverse_path cutting cycles.
     private def build_reverse_scope_via_clause(table)
+      if @reverse_path.include?(table.name)
+        @logger.debug(
+          "  #{table.name}.reverse_scope is already being resolved " \
+          "(#{(@reverse_path + [table.name]).join(' -> ')}); cutting the cycle."
+        )
+        return nil
+      end
+
+      # Each level of a declared chain re-embeds its referencers' subqueries, so
+      # the generated SQL grows exponentially with depth; flag chains deeper than
+      # the intended 2-3. Deduped: this build repeats once per arm per level.
+      if @reverse_path.size >= 3
+        path = (@reverse_path + [table.name]).join(' -> ')
+        unless @deep_chain_warned[path]
+          @deep_chain_warned[path] = true
+          @logger.warn(
+            "  #{table.name}.reverse_scope is nested #{@reverse_path.size + 1} declarations deep " \
+            "(#{path}); the generated SQL grows exponentially with chain depth — consider scoping " \
+            "an intermediate table another way."
+          )
+        end
+      end
+
       arms = table.reverse_scope.via.filter_map do |via|
         referencer = table_by_name[via.table]
         if referencer.nil?
@@ -287,12 +369,11 @@ module Exwiw
           next
         end
 
-        # Build the referencer's own scoped extraction query. allow_reverse is
-        # disabled and this table is added to forward_path to bound recursion
-        # exactly as the single-referencer path does (a referencer that could only
-        # be scoped by recursing back into this table would loop); the referencer
-        # may still forward-scope through other tables.
-        ref_query = self.class.run(referencer.name, table_by_name, dump_target, @logger, allow_reverse: false, forward_path: @forward_path + [table.name])
+        # Build the referencer's own scoped extraction query. The automatic
+        # reverse detection stays off; the referencer may forward-scope through
+        # other tables and (allow_declared_reverse) resolve its own explicit
+        # reverse_scope, with the grown paths keeping it from coming back here.
+        ref_query = self.class.run(referencer.name, table_by_name, dump_target, @logger, allow_reverse: false, allow_declared_reverse: true, forward_path: @forward_path + [table.name], reverse_path: @reverse_path + [table.name], deep_chain_warned: @deep_chain_warned)
 
         unless ref_query.where_clauses.any? || ref_query.join_clauses.any?
           @logger.warn(
@@ -392,8 +473,9 @@ module Exwiw
 
           # 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)
+          # cascade multi-hop; reverse_path rides along to keep an in-progress
+          # reverse resolution from being re-entered.
+          parent_query = self.class.run(parent.name, table_by_name, dump_target, @logger, allow_reverse: true, forward_path: forward_path, reverse_path: @reverse_path, deep_chain_warned: @deep_chain_warned)
 
           # Only a constrained parent narrows anything; an unconstrained parent
           # would select every pk (i.e. dump all) and not help.
@@ -570,7 +652,7 @@ module Exwiw
         return ast
       end
 
-      if @allow_reverse
+      if @allow_reverse || (@allow_declared_reverse && explicit_reverse_scope?(table))
         # Referenced by an extractable (scoped) child: constrain via subquery.
         reverse_clause = build_referenced_by_clause(table)
         if reverse_clause
@@ -619,6 +701,11 @@ module Exwiw
       table.scope_exempt || table.rails_managed?
     end
 
+    # Whether the schema author declared how this table is reverse-scoped.
+    private def explicit_reverse_scope?(table)
+      !!(table.reverse_scope && table.reverse_scope.via.any?)
+    end
+
     private def directly_scoped?(table)
       column = resolved_scope_column(table)
       table.columns.any? { |c| c.name == column }
@@ -855,7 +942,7 @@ module Exwiw
 
       target_query = self.class.run(
         target.name, table_by_name, dump_target, @logger,
-        allow_reverse: true, forward_path: @forward_path + [table.name]
+        allow_reverse: true, forward_path: @forward_path + [table.name], reverse_path: @reverse_path, deep_chain_warned: @deep_chain_warned
       )
       # An unconstrained target selects every id, i.e. does not scope the arm at
       # all; dropping the arm is the safe outcome.
@@ -1041,11 +1128,22 @@ module Exwiw
     end
 
     private def scope_unscopable_message(table)
-      "Table '#{table.name}' cannot be scoped in scope-column mode: it carries no scope " \
+      message =
+        "Table '#{table.name}' cannot be scoped in scope-column mode: it carries no scope " \
         "column (no per-table `scope_column` is declared on it) and has no belongs_to path " \
         "to a table that does. Declare `scope_column: <column>` on it, mark it " \
         "`scope_exempt: true` to export it in full, set `ignore: true` to skip it, or add " \
         "the missing belongs_to."
+
+      # None of the generic options above is the right fix for the referencer
+      # ambiguity; give the same precise remedy the single-target warning gives.
+      if @ambiguous_referencers
+        message += " Note: it is referenced by multiple constrained tables " \
+                   "(#{@ambiguous_referencers}); declaring `reverse_scope` on it to union " \
+                   "their ids is likely the fix."
+      end
+
+      message
     end
   end
 end

data/lib/exwiw/runner.rb

@@ -11,7 +11,6 @@ module Exwiw
       dump_target:,
       logger:,
       output_format: 'insert',
-      insert_only: false,
       after_insert_hook_path: nil,
       parallel_workers: nil,
       cli_options: {}
@@ -21,7 +20,6 @@ module Exwiw
       @schema_dir = schema_dir
       @dump_target = dump_target
       @output_format = output_format
-      @insert_only = insert_only
       @after_insert_hook_path = after_insert_hook_path
       @parallel_workers = parallel_workers
       @cli_options = cli_options
@@ -105,8 +103,8 @@ module Exwiw
 
           # `batch_scope` splits the extraction into one query per slice of the
           # scope's id set, streaming rows like any adapter result. `query_ast`
-          # stays the unbatched query — the DELETE file and the error message
-          # below describe that one.
+          # stays the unbatched query — the error message below describes that
+          # one.
           phase = "resolving the batch_scope id set"
           batched = BatchedExtraction.build(
             adapter: adapter,
@@ -184,21 +182,6 @@ module Exwiw
 
             @logger.info("  Generated INSERT statement for #{record_num} records (#{statement_count} statement(s)).")
           end
-
-          if adapter.supports_bulk_delete? && !@insert_only && !(table.respond_to?(:rails_managed?) && table.rails_managed?)
-            phase = "generating DELETE statement"
-            @logger.debug("  Generate DELETE statement...")
-            delete_sql = adapter.to_bulk_delete(query_ast, table)
-            if @logger.debug?
-              @logger.debug("  Generated DELETE statement:\n#{delete_sql}")
-            else
-              @logger.info("  Generated DELETE statement.")
-            end
-            delete_idx = (total_size - idx).to_s.rjust(3, '0')
-            File.open(File.join(@output_dir, "delete-#{delete_idx}-#{table_name}.#{adapter.output_extension}"), 'w') do |file|
-              file.puts(delete_sql)
-            end
-          end
         rescue => e
           @logger.error("Error while #{phase} for table '#{table_name}' (#{idx + 1}/#{total_size}): #{e.class}: #{e.message}")
           @logger.error("  Extraction query that produced the data being processed:")