constable-rails 1.3.3 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb4658a48f23de1dcb97417de5bab1deda4548a334e2a198835f93b7cac656c3
-  data.tar.gz: c844e9f7ac1c8d797d60349b7b15759bbcbbb0f1b56c914d43e2511e17f75489
+  metadata.gz: 807163563a2d149b1f1267c2dd873ebc19e9948664b8311f4185676ac9698753
+  data.tar.gz: d7c59c367bf69908c0909b2bda248f2d5d0c320a8238bbea628ac203134105a5
 SHA512:
-  metadata.gz: c3e78d5c2d2ab5314ee501795a92a1017fbfe0eb4cab6889c7ab6883d1ff898b02a595a693c3bb774c8e8e26caed2132c4f0c033723e7389735386f7b6c43668
-  data.tar.gz: 9f60ad3894558087d8747a5308e39558ce03d87c1518608dff21c9ca341fc776f11ceea45b7251435f052654ead1bbf348c489086b5857cea8e1b0a845781ff8
+  metadata.gz: 16458c866e5975ed485a03793c52c4d918b1191f8760ee45fd814d824857c943f5a848d268888e2d29334850b360d6f1df56e4cc1f619ad347f79c94a2bec0ae
+  data.tar.gz: 0e7fc08cf6105a1fea100ebbda9dc3d316444982fe5ed467b09e45c27f8d36577711f8f175dc020773724f1973f2748b9a0fd76b0d791d24f48e1afb15a31ed7

data/CHANGELOG.md

@@ -5,6 +5,99 @@ All notable changes to this project are documented here. This project adheres to
 
 ## [Unreleased]
 
+## [1.4.1]
+
+### A parallel run that ran nothing is no longer a pass
+
+Pointing a real app at `worker_databases: reuse` produced this:
+
+```
+CONSTABLE            0 tests · 0 cases · 7.9s
+✓ 0 passed   ✗ 0 failed
+```
+
+Nineteen files scheduled. None ran. Exit 0. The third time this shape has appeared in a
+week, and the most dangerous instance of it.
+
+Two causes. A forked worker only reported `Constable::Error`, so anything else killed it
+silently — the parent saw a closed pipe, no results and no reason. Workers now report
+whatever they die of, including the exit status when they die below Ruby (a signal, a
+segfault, an OOM kill; forking an app that already holds native database connections can
+do exactly that). And the fallback to a serial run was conditional on a worker having
+managed to *explain* itself; it now triggers on the fact that matters — work was
+scheduled and nothing came back. If the serial fallback also produces nothing, that
+raises rather than being summarised as a clean zero.
+
+Same command now: **84 tests run**, serially, with a warning saying why.
+
+### Workers no longer build databases; `constable prepare` does
+
+`reuse` had each worker build its own missing databases after forking. On Postgres the
+clone must disconnect everything attached to the template first — and the template is the
+shared test database *every other worker* is cloning from at the same moment. Twelve
+workers terminated each other's connections and died mid-run.
+
+Preparation happens once, in the parent, through `constable prepare`. A worker that finds
+nothing to connect to says so and names the command. `constable prepare` also boots the
+app first, which it was not doing: it reported "this app has no ActiveRecord test
+databases to prepare" on an app with three of them.
+
+### Configuration is documented where you read it
+
+Every setting in `.constable/config.yml` now carries its explanation, and the ones with
+fixed choices name and describe each value inline — `worker_databases`, `output`, the
+storage adapter. Two tests enforce it: a setting cannot arrive without an explanation, and
+one with fixed choices has to name them.
+
+The blotter section now says outright that it is **not** your application's database.
+Two people read it the other way, which is a naming problem, not a reading problem.
+
+
+## [1.4.0]
+
+Two problems from the same 1,277-file suite: a docket nobody asked for, and 110 minutes.
+
+### A flaky test is no longer jailed by itself
+
+**This is the important one, because jailed means skipped.** A first `constable test` on a
+real suite put **29 tests on a docket the user had never asked for** — each one recorded
+as *"passed, then failed with no code change"* — and every one of them was silently
+skipped from then on. A suite with order-dependent tests, which is most large suites and
+exactly what Constable is pitched at, trips that constantly.
+
+Automatic flake-jailing is now off by default:
+
+```yaml
+jail_flakes: false   # was: always on
+```
+
+`constable test --jail` still jails failures, because that is a thing you asked for.
+Turn the automatic route back on when you want it. Nothing stops being *reported* — a
+flaky test still fails, still shows up, still gets a warrant if warrants are on. It just
+does not remove itself from the suite.
+
+### Per-worker databases without a loadable schema
+
+The same suite ran **serially for 110 minutes on a 12-core machine**, because its schema
+cannot be loaded from `schema.rb` (Postgres custom types), so `worker_databases: off` was
+the only setting that worked.
+
+Postgres can copy a whole database in one statement, and that needs no schema at all:
+
+```sql
+CREATE DATABASE "caseflow_test_3" TEMPLATE "caseflow_test"
+```
+
+`worker_databases: reuse` now clones from the test database you already have, dropping a
+stale copy and disconnecting the template first. It falls back to loading the schema when
+there is nothing to clone, and to Postgres only — anything unexpected takes the old path
+rather than failing. It is also simply faster than replaying a large schema once per
+worker, so it is worth having on any Postgres app.
+
+For a suite that could only run serially, this is the difference between one core and all
+of them.
+
+
 ## [1.3.3]
 
 **1.3.2 was tagged twice.** The console fix in it was rebuilt after the gem had already
@@ -619,7 +712,9 @@ Initial release.
 - Diff-based coverage gate — only lines changed in the current diff are held to the
   threshold. `constable beat` for the full picture, `--html` for a browsable report.
 
-[Unreleased]: https://github.com/Ray-Hughes/constable/compare/v1.3.3...HEAD
+[Unreleased]: https://github.com/Ray-Hughes/constable/compare/v1.4.1...HEAD
+[1.4.1]: https://github.com/Ray-Hughes/constable/compare/v1.4.0...v1.4.1
+[1.4.0]: https://github.com/Ray-Hughes/constable/compare/v1.3.3...v1.4.0
 [1.3.3]: https://github.com/Ray-Hughes/constable/compare/v1.3.2...v1.3.3
 [1.3.2]: https://github.com/Ray-Hughes/constable/compare/v1.3.1...v1.3.2
 [1.3.1]: https://github.com/Ray-Hughes/constable/compare/v1.3.0...v1.3.1

data/README.md

@@ -7,7 +7,7 @@
 
 **A strict Rails testing framework where fast and non-flaky are structural, not disciplinary.**
 
-[![Gem Version](https://img.shields.io/gem/v/constable-rails?color=1f6feb&label=constable-rails)](https://rubygems.org/gems/constable-rails)
+[![Gem Version](https://badge.fury.io/rb/constable-rails.svg)](https://badge.fury.io/rb/constable-rails)
 [![CI](https://github.com/Ray-Hughes/constable/actions/workflows/ci.yml/badge.svg)](https://github.com/Ray-Hughes/constable/actions/workflows/ci.yml)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-CC342D)](https://www.ruby-lang.org)
 [![Rails](https://img.shields.io/badge/rails-%3E%3D%207.0-D30001)](https://rubyonrails.org)

data/lib/constable/cli.rb

@@ -428,6 +428,10 @@ module Constable
     option :workers, type: :numeric, desc: "How many to prepare (default: the configured worker count)"
     def prepare
       config = load_config
+      # The app has to be up before we can ask ActiveRecord anything about it.
+      Runner.boot!
+      config.apply_overrides!(Constable.configuration.overrides)
+
       unless WorkerDatabases.shardable?
         CLI.complain("This app has no ActiveRecord test databases to prepare.")
         exit(EXIT_USAGE)

data/lib/constable/config.rb

@@ -22,6 +22,7 @@ module Constable
       "output" => "concise",
       "parallel_workers" => "auto",
       "worker_databases" => "schema",
+      "jail_flakes" => false,
       "tiers" => {
         "unit" => "test/cases/models/**/*",
         "integration" => "test/cases/controllers/**/*",
@@ -76,6 +77,19 @@ module Constable
 
     def cold_cases         = Array(@raw["cold_cases"])
     def warrants?          = truthy(@raw["warrants"])
+
+    # Should a test that passed last run and failed this one be put on the docket by
+    # itself? Off by default, and the reason is what jailing *does*: a jailed test is
+    # skipped on every later run. Turning that on automatically means a suite quietly
+    # stops running tests nobody chose to stop running.
+    #
+    # Observed on a real suite: a first `constable test` put 29 tests on a docket the user
+    # had never asked for, and every one of them was skipped from then on. A suite with
+    # order-dependent tests -- which is most large suites, and exactly the kind Constable
+    # is pitched at -- trips this constantly.
+    #
+    # `constable test --jail` still jails failures, because that is a thing you asked for.
+    def jail_flakes?       = truthy(@raw["jail_flakes"])
     # Negative retries are a typo for "off", not an instruction to count backwards.
     def warrant_retries    = [@raw["warrant_retries"].to_i, 0].max
     def auto_relink?       = truthy(@raw["auto_relink"])

data/lib/constable/jail.rb

@@ -123,6 +123,13 @@ module Constable
 
     # Consecutive clean runs that earn an automatic release. Floors at 1 -- a period of
     # zero would mean "release on sight", which is not parole.
+    # Opt-in. See Config#jail_flakes? for why the default is off: jailing skips the test on
+    # every later run, and doing that to a test nobody nominated is how a suite quietly
+    # stops testing things.
+    def jail_flakes?
+      @config.respond_to?(:jail_flakes?) ? @config.jail_flakes? : false
+    end
+
     def parole_period
       period = @config.respond_to?(:parole_period) ? @config.parole_period.to_i : 0
       period.positive? ? period : 10
@@ -290,7 +297,7 @@ module Constable
 
       if jail_mode
         jail_failure(result)
-      elsif flake_flip?(result)
+      elsif flake_flip?(result) && jail_flakes?
         jail_for_flake(result)
       else
         result

data/lib/constable/runner.rb

@@ -64,6 +64,20 @@ module Constable
     def jail_run?   = @jail_run
     def coverage?   = @coverage_requested
 
+    # Boots the app the way a run does -- test/case_helper.rb, which requires
+    # config/environment -- without selecting or running anything.
+    #
+    # `constable prepare` needs this: it asks ActiveRecord what databases exist, and
+    # before the helper has run there is no ActiveRecord to ask. It reported "this app has
+    # no test databases to prepare" on an app with three of them.
+    def self.boot!
+      helper = %w[test/case_helper.rb spec/case_helper.rb]
+               .map { |p| File.join(Constable.root, p) }
+               .find { |p| File.exist?(p) }
+      require helper if helper
+      helper
+    end
+
     # Loads every case file and hands back the identities the suite actually defines,
     # without running anything. `constable prune` needs this: which tests still exist is
     # only knowable once the whole suite has been loaded.
@@ -352,8 +366,18 @@ module Constable
             exit!(0)
           end
 
-          bucket.each do |item|
-            run_item(item).each { |result| write_message(writer, :result, result.to_h) }
+          # Anything at all, not just Constable::Error. An uncaught exception in a forked
+          # child kills it silently: the parent sees a closed pipe, no results and no
+          # reason, and a run that scheduled nineteen files reports zero tests and exits
+          # 0. A worker that dies has to say so.
+          begin
+            bucket.each do |item|
+              run_item(item).each { |result| write_message(writer, :result, result.to_h) }
+            end
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            write_message(writer, :worker_error, "#{e.class}: #{e.message}")
+            writer.close
+            exit!(0)
           end
 
           # A worker owns its own cold-case session, and it dies here. Fire the engine's
@@ -374,7 +398,7 @@ module Constable
       end
 
       collected = drain(readers)
-      pids.each { |pid| Process.waitpid(pid) rescue nil } # rubocop:disable Style/RescueModifier
+      record_worker_exits(pids)
 
       # No worker could build itself a database, so no test ran. Not every app can be
       # sharded: an app whose schema.rb cannot rebuild the database on its own -- Postgres
@@ -385,7 +409,13 @@ module Constable
       #
       # Nothing has run yet, so falling back to a serial run costs a restart, not
       # correctness.
-      return run_serially_after_worker_failure(items) if collected.empty? && worker_errors.any?
+      #
+      # The condition is deliberately "nothing came back", not "a worker said why". A
+      # child can die without managing to report -- and then a run that scheduled
+      # nineteen files says "0 tests, 0 failed" and exits 0, which is the worst thing a
+      # test runner can do. If work was scheduled and no result arrived, something is
+      # wrong whether or not anyone explained it.
+      return run_serially_after_worker_failure(items) if collected.empty? && !items.empty?
 
       # A warning raised inside a worker only ever reached that worker's memory, so the
       # results carry them home. Nothing that bends the rules is allowed to go missing
@@ -396,22 +426,58 @@ module Constable
 
     def worker_errors = (@worker_errors ||= [])
 
+    # A worker can die below Ruby: a segfault, an OOM kill, a signal. No `rescue` reaches
+    # that, so the only evidence is the exit status, and without it the run can only say
+    # "the workers exited without reporting anything" -- true, and useless.
+    #
+    # Forking a process that already holds database connections is where this comes from.
+    # An app with a native driver -- Oracle's OCI, for instance -- can have a child die
+    # the moment it touches an inherited handle.
+    def record_worker_exits(pids)
+      pids.each do |pid|
+        _, status = Process.waitpid2(pid)
+        next if status.nil? || status.success?
+
+        worker_errors << if status.signaled?
+                           "a worker was killed by SIG#{Signal.signame(status.termsig)} " \
+                             "-- forking an app that already holds native database " \
+                             "connections can do this"
+                         else
+                           "a worker exited with status #{status.exitstatus}"
+                         end
+      rescue StandardError
+        nil
+      end
+    end
+
     def run_serially_after_worker_failure(items)
       reason = worker_errors.first.to_s
+      reason = "the workers exited without reporting anything" if reason.empty?
 
       Constable.warn!(
-        "no parallel worker could build its own test database, so the suite ran serially " \
-        "instead. This usually means the app's schema cannot rebuild the database by " \
-        "itself -- Postgres custom types, functions and triggers are the common reason, " \
-        "and `rails test` parallelization fails the same way. Set " \
-        "`worker_databases: reuse` to keep prepared databases between runs instead, or " \
-        "`worker_databases: off` to stop trying. The first worker said: #{reason}",
+        "the parallel workers produced no results, so the suite ran serially instead -- " \
+        "everything ran, nothing was skipped. Two things cause this: the app's schema " \
+        "cannot rebuild a database by itself (Postgres custom types; try " \
+        "`worker_databases: reuse` with `constable prepare`), or forking is unsafe in " \
+        "this app, which happens when a native driver's connections are inherited by a " \
+        "child. `worker_databases: off` stops the attempt. The workers said: #{reason}",
         kind: :parallel
       )
 
       # The blotter handle was closed before forking, and the pool was cleared. Both come
       # back on their next use, so there is nothing to reopen by hand.
-      run_serial(items)
+      results = run_serial(items)
+
+      # Belt and braces. If the serial fallback also produces nothing for work that was
+      # scheduled, the run is broken in a way no summary can honestly describe, and
+      # reporting a clean zero would be a lie.
+      if results.empty? && !items.empty?
+        raise Constable::Error,
+              "#{items.size} test file(s) were scheduled and none of them ran. " \
+              "The first worker said: #{reason}"
+      end
+
+      results
     end
 
     # Every message on the pipe is tagged, because results are not the only thing a worker

data/lib/constable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Constable
-  VERSION = "1.3.3"
+  VERSION = "1.4.1"
 end

data/lib/constable/worker_databases.rb

@@ -58,7 +58,7 @@ module Constable
     #            that works when the schema cannot rebuild the database by itself.
     def after_fork!(index, mode: :schema)
       return false unless shardable?
-      return reuse!(index) if mode.to_sym == :reuse
+      return connect_worker!(index) if mode.to_sym == :reuse
 
       ::ActiveRecord::TestDatabases.create_and_load_schema(index, env_name: env_name)
       true
@@ -105,8 +105,105 @@ module Constable
                           .zip(names).each { |config, name| config._database = name if name }
     end
 
-    # The :reuse half. Points every database this environment declares at its `_<index>`
-    # sibling, and only builds the ones that are not there yet.
+    # Postgres can copy a whole database in one statement:
+    #
+    #   CREATE DATABASE "caseflow_test_3" TEMPLATE "caseflow_test"
+    #
+    # That matters because it needs no schema.rb at all. An app whose schema cannot
+    # rebuild the database by itself -- custom types, functions, triggers -- can still get
+    # per-worker databases this way, cloned from the test database it already has. It is
+    # also far faster than replaying a large schema once per worker.
+    #
+    # Returns true when it cloned, false when this is not Postgres or the source is not
+    # there, so the caller can fall back to loading the schema.
+    def clone_database(db_config, index)
+      return false unless postgres?(db_config)
+
+      source = db_config.database.to_s.sub(/_#{index}\z/, "")
+      target = db_config.database.to_s
+      return false if source.empty? || source == target
+
+      maintenance_connection(db_config) do |connection|
+        return false unless database_exists?(connection, source)
+
+        # A template cannot be copied while anything is connected to it.
+        disconnect_everyone_from!(connection, source)
+        connection.execute(%(DROP DATABASE IF EXISTS "#{target}"))
+        connection.execute(%(CREATE DATABASE "#{target}" TEMPLATE "#{source}"))
+      end
+
+      true
+    rescue StandardError
+      # Cloning is the fast path, never the only one. Anything unexpected -- a permission,
+      # a Postgres version, a connection that will not drop -- falls back to the schema.
+      false
+    end
+
+    def postgres?(db_config)
+      db_config.respond_to?(:adapter) && db_config.adapter.to_s.include?("postgre")
+    end
+
+    # Postgres will not let you create a database while connected to the one you are
+    # copying, so the statements run against the cluster's own maintenance database.
+    def maintenance_connection(db_config)
+      previous = ::ActiveRecord::Base.connection_db_config
+      ::ActiveRecord::Base.establish_connection(db_config.configuration_hash.merge(database: "postgres"))
+      yield ::ActiveRecord::Base.connection
+    ensure
+      ::ActiveRecord::Base.establish_connection(previous)
+    end
+
+    def database_exists?(connection, name)
+      # Plain Ruby, not #present?: this runs inside a forked worker in somebody else's app,
+      # and quietly depending on ActiveSupport being loaded is how a fast path silently
+      # turns itself off.
+      value = connection.select_value("SELECT 1 FROM pg_database WHERE datname = #{connection.quote(name)}")
+      !value.nil?
+    rescue StandardError
+      false
+    end
+
+    def disconnect_everyone_from!(connection, name)
+      connection.execute(
+        "SELECT pg_terminate_backend(pid) FROM pg_stat_activity " \
+        "WHERE datname = #{connection.quote(name)} AND pid <> pg_backend_pid()"
+      )
+    rescue StandardError
+      nil
+    end
+
+    # The :reuse half, inside a worker: connect to `<database>_<index>` and nothing else.
+    #
+    # Building is deliberately not done here. Twelve workers forked at once would each try
+    # to build the same missing databases simultaneously, and on Postgres the clone has to
+    # disconnect everything attached to the template first -- which is the shared test
+    # database every other worker is also cloning from. They terminate each other's
+    # connections and die, silently, mid-run. Observed exactly that: nineteen files
+    # scheduled, zero results, workers gone without a word.
+    #
+    # So preparation happens once, in the parent, through `constable prepare`. A worker
+    # that finds nothing to connect to says so, and the runner falls back to serial.
+    def connect_worker!(index)
+      missing = []
+
+      each_worker_config(index) do |db_config|
+        missing << db_config.database unless populated?(db_config)
+      end
+
+      unless missing.empty?
+        raise Constable::Error,
+              "worker #{index} has no database to use (#{missing.join(", ")}). " \
+              "`worker_databases: reuse` expects them to exist already -- run " \
+              "`constable prepare` once, then run the suite."
+      end
+
+      ::ActiveRecord::Base.establish_connection
+      []
+    end
+
+    # The building half, run from the parent by `constable prepare`. Points every database
+    # this environment declares at its `_<index>` sibling, and builds the ones that are
+    # not there yet.
     #
     # "There" means present *and* populated: an empty database is not a prepared one, and
     # connecting to it would hand the worker a suite with no tables. Deciding that per
@@ -121,6 +218,10 @@ module Constable
       each_worker_config(index) do |db_config|
         next if populated?(db_config)
 
+        # Clone first: it needs no schema.rb, which is the only thing that works for an
+        # app whose schema cannot rebuild the database, and it is faster besides.
+        next built << "#{db_config.database} (cloned)" if clone_database(db_config, index)
+
         ::ActiveRecord::Tasks::DatabaseTasks.reconstruct_from_schema(db_config, nil)
         built << db_config.database
       end

data/lib/constable.rb

@@ -149,7 +149,7 @@ module Constable
     SETTINGS = %i[
       cold_cases warrants warrant_retries auto_relink parole_period
       coverage coverage_threshold coverage_html fail_on_warnings parallel_workers
-      worker_databases output tiers
+      worker_databases jail_flakes output tiers
     ].freeze
 
     # `storage` is the one setting that cannot live here, and the reason is ordering, not

data/lib/generators/constable/templates/case_helper.rb.tt

@@ -159,6 +159,7 @@ end
 #      c.worker_databases   = :schema # or :reuse (keep them between runs) / :off
 #      c.output             = :concise    # or :expanded -- a line per test, with timings
 #      c.fail_on_warnings   = false   # CI: fail when the warning count is not trending down
+#      c.jail_flakes        = false   # auto-jail a pass->fail flip (jailed = skipped)
 #      c.warrants           = false   # rerun a failure in isolation before believing it
 #      c.warrant_retries    = 5
 #      c.parole_period      = 10      # clean runs before a paroled test releases itself

data/lib/generators/constable/templates/config.yml.tt

@@ -43,6 +43,11 @@ cold_cases: []
 
 # The blotter: flake history, the jail docket, warrants.
 #
+# NOT your application's database, and nothing to do with it. Your tests keep using
+# whatever config/database.yml says -- Postgres stays Postgres. This is a separate file
+# holding Constable's own bookkeeping, and it never contains a row of your data. Leaving
+# it on SQLite is right even for a Postgres app.
+#
 # Constable owns this store outright. It is deliberately not the app's own
 # database, for two reasons. Native cases run inside a transaction that gets
 # rolled back, so writing "this test just failed" through that connection would
@@ -54,11 +59,22 @@ cold_cases: []
 # need one queryable store shared across many CI machines -- and always at a
 # separate database from the app's own, never its test connection.
 storage:
-  adapter: sqlite                      # sqlite (default) | postgres | mysql
+  adapter: sqlite                      # sqlite (default, and right for almost everyone)
+                                       #   postgres / mysql: only when many CI machines
+                                       #   need to share ONE blotter. Always a separate
+                                       #   database from your app's own.
   path: .constable/constable.sqlite3   # sqlite only
   url:                                 # postgres/mysql only, e.g.
                                        #   postgres://user:pass@host/constable_metadata
 
+# Put a test on the docket by itself when it passed last run and failed this one, with no
+# code change in between. Off by default, and the reason is what jailing *does*: a jailed
+# test is skipped on every later run. Turning that on automatically means a suite quietly
+# stops running tests nobody chose to stop running -- and a suite with order-dependent
+# tests, which is most large ones, trips it constantly. `constable test --jail` still
+# jails failures, because that is a thing you asked for.
+jail_flakes: false
+
 warrants: false          # opt-in flaky detector -- rerun a failure in isolation before believing it
 warrant_retries: 5       # reruns before declaring a warrant (flaky) or a genuine failure
 auto_relink: false       # auto-confirm high-confidence rename detection instead of suggesting it
@@ -73,29 +89,45 @@ fail_on_warnings: false  # CI: fail the build when the warning count doesn't tre
 
 parallel_workers: auto   # or an explicit integer
 
-# How a parallel worker gets a database of its own. Sharing one is not a speed/safety
-# trade but a correctness bug: on SQLite the run dissolves into "database is locked", and
-# on a client/server database tests quietly see each other's rows.
-#
-#   schema  rebuild <database>_<index> from schema on every run. What Rails does for
-#           `rails test`, and correct by construction -- no drift is possible.
-#   reuse   connect to <database>_<index> when it is already there, and build it from
-#           schema only when it is not. Faster, because a large schema is not reloaded
-#           every run -- and the only option that works at all when the schema cannot
-#           rebuild the database by itself, which is true of any app with Postgres custom
-#           types (`CREATE TYPE` has no schema.rb representation, so a from-scratch load
-#           fails). Keeping those databases current becomes your job.
-#   off     do not shard, so do not fork. An explicit serial run: no attempt, no warning.
-worker_databases: schema   # schema | reuse | off
+# How a parallel worker gets a database of its own.
+#
+# Sharing one is not a speed/safety trade, it is a correctness bug: on SQLite the run
+# dissolves into "database is locked", and on a client/server database tests quietly see
+# each other's rows, which is worse because it looks like it worked.
+#
+# Three options:
+#
+#   schema   Rebuild <database>_<index> from schema.rb on every run.
+#            What Rails itself does for `rails test`. Correct by construction -- the
+#            databases cannot drift, because they are thrown away and rebuilt. The right
+#            default, and the wrong choice only when it is slow or impossible.
+#
+#   reuse    Keep <database>_<index> between runs, building it only when it is missing.
+#            Two reasons to want this:
+#              * Speed. A large schema is not replayed once per worker per run. On
+#                Postgres the databases are cloned in one statement
+#                (CREATE DATABASE ... TEMPLATE), which is far faster than a schema load.
+#              * It is the ONLY option that works when your schema cannot rebuild the
+#                database by itself -- true of any app with Postgres custom types, since
+#                CREATE TYPE has no schema.rb representation and a from-scratch load
+#                fails on a dump that references types it never defines.
+#            The cost: keeping those databases current is now your job. Run
+#            `constable prepare` after a migration.
+#
+#   off      Do not shard, so do not fork. An explicit serial run: no attempt to build
+#            anything, and no warning about it. Correct, and as slow as one core.
+#
+worker_databases: schema   # schema (rebuild each run) | reuse (keep them) | off (serial)
 
-# How much the live stream says while the suite is running. The summary is identical
-# either way -- this only changes what you watch on the way there.
-#
-#   concise   one glyph per test, grouped into a run per case. A thousand tests stay
-#             inside one screen, and a wall of green is the point.
-#   expanded  a line per test: glyph, name, duration. Slower to read in bulk, but you
-#             can see which test is hanging while it hangs, rather than after.
-output: concise          # concise | expanded
+# How much the live stream says while the suite is running. The summary at the end is
+# identical either way -- this only changes what you watch on the way there.
+#
+#   concise    One glyph per test, grouped into a run per case. A thousand tests stay
+#              inside one screen, and a wall of green is the point.
+#   expanded   A line per test: glyph, description, duration. Slower to read in bulk, but
+#              you can see which test is hanging while it hangs, rather than afterwards.
+#
+output: concise          # concise (one glyph per test) | expanded (a line per test)
 
 # Fallback path-based tier inference, used only when a case doesn't inherit from
 # a tiered base class. The base classes in test/case_helper.rb are the primary

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: constable-rails
 version: !ruby/object:Gem::Version
-  version: 1.3.3
+  version: 1.4.1
 platform: ruby
 authors:
 - Ray Hughes
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-08 00:00:00.000000000 Z
+date: 2026-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport