Class: Pgbus::Generators::MigrationDetector

Inherits:

Object

Object
Pgbus::Generators::MigrationDetector

show all

Defined in:: lib/pgbus/generators/migration_detector.rb

Overview

Inspects a live ActiveRecord connection and determines which of pgbus's migration generators need to run to bring the schema up to date.

Usage:

detector = Pgbus::Generators::MigrationDetector.new(connection)
detector.missing_migrations
# => [:add_uniqueness_keys, :add_job_stats_queue_index, ...]

The returned symbols correspond to generator names that the pgbus:update generator invokes via Thor composition. Each symbol maps to exactly one generator (see GENERATOR_MAP).

Detection rules:

Fresh install (no core tables) → returns [:fresh_install] as a sentinel. The caller should tell the user to run pgbus:install instead of stacking 8 migrations.
Core tables missing → queued unconditionally. These are features pgbus assumes are present.
Opt-in feature tables missing → queued unconditionally. The user asked for update-to-latest, so we add the migration files but don't enable the feature in config. They'll opt in separately.
Columns missing on existing tables → queued. These are in-place schema upgrades (e.g. add_job_stats_latency adds enqueue_latency_ms + retry_count).
Indexes missing on existing tables → queued. Additive, safe.
Modern uniqueness table (pgbus_uniqueness_keys) missing → queue add_uniqueness_keys unconditionally. A legacy pgbus_job_locks table left over from an older install is not dropped by this detector — run pgbus:migrate_job_locks by hand to retire it.

Constant Summary collapse

FRESH_INSTALL = Sentinel returned when the database looks empty of pgbus tables. The caller (pgbus:update generator) should redirect the user to pgbus:install rather than trying to stack the full schema as individual add_* migrations.

:fresh_install

CORE_INSTALL_TABLES = The set of tables that the base pgbus:install migration creates. If NONE of these exist, we treat the DB as a fresh install.

%w[
  pgbus_processed_events
  pgbus_processes
  pgbus_failed_events
  pgbus_semaphores
  pgbus_blocked_executions
  pgbus_batches
].freeze

GENERATOR_MAP = generator_key → Rails generator name. Passed to Thor's invoke. Note: uniqueness_keys invokes add_uniqueness_keys, which only creates the modern pgbus_uniqueness_keys table. If the legacy pgbus_job_locks table is also present (an install mid-migration), run pgbus:migrate_job_locks separately to drop it — that generator is not part of this detector's default flow since it requires the legacy table to already exist.

{
  uniqueness_keys: "pgbus:add_uniqueness_keys",
  add_job_stats: "pgbus:add_job_stats",
  add_job_stats_latency: "pgbus:add_job_stats_latency",
  add_job_stats_queue_index: "pgbus:add_job_stats_queue_index",
  add_stream_stats: "pgbus:add_stream_stats",
  add_stream_queues: "pgbus:add_stream_queues",
  add_presence: "pgbus:add_presence",
  add_queue_states: "pgbus:add_queue_states",
  add_outbox: "pgbus:add_outbox",
  add_recurring: "pgbus:add_recurring",
  add_failed_events_index: "pgbus:add_failed_events_index",
  tune_autovacuum: "pgbus:tune_autovacuum",
  tune_fillfactor: "pgbus:tune_fillfactor"
}.freeze

DESCRIPTIONS = Human-friendly description of each migration for the generator output. Keeps the update generator's run log readable.

{
  uniqueness_keys: "uniqueness keys table (job deduplication)",
  add_job_stats: "job stats table (Insights dashboard)",
  add_job_stats_latency: "job stats latency columns (enqueue_latency_ms, retry_count)",
  add_job_stats_queue_index: "job stats (queue_name, created_at) index",
  add_stream_stats: "stream stats table (opt-in real-time Insights)",
  add_stream_queues: "stream queue registry (per-stream retention, orphan sweep, wildcard-worker safety)",
  add_presence: "presence members table (Turbo Streams presence)",
  add_queue_states: "queue states table (pause/resume)",
  add_outbox: "outbox entries table (transactional outbox)",
  add_recurring: "recurring tasks + executions tables",
  add_failed_events_index: "unique index on pgbus_failed_events (queue_name, msg_id)",
  tune_autovacuum: "autovacuum tuning for PGMQ queue and archive tables",
  tune_fillfactor: "fillfactor=70 on PGMQ queue tables (reduces page density during update churn)"
}.freeze

Instance Method Summary collapse

#initialize(connection) ⇒ MigrationDetector constructor
A new instance of MigrationDetector.
#missing_migrations ⇒ Object
Returns an Array of generator keys (symbols) in the order they should run.

Constructor Details

#initialize(connection) ⇒ `MigrationDetector`

Returns a new instance of MigrationDetector.



102
103
104

# File 'lib/pgbus/generators/migration_detector.rb', line 102

def initialize(connection)
  @connection = connection
end

Instance Method Details

#missing_migrations ⇒ `Object`

Returns an Array of generator keys (symbols) in the order they should run. Dependencies are resolved implicitly via order: the base table creation for a feature always comes before the column/index add-ons.

# File 'lib/pgbus/generators/migration_detector.rb', line 110

def missing_migrations
  return [FRESH_INSTALL] if fresh_install?

  [
    *uniqueness_key_migrations,
    *job_stats_migrations,
    *stream_stats_migrations,
    *stream_queues_migrations,
    *presence_migrations,
    *queue_states_migrations,
    *outbox_migrations,
    *recurring_migrations,
    *failed_events_index_migrations,
    *autovacuum_migrations,
    *fillfactor_migrations
  ]
end