pgbus 0.11.0 → 0.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44b8e6016eb94d129ba3f90831ee6e3f8eb213c928e61766c35fa4641f0a518b
-  data.tar.gz: d35475deb1eaaf59e893c7096b10bc85498482f5940fc099e5add48af54aecbd
+  metadata.gz: 727dd6a7515414a2a426857ea19cc8cf33b8c5ca2311ecde116bf643114e8d85
+  data.tar.gz: c68f0e3c246b554059160e901e96d61f80c5a5a9aa1716d6e4787f84cfdbe655
 SHA512:
-  metadata.gz: db2122fe97f2b77dd6812e5e9a5264850b4eb84ff3c6094cc2c0e11a148989fa3ae502664e040da26b1ea1bf11b764c2b1f9659a58f9d4a6b663be54c1027cba
-  data.tar.gz: 597210a0238131f0a7912b0cf135dc4d89ce66ab830354dca3b3805dbc70a9ccbd2106830dea85b17c68be73fb79868ff9c43d27813e84e6f457dfbe996107d3
+  metadata.gz: f515f94c6e585a038ab468ca30dc49a284c9666ddb0116998532ce2afdf602ac8309972fbe79606ad055b73bd95da418210778cf80a9e3062288855d67a3b746
+  data.tar.gz: dd748949d2330236bfbc46b94c04ff907268e067830a2c4b91b3ff6b811324b2383d3c46bc950add9511c98355b39b39d9f3a58c03a3fed361838c866b24bf1c

data/CHANGELOG.md

@@ -10,6 +10,7 @@
 
 ### Added
 
+- **`config.doctor_on_boot` (+ `pgbus start --doctor` / `--doctor-strict`) — run the doctor preflight inside the booting supervisor, one Rails boot instead of two (issue #347).** The recommended deploy preflight was `bin/pgbus doctor || true` in the container entrypoint before `bin/pgbus start` — but both commands `require config/environment`, so the job container boots the full Rails app **twice** on every deploy (cost scaling with app boot time), and running doctor pre-supervisor makes the `Process liveness` check false-fail (no workers exist yet), which is exactly why the entrypoint has to swallow the exit code with `|| true` — losing any chance to gate on a genuinely-fatal finding. Now `config.doctor_on_boot = :report` (or `pgbus start --doctor`) runs the checks in the already-booted supervisor, after the DB is verified reachable and queues are bootstrapped but **before any worker is forked**: one boot, and the worker-dependent `Process liveness` check is skipped (it has no workers to observe yet and would false-fail on stale prior-generation rows during a redeploy). `config.doctor_on_boot = :strict` (or `--doctor-strict`) additionally **refuses to boot** — raising before forking anything, so the `ensure shutdown` path tears down the heartbeat/health server and no child starts — but *only* on a genuinely-fatal, non-transient check: a `Configuration` failure (a real config bug) or an **absent** PGMQ schema. It deliberately does **not** abort on `Queues`/`Database` failures — those are the transients the lenient queue bootstrap is built to ride out (children crash-and-backoff until the DB recovers), and `verify_connection!` already gated a hard-down DB moments earlier; making them strict-fatal would take down a whole fleet's cold boot in lockstep on a momentarily-saturated primary. Default `nil`/`false` = off (byte-identical to today; the supervisor constructs no `Doctor` and does zero extra work). The standalone `pgbus doctor` command and its exit-code semantics are unchanged. Refs #347.
 - **`Pgbus::Streams::PhlexHelpers` — a Phlex-includable `pgbus_stream_from`, and `Pgbus.stream_name_budget` (issue #334).** Two small helpers that stop consuming apps reimplementing pgbus glue. (1) `pgbus_stream_from` is a Rails view helper, so a Phlex component couldn't call it without hand-registering an output-helper macro (phlex-rails ships no `Phlex::Rails::Helpers::PgbusStreamFrom`). `include Pgbus::Streams::PhlexHelpers` now bridges it exactly like phlex-rails' own `TurboStreamFrom`. phlex-rails stays an **optional** dependency — the module references its `HelperMacros` and is loaded on demand (`require "pgbus/streams/phlex_helpers"`), never eagerly. (2) `Pgbus.stream_name_budget` exposes the maximum stream-name length (the pgmq queue-name cap minus the queue prefix) so apps size/truncate stream identifiers up front instead of hand-computing `MAX_QUEUE_NAME_LENGTH - queue_prefix.length - 1` at every call site. Refs #334.
 - **`EventBus::Registry#setup_all!(safe: true)` — a boot/rake-safe way to eagerly set up event subscribers (issue #334).** Calling `setup_all!` opens a PGMQ connection per subscriber (to create its queue + bind its topic), which is wrong during a `db:`/schema rake task (a live connection blocks `DROP DATABASE`) and crashes boot if the database isn't up yet — so apps wrapped it in a hand-rolled multi-class rescue plus a rake-task skip. `setup_all!(safe: true)` bakes that in: it skips entirely in a schema/asset rake context and swallows a connection error with a warning instead of raising. The default `setup_all!` is unchanged (raises). Refs #334.
 - **Connection-pooler safety (`config.require_primary`, `config.connection_guc_mode`) — pgbus is now correct-and-loud behind a transaction/read-write-splitting pooler instead of silently stalling (issue #332).** Three linked fixes. (1) **Primary affinity:** a read/write-splitting pooler (pgdog/pgcat) can route pgmq's VOLATILE `read`/`archive`/`delete` to a read replica, where workers read nothing (`read_ct=0`) and jobs stop with a **healthy heartbeat** — the supervisor watchdog keys on loop advancement, not read progress, so nothing surfaced the stall. The job read path had zero primary-affinity defense (only the LISTEN/streamer paths validated the primary via `PrimaryValidator`). Setting `config.require_primary = true` (default **false** — a single-primary deployment is byte-identical) makes `verify_connection!` reject a connection that lands on a replica (`pg_is_in_recovery() => t`) at supervisor boot, raising a clear `ConfigurationError` instead of forking children that read nothing. (2) **GUC forwarding:** pgbus's AR-config extraction dropped database.yml's `variables:` block, so `client_min_messages` (and any GUC) never reached pgmq's dedicated raw connections (NOTICE flooding that three consuming apps hand-patched via `connection_params`). GUCs are now forwarded, on both the AR-extracted and explicit-`connection_params` paths, by `config.connection_guc_mode`: `:options` (default) bakes them into the libpq `options` STARTUP param (byte-compatible with today for the read-timeout `statement_timeout`, now also carrying `variables:`), while `:session` applies them via post-connect `SET` on a fresh connection instead — for a transaction-mode PgBouncer that **rejects** the `options` startup param with a FATAL. `pgbus doctor` gains a ninth check ("Primary affinity") that warns (never fails) when the job connection is currently on a replica, naming the direct-port remediation. DB-gated integration tests prove both GUC modes round-trip a forwarded GUC and that `require_primary` verifies on a real primary. Refs #332.
@@ -32,6 +33,8 @@
 
 ### Fixed
 
+- **Migration generators now route to the pgbus database when `connects_to` is configured, even without an explicit `--database` (issue #344).** `rails g pgbus:add_stream_queues` (and every sibling generator via `Generators::MigrationPath`) keyed the separate-database decision purely on the `--database` flag. An app that had already set `config.connects_to = { database: { writing: :pgbus } }` (so its pgbus migrations live in `db/pgbus_migrate/` per database.yml's `migrations_paths:`) still got the migration written to the **primary** DB's `db/migrate/` on a bare invocation — where it then ran against the wrong database — and the "Next steps" output told the operator to run `rails db:migrate` instead of `rails db:migrate:pgbus`. `MigrationPath` now auto-detects the target database from `connects_to` (via the existing `DatabaseTargetDetector`: runtime config → initializer scan → application.rb scan) when `--database` is absent; an explicit `--database` still wins. The detected name drives both the migration path (resolving `migrations_paths` for that database, falling back to the `db/pgbus_migrate` convention) and the `db:migrate:<name>` suffix in every generator's post-install output. An app with no separate database is unaffected. Refs #344.
+- **`extract_ar_connection_hash` no longer forces `host: "localhost"` / `port: 5432` on a socket-based (host-less) database.yml — pgmq's connections now match ActiveRecord's on Unix-socket dev setups (issue #343).** A local database.yml with no `host:` is a Unix-socket connection: ActiveRecord connects via libpq's default socket (`PGHOST` / the default socket dir), but pgbus's AR-config extraction defaulted the absent `host`/`port` to TCP `localhost:5432`, silently diverging from AR and pointing pgmq's dedicated raw connections at a *different* server (or nothing) on any machine where the socket dir isn't `localhost`. Apps on socket-based dev DBs therefore couldn't use the AR-extraction path at all and had to pin an explicit `connection_params` Hash whose only real job was *not* defaulting `host` (cosmos carried an `after_initialize` block for exactly this). The two fallbacks are dropped: `host`/`port` now pass through as-is and `.compact` removes them when absent, so libpq applies its own socket defaults and matches AR. A config that *does* set `host`/`port` is byte-identical to before. Refs #343.
 - **`config.log_format` no longer breaks `ActiveSupport::TaggedLogging` — tags are preserved instead of dropped, and `logger.tagged` no longer raises (issue #334).** TaggedLogging works by extending the logger's formatter instance with a module that prepends the current tags. Installing a fresh pgbus formatter (`LogFormatter::JSON`/`Text`) stripped that extension, so `logger.tagged("req-42") { ... }` dropped the tag — and, worse, raised `NoMethodError: undefined method 'tagged'` on the pgbus formatter (a deploy-breaker several apps hit, then worked around with a dedicated `$stdout` logger). `log_format=` now re-extends the replacement formatter with `ActiveSupport::TaggedLogging::Formatter` when the previous one carried it, so tagging keeps working. Refs #334.
 - **The "Dashboard is accessible without authentication" warning is no longer a false positive when a gating `base_controller_class` is set (issue #334).** The warning fired whenever `web_auth` was nil, ignoring that a non-default `base_controller_class` (e.g. an `AdminController` with its own `before_action`) already gates the dashboard — so apps set a redundant `web_auth` lambda purely to silence the log line. The warning now stays quiet when `base_controller_class` is anything other than the default `::ActionController::Base`. Refs #334.
 - **`retry_on` on an `:until_executed` job no longer dead-letters the job instead of retrying (issue #333).** The uniqueness key is released only on success or DLQ, but ActiveJob's `retry_on` re-enqueues from *inside* `perform_now` (after incrementing `executions`), while the executor still holds the key. That retry re-enqueue hit the job's own still-held key, was rejected as a duplicate (`JobNotUnique` under `on_conflict: :reject`), and the original message dead-lettered — so a job with both `ensures_uniqueness :until_executed` and `retry_on` lost its retry and DLQ'd on the first transient failure. A retry re-enqueue (`executions > 0`) is now recognized as the same logical job re-acquiring its own key and is allowed through; the existing key row correctly stays held until the job finally succeeds or dead-letters. Cross-job uniqueness (a genuine fresh duplicate, `executions == 0`) is still rejected. Proven end-to-end with a DB-gated integration test (fail-once-then-succeed runs to success exactly once, no `JobNotUnique`, no DLQ, key cleaned up). Refs #333.

data/README.md

@@ -1872,6 +1872,25 @@ rake pgbus:doctor  # identical checks, for a Rake-based deploy pipeline
 
 The report ends with a resolved-config summary (queue prefix, pool size, roles, capsules) with any password redacted from `database_url` / `connection_params`. Warnings do not fail the exit code — only a `:fail` result does.
 
+##### Doctor preflight at boot (single Rails boot)
+
+Running `pgbus doctor || true` in a container entrypoint before `pgbus start` boots the full Rails app **twice** on every deploy, and the pre-supervisor `Process liveness` check false-fails (no workers exist yet) — which is why the `|| true` is needed, swallowing any genuinely-fatal finding too. Instead, run the preflight *inside* the booting supervisor:
+
+```bash
+pgbus start --doctor          # run the preflight, log the report, always boot
+pgbus start --doctor-strict   # refuse to boot on a fatal check (exit non-zero, fork nothing)
+```
+
+or set it in the initializer:
+
+```ruby
+Pgbus.configure do |c|
+  c.doctor_on_boot = :report   # or :strict; nil/false (default) is off
+end
+```
+
+The boot preflight runs after the DB is verified reachable and queues are bootstrapped, but **before any worker is forked** — one Rails boot, and the `Process liveness` check is skipped (nothing to observe yet, so it can't false-fail). `:strict` aborts the boot only on a genuinely-fatal, non-transient check — a `Configuration` failure or an **absent** PGMQ schema. A transient DB blip that the lenient queue bootstrap is designed to ride out (surfacing as a `Queues` or `Database` failure) is reported but never aborts, so a fleet-wide cold boot against a momentarily-saturated primary doesn't fail every pod in lockstep.
+
 #### pgbus dlq
 
 Dead-letter inspect/drain operations from a headless deployment or incident runbook, routed through `Web::DataSource` so retry/discard semantics are identical to the dashboard (origin-queue re-enqueue, transactional produce+delete, lock release on discard) with zero raw SQL and no direct PGMQ calls:

data/lib/generators/pgbus/add_failed_events_index_generator.rb

@@ -29,7 +29,7 @@ module Pgbus
         say "Pgbus failed events unique index added!", :green
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Failed jobs will now be tracked in the dashboard"
         say ""
       end

data/lib/generators/pgbus/add_job_stats_generator.rb

@@ -29,7 +29,7 @@ module Pgbus
         say "Pgbus job stats table installed!", :green
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Stats collection is enabled by default"
         say "  3. View insights at /pgbus/insights"
         say ""

data/lib/generators/pgbus/add_job_stats_latency_generator.rb

@@ -29,7 +29,7 @@ module Pgbus
         say "Pgbus job stats latency columns installed!", :green
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Queue latency and retry metrics are now tracked automatically"
         say "  3. View latency insights at /pgbus/insights"
         say ""

data/lib/generators/pgbus/add_job_stats_queue_index_generator.rb

@@ -29,7 +29,7 @@ module Pgbus
         say "Pgbus job stats queue index added!", :green
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. The Insights 'latency by queue' aggregation will now use the index"
         say "     instead of sequentially scanning pgbus_job_stats. Install this on"
         say "     heavy-traffic deployments with a large job stats retention window."

data/lib/generators/pgbus/add_outbox_generator.rb

@@ -29,7 +29,7 @@ module Pgbus
         say "Pgbus outbox installed!", :green
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Enable in config: config.outbox_enabled = true"
         say "  3. Restart pgbus: bin/pgbus start"
         say ""

data/lib/generators/pgbus/add_presence_generator.rb

@@ -29,7 +29,7 @@ module Pgbus
         say "Pgbus presence installed!", :green
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Use in your code:"
         say "       Pgbus.stream(@room).presence.join(member_id: current_user.id.to_s)"
         say "       Pgbus.stream(@room).presence.members"

data/lib/generators/pgbus/add_queue_states_generator.rb

@@ -29,7 +29,7 @@ module Pgbus
         say "Pgbus queue states table installed!", :green
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Restart pgbus: bin/pgbus start"
         say ""
       end

data/lib/generators/pgbus/add_recurring_generator.rb

@@ -33,7 +33,7 @@ module Pgbus
         say "Pgbus recurring jobs installed!", :green
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Edit config/recurring.yml to define your recurring tasks"
         say "  3. Restart pgbus: bin/pgbus start"
         say ""

data/lib/generators/pgbus/add_stream_queues_generator.rb

@@ -35,7 +35,7 @@ module Pgbus
         say "streams register themselves on their next broadcast after migrating."
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Restart pgbus: bin/pgbus start"
         say ""
       end

data/lib/generators/pgbus/add_stream_stats_generator.rb

@@ -29,7 +29,7 @@ module Pgbus
         say "Pgbus stream stats table installed!", :green
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Opt in by setting `config.streams_stats_enabled = true` in your"
         say "     pgbus initializer (disabled by default — stream event volume can"
         say "     be high, so stats recording is off unless you ask for it)."

data/lib/generators/pgbus/add_uniqueness_keys_generator.rb

@@ -29,7 +29,7 @@ module Pgbus
         say "Pgbus uniqueness keys table installed!", :green
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Add `ensures_uniqueness` to your job classes (DSL is auto-included)"
         say "  3. Restart pgbus: bin/pgbus start"
         say ""

data/lib/generators/pgbus/install_generator.rb

@@ -99,7 +99,7 @@ module Pgbus
 
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{database_name}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Edit config/initializers/pgbus.rb to configure workers"
         say "  3. Start processing: bin/pgbus start"
         say ""
@@ -115,8 +115,11 @@ module Pgbus
         options[:pgmq_schema_mode]
       end
 
+      # An explicit --database wins; otherwise fall back to a database already
+      # configured via connects_to so a bare re-install targets the right DB
+      # and its setup hints/output name it (issue #344).
       def database_name
-        options[:database]
+        effective_database_name
       end
     end
   end

data/lib/generators/pgbus/migrate_job_locks_generator.rb

@@ -34,7 +34,7 @@ module Pgbus
         say "  3. Drop the old pgbus_job_locks table (8 columns, 3 indexes)"
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Restart pgbus: bin/pgbus start"
         say ""
       end

data/lib/generators/pgbus/migration_path.rb

@@ -1,27 +1,93 @@
 # frozen_string_literal: true
 
+require "pgbus/generators/database_target_detector"
+
 module Pgbus
   module Generators
     # Shared migration path logic for all pgbus generators.
     #
-    # When --database is passed, uses Rails' built-in db_migrate_path which
-    # reads migrations_paths from database.yml. This is the standard Rails
-    # multi-database mechanism and respects custom paths like db/pgbus_migrate/.
+    # A separate pgbus database can be selected two ways:
+    #
+    #   1. --database=pgbus explicitly on the generator invocation, or
+    #   2. the host app has already configured Pgbus with a dedicated database
+    #      (config.connects_to = { database: { writing: :pgbus } }).
     #
-    # Falls back to db/migrate/ when no --database is set (single-database mode).
+    # When either applies, migrations go to the separate-database path (e.g.
+    # db/pgbus_migrate) and the post-install output names the db:migrate:<name>
+    # task. When neither applies, everything falls back to db/migrate.
+    #
+    # Auto-detecting from connects_to (case 2) fixes issue #344: a bare
+    # `rails g pgbus:add_*` in an app configured for a separate database used to
+    # silently write to db/migrate and run against the WRONG database.
     module MigrationPath
       private
 
       def pgbus_migrate_path
-        if separate_database?
+        return "db/migrate" unless separate_database?
+
+        # --database was passed: Rails' db_migrate_path reads options[:database]
+        # and resolves migrations_paths from database.yml. When the database was
+        # instead auto-detected from connects_to, options[:database] is nil, so
+        # db_migrate_path can't see it — resolve the path for the detected
+        # database ourselves.
+        if options[:database].present?
           db_migrate_path
         else
-          "db/migrate"
+          resolve_detected_migrate_path
         end
       end
 
       def separate_database?
-        options[:database].present?
+        effective_database_name.present?
+      end
+
+      # The database name that migrations should target: an explicit --database
+      # wins; otherwise auto-detect from the app's connects_to configuration.
+      def effective_database_name
+        return @effective_database_name if defined?(@effective_database_name)
+
+        @effective_database_name =
+          if options[:database].present?
+            options[:database]
+          else
+            DatabaseTargetDetector.new(destination_root: destination_root).detect
+          end
+      end
+
+      # The `:name` suffix appended to `rails db:migrate` in post-install
+      # output. Empty string for single-database mode so the line reads a plain
+      # `rails db:migrate`.
+      def migrate_command_suffix
+        separate_database? ? ":#{effective_database_name}" : ""
+      end
+
+      # Migrations path for an auto-detected separate database. Rails' own
+      # db_migrate_path is keyed on options[:database], which is nil here, so
+      # look up migrations_paths for the detected database directly and fall
+      # back to the db/pgbus_migrate convention if it isn't in database.yml.
+      def resolve_detected_migrate_path
+        migrations_path_for(effective_database_name) || "db/pgbus_migrate"
+      end
+
+      def migrations_path_for(database_name)
+        return nil unless defined?(::ActiveRecord::Base) && defined?(::Rails) && ::Rails.respond_to?(:env)
+
+        config = ::ActiveRecord::Base.configurations.configs_for(
+          env_name: ::Rails.env,
+          name: database_name
+        )
+        Array(config&.migrations_paths).first
+      rescue StandardError => e
+        # A missing config for `database_name` isn't an error — configs_for
+        # returns nil and we fall back to the db/pgbus_migrate convention. But a
+        # genuine failure here (malformed database.yml, an AR API change) would
+        # otherwise be invisible, so surface it via the generator's own output
+        # the way update_generator#resolve_connection does — not Pgbus.logger
+        # (unavailable/inappropriate at generate time; pgbus_failed_events is the
+        # runtime job-failure table, not a generator diagnostics sink).
+        say "  !  could not resolve migrations_paths for #{database_name.inspect}: " \
+            "#{e.class}: #{e.message} (falling back to db/pgbus_migrate)", :yellow
+        nil
       end
     end
   end

data/lib/generators/pgbus/tune_autovacuum_generator.rb

@@ -33,7 +33,7 @@ module Pgbus
         say "automatically receive these settings."
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Restart pgbus: bin/pgbus start"
         say ""
       end

data/lib/generators/pgbus/tune_fillfactor_generator.rb

@@ -36,7 +36,7 @@ module Pgbus
         say "this setting."
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  1. Run: rails db:migrate#{migrate_command_suffix}"
         say "  2. Restart pgbus: bin/pgbus start"
         say ""
       end

data/lib/generators/pgbus/upgrade_pgmq_generator.rb

@@ -31,7 +31,7 @@ module Pgbus
         say ""
         say "Next steps:"
         say "  1. Review the migration in db/#{separate_database? ? "pgbus_migrate" : "migrate"}/"
-        say "  2. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  2. Run: rails db:migrate#{migrate_command_suffix}"
         say ""
       end
 

data/lib/pgbus/cli.rb

@@ -51,6 +51,16 @@ module Pgbus
       Pgbus.configuration.execution_mode = options[:execution_mode].to_sym if options[:execution_mode]
       apply_capsule_filter(options[:capsule]) if options[:capsule]
       apply_role_filter(options)
+      apply_doctor_flag(options)
+    end
+
+    # --doctor runs the boot preflight in report mode; --doctor-strict aborts
+    # the boot on a fatal finding. Both set config.doctor_on_boot, which the
+    # supervisor reads at boot (issue #347). Strict wins if both are passed — it
+    # is the stronger gate, so a user asking for both clearly wants strict.
+    def apply_doctor_flag(options)
+      Pgbus.configuration.doctor_on_boot = :report if options[:doctor]
+      Pgbus.configuration.doctor_on_boot = :strict if options[:doctor_strict]
     end
 
     def parse_start_options(args)
@@ -81,6 +91,14 @@ module Pgbus
         opts.on("--execution-mode MODE", "Execution mode: threads (default) or async") do |v|
           options[:execution_mode] = v
         end
+
+        opts.on("--doctor", "Run doctor preflight checks at boot and log the report (issue #347)") do
+          options[:doctor] = true
+        end
+
+        opts.on("--doctor-strict", "Run doctor preflight and refuse to boot on a fatal finding") do
+          options[:doctor_strict] = true
+        end
       end.parse!(args.dup)
       options
     end
@@ -199,6 +217,12 @@ module Pgbus
                              pattern)
           --execution-mode   Execution mode: threads (default) or async
                              (fiber-based, lower connection usage)
+          --doctor           Run doctor preflight checks in the booting
+                             supervisor and log the report (one Rails boot
+                             instead of `pgbus doctor` + `pgbus start`)
+          --doctor-strict    Like --doctor, but refuse to boot (exit non-zero,
+                             fork nothing) if a fatal check fails (bad config
+                             or an absent PGMQ schema)
 
         Environment for `mcp`:
           PGBUS_MCP_TOKEN          If set, PGBUS_MCP_AUTH_TOKEN must match for

data/lib/pgbus/configuration.rb

@@ -89,6 +89,19 @@ module Pgbus
     # PGMQ schema installation mode (:auto, :extension, :embedded)
     attr_reader :pgmq_schema_mode
 
+    # Run doctor preflight checks inside the supervisor at boot (issue #347),
+    # so an entrypoint need not boot Rails twice (once for `pgbus doctor`, once
+    # for `pgbus start`). nil/false (default) — off, byte-identical to today.
+    #   :report — run the preflight and log the report, always continue booting.
+    #   :strict — additionally REFUSE to boot (raise before forking any worker)
+    #             when a genuinely-fatal, non-transient check fails. The strict
+    #             set is deliberately narrow (Configuration, PGMQ schema) so a
+    #             transient boot-time DB blip — which the lenient queue bootstrap
+    #             is designed to ride out via child crash-and-backoff — never
+    #             aborts a whole fleet's cold boot in lockstep. Set via the
+    #             `--doctor` / `--doctor-strict` start flags too.
+    attr_reader :doctor_on_boot
+
     # Event consumers
     attr_reader :event_consumers
 
@@ -248,6 +261,7 @@ module Pgbus
       @worker_notify_database_url = nil
 
       @pgmq_schema_mode = :auto
+      @doctor_on_boot = nil
 
       @event_consumers = nil
 
@@ -566,6 +580,28 @@ module Pgbus
       @pgmq_schema_mode = mode
     end
 
+    VALID_DOCTOR_ON_BOOT_MODES = [nil, :report, :strict].freeze
+
+    # nil/false are both "off"; a String is coerced to a Symbol so the CLI flags
+    # and YAML-ish configs work. Validated at assignment time (like the other
+    # enum options), not in validate!.
+    def doctor_on_boot=(mode)
+      coerced = case mode
+                when nil, false then nil
+                when Symbol then mode
+                when String then mode.to_sym
+                else
+                  raise Pgbus::ConfigurationError,
+                        "Invalid doctor_on_boot type: #{mode.class}. Must be nil, false, String, or Symbol"
+                end
+      unless VALID_DOCTOR_ON_BOOT_MODES.include?(coerced)
+        raise Pgbus::ConfigurationError,
+              "Invalid doctor_on_boot: #{coerced.inspect}. Must be nil/false (off), :report, or :strict"
+      end
+
+      @doctor_on_boot = coerced
+    end
+
     def validate!
       if pool_size && !(pool_size.is_a?(Numeric) && pool_size.positive?)
         raise Pgbus::ConfigurationError, "pool_size must be a positive number or nil (auto-tune)"
@@ -1439,9 +1475,15 @@ module Pgbus
       # Rails 7.1+ db_config.configuration_hash returns the full config
       config_hash = db_config.configuration_hash
 
+      # Do NOT default host/port here. An absent `host:` in database.yml is a
+      # Unix-socket connection; AR connects via libpq's socket default, so pgmq's
+      # raw connections must too. Forcing TCP localhost:5432 diverges from AR on
+      # socket-based configs (issue #343). `.compact` drops the absent keys and
+      # libpq applies its own defaults (PGHOST / default socket dir). A
+      # present-but-nil port is preserved as nil (also dropped by compact).
       base = {
-        host: config_hash[:host] || "localhost",
-        port: (config_hash[:port] || 5432).to_i,
+        host: config_hash[:host],
+        port: config_hash[:port]&.to_i,
         dbname: config_hash[:database],
         user: config_hash[:username],
         password: config_hash[:password]

data/lib/pgbus/doctor.rb

@@ -25,26 +25,47 @@ module Pgbus
 
     STATUS_ICON = { ok: "✓", warn: "!", fail: "✗" }.freeze
 
+    # The ordered check suite, name → method. The name strings are the public,
+    # stable identity of each check (used in the report and to select subsets).
+    CHECKS = {
+      "Configuration" => :check_configuration,
+      "Database" => :check_database,
+      "PGMQ schema" => :check_pgmq_schema,
+      "Queues" => :check_queues,
+      "LISTEN/NOTIFY" => :check_notify,
+      "Process liveness" => :check_processes,
+      "GlobalID allowlist" => :check_allowed_global_id_models,
+      "Broadcast queue" => :check_broadcast_queue,
+      "Primary affinity" => :check_primary
+    }.freeze
+
+    # Process liveness reads the pgbus_processes table (via HealthAnalyzer), so
+    # it is only meaningful once workers have registered. The supervisor boot
+    # preflight (issue #347) runs BEFORE forking any worker, so it excludes this
+    # check — otherwise stale prior-generation worker rows plus a visible backlog
+    # would produce a false STALLED verdict on a redeploy.
+    BOOT_SKIP = ["Process liveness"].freeze
+
+    # The subset of checks whose :fail is genuinely deploy-fatal AND not a
+    # transient the supervisor is designed to ride out. Only these abort a
+    # `:strict` boot. Configuration#validate! failing is a real config bug;
+    # an absent PGMQ schema means the migrations never ran. Deliberately NOT
+    # Queues/Database: the lenient queue bootstrap swallows a boot-time DB blip
+    # so children crash-and-backoff and recover, and verify_connection! already
+    # gated a hard-down DB before the preflight — making either strict-fatal
+    # would turn a tolerated transient into a fleet-wide lockstep boot abort.
+    STRICT_FATAL = ["Configuration", "PGMQ schema"].freeze
+
     def initialize(config: Pgbus.configuration, client: Pgbus.client, data_source: nil)
       @config = config
       @client = client
-      @data_source = data_source || Pgbus::Web::DataSource.new(client: client)
+      @data_source = data_source
     end
 
     # Run all checks and return an array of result hashes:
     #   { name:, status: :ok|:warn|:fail, detail: }
     def run
-      @run ||= [
-        check_configuration,
-        check_database,
-        check_pgmq_schema,
-        check_queues,
-        check_notify,
-        check_processes,
-        check_allowed_global_id_models,
-        check_broadcast_queue,
-        check_primary
-      ].map(&:to_h)
+      @run ||= run_checks(CHECKS.keys)
     end
 
     # True when no check failed. Warnings do not fail the run — they surface a
@@ -53,11 +74,34 @@ module Pgbus
       run.none? { |c| c[:status] == :fail }
     end
 
+    # --- Supervisor boot preflight (issue #347) ---
+
+    # The checks safe to run inside the booting supervisor before any worker is
+    # forked: everything except the worker-dependent process-liveness check.
+    # Runs a genuine SUBSET — check_processes is never invoked — so there is no
+    # pre-fork HealthAnalyzer/DataSource round-trip.
+    def boot_checks
+      @boot_checks ||= run_checks(CHECKS.keys - BOOT_SKIP)
+    end
+
+    # True unless a strict-fatal check (see STRICT_FATAL) failed. Warnings and
+    # transient-shaped failures (Queues, Database) never block a `:strict` boot.
+    def boot_ok?
+      boot_checks.none? { |c| c[:status] == :fail && STRICT_FATAL.include?(c[:name]) }
+    end
+
+    # Human-readable report for the boot preflight — the boot_checks subset.
+    def boot_report
+      report(boot_checks)
+    end
+
     # Human-readable report: one line per check, then a resolved-config summary
     # with passwords redacted. Suitable for stdout in the CLI and rake task.
-    def report
+    # Defaults to the full run; pass a filtered result array (e.g. boot_checks)
+    # to render a subset.
+    def report(checks = run)
       lines = ["Pgbus Doctor", "=" * 40]
-      run.each do |check|
+      checks.each do |check|
         icon = STATUS_ICON.fetch(check[:status], "?")
         lines << format("%<icon>s %<name>-22s %<detail>s", icon: icon, name: check[:name], detail: check[:detail])
       end
@@ -86,6 +130,21 @@ module Pgbus
 
     private
 
+    # Run the named checks in CHECKS order and return an array of result hashes.
+    # Only the requested checks are INVOKED — a check omitted from `names` does
+    # no work (e.g. boot_checks never calls check_processes, so no HealthAnalyzer
+    # round-trip pre-fork).
+    def run_checks(names)
+      CHECKS.filter_map { |name, method| send(method).to_h if names.include?(name) }
+    end
+
+    # The dashboard data source backing the process-liveness check. Built lazily
+    # so the boot preflight (which excludes that check) never constructs a
+    # DataSource or touches the dashboard layer at the fork boundary.
+    def data_source
+      @data_source ||= Pgbus::Web::DataSource.new(client: @client)
+    end
+
     # True in a Rails production environment. Guarded so the doctor still runs
     # outside Rails (plain Ruby, tests) without assuming Rails is loaded.
     def production?
@@ -181,7 +240,7 @@ module Pgbus
     # from the shared HealthAnalyzer. STALLED (the silent-worker-wedge) is a
     # failure; DEGRADED is a warning; OK passes.
     def check_processes
-      verdict = Pgbus::MCP::HealthAnalyzer.new(@data_source).verdict
+      verdict = Pgbus::MCP::HealthAnalyzer.new(data_source).verdict
       status = verdict[:status]
       detail = Array(verdict[:reasons]).first || status
 

data/lib/pgbus/process/supervisor.rb

@@ -76,6 +76,14 @@ module Pgbus
         # notify_trigger_current? makes those calls cheap no-ops.
         bootstrap_queues
 
+        # Optional in-process doctor preflight (issue #347): run the diagnostic
+        # checks here — after config is loaded, the DB is verified reachable, and
+        # queues are bootstrapped, but BEFORE any worker is forked — so an
+        # entrypoint gets a single Rails boot instead of `pgbus doctor` + `pgbus
+        # start`. :strict aborts the boot (raising, so nothing forks) on a
+        # genuinely-fatal finding; :report only logs. Off by default.
+        run_doctor_preflight unless config.doctor_on_boot.nil?
+
         boot_processes
         monitor_loop
       ensure
@@ -683,6 +691,33 @@ module Pgbus
         ErrorReporter.report(e, { action: "bootstrap_queues" })
       end
 
+      # In-process doctor preflight (issue #347). Runs the boot-safe subset of
+      # doctor checks (everything except the worker-dependent process-liveness
+      # check, which has no workers to observe yet) against the supervisor's own
+      # config and the already-verified shared client, and logs the report.
+      #
+      # In :strict mode, a genuinely-fatal check (Doctor::STRICT_FATAL —
+      # Configuration or an absent PGMQ schema) aborts the boot by raising
+      # Pgbus::ConfigurationError. Because this runs before boot_processes, no
+      # child is forked, and `run`'s `ensure shutdown` tears down the heartbeat
+      # and health server — the same fail-fast path verify_connection! uses.
+      # A transient-shaped failure (Queues, Database) is reported but never
+      # aborts: the lenient bootstrap above is built to let children ride out a
+      # boot-time DB blip, and a strict abort there would take down a whole
+      # fleet's cold boot in lockstep.
+      def run_doctor_preflight
+        doctor = Pgbus::Doctor.new(config: config, client: Pgbus.client)
+        report = doctor.boot_report
+        Pgbus.logger.info { "[Pgbus] doctor preflight (#{config.doctor_on_boot}):\n#{report}" }
+
+        return unless config.doctor_on_boot == :strict
+        return if doctor.boot_ok?
+
+        raise Pgbus::ConfigurationError,
+              "doctor preflight failed a fatal check (doctor_on_boot: :strict) — refusing to boot. " \
+              "See the report above."
+      end
+
       def load_rails_app
         return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
 

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.11.0"
+  VERSION = "0.11.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.11.2
 platform: ruby
 authors:
 - Mikael Henriksson