pgbus 0.0.1 → 0.1.1

data/app/views/pgbus/jobs/_enqueued_table.html.erb

@@ -6,21 +6,59 @@
         <thead class="bg-gray-50">
           <tr>
             <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">ID</th>
+            <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Job Class</th>
             <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Queue</th>
             <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Enqueued</th>
             <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Reads</th>
-            <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Payload</th>
           </tr>
         </thead>
         <tbody class="divide-y divide-gray-100">
           <% @jobs.each do |j| %>
-            <tr class="hover:bg-gray-50">
-              <td class="px-4 py-3 text-sm font-mono text-gray-900"><%= j[:msg_id] %></td>
-              <td class="px-4 py-3 text-sm text-gray-700"><%= j[:queue_name] %></td>
-              <td class="px-4 py-3 text-sm text-gray-500"><%= pgbus_time_ago(j[:enqueued_at]) %></td>
-              <td class="px-4 py-3 text-sm text-gray-500"><%= j[:read_ct] %></td>
-              <td class="px-4 py-3 text-sm text-gray-600 font-mono text-xs max-w-md truncate">
-                <%= pgbus_json_preview(j[:message]) %>
+            <% payload = pgbus_parse_message(j[:message]) %>
+            <tr>
+              <td colspan="5" class="p-0">
+                <details class="group">
+                  <summary class="flex cursor-pointer hover:bg-gray-50 list-none">
+                    <span class="w-16 shrink-0 px-4 py-3 text-sm font-mono text-gray-900"><%= j[:msg_id] %></span>
+                    <span class="flex-1 px-4 py-3 text-sm font-medium text-gray-900"><%= payload["job_class"] || "—" %></span>
+                    <span class="w-40 shrink-0 px-4 py-3 text-sm text-gray-700"><%= j[:queue_name] %></span>
+                    <span class="w-28 shrink-0 px-4 py-3 text-sm text-gray-500"><%= pgbus_time_ago(j[:enqueued_at]) %></span>
+                    <span class="w-16 shrink-0 px-4 py-3 text-sm text-gray-500"><%= j[:read_ct] %></span>
+                  </summary>
+                  <div class="px-4 pb-4 bg-gray-50 border-t border-gray-100">
+                    <div class="flex items-center mt-3 mb-3">
+                      <span class="text-xs font-mono text-gray-400">Job ID: <%= payload["job_id"] %></span>
+                    </div>
+                    <div class="grid grid-cols-2 gap-4 mb-3">
+                      <div>
+                        <span class="text-xs font-medium text-gray-500">Arguments</span>
+                        <pre class="text-xs text-gray-700 bg-white rounded p-2 mt-1 overflow-x-auto max-h-40"><%= JSON.pretty_generate(payload["arguments"] || []) rescue "—" %></pre>
+                      </div>
+                      <div>
+                        <span class="text-xs font-medium text-gray-500">Metadata</span>
+                        <div class="text-xs text-gray-600 bg-white rounded p-2 mt-1 space-y-1">
+                          <% if payload["queue_name"] %><p><strong>Queue:</strong> <%= payload["queue_name"] %></p><% end %>
+                          <% if payload["priority"] %><p><strong>Priority:</strong> <%= payload["priority"] %></p><% end %>
+                          <% if payload["locale"] %><p><strong>Locale:</strong> <%= payload["locale"] %></p><% end %>
+                          <% if payload["timezone"] %><p><strong>Timezone:</strong> <%= payload["timezone"] %></p><% end %>
+                          <% if payload["scheduled_at"] %><p><strong>Scheduled:</strong> <%= payload["scheduled_at"] %></p><% end %>
+                          <% if j[:vt] %><p><strong>Visible at:</strong> <%= j[:vt] %></p><% end %>
+                          <% if j[:last_read_at] %><p><strong>Last read:</strong> <%= j[:last_read_at] %></p><% end %>
+                        </div>
+                      </div>
+                    </div>
+                    <details class="mt-2">
+                      <summary class="text-xs font-medium text-gray-500 cursor-pointer hover:text-gray-700">Full JSON payload</summary>
+                      <pre class="text-xs text-gray-600 bg-white rounded p-2 mt-1 overflow-x-auto max-h-96"><%= JSON.pretty_generate(payload) rescue j[:message] %></pre>
+                    </details>
+                    <% if j[:headers] %>
+                      <details class="mt-2">
+                        <summary class="text-xs font-medium text-gray-500 cursor-pointer hover:text-gray-700">Headers</summary>
+                        <pre class="text-xs text-gray-600 bg-white rounded p-2 mt-1 overflow-x-auto"><%= JSON.pretty_generate(JSON.parse(j[:headers])) rescue j[:headers] %></pre>
+                      </details>
+                    <% end %>
+                  </div>
+                </details>
               </td>
             </tr>
           <% end %>

data/app/views/pgbus/recurring_tasks/_tasks_table.html.erb

@@ -0,0 +1,79 @@
+<turbo-frame id="recurring-tasks" data-auto-refresh src="<%= pgbus.recurring_tasks_path(frame: 'recurring_tasks') %>">
+  <div class="rounded-lg bg-white shadow ring-1 ring-gray-200">
+    <% if @recurring_tasks.empty? %>
+      <div class="p-8 text-center text-gray-500">
+        <p class="text-lg font-medium">No recurring tasks configured</p>
+        <p class="mt-1 text-sm">Add tasks to <code class="bg-gray-100 px-1.5 py-0.5 rounded text-xs">config/recurring.yml</code></p>
+      </div>
+    <% else %>
+      <table class="min-w-full divide-y divide-gray-200">
+        <thead class="bg-gray-50">
+          <tr>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Task</th>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Schedule</th>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Queue</th>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Last Run</th>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Next Run</th>
+            <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Status</th>
+            <th class="px-4 py-3 text-right text-xs font-medium text-gray-500 uppercase">Actions</th>
+          </tr>
+        </thead>
+        <tbody class="divide-y divide-gray-200">
+          <% @recurring_tasks.each do |task| %>
+            <tr class="hover:bg-gray-50">
+              <td class="px-4 py-3">
+                <div>
+                  <%= link_to task[:key], pgbus.recurring_task_path(task[:id]),
+                      class: "text-sm font-medium text-blue-600 hover:text-blue-800" %>
+                </div>
+                <div class="text-xs text-gray-500"><%= task[:class_name] || task[:command]&.truncate(40) %></div>
+                <% if task[:description] %>
+                  <div class="text-xs text-gray-400 mt-0.5"><%= task[:description] %></div>
+                <% end %>
+              </td>
+              <td class="px-4 py-3">
+                <div class="text-sm text-gray-900"><%= task[:schedule] %></div>
+                <% if task[:human_schedule] && task[:human_schedule] != task[:schedule] %>
+                  <div class="text-xs text-gray-400"><%= task[:human_schedule] %></div>
+                <% end %>
+              </td>
+              <td class="px-4 py-3 text-sm text-gray-600">
+                <%= task[:queue_name] || "default" %>
+              </td>
+              <td class="px-4 py-3 text-sm text-gray-600">
+                <%= task[:last_run_at] ? pgbus_time_ago(task[:last_run_at]) : "Never" %>
+              </td>
+              <td class="px-4 py-3 text-sm text-gray-600">
+                <% if task[:enabled] && task[:next_run_at] %>
+                  <%= pgbus_time_ago_future(task[:next_run_at]) %>
+                <% else %>
+                  <span class="text-gray-400">—</span>
+                <% end %>
+              </td>
+              <td class="px-4 py-3">
+                <% if task[:enabled] %>
+                  <%= pgbus_recurring_health_badge(task) %>
+                <% else %>
+                  <span class="inline-flex items-center rounded-full bg-gray-100 px-2.5 py-0.5 text-xs font-medium text-gray-600">
+                    Disabled
+                  </span>
+                <% end %>
+              </td>
+              <td class="px-4 py-3 text-right space-x-1">
+                <%= button_to task[:enabled] ? "Disable" : "Enable",
+                    pgbus.toggle_recurring_task_path(task[:id]),
+                    class: "inline-flex items-center rounded px-2 py-1 text-xs font-medium " \
+                           "#{task[:enabled] ? 'bg-yellow-100 text-yellow-700 hover:bg-yellow-200' : 'bg-green-100 text-green-700 hover:bg-green-200'}" %>
+                <% if task[:enabled] %>
+                  <%= button_to "Run Now",
+                      pgbus.enqueue_recurring_task_path(task[:id]),
+                      class: "inline-flex items-center rounded bg-blue-100 px-2 py-1 text-xs font-medium text-blue-700 hover:bg-blue-200" %>
+                <% end %>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    <% end %>
+  </div>
+</turbo-frame>

data/app/views/pgbus/recurring_tasks/index.html.erb

@@ -0,0 +1,6 @@
+<div class="flex items-center justify-between mb-6">
+  <h1 class="text-2xl font-bold text-gray-900">Recurring Tasks</h1>
+  <span class="text-sm text-gray-500"><%= @recurring_tasks.size %> task(s) configured</span>
+</div>
+
+<%= render "pgbus/recurring_tasks/tasks_table" %>

data/app/views/pgbus/recurring_tasks/show.html.erb

@@ -0,0 +1,122 @@
+<div class="mb-6">
+  <div class="flex items-center justify-between">
+    <div>
+      <h1 class="text-2xl font-bold text-gray-900"><%= @task[:key] %></h1>
+      <p class="mt-1 text-sm text-gray-500"><%= @task[:class_name] || @task[:command] %></p>
+    </div>
+    <div class="flex space-x-2">
+      <%= button_to @task[:enabled] ? "Disable" : "Enable",
+          pgbus.toggle_recurring_task_path(@task[:id]),
+          class: "inline-flex items-center rounded-md px-3 py-2 text-sm font-medium " \
+                 "#{@task[:enabled] ? 'bg-yellow-100 text-yellow-700 hover:bg-yellow-200' : 'bg-green-100 text-green-700 hover:bg-green-200'}" %>
+      <% if @task[:enabled] %>
+        <%= button_to "Run Now",
+            pgbus.enqueue_recurring_task_path(@task[:id]),
+            class: "inline-flex items-center rounded-md bg-blue-600 px-3 py-2 text-sm font-medium text-white hover:bg-blue-700" %>
+      <% end %>
+      <%= link_to "Back", pgbus.recurring_tasks_path,
+          class: "inline-flex items-center rounded-md bg-gray-100 px-3 py-2 text-sm font-medium text-gray-700 hover:bg-gray-200" %>
+    </div>
+  </div>
+</div>
+
+<div class="grid grid-cols-1 lg:grid-cols-3 gap-6 mb-8">
+  <div class="rounded-lg bg-white p-5 shadow ring-1 ring-gray-200">
+    <p class="text-sm font-medium text-gray-500">Schedule</p>
+    <p class="mt-1 text-lg font-semibold text-gray-900"><%= @task[:schedule] %></p>
+    <% if @task[:human_schedule] && @task[:human_schedule] != @task[:schedule] %>
+      <p class="text-xs text-gray-400"><%= @task[:human_schedule] %></p>
+    <% end %>
+  </div>
+
+  <div class="rounded-lg bg-white p-5 shadow ring-1 ring-gray-200">
+    <p class="text-sm font-medium text-gray-500">Next Run</p>
+    <% if @task[:enabled] && @task[:next_run_at] %>
+      <p class="mt-1 text-lg font-semibold text-gray-900"><%= pgbus_time_ago_future(@task[:next_run_at]) %></p>
+      <p class="text-xs text-gray-400"><%= @task[:next_run_at]&.strftime("%Y-%m-%d %H:%M:%S %Z") %></p>
+    <% else %>
+      <p class="mt-1 text-lg font-semibold text-gray-400">—</p>
+    <% end %>
+  </div>
+
+  <div class="rounded-lg bg-white p-5 shadow ring-1 ring-gray-200">
+    <p class="text-sm font-medium text-gray-500">Status</p>
+    <p class="mt-1"><%= @task[:enabled] ? pgbus_recurring_health_badge(@task) : raw('<span class="inline-flex items-center rounded-full bg-gray-100 px-2.5 py-0.5 text-xs font-medium text-gray-600">Disabled</span>') %></p>
+  </div>
+</div>
+
+<div class="rounded-lg bg-white shadow ring-1 ring-gray-200 mb-8">
+  <div class="px-4 py-3 border-b border-gray-200">
+    <h2 class="text-lg font-medium text-gray-900">Configuration</h2>
+  </div>
+  <div class="p-4">
+    <dl class="grid grid-cols-1 sm:grid-cols-2 gap-4">
+      <div>
+        <dt class="text-sm font-medium text-gray-500">Job Class</dt>
+        <dd class="mt-1 text-sm text-gray-900"><%= @task[:class_name] || "—" %></dd>
+      </div>
+      <% if @task[:command] %>
+        <div>
+          <dt class="text-sm font-medium text-gray-500">Command</dt>
+          <dd class="mt-1 text-sm text-gray-900 font-mono text-xs"><%= @task[:command] %></dd>
+        </div>
+      <% end %>
+      <div>
+        <dt class="text-sm font-medium text-gray-500">Queue</dt>
+        <dd class="mt-1 text-sm text-gray-900"><%= @task[:queue_name] || "default" %></dd>
+      </div>
+      <div>
+        <dt class="text-sm font-medium text-gray-500">Priority</dt>
+        <dd class="mt-1 text-sm text-gray-900"><%= @task[:priority] %></dd>
+      </div>
+      <% if @task[:arguments]&.any? %>
+        <div class="sm:col-span-2">
+          <dt class="text-sm font-medium text-gray-500">Arguments</dt>
+          <dd class="mt-1 text-sm text-gray-900 font-mono text-xs"><%= @task[:arguments].inspect %></dd>
+        </div>
+      <% end %>
+      <% if @task[:description] %>
+        <div class="sm:col-span-2">
+          <dt class="text-sm font-medium text-gray-500">Description</dt>
+          <dd class="mt-1 text-sm text-gray-900"><%= @task[:description] %></dd>
+        </div>
+      <% end %>
+      <div>
+        <dt class="text-sm font-medium text-gray-500">Source</dt>
+        <dd class="mt-1 text-sm text-gray-900"><%= @task[:static] ? "Config file" : "Dynamic" %></dd>
+      </div>
+    </dl>
+  </div>
+</div>
+
+<div class="rounded-lg bg-white shadow ring-1 ring-gray-200">
+  <div class="px-4 py-3 border-b border-gray-200">
+    <h2 class="text-lg font-medium text-gray-900">Recent Executions</h2>
+  </div>
+  <% if @task[:executions]&.any? %>
+    <table class="min-w-full divide-y divide-gray-200">
+      <thead class="bg-gray-50">
+        <tr>
+          <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Scheduled For</th>
+          <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Enqueued At</th>
+        </tr>
+      </thead>
+      <tbody class="divide-y divide-gray-200">
+        <% @task[:executions].each do |exec| %>
+          <tr class="hover:bg-gray-50">
+            <td class="px-4 py-3 text-sm text-gray-900">
+              <%= exec[:run_at]&.strftime("%Y-%m-%d %H:%M:%S %Z") %>
+            </td>
+            <td class="px-4 py-3 text-sm text-gray-600">
+              <%= exec[:created_at] ? pgbus_time_ago(exec[:created_at]) : "—" %>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% else %>
+    <div class="p-8 text-center text-gray-500">
+      <p>No executions recorded yet</p>
+    </div>
+  <% end %>
+</div>

data/config/routes.rb

@@ -20,6 +20,13 @@ Pgbus::Engine.routes.draw do
     end
   end
 
+  resources :recurring_tasks, only: %i[index show] do
+    member do
+      post :toggle
+      post :enqueue
+    end
+  end
+
   resources :processes, only: [:index]
 
   resources :events, only: %i[index show] do

data/lib/active_job/queue_adapters/pgbus_adapter.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "pgbus" unless defined?(Pgbus)
+
+module ActiveJob
+  module QueueAdapters
+    # Adapter for Rails ActiveJob integration with Pgbus.
+    #
+    # This class lives in the ActiveJob::QueueAdapters namespace so that
+    # Rails can find it via const_get("PgbusAdapter") — the standard
+    # lookup mechanism used across all Rails versions (7.1+).
+    #
+    # Usage:
+    #   config.active_job.queue_adapter = :pgbus
+    class PgbusAdapter
+      delegate :enqueue, :enqueue_at, :enqueue_all, to: :adapter
+
+      def enqueue_after_transaction_commit?
+        true
+      end
+
+      private
+
+      def adapter
+        @adapter ||= Pgbus::ActiveJob::Adapter.new
+      end
+    end
+  end
+end

data/lib/generators/pgbus/add_recurring_generator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Pgbus
+  module Generators
+    class AddRecurringGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Add recurring jobs tables to an existing Pgbus installation"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus)"
+
+      def create_migration
+        if separate_database?
+          migration_template "add_recurring_tables.rb.erb",
+                             "db/pgbus_migrate/add_pgbus_recurring_tables.rb"
+        else
+          migration_template "add_recurring_tables.rb.erb",
+                             "db/migrate/add_pgbus_recurring_tables.rb"
+        end
+      end
+
+      def create_recurring_config
+        template "recurring.yml.erb", "config/recurring.yml"
+      end
+
+      def display_post_install
+        say ""
+        say "Pgbus recurring jobs installed!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run: rails db:migrate#{":#{options[:database]}" if separate_database?}"
+        say "  2. Edit config/recurring.yml to define your recurring tasks"
+        say "  3. Restart pgbus: bin/pgbus start"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+
+      def separate_database?
+        options[:database].present?
+      end
+    end
+  end
+end

data/lib/generators/pgbus/install_generator.rb

@@ -12,8 +12,26 @@ module Pgbus
 
       desc "Install Pgbus: create migration, config file, and binstub"
 
+      class_option :pgmq_schema_mode,
+                   type: :string,
+                   default: "auto",
+                   desc: "PGMQ install mode: auto (try extension, fallback embedded), " \
+                         "extension (require ext), embedded (no ext)"
+
+      class_option :database,
+                   type: :string,
+                   default: nil,
+                   desc: "Use a separate database for pgbus tables (e.g. --database=pgbus). " \
+                         "Migrations go to db/pgbus_migrate/ and schema to db/pgbus_schema.rb"
+
       def create_migration
-        migration_template "migration.rb.erb", "db/migrate/install_pgbus.rb"
+        if separate_database?
+          migration_template "migration.rb.erb",
+                             "db/pgbus_migrate/create_pgbus_tables.rb"
+        else
+          migration_template "migration.rb.erb",
+                             "db/migrate/create_pgbus_tables.rb"
+        end
       end
 
       def create_config_file
@@ -35,12 +53,56 @@ module Pgbus
                          after: "class Application < Rails::Application\n"
       end
 
+      def configure_separate_database
+        return unless separate_database?
+
+        db_config = <<~YAML
+
+          # Pgbus separate database (added by pgbus:install --database=#{database_name})
+          # Uncomment and configure for your environment:
+          # #{database_name}:
+          #   primary:
+          #     <<: *default
+          #     database: #{Rails.application.class.module_parent_name.underscore}_#{database_name}_<%= Rails.env %>
+          #     migrations_paths: db/pgbus_migrate
+        YAML
+
+        say ""
+        say "Separate database mode enabled!", :yellow
+        say "Add the following to your config/database.yml:", :yellow
+        say db_config, :cyan
+        say ""
+        say "Then add to config/application.rb or an initializer:", :yellow
+        say "  Pgbus.configure { |c| c.connects_to = { database: { writing: :#{database_name} } } }", :cyan
+        say ""
+      end
+
       def display_post_install
         say ""
         say "Pgbus installed successfully!", :green
+        say ""
+        say "PGMQ schema mode: #{pgmq_schema_mode}", :yellow
+        case pgmq_schema_mode
+        when "auto"
+          say "  The migration will try the pgmq extension first."
+          say "  If unavailable, it falls back to embedded SQL (no extension needed)."
+        when "extension"
+          say "  The migration requires the pgmq PostgreSQL extension."
+          say "  Install it: CREATE EXTENSION pgmq;"
+        when "embedded"
+          say "  The migration uses embedded SQL — no pgmq extension needed."
+          say "  PGMQ #{Pgbus::PgmqSchema.latest_version} schema will be created directly."
+        end
+
+        if separate_database?
+          say ""
+          say "Migrations path: db/pgbus_migrate/", :yellow
+          say "Schema dump: db/pgbus_schema.rb", :yellow
+        end
+
         say ""
         say "Next steps:"
-        say "  1. Run: rails db:migrate"
+        say "  1. Run: rails db:migrate#{":#{database_name}" if separate_database?}"
         say "  2. Edit config/pgbus.yml to configure workers"
         say "  3. Start processing: bin/pgbus start"
         say ""
@@ -51,6 +113,18 @@ module Pgbus
       def migration_version
         "[#{ActiveRecord::Migration.current_version}]"
       end
+
+      def pgmq_schema_mode
+        options[:pgmq_schema_mode]
+      end
+
+      def database_name
+        options[:database]
+      end
+
+      def separate_database?
+        database_name.present?
+      end
     end
   end
 end

data/lib/generators/pgbus/templates/add_recurring_tables.rb.erb

@@ -0,0 +1,31 @@
+class AddPgbusRecurringTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :pgbus_recurring_tasks do |t|
+      t.string :key, null: false
+      t.string :class_name
+      t.string :command, limit: 2048
+      t.string :schedule, null: false
+      t.text :arguments
+      t.string :queue_name
+      t.integer :priority, default: 0
+      t.boolean :static, null: false, default: true
+      t.boolean :enabled, null: false, default: true
+      t.text :description
+      t.timestamps
+    end
+
+    add_index :pgbus_recurring_tasks, :key,
+      unique: true, name: "idx_pgbus_recurring_tasks_key"
+
+    create_table :pgbus_recurring_executions do |t|
+      t.string :task_key, null: false
+      t.datetime :run_at, null: false
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+    end
+
+    add_index :pgbus_recurring_executions, [:task_key, :run_at],
+      unique: true, name: "idx_pgbus_recurring_executions_dedup"
+    add_index :pgbus_recurring_executions, :run_at,
+      name: "idx_pgbus_recurring_executions_cleanup"
+  end
+end

data/lib/generators/pgbus/templates/migration.rb.erb

@@ -1,7 +1,29 @@
-class InstallPgbus < ActiveRecord::Migration<%= migration_version %>
+class CreatePgbusTables < ActiveRecord::Migration<%= migration_version %>
   def up
-    # Install PGMQ extension
-    enable_extension "pgmq"
+    # Install PGMQ schema based on pgmq_schema_mode configuration.
+    #
+    # Modes:
+    #   :auto      - Try extension first, fall back to embedded SQL (default)
+    #   :extension - Require the pgmq PostgreSQL extension
+    #   :embedded  - Use vendored SQL, no extension needed
+    pgmq_schema_mode = :<%= pgmq_schema_mode %>
+
+    case pgmq_schema_mode
+    when :extension
+      enable_extension "pgmq"
+      execute Pgbus::PgmqSchema.version_tracking_extension_sql
+    when :embedded
+      execute Pgbus::PgmqSchema.install_sql
+      execute Pgbus::PgmqSchema.version_tracking_sql
+    when :auto
+      if extension_available?("pgmq")
+        enable_extension "pgmq"
+        execute Pgbus::PgmqSchema.version_tracking_extension_sql
+      else
+        execute Pgbus::PgmqSchema.install_sql
+        execute Pgbus::PgmqSchema.version_tracking_sql
+      end
+    end
 
     # Idempotent event processing deduplication
     create_table :pgbus_processed_events do |t|
@@ -93,6 +115,36 @@ class InstallPgbus < ActiveRecord::Migration<%= migration_version %>
     add_index :pgbus_batches, :status,
       name: "idx_pgbus_batches_status"
 
+    # Recurring task definitions (synced from config/recurring.yml)
+    create_table :pgbus_recurring_tasks do |t|
+      t.string :key, null: false
+      t.string :class_name
+      t.string :command, limit: 2048
+      t.string :schedule, null: false
+      t.text :arguments
+      t.string :queue_name
+      t.integer :priority, default: 0
+      t.boolean :static, null: false, default: true
+      t.boolean :enabled, null: false, default: true
+      t.text :description
+      t.timestamps
+    end
+
+    add_index :pgbus_recurring_tasks, :key,
+      unique: true, name: "idx_pgbus_recurring_tasks_key"
+
+    # Recurring execution deduplication (prevents double-enqueue)
+    create_table :pgbus_recurring_executions do |t|
+      t.string :task_key, null: false
+      t.datetime :run_at, null: false
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+    end
+
+    add_index :pgbus_recurring_executions, [:task_key, :run_at],
+      unique: true, name: "idx_pgbus_recurring_executions_dedup"
+    add_index :pgbus_recurring_executions, :run_at,
+      name: "idx_pgbus_recurring_executions_cleanup"
+
     # Create default queues via PGMQ
     execute "SELECT pgmq.create('pgbus_default')"
     execute "SELECT pgmq.create('pgbus_default_dlq')"
@@ -102,13 +154,29 @@ class InstallPgbus < ActiveRecord::Migration<%= migration_version %>
     execute "SELECT pgmq.drop_queue('pgbus_default_dlq')"
     execute "SELECT pgmq.drop_queue('pgbus_default')"
 
+    drop_table :pgbus_recurring_executions
+    drop_table :pgbus_recurring_tasks
     drop_table :pgbus_batches
     drop_table :pgbus_blocked_executions
     drop_table :pgbus_semaphores
     drop_table :pgbus_failed_events
     drop_table :pgbus_processes
     drop_table :pgbus_processed_events
+    drop_table :pgbus_pgmq_schema_versions
+
+    # Drop PGMQ schema (functions, types, tables)
+    execute "DROP SCHEMA IF EXISTS pgmq CASCADE"
+
+    # Also try to disable extension in case it was installed that way
+    disable_extension "pgmq" if extension_available?("pgmq")
+  end
+
+  private
 
-    disable_extension "pgmq"
+  def extension_available?(name)
+    result = execute("SELECT 1 FROM pg_available_extensions WHERE name = '#{name}' LIMIT 1")
+    result.any?
+  rescue ActiveRecord::StatementInvalid
+    false
   end
 end

data/lib/generators/pgbus/templates/recurring.yml.erb

@@ -0,0 +1,40 @@
+# Pgbus Recurring Tasks Configuration
+#
+# Compatible with Solid Queue's recurring.yml format for easy migration.
+# Supports environment-scoped or flat configuration.
+#
+# Format:
+#   task_key:
+#     class: JobClassName      # ActiveJob class to run (or use command:)
+#     schedule: "0 * * * *"    # Cron expression or natural language
+#     queue: default           # Optional: queue name (default: pgbus default queue)
+#     args: [arg1, arg2]       # Optional: job arguments
+#     priority: 0              # Optional: numeric priority
+#     description: "text"      # Optional: human-readable description
+#
+# Schedule examples:
+#   "0 2 * * *"           → Every day at 2:00 AM
+#   "*/5 * * * *"         → Every 5 minutes
+#   "every hour"          → Every hour at :00
+#   "every day at 2am"    → Daily at 2:00 AM
+#   "@daily"              → Daily at midnight
+#   "0 9 * * mon-fri"     → Weekdays at 9:00 AM
+#
+# Command-based tasks (no job class needed):
+#   cleanup_old_records:
+#     command: "OldRecord.where('created_at < ?', 30.days.ago).delete_all"
+#     schedule: every day at 3am
+#
+# Examples:
+#
+# production:
+#   periodic_cleanup:
+#     class: CleanupJob
+#     queue: maintenance
+#     args: [1000, { batch_size: 500 }]
+#     schedule: every hour
+#
+#   daily_report:
+#     class: DailyReportJob
+#     schedule: "0 8 * * mon-fri"
+#     description: Generate daily business report