solid_queue_autoscaler 1.0.8 → 1.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2caadbfc7fd3df7b06be9dbea2e3e667b5e8b49e8c302720fb07d56cfb1a7d1c
-  data.tar.gz: 0b4c14b56f29e1ed6537ecac97d279661d08d943320df901bf7c73f3a6bd8694
+  metadata.gz: 81d3e6d0be9fecbd42eb8e0539acec901babd77d99688e685a051a4c84e8c90f
+  data.tar.gz: 987c1f62cec4ce7435a1c5c07d37a01e15705919b81d5e7f8d28cb04688f91f5
 SHA512:
-  metadata.gz: f2b316153846191155d72961c4be0e95b6d6c2dd71aedc32a268dff92bd570736e703cc2a8e1e7be564b9899d407c80959350014a3ea167f0f3472d0224d2109
-  data.tar.gz: 4048d221c232b9b079d08f24e571dcc9b56c7c4b3c69d7ce14262e5986568c87c93d07152664667021e981018da79ac581335db82420070c5fcc243bfe626efd
+  metadata.gz: d07364fdabd8df5280f9f9216513fa1f7d0dc480f46a4ee7a7b854c586bf64131fd9f28495cf7cae698df90812c7713eb30c686265cebfeac5008017dab00e7e
+  data.tar.gz: cf31a9d4f505b68e80d12efbc36cbfb97452ac9207c66c6075093b77aeb74660b2fd20b722fa41dfd5e1d07be2dd1cf15594815ce1c775db02f6c7314e0e4f11

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.9] - 2025-01-17
+
+### Added
+- **`verify_setup!` method** - New diagnostic method to verify installation is correct
+  - Checks database connection (multi-database aware)
+  - Verifies both autoscaler tables exist with correct columns
+  - Tests adapter connectivity
+  - Returns a `VerificationResult` struct with `ok?`, `tables_exist?`, `cooldowns_shared?` methods
+  - Run `SolidQueueAutoscaler.verify_setup!` in Rails console to diagnose issues
+- **`verify_install!` alias** - Alias for `verify_setup!`
+- **`persist_cooldowns` configuration option** - Control whether cooldowns are stored in database (default: true) or in-memory
+
+### Fixed
+- **Fixed multi-database migration bug** - Migration generator now correctly handles `migrations_paths` as a string (not just array)
+  - Previously, migrations would be placed in a `d/` directory instead of `db/queue_migrate/` due to calling `.first` on a string
+  - Migrations now auto-detect the correct directory from your `database.yml` configuration
+- **Removed unreliable `self.connection` override** from migration templates - This didn't work because `SolidQueue::Record` isn't loaded at migration time
+- **Improved migration generator output** - Clearer instructions for single-database vs multi-database setups
+
+### Changed
+- `verify_setup!` returns `nil` instead of the result object to keep console output clean
+- Migration templates no longer try to override the database connection (rely on Rails native multi-database support instead)
+
 ## [1.0.8] - 2025-01-17
 
 ### Added

data/README.md

@@ -743,19 +743,23 @@ Solid Queue processes queues in order, so listing `autoscaler` first ensures tho
 
 ### Running as a Solid Queue Recurring Job (Recommended)
 
+> ⚠️ **IMPORTANT**: The `queue:` setting in `recurring.yml` **overrides** the `config.job_queue` setting!
+> If you omit `queue:` in your recurring.yml, the job will go to the `default` queue, NOT your configured queue.
+> Always ensure your `recurring.yml` queue matches your `config.job_queue` setting.
+
 Add to your `config/recurring.yml`:
 
 ```yaml
 # Single worker configuration
 autoscaler:
   class: SolidQueueAutoscaler::AutoscaleJob
-  queue: autoscaler
+  queue: autoscaler  # ⚠️ REQUIRED: Must match config.job_queue!
   schedule: every 30 seconds
 
 # Or for multi-worker: scale all workers
 autoscaler_all:
   class: SolidQueueAutoscaler::AutoscaleJob
-  queue: autoscaler
+  queue: autoscaler  # ⚠️ REQUIRED!
   schedule: every 30 seconds
   args:
     - :all
@@ -763,19 +767,25 @@ autoscaler_all:
 # Or scale specific worker types on different schedules
 autoscaler_critical:
   class: SolidQueueAutoscaler::AutoscaleJob
-  queue: autoscaler
+  queue: autoscaler  # ⚠️ REQUIRED!
   schedule: every 15 seconds
   args:
     - :critical_worker
 
 autoscaler_default:
   class: SolidQueueAutoscaler::AutoscaleJob
-  queue: autoscaler
+  queue: autoscaler  # ⚠️ REQUIRED!
   schedule: every 60 seconds
   args:
     - :default_worker
 ```
 
+> **Note on multiple worker dynos**: SolidQueue's recurring jobs are processed by the **dispatcher** process,
+> not workers. If each of your worker dynos runs its own dispatcher (which is the default on Heroku),
+> each dyno will try to enqueue the recurring job. To prevent duplicate enqueuing:
+> 1. Run a single dedicated dispatcher dyno, OR
+> 2. Configure workers to NOT run the dispatcher (set `dispatchers: []` in their solid_queue.yml)
+
 ### Running via Rake Tasks
 
 ```bash

data/lib/generators/solid_queue_autoscaler/migration_generator.rb

@@ -10,19 +10,195 @@ module SolidQueueAutoscaler
 
       source_root File.expand_path('templates', __dir__)
 
-      desc 'Creates the migration for SolidQueueAutoscaler state table'
+      class_option :database, type: :string, default: nil,
+                   desc: 'Specify database for multi-database setups (e.g., --database=queue)'
 
-      def create_migration_file
+      desc 'Creates migrations for SolidQueueAutoscaler tables'
+
+      def create_migration_files
+        detected_config = detect_database_config
+        migration_dir = determine_migration_directory(detected_config)
+        db_name = effective_database_name(detected_config)
+
+        # Show what we detected
+        print_detection_info(detected_config, migration_dir)
+
+        # Create state table migration
         migration_template 'create_solid_queue_autoscaler_state.rb.erb',
-                           'db/migrate/create_solid_queue_autoscaler_state.rb'
+                           "#{migration_dir}/create_solid_queue_autoscaler_state.rb"
+
+        # Create events table migration
+        migration_template 'create_solid_queue_autoscaler_events.rb.erb',
+                           "#{migration_dir}/create_solid_queue_autoscaler_events.rb"
+
+        print_instructions(migration_dir, db_name)
       end
 
       private
 
+      # Detect database configuration for SolidQueue.
+      # Returns a hash with :database_name, :migrations_path, :is_multi_db.
+      def detect_database_config
+        result = { database_name: nil, migrations_path: nil, is_multi_db: false }
+
+        # Check if Rails database config is available
+        return result unless defined?(Rails) && Rails.application
+
+        db_configs = Rails.application.config.database_configuration
+        env_config = db_configs[Rails.env.to_s] || {}
+
+        # Look for a 'queue' database configuration (Rails multi-DB naming convention).
+        # SolidQueue typically uses 'queue' as the database name.
+        queue_config = find_queue_database_config(env_config)
+
+        if queue_config
+          result[:is_multi_db] = true
+          result[:database_name] = queue_config[:name]
+          result[:migrations_path] = queue_config[:migrations_path]
+        end
+
+        result
+      rescue StandardError => e
+        say '  (Could not detect database config: ' + e.message + ')', :yellow
+        { database_name: nil, migrations_path: nil, is_multi_db: false }
+      end
+
+      # Find the queue database configuration from environment config.
+      def find_queue_database_config(env_config)
+        # Rails 7+ multi-database format: { 'primary' => {...}, 'queue' => {...} }
+        # Look for common queue database names.
+        queue_db_names = %w[queue solid_queue queue_database]
+
+        queue_db_names.each do |db_name|
+          if env_config[db_name].is_a?(Hash)
+            config = env_config[db_name]
+            migrations_path = normalize_migrations_path(config['migrations_paths'], db_name)
+            return { name: db_name, migrations_path: migrations_path }
+          end
+        end
+
+        # Check if any database config has migrations_paths containing 'queue'.
+        env_config.each do |name, config|
+          next unless config.is_a?(Hash)
+          next if name == 'primary' # Skip primary database
+
+          migrations_paths = config['migrations_paths']
+          path_str = normalize_migrations_path(migrations_paths, name)
+          if path_str.include?('queue')
+            return { name: name, migrations_path: path_str }
+          end
+        end
+
+        nil
+      end
+
+      # Normalize migrations_paths which can be a string or array.
+      def normalize_migrations_path(migrations_paths, db_name)
+        case migrations_paths
+        when String
+          migrations_paths
+        when Array
+          migrations_paths.first || "db/#{db_name}_migrate"
+        else
+          "db/#{db_name}_migrate"
+        end
+      end
+
+      # Determine the migration directory to use.
+      def determine_migration_directory(detected_config)
+        # 1. Explicit --database option takes precedence
+        if options[:database]
+          return 'db/' + options[:database] + '_migrate'
+        end
+
+        # 2. If we detected a queue database with migrations_path, use it
+        if detected_config[:is_multi_db] && detected_config[:migrations_path]
+          return detected_config[:migrations_path]
+        end
+
+        # 3. Default to standard migrate directory
+        'db/migrate'
+      end
+
+      # Get the effective database name for running migrations.
+      def effective_database_name(detected_config)
+        return options[:database] if options[:database]
+        return detected_config[:database_name] if detected_config[:is_multi_db]
+
+        nil
+      end
+
+      def print_detection_info(detected_config, migration_dir)
+        say ''
+
+        if options[:database]
+          say '📁 Using specified database: ' + options[:database], :green
+        elsif detected_config[:is_multi_db]
+          say '📁 Auto-detected multi-database setup!', :green
+          say '   Database: ' + detected_config[:database_name].to_s, :green
+          say '   Migration path: ' + detected_config[:migrations_path].to_s, :green
+        else
+          say '📁 Using standard migration directory', :green
+
+          # Runtime check: warn if SolidQueue appears to use separate connection
+          if solidqueue_uses_separate_connection?
+            say ''
+            say '⚠️  Warning: SolidQueue appears to use a separate database connection!', :yellow
+            say '   But we could not detect the migrations_paths from database.yml.', :yellow
+            say '   If tables end up in the wrong database, re-run with:', :yellow
+            say '   rails g solid_queue_autoscaler:migration --database=queue', :yellow
+            say ''
+          end
+        end
+
+        say '   Placing migrations in: ' + migration_dir + '/', :blue
+        say ''
+      end
+
+      # Check at runtime if SolidQueue uses a separate database connection.
+      def solidqueue_uses_separate_connection?
+        return false unless defined?(SolidQueue::Record)
+        return false unless SolidQueue::Record.respond_to?(:connection)
+
+        sq_pool = SolidQueue::Record.connection_pool
+        ar_pool = ActiveRecord::Base.connection_pool
+
+        sq_pool.db_config.database != ar_pool.db_config.database
+      rescue StandardError
+        false
+      end
+
+      def print_instructions(migration_dir, db_name)
+        say '✅ Migrations generated successfully!', :green
+        say ''
+        say '📖 To run the migrations:', :blue
+
+        if db_name
+          # Multi-database setup
+          say '   rails db:migrate:' + db_name.to_s, :cyan
+          say ''
+          say '   Or if that does not work:', :blue
+          say '   DATABASE=' + db_name.to_s + ' rails db:migrate', :cyan
+        elsif migration_dir != 'db/migrate'
+          # Custom migration directory without detected database name
+          db_from_path = migration_dir.sub('db/', '').sub('_migrate', '')
+          say '   rails db:migrate:' + db_from_path, :cyan
+        else
+          # Standard single-database
+          say '   rails db:migrate', :cyan
+        end
+
+        say ''
+        say '🔍 To verify setup after migration:', :blue
+        say '   SolidQueueAutoscaler.verify_setup!', :cyan
+        say ''
+      end
+
       def migration_version
         return unless defined?(ActiveRecord::VERSION)
 
-        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+        '[' + ActiveRecord::VERSION::MAJOR.to_s + '.' +
+          ActiveRecord::VERSION::MINOR.to_s + ']'
       end
     end
   end

data/lib/generators/solid_queue_autoscaler/templates/README

@@ -5,24 +5,45 @@ SolidQueueAutoscaler has been installed!
 Next steps:
 
 1. Set environment variables:
-   - HEROKU_API_KEY: Generate with `heroku authorizations:create -d "Solid Queue Autoscaler"`
+   - HEROKU_API_KEY: Generate with `heroku authorizations:create -d 'Solid Queue Autoscaler'`
    - HEROKU_APP_NAME: Your Heroku app name
 
-2. Run the migration generator for persistent cooldown tracking:
+2. Run the migration generator:
 
+   SINGLE DATABASE (SolidQueue uses same database as your app):
+   ---------------------------------------------------------------
    rails generate solid_queue_autoscaler:migration
    rails db:migrate
 
-3. Review config/initializers/solid_queue_autoscaler.rb and adjust thresholds
+   MULTI-DATABASE (SolidQueue in separate 'queue' database):
+   ---------------------------------------------------------------
+   The generator will auto-detect your setup and place migrations
+   in the correct directory (e.g., db/queue_migrate/).
 
-4. Add the recurring job to config/recurring.yml:
+   rails generate solid_queue_autoscaler:migration
+   rails db:migrate:queue
+
+   Or specify explicitly:
+   rails generate solid_queue_autoscaler:migration --database=queue
+   rails db:migrate:queue
+
+3. Verify installation:
+
+   rails console
+   > SolidQueueAutoscaler.verify_setup!
+
+   This will check that tables are in the correct database.
+
+4. Review config/initializers/solid_queue_autoscaler.rb and adjust thresholds
+
+5. Add the recurring job to config/recurring.yml:
 
    autoscaler:
      class: SolidQueueAutoscaler::AutoscaleJob
      queue: autoscaler
      schedule: every 30 seconds
 
-5. Configure a dedicated queue in config/queue.yml:
+6. Configure a dedicated queue in config/queue.yml:
 
    queues:
      - autoscaler
@@ -34,7 +55,7 @@ Next steps:
      - queues: [default]
        threads: 5
 
-6. Test with dry_run mode before enabling in production
+7. Test with dry_run mode before enabling in production
 
 For more information, see: https://github.com/reillyse/solid_queue_autoscaler
 

data/lib/generators/solid_queue_autoscaler/templates/create_solid_queue_autoscaler_events.rb.erb

@@ -1,33 +1,31 @@
 # frozen_string_literal: true
 
+# Migration for SolidQueueAutoscaler events table (for dashboard and event history).
+#
+# For multi-database setups (SolidQueue in separate database):
+#   This migration should be placed in db/queue_migrate/ (or your queue DB's migration path)
+#   Run with: rails db:migrate:queue
+#
+# For single-database setups:
+#   Place in db/migrate/ and run: rails db:migrate
+#
 class CreateSolidQueueAutoscalerEvents < ActiveRecord::Migration<%= migration_version %>
-  # Use the same database connection as SolidQueue for multi-database setups
-  def self.connection
-    if defined?(SolidQueue::Record) && SolidQueue::Record.respond_to?(:connection)
-      SolidQueue::Record.connection
-    else
-      super
-    end
-  end
-
   def change
     create_table :solid_queue_autoscaler_events do |t|
-      t.string :worker_name, null: false
+      t.string :worker_name, null: false, default: 'default'
       t.string :action, null: false
-      t.integer :from_workers, null: false, default: 0
-      t.integer :to_workers, null: false, default: 0
-      t.text :reason
-      t.integer :queue_depth, default: 0
-      t.float :latency_seconds, default: 0.0
-      t.jsonb :metrics_json
+      t.integer :from_workers, null: false
+      t.integer :to_workers, null: false
+      t.string :reason
+      t.integer :queue_depth
+      t.float :latency_seconds
+      t.text :metrics_json
       t.boolean :dry_run, default: false
-
       t.datetime :created_at, null: false
     end
 
+    add_index :solid_queue_autoscaler_events, :created_at
     add_index :solid_queue_autoscaler_events, :worker_name
     add_index :solid_queue_autoscaler_events, :action
-    add_index :solid_queue_autoscaler_events, :created_at
-    add_index :solid_queue_autoscaler_events, %i[worker_name created_at]
   end
 end

data/lib/generators/solid_queue_autoscaler/templates/create_solid_queue_autoscaler_state.rb.erb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
+# Migration for SolidQueueAutoscaler cooldown state table.
+#
+# For multi-database setups (SolidQueue in separate database):
+#   This migration should be placed in db/queue_migrate/ (or your queue DB's migration path)
+#   Run with: rails db:migrate:queue
+#
+# For single-database setups:
+#   Place in db/migrate/ and run: rails db:migrate
+#
 class CreateSolidQueueAutoscalerState < ActiveRecord::Migration<%= migration_version %>
-  # Use the same database connection as SolidQueue for multi-database setups
-  def self.connection
-    if defined?(SolidQueue::Record) && SolidQueue::Record.respond_to?(:connection)
-      SolidQueue::Record.connection
-    else
-      super
-    end
-  end
-
   def change
     create_table :solid_queue_autoscaler_state do |t|
       t.string :key, null: false

data/lib/solid_queue_autoscaler/autoscale_job.rb

@@ -2,39 +2,16 @@
 
 module SolidQueueAutoscaler
   class AutoscaleJob < ActiveJob::Base
-    # Use configured queue for the target worker (defaults to :autoscaler)
-    queue_as do
-      # perform(worker_name = :default)
-      worker_name = arguments.first
-
-      # When scaling all workers, or when worker_name is nil, use the default configuration
-      config_name =
-        if worker_name.nil? || worker_name == :all || worker_name == "all"
-          :default
-        else
-          # Handle both Symbol and String values safely
-          worker_name.to_sym rescue :default
-        end
-
-      SolidQueueAutoscaler.config(config_name).job_queue || :autoscaler
-    end
-
-    # Use configured priority for the target worker (defaults to nil/no priority)
-    queue_with_priority do
-      # perform(worker_name = :default)
-      worker_name = arguments.first
-
-      # When scaling all workers, or when worker_name is nil, use the default configuration
-      config_name =
-        if worker_name.nil? || worker_name == :all || worker_name == "all"
-          :default
-        else
-          # Handle both Symbol and String values safely
-          worker_name.to_sym rescue :default
-        end
-
-      SolidQueueAutoscaler.config(config_name).job_priority
-    end
+    # IMPORTANT: Use a static queue name so SolidQueue recurring jobs work correctly.
+    # When using SolidQueue recurring.yml without specifying queue:, SolidQueue
+    # checks the job class's queue_name attribute. A dynamic queue_as block
+    # returns a Proc that isn't evaluated by recurring jobs, causing jobs to
+    # go to 'default' queue instead.
+    #
+    # To use a custom queue:
+    # 1. Set queue: in your recurring.yml (recommended)
+    # 2. Or use AutoscaleJob.set(queue: :my_queue).perform_later
+    queue_as :autoscaler
 
     discard_on ConfigurationError
 

data/lib/solid_queue_autoscaler/configuration.rb

@@ -63,6 +63,9 @@ module SolidQueueAutoscaler
     # Dashboard/event recording settings
     attr_accessor :record_events, :record_all_events
 
+    # Cooldown persistence (survives process restarts)
+    attr_accessor :persist_cooldowns
+
     # AutoscaleJob settings
     attr_accessor :job_queue, :job_priority
 
@@ -132,6 +135,9 @@ module SolidQueueAutoscaler
       @record_events = true # Record scale events to database
       @record_all_events = false # Also record no_change events (verbose)
 
+      # Cooldown persistence (survives process restarts, requires migration)
+      @persist_cooldowns = true
+
       # AutoscaleJob settings
       @job_queue = :autoscaler # Queue name for the autoscaler job
       @job_priority = nil # Job priority (lower = higher priority, nil = default)

data/lib/solid_queue_autoscaler/scale_event.rb

@@ -48,6 +48,124 @@ module SolidQueueAutoscaler
     end
 
     class << self
+      # Diagnostic method to help debug why events aren't being saved.
+      # @param config [Configuration, nil] Configuration to check (uses default if nil)
+      # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter, nil] Database connection
+      # @return [Hash] Diagnostic information
+      def debug_event_saving(config: nil, connection: nil)
+        config ||= SolidQueueAutoscaler.config rescue nil
+        conn = connection || default_connection rescue nil
+
+        diagnostics = {
+          timestamp: Time.current,
+          config_present: !config.nil?,
+          connection_present: !conn.nil?,
+          record_events_setting: nil,
+          connection_available: false,
+          record_events_effective: false,
+          table_exists: false,
+          can_query: false,
+          can_insert: false,
+          issues: [],
+          connection_class: nil,
+          error: nil
+        }
+
+        # Check config settings
+        if config
+          diagnostics[:record_events_setting] = config.record_events
+          diagnostics[:connection_available] = config.connection_available?
+          diagnostics[:record_events_effective] = config.record_events?
+
+          unless config.record_events
+            diagnostics[:issues] << 'config.record_events is false'
+          end
+
+          unless config.connection_available?
+            diagnostics[:issues] << 'config.connection_available? returned false'
+          end
+        else
+          diagnostics[:issues] << 'No configuration found'
+        end
+
+        # Check connection
+        if conn
+          diagnostics[:connection_class] = conn.class.name
+
+          # Check table exists
+          begin
+            diagnostics[:table_exists] = conn.table_exists?(TABLE_NAME)
+            unless diagnostics[:table_exists]
+              diagnostics[:issues] << "Table '#{TABLE_NAME}' does not exist. Run: rails generate solid_queue_autoscaler:dashboard"
+            end
+          rescue StandardError => e
+            diagnostics[:issues] << "Error checking table existence: #{e.message}"
+          end
+
+          # Check can query
+          if diagnostics[:table_exists]
+            begin
+              conn.select_value("SELECT COUNT(*) FROM #{TABLE_NAME}")
+              diagnostics[:can_query] = true
+            rescue StandardError => e
+              diagnostics[:issues] << "Error querying table: #{e.message}"
+            end
+          end
+
+          # Check can insert (with rollback)
+          if diagnostics[:can_query]
+            begin
+              # Try a test insert that we'll check but not actually commit
+              test_sql = <<~SQL
+                INSERT INTO #{TABLE_NAME}
+                  (worker_name, action, from_workers, to_workers, reason,
+                   queue_depth, latency_seconds, metrics_json, dry_run, created_at)
+                VALUES
+                  (#{conn.quote('_debug_test')},
+                   #{conn.quote('skipped')},
+                   #{conn.quote(0)},
+                   #{conn.quote(0)},
+                   #{conn.quote('debug test - should be deleted')},
+                   #{conn.quote(0)},
+                   #{conn.quote(0.0)},
+                   #{conn.quote(nil)},
+                   #{conn.quote(true)},
+                   #{conn.quote(Time.current)})
+                RETURNING id
+              SQL
+
+              result = conn.execute(test_sql)
+              test_id = result.first&.fetch('id', nil)
+
+              if test_id
+                diagnostics[:can_insert] = true
+                # Clean up test record
+                conn.execute("DELETE FROM #{TABLE_NAME} WHERE id = #{test_id}")
+              else
+                diagnostics[:issues] << 'INSERT succeeded but no id returned'
+              end
+            rescue StandardError => e
+              diagnostics[:issues] << "Error inserting test record: #{e.message}"
+            end
+          end
+        else
+          diagnostics[:issues] << 'No database connection available'
+        end
+
+        # Summary
+        diagnostics[:would_save_events] = diagnostics[:record_events_effective] &&
+                                          diagnostics[:table_exists] &&
+                                          diagnostics[:can_insert]
+
+        diagnostics
+      rescue StandardError => e
+        {
+          timestamp: Time.current,
+          error: "#{e.class}: #{e.message}",
+          issues: ["Unexpected error during diagnostics: #{e.message}"]
+        }
+      end
+
       # Creates a new scale event record.
       # @param attrs [Hash] Event attributes
       # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] Database connection
@@ -209,6 +327,71 @@ module SolidQueueAutoscaler
         0
       end
 
+      # Returns diagnostic information to help debug event storage issues.
+      # Use this method in Rails console to understand why events might not be stored.
+      #
+      # @example Check why events aren't being stored
+      #   SolidQueueAutoscaler::ScaleEvent.diagnostics
+      #   # => { table_exists: false, error: "Table does not exist..." }
+      #
+      # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] Database connection
+      # @return [Hash] Diagnostic information
+      def diagnostics(connection: nil)
+        conn = connection || default_connection
+        result = {
+          table_name: TABLE_NAME,
+          connection_class: conn.class.name,
+          table_exists: false,
+          event_count: 0,
+          recent_events: 0,
+          last_event_at: nil,
+          error: nil
+        }
+
+        # Check table existence
+        begin
+          result[:table_exists] = conn.table_exists?(TABLE_NAME)
+        rescue StandardError => e
+          result[:error] = "Failed to check table existence: #{e.message}"
+          return result
+        end
+
+        unless result[:table_exists]
+          result[:error] = "Table does not exist. Run: rails generate solid_queue_autoscaler:migration && rails db:migrate"
+          return result
+        end
+
+        # Get event counts
+        begin
+          result[:event_count] = count(connection: conn)
+          result[:recent_events] = count(since: 24.hours.ago, connection: conn)
+
+          # Get last event time
+          sql = "SELECT MAX(created_at) FROM #{TABLE_NAME}"
+          last_at = conn.select_value(sql)
+          result[:last_event_at] = last_at ? parse_time(last_at) : nil
+        rescue StandardError => e
+          result[:error] = "Failed to query events: #{e.message}"
+        end
+
+        # Add configuration info
+        begin
+          config = SolidQueueAutoscaler.config
+          result[:config] = {
+            record_events: config.record_events,
+            record_all_events: config.record_all_events,
+            record_events_effective: config.record_events?,
+            connection_available: config.connection_available?
+          }
+        rescue StandardError => e
+          result[:config_error] = e.message
+        end
+
+        result
+      rescue StandardError => e
+        { error: "Diagnostics failed: #{e.message}" }
+      end
+
       private
 
       def default_connection

data/lib/solid_queue_autoscaler/scaler.rb

@@ -82,6 +82,7 @@ module SolidQueueAutoscaler
       @metrics_collector = Metrics.new(config: @config)
       @decision_engine = DecisionEngine.new(config: @config)
       @adapter = @config.adapter
+      @cooldown_tracker = nil # Lazy-loaded when persist_cooldowns is enabled
     end
 
     def run
@@ -124,44 +125,117 @@ module SolidQueueAutoscaler
     end
 
     def apply_decision(decision, metrics)
-      @adapter.scale(decision.to)
+      # Re-verify current workers to catch race conditions where another instance
+      # may have scaled while we were making our decision
+      verified_current = @adapter.current_workers
+      
+      if verified_current != decision.from
+        logger.warn(
+          "[Autoscaler] Worker count changed during decision: expected=#{decision.from}, actual=#{verified_current}. " \
+          "Re-evaluating..."
+        )
+        
+        # If we're already at or above max, don't scale up
+        if decision.scale_up? && verified_current >= @config.max_workers
+          return skipped_result(
+            "Aborted scale_up: already at max_workers (#{verified_current} >= #{@config.max_workers})",
+            decision: decision,
+            metrics: metrics
+          )
+        end
+        
+        # If we're already at or below min, don't scale down
+        if decision.scale_down? && verified_current <= @config.min_workers
+          return skipped_result(
+            "Aborted scale_down: already at min_workers (#{verified_current} <= #{@config.min_workers})",
+            decision: decision,
+            metrics: metrics
+          )
+        end
+      end
+
+      # Final safety clamp: never exceed configured limits
+      target = decision.to.clamp(@config.min_workers, @config.max_workers)
+      
+      if target != decision.to
+        logger.warn(
+          "[Autoscaler] Clamping target from #{decision.to} to #{target} " \
+          "(limits: #{@config.min_workers}-#{@config.max_workers})"
+        )
+        # Ensure decision reflects the clamped target for logging and events
+        decision.to = target
+      end
+      
+      @adapter.scale(target)
       record_scale_time(decision)
       record_scale_event(decision, metrics)
-
+      
       log_scale_action(decision)
 
       success_result(decision, metrics)
     end
 
     def cooldown_active?(decision)
-      config_name = @config.name
-      if decision.scale_up?
-        last_scale_up = self.class.last_scale_up_at(config_name)
-        return false unless last_scale_up
-
-        Time.current - last_scale_up < @config.effective_scale_up_cooldown
-      elsif decision.scale_down?
-        last_scale_down = self.class.last_scale_down_at(config_name)
-        return false unless last_scale_down
-
-        Time.current - last_scale_down < @config.effective_scale_down_cooldown
+      if @config.persist_cooldowns && cooldown_tracker.table_exists?
+        # Use database-persisted cooldowns (survives process restarts)
+        if decision.scale_up?
+          cooldown_tracker.cooldown_active_for_scale_up?
+        elsif decision.scale_down?
+          cooldown_tracker.cooldown_active_for_scale_down?
+        else
+          false
+        end
       else
-        false
+        # Fall back to in-memory cooldowns
+        config_name = @config.name
+        if decision.scale_up?
+          last_scale_up = self.class.last_scale_up_at(config_name)
+          return false unless last_scale_up
+
+          Time.current - last_scale_up < @config.effective_scale_up_cooldown
+        elsif decision.scale_down?
+          last_scale_down = self.class.last_scale_down_at(config_name)
+          return false unless last_scale_down
+
+          Time.current - last_scale_down < @config.effective_scale_down_cooldown
+        else
+          false
+        end
       end
     end
 
     def cooldown_remaining(decision)
-      config_name = @config.name
-      if decision.scale_up?
-        elapsed = Time.current - self.class.last_scale_up_at(config_name)
-        @config.effective_scale_up_cooldown - elapsed
+      if @config.persist_cooldowns && cooldown_tracker.table_exists?
+        # Use database-persisted cooldowns
+        if decision.scale_up?
+          cooldown_tracker.scale_up_cooldown_remaining
+        else
+          cooldown_tracker.scale_down_cooldown_remaining
+        end
       else
-        elapsed = Time.current - self.class.last_scale_down_at(config_name)
-        @config.effective_scale_down_cooldown - elapsed
+        # Fall back to in-memory cooldowns
+        config_name = @config.name
+        if decision.scale_up?
+          elapsed = Time.current - self.class.last_scale_up_at(config_name)
+          @config.effective_scale_up_cooldown - elapsed
+        else
+          elapsed = Time.current - self.class.last_scale_down_at(config_name)
+          @config.effective_scale_down_cooldown - elapsed
+        end
       end
     end
 
     def record_scale_time(decision)
+      if @config.persist_cooldowns && cooldown_tracker.table_exists?
+        # Use database-persisted cooldowns
+        if decision.scale_up?
+          cooldown_tracker.record_scale_up!
+        elsif decision.scale_down?
+          cooldown_tracker.record_scale_down!
+        end
+      end
+
+      # Always update in-memory cooldowns as well (for immediate effect within same process)
       config_name = @config.name
       if decision.scale_up?
         self.class.set_last_scale_up_at(config_name, Time.current)
@@ -170,6 +244,10 @@ module SolidQueueAutoscaler
       end
     end
 
+    def cooldown_tracker
+      @cooldown_tracker ||= CooldownTracker.new(config: @config, key: @config.name.to_s)
+    end
+
     def log_decision(decision, metrics)
       worker_label = @config.name == :default ? '' : "[#{@config.name}] "
       logger.info(

data/lib/solid_queue_autoscaler/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidQueueAutoscaler
-  VERSION = '1.0.8'
+  VERSION = '1.0.9'
 end

data/lib/solid_queue_autoscaler.rb

@@ -99,6 +99,260 @@ module SolidQueueAutoscaler
         configurations[:default] = config_obj
       end
     end
+
+    # Verify the installation is complete and working.
+    # Prints a human-friendly report (when verbose: true) and returns a VerificationResult.
+    #
+    # Usage (Rails/Heroku console):
+    #   SolidQueueAutoscaler.verify_setup!
+    #   # or alias:
+    #   SolidQueueAutoscaler.verify_install!
+    #
+    # You can also inspect the returned struct:
+    #   result = SolidQueueAutoscaler.verify_setup!(verbose: false)
+    #   result.ok?   # => true/false
+    #   result.to_h  # => hash of details
+    def verify_setup!(name = :default, verbose: true)
+      result = VerificationResult.new
+      cfg = config(name)
+      connection = cfg.connection
+
+      output = []
+      output << '=' * 60
+      output << 'SolidQueueAutoscaler Setup Verification'
+      output << '=' * 60
+      output << ''
+      output << "Version: #{VERSION}"
+      output << "Configuration: #{name}"
+
+      # Check connection type (handles SolidQueue in its own DB)
+      if defined?(SolidQueue::Record) && SolidQueue::Record.respond_to?(:connection)
+        output << '✓ Using SolidQueue::Record connection (multi-database setup)'
+        result.connection_type = :solid_queue_record
+      else
+        output << '✓ Using ActiveRecord::Base connection'
+        result.connection_type = :active_record_base
+      end
+
+      # 1. Cooldown state table
+      output << ''
+      output << '-' * 60
+      output << '1. COOLDOWN STATE TABLE (solid_queue_autoscaler_state)'
+      output << '-' * 60
+
+      if connection.table_exists?(:solid_queue_autoscaler_state)
+        result.state_table_exists = true
+        output << '✓ Table exists'
+
+        columns = connection.columns(:solid_queue_autoscaler_state).map(&:name)
+        expected = %w[id key last_scale_up_at last_scale_down_at created_at updated_at]
+        missing = expected - columns
+
+        if missing.empty?
+          result.state_table_columns_ok = true
+          output << '  ✓ All expected columns present'
+        else
+          result.state_table_columns_ok = false
+          result.add_warning("State table missing columns: #{missing.join(', ')}")
+          output << "  ⚠ Missing columns: #{missing.join(', ')}"
+        end
+
+        state_count = connection.select_value('SELECT COUNT(*) FROM solid_queue_autoscaler_state').to_i
+        output << "  Current records: #{state_count}"
+      else
+        result.state_table_exists = false
+        result.add_error('Cooldown state table does not exist')
+        output << '✗ Table DOES NOT EXIST'
+        output << '  Run: rails generate solid_queue_autoscaler:migration && rails db:migrate'
+        output << '  ⚠ Cooldowns are NOT shared across workers (using in-memory fallback)'
+      end
+
+      # 2. Events table
+      output << ''
+      output << '-' * 60
+      output << '2. EVENTS TABLE (solid_queue_autoscaler_events)'
+      output << '-' * 60
+
+      if connection.table_exists?(:solid_queue_autoscaler_events)
+        result.events_table_exists = true
+        output << '✓ Table exists'
+
+        columns = connection.columns(:solid_queue_autoscaler_events).map(&:name)
+        expected = %w[id worker_name action from_workers to_workers reason queue_depth latency_seconds metrics_json dry_run created_at]
+        missing = expected - columns
+
+        if missing.empty?
+          result.events_table_columns_ok = true
+          output << '  ✓ All expected columns present'
+        else
+          result.events_table_columns_ok = false
+          result.add_warning("Events table missing columns: #{missing.join(', ')}")
+          output << "  ⚠ Missing columns: #{missing.join(', ')}"
+        end
+
+        event_count = connection.select_value('SELECT COUNT(*) FROM solid_queue_autoscaler_events').to_i
+        output << "  Total events: #{event_count}"
+      else
+        result.events_table_exists = false
+        result.add_error('Events table does not exist')
+        output << '✗ Table DOES NOT EXIST'
+        output << '  Run: rails generate solid_queue_autoscaler:migration && rails db:migrate'
+        output << '  ⚠ Scale events are NOT being recorded (dashboard will be empty)'
+      end
+
+      # 3. Configuration
+      output << ''
+      output << '-' * 60
+      output << '3. CONFIGURATION'
+      output << '-' * 60
+
+      begin
+        result.config_valid = true
+        output << '✓ Configuration loaded'
+        output << "  enabled: #{cfg.enabled?}"
+        output << "  dry_run: #{cfg.dry_run?}"
+        output << "  persist_cooldowns: #{cfg.respond_to?(:persist_cooldowns) ? cfg.persist_cooldowns : '(not supported in this version)'}"
+        output << "  record_events: #{cfg.respond_to?(:record_events) ? cfg.record_events : '(not supported in this version)'}"
+        output << "  min_workers: #{cfg.min_workers}"
+        output << "  max_workers: #{cfg.max_workers}"
+        output << "  job_queue: #{cfg.job_queue}"
+        output << "  adapter: #{cfg.adapter.class.name}"
+      rescue StandardError => e
+        result.config_valid = false
+        result.add_error("Configuration error: #{e.message}")
+        output << "✗ Configuration error: #{e.message}"
+      end
+
+      # 4. Adapter connectivity
+      output << ''
+      output << '-' * 60
+      output << '4. ADAPTER CONNECTIVITY'
+      output << '-' * 60
+
+      begin
+        workers = cfg.adapter.current_workers
+        result.adapter_connected = true
+        output << "✓ Adapter connected (current workers: #{workers})"
+      rescue StandardError => e
+        result.adapter_connected = false
+        result.add_error("Adapter connection failed: #{e.message}")
+        output << "✗ Adapter connection failed: #{e.message}"
+      end
+
+      # 5. Solid Queue tables
+      output << ''
+      output << '-' * 60
+      output << '5. SOLID QUEUE TABLES'
+      output << '-' * 60
+
+      sq_tables = %w[solid_queue_jobs solid_queue_ready_executions solid_queue_claimed_executions solid_queue_processes]
+      result.solid_queue_tables = {}
+
+      sq_tables.each do |table|
+        if connection.table_exists?(table)
+          count = connection.select_value("SELECT COUNT(*) FROM #{table}").to_i
+          result.solid_queue_tables[table] = count
+          output << "✓ #{table}: #{count} records"
+        else
+          result.solid_queue_tables[table] = nil
+          output << "✗ #{table}: MISSING"
+        end
+      end
+
+      # Summary
+      output << ''
+      output << '=' * 60
+      output << 'SUMMARY'
+      output << '=' * 60
+
+      if result.ok?
+        output << '✓ All checks passed! Autoscaler is correctly configured.'
+        if result.cooldowns_shared?
+          output << '  Cooldowns: SHARED across workers (database-persisted)'
+        else
+          output << '  Cooldowns: In-memory only (not shared across workers)'
+        end
+        if result.events_table_exists
+          output << '  Events: RECORDING to database'
+        else
+          output << '  Events: NOT recording (events table missing)'
+        end
+      else
+        output << '⚠ Some issues found:'
+        result.errors.each { |err| output << "  ✗ #{err}" }
+        result.warnings.each { |warn| output << "  ⚠ #{warn}" }
+        output << ''
+        output << 'To fix missing tables, run:'
+        output << '  rails generate solid_queue_autoscaler:migration'
+        output << '  rails db:migrate'
+      end
+
+      puts output.join("\n") if verbose
+
+      nil
+    end
+
+    # Convenience alias so users can call verify_install! as requested
+    def verify_install!(name = :default, verbose: true)
+      verify_setup!(name, verbose: verbose)
+    end
+  end
+
+  # Structured result from verify_setup!/verify_install!
+  class VerificationResult
+    attr_accessor :connection_type,
+                  :state_table_exists, :state_table_columns_ok,
+                  :events_table_exists, :events_table_columns_ok,
+                  :config_valid, :adapter_connected,
+                  :solid_queue_tables
+
+    def initialize
+      @errors = []
+      @warnings = []
+      @solid_queue_tables = {}
+    end
+
+    def errors
+      @errors
+    end
+
+    def warnings
+      @warnings
+    end
+
+    def add_error(message)
+      @errors << message
+    end
+
+    def add_warning(message)
+      @warnings << message
+    end
+
+    def ok?
+      @errors.empty?
+    end
+
+    def tables_exist?
+      state_table_exists && events_table_exists
+    end
+
+    def cooldowns_shared?
+      state_table_exists && state_table_columns_ok
+    end
+
+    def to_h
+      {
+        ok: ok?,
+        connection_type: connection_type,
+        state_table: { exists: state_table_exists, columns_ok: state_table_columns_ok },
+        events_table: { exists: events_table_exists, columns_ok: events_table_columns_ok },
+        config_valid: config_valid,
+        adapter_connected: adapter_connected,
+        solid_queue_tables: solid_queue_tables,
+        errors: errors,
+        warnings: warnings
+      }
+    end
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_queue_autoscaler
 version: !ruby/object:Gem::Version
-  version: 1.0.8
+  version: 1.0.9
 platform: ruby
 authors:
 - reillyse
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-16 00:00:00.000000000 Z
+date: 2026-01-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord