polyrun 1.0.0

data/lib/polyrun/data/cached_fixtures.rb

@@ -0,0 +1,122 @@
+module Polyrun
+  module Data
+    # Process-local memoization for expensive fixture setup (+register+ / +cached+).
+    # Use inside +before(:suite)+ or a support file so each parallel **process** builds once; not for threads
+    # without external locking (see {ParallelProvisioning}).
+    #
+    # Example:
+    #
+    #   Polyrun::Data::CachedFixtures.register(:admin) { User.create!(email: "a@example.com") }
+    #   Polyrun::Data::CachedFixtures.fetch(:admin) # => same object
+    #
+    module CachedFixtures
+      # :nodoc:
+      class Cache
+        attr_reader :store
+
+        def initialize
+          @store = {}
+          @stats = {}
+        end
+
+        def fetch(key, &block)
+          k = key.to_s
+          if store.key?(k)
+            @stats[k][:hits] += 1
+            return store[k]
+          end
+
+          t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          store[k] = yield
+          @stats[k] = {
+            build_time: Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0,
+            hits: 0
+          }
+          store[k]
+        end
+
+        def clear
+          store.clear
+          @stats.clear
+        end
+
+        def stats_snapshot
+          @stats.transform_values(&:dup)
+        end
+      end
+
+      # Mutable process-local state lives on a plain object so the singleton class avoids class ivars
+      # (ThreadSafety/ClassInstanceVariable); still one cache per process, not thread-safe for concurrent threads.
+      class Registry
+        attr_accessor :disabled
+        attr_reader :cache, :callbacks
+
+        def initialize
+          @disabled = false
+          @cache = Cache.new
+          @callbacks = {before_reset: [], after_reset: []}
+        end
+      end
+      private_constant :Registry
+
+      REGISTRY = Registry.new
+      private_constant :REGISTRY
+
+      class << self
+        def fetch(id, &block)
+          return yield if disabled?
+
+          REGISTRY.cache.fetch(id.to_s, &block)
+        end
+
+        alias_method :register, :fetch
+
+        def cached(id)
+          return unless REGISTRY.cache.store.key?(id.to_s)
+
+          REGISTRY.cache.store[id.to_s]
+        end
+
+        def reset!
+          REGISTRY.callbacks[:before_reset].each(&:call)
+          REGISTRY.cache.clear
+          REGISTRY.callbacks[:after_reset].each(&:call)
+          REGISTRY.callbacks[:before_reset].clear
+          REGISTRY.callbacks[:after_reset].clear
+        end
+
+        def before_reset(&block)
+          REGISTRY.callbacks[:before_reset] << block if block
+        end
+
+        def after_reset(&block)
+          REGISTRY.callbacks[:after_reset] << block if block
+        end
+
+        def disable!
+          REGISTRY.disabled = true
+        end
+
+        def enable!
+          REGISTRY.disabled = false
+        end
+
+        def disabled?
+          REGISTRY.disabled == true
+        end
+
+        def stats
+          REGISTRY.cache.stats_snapshot
+        end
+
+        def format_stats_report(title: "Polyrun cached fixtures")
+          lines = [title]
+          REGISTRY.cache.stats_snapshot.each do |key, s|
+            lines << format("  %-40s  build: %0.4fs  hits: %d", key, s[:build_time], s[:hits])
+          end
+          lines.join("\n") + "\n"
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/data/factory_counts.rb

@@ -0,0 +1,35 @@
+module Polyrun
+  module Data
+    # Lightweight per-example factory/build counters with zero dependencies.
+    # Call +reset!+ in +before(:suite)+ or +setup+, +record+ inside factory helpers, +summary+ in +after(:suite)+.
+    module FactoryCounts
+      class << self
+        def reset!
+          @counts = Hash.new(0)
+        end
+
+        def record(factory_name)
+          @counts ||= Hash.new(0)
+          @counts[factory_name.to_s] += 1
+        end
+
+        def counts
+          @counts ||= Hash.new(0)
+          @counts.dup
+        end
+
+        def summary_lines(top: 20)
+          @counts ||= Hash.new(0)
+          sorted = @counts.sort_by { |_, n| -n }
+          sorted[0, top].map { |name, n| "  #{name}: #{n}" }
+        end
+
+        def format_summary(title: "Polyrun factory counts")
+          lines = [title]
+          lines.concat(summary_lines)
+          lines.join("\n") + "\n"
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/data/factory_instrumentation.rb

@@ -0,0 +1,50 @@
+module Polyrun
+  module Data
+    # Opt-in FactoryBot hook so {#FactoryCounts} sees every factory run (minimal patch).
+    # Requires the +factory_bot+ gem and must run after FactoryBot is loaded.
+    #
+    #   require "factory_bot"
+    #   Polyrun::Data::FactoryInstrumentation.instrument_factory_bot!
+    module FactoryInstrumentation
+      class << self
+        def instrument_factory_bot!
+          return false unless defined?(FactoryBot)
+
+          factory_class = resolve_factory_runner_class
+          return false unless factory_class
+
+          return true if factory_class.instance_variable_defined?(:@polyrun_factory_instrumented) &&
+            factory_class.instance_variable_get(:@polyrun_factory_instrumented)
+
+          patch = Module.new do
+            def run(...)
+              Polyrun::Data::FactoryCounts.record(name)
+              super
+            end
+          end
+          factory_class.prepend(patch)
+          factory_class.instance_variable_set(:@polyrun_factory_instrumented, true)
+          true
+        end
+
+        def instrumented?
+          return false unless defined?(FactoryBot)
+
+          fc = resolve_factory_runner_class
+          return false unless fc
+
+          fc.instance_variable_defined?(:@polyrun_factory_instrumented) &&
+            fc.instance_variable_get(:@polyrun_factory_instrumented)
+        end
+
+        private
+
+        def resolve_factory_runner_class
+          return FactoryBot::Factory if defined?(FactoryBot::Factory)
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/data/fixtures.rb

@@ -0,0 +1,68 @@
+require "yaml"
+
+module Polyrun
+  module Data
+    # Declarative YAML fixture batches (**YAML → table → rows**).
+    # Polyrun does **not** ship a seed/register loader DSL—only **stdlib YAML** + iteration helpers.
+    # Typical layout: +spec/fixtures/polyrun/*.yml+ with top-level keys = table names.
+    #
+    #   users:
+    #     - name: Ada
+    #       email: ada@example.com
+    module Fixtures
+      module_function
+
+      def load_yaml(path)
+        YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: true) || {}
+      end
+
+      # Returns { "batch_name" => { "table" => [rows] } } for every +.yml+ under +dir+ (recursive).
+      def load_directory(dir)
+        Dir.glob(File.join(dir, "**", "*.yml")).sort.each_with_object({}) do |path, acc|
+          key = File.basename(path, ".*")
+          acc[key] = load_yaml(path)
+        end
+      end
+
+      # Iterates each table in a single batch hash. Skips keys starting with "_".
+      def each_table(batch)
+        return enum_for(:each_table, batch) unless block_given?
+
+        batch.each do |table, rows|
+          t = table.to_s
+          next if t.start_with?("_")
+
+          raise Polyrun::Error, "fixtures: #{t} must be an Array of rows" unless rows.is_a?(Array)
+
+          yield(t, rows)
+        end
+      end
+
+      # Loads all batches from +dir+ and yields (batch_name, table, rows).
+      def each_table_in_directory(dir)
+        return enum_for(:each_table_in_directory, dir) unless block_given?
+
+        load_directory(dir).each do |batch_name, batch|
+          each_table(batch) do |table, rows|
+            yield(batch_name, table, rows)
+          end
+        end
+      end
+
+      # Bulk insert YAML rows via ActiveRecord (batch load optimization). Requires ActiveRecord
+      # and a +connection+ that responds to +insert_all(table_name, records)+ (Rails 6+).
+      def apply_insert_all!(batch, connection: nil)
+        unless defined?(ActiveRecord::Base)
+          raise Polyrun::Error, "Fixtures.apply_insert_all! requires ActiveRecord"
+        end
+
+        conn = connection || ActiveRecord::Base.connection
+        each_table(batch) do |table, rows|
+          next if rows.empty?
+
+          conn.insert_all(table, rows)
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/data/parallel_provisioning.rb

@@ -0,0 +1,93 @@
+module Polyrun
+  module Data
+    # Branching helpers for **serial** vs **parallel worker** test DB setup (seeds, truncate).
+    # Polyrun does not call Rails +truncate+ or +load_seed+ for you — wire those in the callbacks you assign.
+    #
+    # Typical split (empty parallel DBs get seeds only; serial run truncates then seeds):
+    #
+    #   Polyrun::Data::ParallelProvisioning.configure do |c|
+    #     c.serial { replant_and_load_seed }
+    #     c.parallel_worker { load_seed_only }
+    #   end
+    #   # In spec_helper after configure:
+    #   Polyrun::Data::ParallelProvisioning.run_suite_hooks!
+    #
+    # Or use {Polyrun::RSpec.install_parallel_provisioning!} (+before(:suite)+) or {Polyrun::Minitest.install_parallel_provisioning!}
+    # (+require+ +polyrun/minitest+ from +test/test_helper.rb+).
+    module ParallelProvisioning
+      class Configuration
+        attr_accessor :serial_hook, :parallel_worker_hook
+
+        def serial(&block)
+          self.serial_hook = block if block
+        end
+
+        def parallel_worker(&block)
+          self.parallel_worker_hook = block if block
+        end
+      end
+
+      class Storage
+        attr_accessor :configuration
+
+        def initialize
+          @configuration = Configuration.new
+        end
+      end
+      private_constant :Storage
+
+      STORAGE = Storage.new
+      private_constant :STORAGE
+
+      class << self
+        def configure
+          yield configuration
+        end
+
+        def configuration
+          STORAGE.configuration
+        end
+
+        def reset_configuration!
+          STORAGE.configuration = Configuration.new
+        end
+
+        # True when multiple shards are in use ({Database::Shard} sets +POLYRUN_SHARD_TOTAL+).
+        def parallel_workers?
+          shard_total > 1
+        end
+
+        # 0-based worker index; prefers +POLYRUN_SHARD_INDEX+, else derives from +TEST_ENV_NUMBER+ (parallel_tests).
+        def shard_index
+          if (s = ENV["POLYRUN_SHARD_INDEX"]) && !s.to_s.empty?
+            Integer(s)
+          elsif (n = ENV["TEST_ENV_NUMBER"]).to_s.empty? || n == "0"
+            0
+          else
+            Integer(n) - 1
+          end
+        rescue ArgumentError
+          0
+        end
+
+        def shard_total
+          t = ENV["POLYRUN_SHARD_TOTAL"]
+          return Integer(t) if t && !t.to_s.empty?
+
+          1
+        rescue ArgumentError
+          1
+        end
+
+        # Runs +parallel_worker_hook+ when {#parallel_workers?}, else +serial_hook+. No-op if the chosen hook is nil.
+        def run_suite_hooks!
+          if parallel_workers?
+            configuration.parallel_worker_hook&.call
+          else
+            configuration.serial_hook&.call
+          end
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/data/snapshot.rb

@@ -0,0 +1,84 @@
+require "fileutils"
+require "open3"
+
+module Polyrun
+  module Data
+    # PostgreSQL data snapshots via +pg_dump+ / +psql+ (no +pg+ gem). Configure with ENV or explicit args.
+    # Non-Postgres adapters: use native backup/export tools; not covered here.
+    module SqlSnapshot
+      module_function
+
+      def default_connection
+        {
+          host: ENV["PGHOST"],
+          port: ENV["PGPORT"],
+          username: ENV["PGUSER"] || ENV["USER"],
+          database: ENV["PGDATABASE"]
+        }
+      end
+
+      # Writes data-only SQL to +root+/spec/fixtures/sql_snapshots/<name>.sql
+      def create!(name, root:, database: nil, username: nil, host: nil, port: nil)
+        database ||= default_connection[:database] or raise Polyrun::Error, "SqlSnapshot: set database: or PGDATABASE"
+        username ||= default_connection[:username]
+        path = File.join(root, "spec", "fixtures", "sql_snapshots", "#{name}.sql")
+        FileUtils.mkdir_p(File.dirname(path))
+
+        cmd = ["pg_dump", "--data-only", "-U", username]
+        cmd += ["-h", host] if host && !host.to_s.empty?
+        cmd += ["-p", port.to_s] if port && !port.to_s.empty?
+        cmd << database
+
+        out, err, st = Open3.capture3(*cmd)
+        raise Polyrun::Error, "pg_dump failed: #{err}" unless st.success?
+
+        File.write(path, out)
+        path
+      end
+
+      # Truncates listed tables (if any), then loads snapshot SQL. +tables+ optional; if nil and ActiveRecord
+      # is loaded, uses +connection.tables+.
+      def load!(name, root:, database: nil, username: nil, host: nil, port: nil, tables: nil)
+        database ||= default_connection[:database] or raise Polyrun::Error, "SqlSnapshot: set database: or PGDATABASE"
+        username ||= default_connection[:username]
+        path = File.join(root, "spec", "fixtures", "sql_snapshots", "#{name}.sql")
+        raise Polyrun::Error, "SqlSnapshot: missing #{path}" unless File.file?(path)
+
+        if tables.nil? && defined?(ActiveRecord::Base) && ActiveRecord::Base.connected?
+          tables = ActiveRecord::Base.connection.tables
+        end
+        tables ||= []
+
+        psql = sql_snapshot_psql_base(username, database, host, port)
+        sql_snapshot_truncate_tables!(psql, tables) if tables.any?
+        sql_snapshot_load_file!(psql, path)
+        true
+      end
+
+      def sql_snapshot_psql_base(username, database, host, port)
+        psql = ["psql", "-U", username, "-d", database]
+        psql += ["-h", host] if host && !host.to_s.empty?
+        psql += ["-p", port.to_s] if port && !port.to_s.empty?
+        psql
+      end
+
+      def sql_snapshot_truncate_tables!(psql, tables)
+        quoted = tables.map { |t| %("#{t.gsub('"', '""')}") }.join(", ")
+        trunc = "TRUNCATE TABLE #{quoted} CASCADE;"
+        _trunc_out, err, st = Open3.capture3(*psql, "-v", "ON_ERROR_STOP=1", "-c", trunc)
+        raise Polyrun::Error, "psql truncate failed: #{err}" unless st.success?
+      end
+
+      def sql_snapshot_load_file!(psql, path)
+        _load_out, err, st = Open3.capture3(
+          *psql,
+          "-v", "ON_ERROR_STOP=1",
+          "-c", "SET session_replication_role = 'replica';",
+          "-f", path,
+          "-c", "SET session_replication_role = 'origin';"
+        )
+        raise Polyrun::Error, "psql load failed: #{err}" unless st.success?
+      end
+    end
+  end
+end

data/lib/polyrun/database/clone_shards.rb

@@ -0,0 +1,81 @@
+module Polyrun
+  module Database
+    # Prepare canonical template DBs with one +bin/rails db:prepare+ (all +DATABASE_URL*+ keys in one process for multi-DB apps), then create per-shard databases in parallel (PostgreSQL +CREATE DATABASE … TEMPLATE …+).
+    # Other ActiveRecord adapters (MySQL, SQL Server, SQLite, …) are not automated here—use +polyrun env+ URLs with your own +db:*+ scripts.
+    # Replaces shell loops like +dropdb+ / +createdb -T+ when +polyrun.yml databases:+ lists primary + +connections+.
+    module CloneShards
+      module_function
+
+      # See +provision!+ on the singleton class for options.
+      def provision!(databases_hash, workers:, rails_root:, migrate: true, replace: true, force_drop: false, dry_run: false, silent: true)
+        dh = databases_hash.is_a?(Hash) ? databases_hash : {}
+        workers = Integer(workers)
+        raise Polyrun::Error, "workers must be >= 1" if workers < 1
+
+        rails_root = File.expand_path(rails_root)
+
+        migrate_canonical_databases!(dh, rails_root, dry_run, silent) if migrate
+        create_shards_from_plan!(dh, workers, replace, force_drop, dry_run)
+        true
+      end
+
+      def migrate_canonical_databases!(dh, rails_root, dry_run, silent)
+        pt = (dh["template_db"] || dh[:template_db]).to_s
+        if pt.empty?
+          raise Polyrun::Error, "CloneShards: set databases.template_db (and optional connections[].template_db)"
+        end
+
+        if dry_run
+          log = UrlBuilder.template_prepare_env_shell_log(dh)
+          Polyrun::Log.warn "would: RAILS_ENV=test #{log} bin/rails db:prepare"
+        else
+          child_env = ENV.to_h.merge(UrlBuilder.template_prepare_env(dh))
+          child_env["RAILS_ENV"] ||= ENV["RAILS_ENV"] || "test"
+          Provision.prepare_template!(rails_root: rails_root, env: child_env, silent: silent)
+        end
+      end
+      private_class_method :migrate_canonical_databases!
+
+      def create_shards_from_plan!(dh, workers, replace, force_drop, dry_run)
+        if dry_run
+          workers.times do |shard_index|
+            plan = UrlBuilder.shard_database_plan(dh, shard_index: shard_index)
+            if plan.empty?
+              raise Polyrun::Error, "CloneShards: empty shard plan for shard_index=#{shard_index}"
+            end
+
+            plan.each { |row| create_one_shard!(row, replace, force_drop, dry_run) }
+          end
+          return
+        end
+
+        threads = workers.times.map do |shard_index|
+          Thread.new do
+            plan = UrlBuilder.shard_database_plan(dh, shard_index: shard_index)
+            if plan.empty?
+              raise Polyrun::Error, "CloneShards: empty shard plan for shard_index=#{shard_index}"
+            end
+
+            plan.each { |row| create_one_shard!(row, replace, force_drop, dry_run) }
+          end
+        end
+        threads.each(&:join)
+      end
+      private_class_method :create_shards_from_plan!
+
+      def create_one_shard!(row, replace, force_drop, dry_run)
+        new_db = row[:new_db].to_s
+        tmpl = row[:template_db].to_s
+        if dry_run
+          Polyrun::Log.warn "would: DROP DATABASE IF EXISTS #{new_db}" if replace
+          Polyrun::Log.warn "would: CREATE DATABASE #{new_db} TEMPLATE #{tmpl}"
+          return
+        end
+
+        Provision.drop_database_if_exists!(database: new_db, force: force_drop) if replace
+        Provision.create_database_from_template!(new_db: new_db, template_db: tmpl)
+      end
+      private_class_method :create_one_shard!
+    end
+  end
+end

data/lib/polyrun/database/provision.rb

@@ -0,0 +1,72 @@
+require "open3"
+require "shellwords"
+
+module Polyrun
+  module Database
+    # PostgreSQL-only provisioning via +psql+ / +createdb+ (spec2 §5.3). No +pg+ gem.
+    # For other adapters, use Rails tasks or vendor CLIs; +Polyrun::Database::UrlBuilder+ still emits +DATABASE_URL+ for supported schemes.
+    module Provision
+      module_function
+
+      def quote_ident(name)
+        '"' + name.to_s.gsub('"', '""') + '"'
+      end
+
+      # +DROP DATABASE IF EXISTS name;+ — maintenance DB +postgres+ (or +maintenance_db+).
+      def drop_database_if_exists!(database:, host: nil, port: nil, username: nil, maintenance_db: "postgres", force: false)
+        host ||= ENV["PGHOST"] || "localhost"
+        port ||= ENV["PGPORT"] || "5432"
+        username ||= ENV["PGUSER"] || "postgres"
+
+        sql =
+          if force
+            "DROP DATABASE IF EXISTS #{quote_ident(database)} WITH (FORCE);"
+          else
+            "DROP DATABASE IF EXISTS #{quote_ident(database)};"
+          end
+        cmd = ["psql", "-U", username, "-h", host, "-p", port.to_s, "-d", maintenance_db, "-v", "ON_ERROR_STOP=1", "-c", sql]
+        _out, err, st = Open3.capture3(*cmd)
+        raise Polyrun::Error, "drop database failed: #{err}" unless st.success?
+
+        true
+      end
+
+      # CREATE DATABASE new_db TEMPLATE template_db — connects to maintenance DB +postgres+.
+      def create_database_from_template!(new_db:, template_db:, host: nil, port: nil, username: nil, maintenance_db: "postgres")
+        host ||= ENV["PGHOST"] || "localhost"
+        port ||= ENV["PGPORT"] || "5432"
+        username ||= ENV["PGUSER"] || "postgres"
+
+        sql = "CREATE DATABASE #{quote_ident(new_db)} TEMPLATE #{quote_ident(template_db)};"
+        cmd = ["psql", "-U", username, "-h", host, "-p", port.to_s, "-d", maintenance_db, "-v", "ON_ERROR_STOP=1", "-c", sql]
+        _out, err, st = Open3.capture3(*cmd)
+        raise Polyrun::Error, "create database failed: #{err}" unless st.success?
+
+        true
+      end
+
+      # Runs +bin/rails db:prepare+ with merged ENV (+DATABASE_URL+ for primary, +CACHE_DATABASE_URL+, etc.).
+      # Multi-DB Rails apps must pass all template URLs in one invocation so each DB uses its own +migrations_paths+.
+      # Uses +db:prepare+ (not +db:migrate+ alone) so empty template databases load +schema.rb+ first;
+      # apps that squash or archive migrations and keep only incremental files need that path.
+      def prepare_template!(rails_root:, env:, silent: true)
+        exe = File.join(rails_root, "bin", "rails")
+        raise Polyrun::Error, "Provision: missing #{exe}" unless File.executable?(exe)
+
+        child_env = ENV.to_h.merge(env)
+        child_env["RAILS_ENV"] ||= ENV["RAILS_ENV"] || "test"
+        rails_out, err, st = Open3.capture3(child_env, exe, "db:prepare", chdir: rails_root)
+        Polyrun::Log.warn err if !silent && !err.to_s.empty?
+        unless st.success?
+          msg = +"db:prepare failed"
+          msg << "\n--- stderr ---\n#{err}" unless err.to_s.strip.empty?
+          # Rails often prints the first migration/SQL error on stdout; stderr may only show InFailedSqlTransaction.
+          msg << "\n--- stdout ---\n#{rails_out}" unless rails_out.to_s.strip.empty?
+          raise Polyrun::Error, msg
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/polyrun/database/shard.rb

@@ -0,0 +1,63 @@
+module Polyrun
+  module Database
+    # ENV helpers for sharded test databases (parallel_tests–style), stdlib only.
+    module Shard
+      module_function
+
+      # Builds a hash of suggested ENV vars for this shard (strings).
+      def env_map(shard_index:, shard_total:, base_database: nil)
+        idx = Integer(shard_index)
+        tot = Integer(shard_total)
+        raise Polyrun::Error, "shard_index out of range" if idx < 0 || idx >= tot
+
+        out = {
+          "POLYRUN_SHARD_INDEX" => idx.to_s,
+          "POLYRUN_SHARD_TOTAL" => tot.to_s
+        }
+        out["TEST_ENV_NUMBER"] = (idx + 1).to_s if tot > 1
+        if base_database && !base_database.to_s.empty?
+          out["POLYRUN_TEST_DATABASE"] = expand_database_name(base_database.to_s, idx)
+        end
+        out
+      end
+
+      def expand_database_name(template, shard_index)
+        template.gsub("%{shard}", Integer(shard_index).to_s).gsub("%<shard>d", format("%d", Integer(shard_index)))
+      end
+
+      # Common URL transform: shard suffix on the database segment (+scheme://host/...+) or +sqlite3:+ path.
+      def database_url_with_shard(url, shard_index)
+        return url if url.nil? || url.to_s.empty?
+
+        u = url.to_s
+        return u if u.start_with?("http://", "https://", "file://")
+
+        if u.match?(/\Asqlite3:/i)
+          path = u.sub(/\Asqlite3:/i, "")
+          if path.match?(%r{([^/]+?)(\.sqlite3)\z}i)
+            idx = Integer(shard_index)
+            new_path = path.sub(%r{([^/]+?)(\.sqlite3)\z}i) { "#{$1}_#{idx}#{$2}" }
+            return "sqlite3:#{new_path}"
+          end
+          return u
+        end
+
+        return u unless u.match?(%r{\A[a-z][a-z0-9+.-]*://}i)
+
+        if (m = u.match(%r{/([^/?]+)(\?|$)}))
+          base = m[1]
+          suffixed = "#{base}_#{Integer(shard_index)}"
+          u.sub(%r{/#{Regexp.escape(base)}(\?|$)}, "/#{suffixed}\\1")
+        else
+          u
+        end
+      end
+
+      def print_exports(shard_index:, shard_total:, base_database: nil)
+        env_map(shard_index: shard_index, shard_total: shard_total, base_database: base_database).each do |k, v|
+          Polyrun::Log.puts %(export #{k}=#{v})
+        end
+      end
+    end
+  end
+end