rails_pulse 0.4.2 → 0.5.0.pre.2

data/app/views/rails_pulse/dashboard/_storage_panel.html.erb

@@ -14,6 +14,9 @@
           <div class="flex flex-col">
             <h3 class="font-semibold leading-none mbe-2 uppercase text-sm">Storage</h3>
             <p class="text-sm text-subtle">How full Rails Pulse tables are relative to <code>max_table_records</code>, plus cleanup health. Open the full page for every table, retention details, and database size.</p>
+            <% if @storage_status.estimated? %>
+              <p class="text-sm text-subtle mbs-2">Counting rows exactly means scanning every table, so the dashboard uses the database's own row estimates<% unless @storage_status.counts_available? %>, which SQLite does not keep<% end %>. The Storage page counts exactly.</p>
+            <% end %>
           </div>
         </div>
       </div>
@@ -23,7 +26,9 @@
     </div>
   </div>
 
+  <% approx = @storage_status.estimated? ? "~" : "" %>
   <div class="storage-panel-stats">
+    <% if @storage_status.counts_available? %>
     <div>
       <p class="font-semibold uppercase text-xs text-subtle mbe-1">Highest fill</p>
       <p class="text-lg font-bold"><% if @storage_status.overview[:hottest_percent] %><%= @storage_status.overview[:hottest_percent].round %>%<% else %>--<% end %></p>
@@ -31,9 +36,10 @@
     </div>
     <div>
       <p class="font-semibold uppercase text-xs text-subtle mbe-1">Records</p>
-      <p class="text-lg font-bold"><%= number_with_delimiter(@storage_status.overview[:total_records]) %></p>
+      <p class="text-lg font-bold"><%= approx %><%= number_with_delimiter(@storage_status.overview[:total_records]) %></p>
       <p class="text-xs text-subtle">Across <%= @storage_status.tables.size %> tables</p>
     </div>
+    <% end %>
     <div>
       <p class="font-semibold uppercase text-xs text-subtle mbe-1">Disk used</p>
       <p class="text-lg font-bold"><%= @storage_status.overview[:display_bytes] ? human_readable_bytes(@storage_status.overview[:display_bytes]) : "—" %></p>
@@ -46,6 +52,7 @@
     </div>
   </div>
 
+  <% if @storage_status.counts_available? %>
   <div class="storage-panel-tables">
     <% @storage_status.dashboard_tables.each do |table| %>
       <div class="storage-panel-row">
@@ -55,13 +62,16 @@
         </div>
         <span class="storage-panel-row__count text-xs text-subtle">
           <% if table[:limit] %>
-            <%= number_with_delimiter(table[:count]) %> / <%= number_with_delimiter(table[:limit]) %>
+            <%= approx %><%= number_with_delimiter(table[:count]) %> / <%= number_with_delimiter(table[:limit]) %>
             · <%= table[:percent_label] %>
           <% else %>
-            <%= number_with_delimiter(table[:count]) %>
+            <%= approx %><%= number_with_delimiter(table[:count]) %>
           <% end %>
         </span>
       </div>
     <% end %>
   </div>
+  <% else %>
+  <p class="text-sm text-subtle">Record counts need a full scan of each table on SQLite, so the dashboard leaves them out. <%= link_to "Open Storage", storage_path %> to count them.</p>
+  <% end %>
 </div>

data/app/views/rails_pulse/dashboard/index.html.erb

@@ -29,10 +29,24 @@
         critical_label: "critical",
         link_url: exceptions_path %>
       <% end %>
+      <%# Nil until a background writer has reported a heartbeat. Shown only
+          when a writer is backlogged or dropping requests. %>
+      <% if @health_summary[:tracking] %>
+        <%= render "rails_pulse/dashboard/health_badge",
+        name: "Tracking",
+        health: @health_summary[:tracking],
+        healthy_label: "writing",
+        slow_label: "backlogged",
+        critical_label: "dropping",
+        hide_when_healthy: true,
+        link_url: storage_path %>
+      <% end %>
+      <%# Shown only when storage is under warning or critical pressure. %>
       <%= render "rails_pulse/dashboard/health_badge",
       name: "Storage",
       health: @health_summary[:storage],
       critical_label: "critical",
+      hide_when_healthy: true,
       link_url: storage_path %>
     </div>
   </div>
@@ -130,7 +144,7 @@
           </span>
         <% end %>
         <span class="text-xs text-subtle mis-2">Ranked by severity ·
-          <%= humanize_time_range(@selected_time_range) %></span>
+          <%= humanize_time_range(@time_range.selected_time_range) %></span>
       </div>
       <div
         data-controller="rails-pulse--popover"
@@ -179,7 +193,7 @@
         </span>
         <p class="font-semibold text-sm text-positive">All clear</p>
         <p class="text-xs text-subtle">No routes, queries, or jobs need attention in the
-          <%= humanize_time_range(@selected_time_range) %>.</p>
+          <%= humanize_time_range(@time_range.selected_time_range) %>.</p>
       </div>
     <% else %>
       <div class="flex flex-col">

data/app/views/rails_pulse/jobs/_chart_tabs.html.erb

@@ -56,6 +56,7 @@
     </div>
     <%= render "rails_pulse/shared/deployment_markers_toggle" %>
   </div>
+  <%= render "rails_pulse/shared/aggregation_zone_badge" %>
 </div>
 
 <!-- Duration Chart -->

data/app/views/rails_pulse/jobs/index.html.erb

@@ -29,7 +29,7 @@
         %>
         <%= form.select :avg_duration,
           duration_options(:job),
-          { selected: @selected_response_range },
+          { selected: @time_range&.selected_response_range },
           { class: "input" }
         %>
         <%= if params.has_key?(:q) || params[:queue_name].present?

data/app/views/rails_pulse/queries/_chart_tabs.html.erb

@@ -56,6 +56,7 @@
     </div>
     <%= render "rails_pulse/shared/deployment_markers_toggle" %>
   </div>
+  <%= render "rails_pulse/shared/aggregation_zone_badge" %>
 </div>
 
 <!-- Query Performance Chart -->

data/app/views/rails_pulse/queries/index.html.erb

@@ -26,7 +26,7 @@
         >
         <%= form.select :avg_duration,
                     duration_options(:query),
-                    { selected: @selected_response_range },
+                    { selected: @time_range&.selected_response_range },
                     { class: "input" } %>
         <%= if params.has_key?(:q)
           link_to "Reset",

data/app/views/rails_pulse/queries/show.html.erb

@@ -24,7 +24,7 @@
         >
         <%= form.select :duration,
           duration_options(:query),
-          { selected: @selected_response_range },
+          { selected: @time_range&.selected_response_range },
           { class: "input" }
         %>
         <%= link_to "Reset", query_path(@query), class: "btn btn--plain", style: "text-decoration: none; color: var(--color-text-muted);" if params.has_key?(:q) %>

data/app/views/rails_pulse/requests/index.html.erb

@@ -23,7 +23,7 @@
 
       <%= form.select :duration_gteq,
         duration_options(:request),
-        { selected: @selected_response_range, prompt: "Min duration" },
+        { selected: @time_range&.selected_response_range, prompt: "Min duration" },
         { class: "input" }
       %>
 

data/app/views/rails_pulse/routes/_chart_tabs.html.erb

@@ -82,6 +82,7 @@
     </div>
     <%= render "rails_pulse/shared/deployment_markers_toggle" %>
   </div>
+  <%= render "rails_pulse/shared/aggregation_zone_badge" %>
 </div>
 <!-- Response Time Chart -->
 <div

data/app/views/rails_pulse/routes/index.html.erb

@@ -34,7 +34,7 @@
                           class: "input" %>
         <%= form.select :avg_duration,
                     duration_options(:route),
-                    { selected: @selected_response_range },
+                    { selected: @time_range&.selected_response_range },
                     { class: "input" } %>
         <%= if params.has_key?(:q)
           link_to "Reset",

data/app/views/rails_pulse/routes/show.html.erb

@@ -26,7 +26,7 @@
           >
           <%= form.select :avg_duration,
             duration_options(:route),
-            { selected: @selected_response_range },
+            { selected: @time_range&.selected_response_range },
             { class: "input" }
           %>
           <%= form.select :http_method_eq,

data/app/views/rails_pulse/shared/_aggregation_zone_badge.html.erb

@@ -0,0 +1,4 @@
+<%# Zone every chart on the page is bucketed and labelled in. The short
+    label is always visible; the title carries the full zone name and, when
+    a controller resolved one, the exact window being shown. %>
+<span class="zone-badge" title="<%= time_range_zone_tooltip %>"><%= RailsPulse::TimeRange.aggregation_zone_short_label %></span>

data/app/views/rails_pulse/storage/show.html.erb

@@ -75,7 +75,7 @@
   <%= render "rails_pulse/components/panel",
       title: "Cleanup",
       help_heading: "How cleanup works",
-      help_text: "Time-based cleanup deletes records older than full_retention_period, but only after that period has been summarised. Count-based cleanup then trims each table down to max_table_records. Schedule RailsPulse::CleanupJob daily." do %>
+      help_text: "Time-based cleanup deletes records older than full_retention_period. Count-based cleanup then trims each table down to max_table_records, taking requests and operations only from periods already summarised. Schedule RailsPulse::CleanupJob daily." do %>
     <dl class="descriptive-list mbs-4">
       <dt>Automatic cleanup</dt>
       <dd><%= @status.cleanup[:enabled] ? "Enabled" : "Disabled (archiving_enabled = false)" %></dd>
@@ -87,7 +87,7 @@
           <%= human_readable_occurred_at(@status.cleanup[:last_summary_at]) %>
           <span class="text-subtle">(<%= time_ago_in_words(@status.cleanup[:last_summary_at]) %>)</span>
         <% else %>
-          Never — cleanup will not delete unsummarised requests
+          Never — count-based cleanup will not trim unsummarised requests
         <% end %>
       </dd>
       <dt>Count caps</dt>
@@ -120,4 +120,41 @@
       <% end %>
     </dl>
   <% end %>
+
+  <%= render "rails_pulse/components/panel",
+      title: "Tracking writers",
+      help_heading: "The background writer",
+      help_text: "Each process queues tracked requests for one writer thread, which reports a heartbeat every minute. When a queue is full the newest request is dropped rather than slowing the app; dropped requests mean the charts undercount traffic. Raise async_queue_size or fix database latency." do %>
+    <% tracking = @status.tracking %>
+    <dl class="descriptive-list mbs-4">
+      <dt>Live writers</dt>
+      <dd><%= tracking[:live_count] %></dd>
+      <dt>Queue depth</dt>
+      <dd><%= number_with_delimiter(tracking[:queue_depth]) %><% if tracking[:queue_size].to_i.positive? %> <span class="text-subtle">/ <%= number_with_delimiter(tracking[:queue_size]) %> per process</span><% end %></dd>
+      <dt>Dropped in the last hour</dt>
+      <dd class="<%= tracking[:dropped].to_i.positive? ? "text-negative font-semibold" : "" %>"><%= number_with_delimiter(tracking[:dropped]) %></dd>
+      <dt>Last heartbeat</dt>
+      <dd>
+        <% if tracking[:last_sampled_at] %>
+          <%= human_readable_occurred_at(tracking[:last_sampled_at]) %>
+          <span class="text-subtle">(<%= time_ago_in_words(tracking[:last_sampled_at]) %>)</span>
+        <% else %>
+          Never — heartbeats start when a process with <code>async</code> on tracks its first request
+        <% end %>
+      </dd>
+      <% tracking[:processes].each do |process| %>
+        <dt><code><%= process[:label] %></code></dt>
+        <dd>
+          <%= number_with_delimiter(process[:queue_depth]) %> / <%= number_with_delimiter(process[:queue_size]) %> queued
+          <% if process[:dropped_last_hour].positive? %>
+            <span class="badge storage-table__percent storage-table__percent--critical"><%= number_with_delimiter(process[:dropped_last_hour]) %> dropped</span>
+          <% else %>
+            <span class="badge storage-table__percent storage-table__percent--uncapped">0 dropped</span>
+          <% end %>
+          <br>
+          <span class="text-subtle">last heartbeat <%= time_ago_in_words(process[:last_seen_at]) %></span>
+        </dd>
+      <% end %>
+    </dl>
+  <% end %>
 </div>

data/config/routes.rb

@@ -37,6 +37,29 @@ RailsPulse::Engine.routes.draw do
     end
   end
 
+  # Read-only JSON API for the rails-pulse CLI, the MCP server and CI, all
+  # authenticated by config.api_token (app/controllers/rails_pulse/api/v1).
+  scope path: "api/v1", module: "api/v1", as: :api_v1 do
+    resources :routes,      only: :index
+    resources :requests,    only: :index
+    resources :queries,     only: :index
+    resources :jobs,        only: :index
+    resources :job_runs,    only: :index
+    resources :deployments, only: :index
+    resources :exceptions,  only: %i[index show]
+
+    # Whether the data is there, rather than a question about the data.
+    get "coverage", to: "coverage#show", as: :coverage
+
+    # What needs attention over one summary period, and whether the
+    # thresholds fit it.
+    get "insights", to: "insights#show", as: :insights
+
+    # Which application, environment and version answered, so results gathered
+    # against staging are not read as production.
+    get "capabilities", to: "capabilities#show", as: :capabilities
+  end
+
   # CSP compliance testing (development/test only)
   if Rails.env.local?
     get "csp_test", to: "csp_test#show", as: :csp_test

data/db/rails_pulse_cloud_schema.rb

@@ -0,0 +1,58 @@
+# Rails Pulse Cloud Database Schema
+# The tables Rails Pulse Cloud's sync needs, kept apart from
+# db/rails_pulse_schema.rb so an install that does not use Cloud never has
+# them. Installed by `rails generate rails_pulse:install_cloud`; loaded by its
+# migration, and by db:prepare on a separate Rails Pulse database.
+
+RailsPulse::CloudSchema = lambda do |connection|
+  required_tables = [ :rails_pulse_cloud_installations, :rails_pulse_cloud_batches ]
+
+  missing_tables = required_tables.reject { |table| connection.table_exists?(table) }
+  if missing_tables.empty?
+    puts "[RailsPulse::CloudSchema] All Rails Pulse Cloud tables already exist. Skipping schema load."
+    return
+  end
+
+  puts "[RailsPulse::CloudSchema] Creating missing tables: #{missing_tables.join(', ')}"
+
+  unless connection.table_exists?(:rails_pulse_cloud_installations)
+    connection.create_table :rails_pulse_cloud_installations do |t|
+      t.string   :installation_id, limit: 36, null: false, comment: "UUID naming this Rails Pulse database to Rails Pulse Cloud, generated once"
+      t.datetime :last_hour_sent_at,                    comment: "Start of the newest hour whose summaries were queued for Cloud"
+      t.datetime :exception_groups_sent_through,        comment: "Exception groups updated before this were queued for Cloud"
+      t.datetime :deployments_sent_through,             comment: "Deployments updated before this were queued for Cloud"
+      t.datetime :last_success_at,                      comment: "When Cloud last accepted a batch or health update"
+      t.datetime :last_health_at,                       comment: "When the last health update was sent"
+      t.text     :last_error,                           comment: "The most recent failure, for rails_pulse:status"
+      t.datetime :last_error_at
+      t.datetime :paused_until,                         comment: "No sending before this, after Cloud refused the key, plan, application or contract"
+      t.text     :pause_reason,                         comment: "Cloud's message for the pause"
+      t.string   :contract_deprecated_on,               comment: "Date from Cloud's Rails-Pulse-Contract-Deprecated header"
+      t.timestamps
+    end
+
+    connection.add_index :rails_pulse_cloud_installations, :installation_id, unique: true,
+      name: "index_rp_cloud_installations_on_installation_id"
+  end
+
+  unless connection.table_exists?(:rails_pulse_cloud_batches)
+    connection.create_table :rails_pulse_cloud_batches do |t|
+      t.string   :batch_id,        limit: 36, null: false, comment: "The batch's UUID, resent unchanged on every retry"
+      t.binary   :payload,         limit: 16.megabytes, null: false, comment: "The batch as gzipped JSON"
+      t.integer  :byte_size,       null: false, comment: "Size of the gzipped payload, for the buffer limit"
+      t.integer  :item_count,      null: false
+      t.integer  :attempts,        null: false, default: 0
+      t.datetime :next_attempt_at, null: false, comment: "Not sent before this; set by backoff and Retry-After"
+      t.text     :last_error
+      t.timestamps
+    end
+
+    connection.add_index :rails_pulse_cloud_batches, :batch_id, unique: true, name: "index_rp_cloud_batches_on_batch_id"
+    connection.add_index :rails_pulse_cloud_batches, :next_attempt_at, name: "index_rp_cloud_batches_on_next_attempt_at"
+    connection.add_index :rails_pulse_cloud_batches, :created_at, name: "index_rp_cloud_batches_on_created_at"
+  end
+end unless defined?(RailsPulse::CloudSchema)
+
+if defined?(RailsPulse::ApplicationRecord)
+  RailsPulse::CloudSchema.call(RailsPulse::ApplicationRecord.connection)
+end

data/db/rails_pulse_migrate/20260506000001_create_rails_pulse_exceptions.rb

@@ -32,7 +32,7 @@ class CreateRailsPulseExceptions < ActiveRecord::Migration[7.0]
         t.string   :request_url,     comment: "Nullable — web requests only"
         t.string   :request_method,  comment: "GET, POST, etc."
         t.string   :environment,     comment: "production, staging, etc."
-        t.string   :deploy_sha,       comment: "Captured now even though Pro uses it — cannot backfill later"
+        t.string   :deploy_sha,       comment: "Captured at occurrence time — cannot backfill later"
         t.text     :request_params,   comment: "JSON hash of filtered request params — web requests only"
         t.datetime :occurred_at,      null: false
         t.timestamps

data/db/rails_pulse_migrate/20260921000001_create_rails_pulse_events.rb

@@ -0,0 +1,21 @@
+class CreateRailsPulseEvents < ActiveRecord::Migration[7.0]
+  def change
+    return if table_exists?(:rails_pulse_events)
+
+    create_table :rails_pulse_events do |t|
+      t.string   :kind,        null: false, comment: "What noticed it, e.g. writer_heartbeat"
+      t.string   :subject,                  comment: "Who it is about: host:pid, rule name, job name, exception class"
+      t.string   :outcome,     null: false, comment: "sampled, triggered, clean, insufficient_data, ran"
+      t.decimal  :value,       precision: 15, scale: 6, comment: "The number behind it: requests dropped since the last sample, or the triggered metric value"
+      t.datetime :occurred_at, null: false
+      t.text     :message
+      t.text     :metadata,                 comment: "JSON with the kind-specific detail"
+      t.timestamps
+    end
+
+    add_index :rails_pulse_events, [ :kind, :occurred_at ],
+      name: "index_rp_events_on_kind_and_occurred_at"
+    add_index :rails_pulse_events, [ :kind, :subject, :occurred_at ],
+      name: "index_rp_events_on_kind_subject_and_occurred_at"
+  end
+end

data/db/rails_pulse_schema.rb

@@ -7,7 +7,7 @@ require "rails_pulse/route_indexes" unless defined?(RailsPulse::RouteIndexes)
 RailsPulse::Schema = lambda do |connection|
   adapter = connection.adapter_name.downcase
   # Skip if all tables already exist to prevent conflicts
-  required_tables = [ :rails_pulse_routes, :rails_pulse_queries, :rails_pulse_requests, :rails_pulse_operations, :rails_pulse_jobs, :rails_pulse_job_runs, :rails_pulse_summaries, :rails_pulse_deployments, :rails_pulse_exception_groups, :rails_pulse_exception_occurrences ]
+  required_tables = [ :rails_pulse_routes, :rails_pulse_queries, :rails_pulse_requests, :rails_pulse_operations, :rails_pulse_jobs, :rails_pulse_job_runs, :rails_pulse_summaries, :rails_pulse_deployments, :rails_pulse_exception_groups, :rails_pulse_exception_occurrences, :rails_pulse_events ]
 
   # Check which tables already exist
   existing_tables = required_tables.select { |table| connection.table_exists?(table) }
@@ -249,7 +249,7 @@ RailsPulse::Schema = lambda do |connection|
       t.string   :request_url,     comment: "Nullable — web requests only"
       t.string   :request_method,  comment: "GET, POST, etc."
       t.string   :environment,     comment: "production, staging, etc."
-      t.string   :deploy_sha,       comment: "Captured now even though Pro uses it — cannot backfill later"
+      t.string   :deploy_sha,       comment: "Captured at occurrence time — cannot backfill later"
       t.text     :request_params,   comment: "JSON hash of filtered request params — web requests only"
       t.datetime :occurred_at,      null: false
       t.timestamps
@@ -259,6 +259,24 @@ RailsPulse::Schema = lambda do |connection|
     connection.add_index :rails_pulse_exception_occurrences, :exception_group_id, name: "index_rp_exception_occurrences_on_group_id"
   end
 
+  unless connection.table_exists?(:rails_pulse_events)
+    connection.create_table :rails_pulse_events do |t|
+      t.string   :kind,        null: false, comment: "What noticed it, e.g. writer_heartbeat"
+      t.string   :subject,                  comment: "Who it is about: host:pid, rule name, job name, exception class"
+      t.string   :outcome,     null: false, comment: "sampled, triggered, clean, insufficient_data, ran"
+      t.decimal  :value,       precision: 15, scale: 6, comment: "The number behind it: requests dropped since the last sample, or the triggered metric value"
+      t.datetime :occurred_at, null: false
+      t.text     :message
+      t.text     :metadata,                 comment: "JSON with the kind-specific detail"
+      t.timestamps
+    end
+
+    connection.add_index :rails_pulse_events, [ :kind, :occurred_at ],
+      name: "index_rp_events_on_kind_and_occurred_at"
+    connection.add_index :rails_pulse_events, [ :kind, :subject, :occurred_at ],
+      name: "index_rp_events_on_kind_subject_and_occurred_at"
+  end
+
   # Add indexes to existing tables for efficient aggregation
   unless connection.index_exists?(:rails_pulse_requests, [ :created_at, :route_id ], name: "idx_requests_for_aggregation")
     connection.add_index :rails_pulse_requests, [ :created_at, :route_id ], name: "idx_requests_for_aggregation"

data/exe/rails-pulse

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Runs outside the Rails app: talks to it over the JSON API, so only the CLI
+# is loaded here, never the engine.
+require "rails_pulse/cli/main"
+RailsPulse::CLI::Main.start(ARGV)

data/lib/generators/rails_pulse/base_methods.rb

@@ -15,6 +15,7 @@ module RailsPulse
         rails_pulse_deployments
         rails_pulse_exception_groups
         rails_pulse_exception_occurrences
+        rails_pulse_events
       ].freeze
 
       # Generate next migration number for timestamped migrations
@@ -45,6 +46,24 @@ module RailsPulse
         false
       end
 
+      # True when config/database.yml names a rails_pulse database in any
+      # environment.
+      def has_separate_database_config?
+        config_path = File.join(root_path, "config/database.yml")
+        return false unless File.exist?(config_path)
+
+        require "yaml"
+        require "erb"
+        # Process ERB before YAML parsing — database.yml files commonly use ERB
+        # for environment-specific values. YAML.safe_load alone raises SyntaxError
+        # on ERB tags.
+        yaml_content = ERB.new(File.read(config_path)).result
+        db_config = YAML.safe_load(yaml_content, aliases: true)
+        db_config.values.any? { |env| env.is_a?(Hash) && env.key?("rails_pulse") }
+      rescue
+        false
+      end
+
       # Get root path (destination_root in tests, Rails.root in production)
       def root_path
         respond_to?(:destination_root) ? destination_root : Rails.root

data/lib/generators/rails_pulse/install_cloud_generator.rb

@@ -0,0 +1,84 @@
+require_relative "base_methods"
+
+module RailsPulse
+  module Generators
+    # Adds the tables Rails Pulse Cloud's sync needs to an existing Rails
+    # Pulse install. Kept out of rails_pulse:install so an app that never
+    # uses Cloud never has them: like the main install, it copies a schema
+    # file (db/rails_pulse_cloud_schema.rb) and a migration that loads it.
+    class InstallCloudGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      include BaseMethods
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install the Rails Pulse Cloud tables into an existing Rails Pulse setup"
+
+      class_option :database, type: :string, default: "detect",
+                   desc: "Database setup: 'single', 'separate', or 'detect' (default)"
+
+      def check_rails_pulse_installed
+        return if File.exist?(File.join(root_path, "db/rails_pulse_schema.rb"))
+
+        say "Rails Pulse not detected. Run 'rails generate rails_pulse:install' first.", :red
+        exit 1
+      end
+
+      def copy_schema
+        copy_file "db/rails_pulse_cloud_schema.rb", "db/rails_pulse_cloud_schema.rb"
+      end
+
+      # The migration goes where Rails Pulse's own migrations run. On a
+      # separate database that is db/rails_pulse_migrate: the database
+      # already exists, so db:migrate:rails_pulse has to create the tables,
+      # and a fresh one built by db:prepare loads the schema file instead.
+      def copy_migration
+        migration_template(
+          "migrations/install_rails_pulse_cloud_tables.rb",
+          "#{migration_dir}/install_rails_pulse_cloud_tables.rb"
+        )
+      end
+
+      def display_post_install_message
+        say <<~MESSAGE
+
+          Rails Pulse Cloud tables ready to install (#{separate_database? ? 'separate' : 'single'} database setup).
+
+          Next steps:
+          1. Run: #{separate_database? ? 'rails db:migrate:rails_pulse' : 'rails db:migrate'}
+          2. Set these in config/initializers/rails_pulse.rb (the key comes from your
+             Application's settings in Rails Pulse Cloud; application is its slug):
+
+               config.cloud.api_key = ENV["RAILS_PULSE_CLOUD_API_KEY"]
+               config.cloud.application = "your-app"
+
+          3. Schedule the health update every minute, for example in config/recurring.yml:
+
+               rails_pulse_cloud_health:
+                 class: RailsPulse::CloudHealthJob
+                 schedule: every minute
+
+             The hourly sync needs no schedule: RailsPulse::SummaryJob starts it.
+          4. Check what will be sent: rails rails_pulse:cloud:preview
+          5. Restart your Rails server and workers
+
+          The schema file db/rails_pulse_cloud_schema.rb is the source of truth for
+          these tables, and rails_pulse:upgrade keeps it current.
+
+        MESSAGE
+      end
+
+      private
+
+      def separate_database?
+        return options[:database] == "separate" unless options[:database] == "detect"
+
+        has_separate_database_config?
+      end
+
+      def migration_dir
+        separate_database? ? "db/rails_pulse_migrate" : "db/migrate"
+      end
+    end
+  end
+end

data/lib/generators/rails_pulse/templates/db/rails_pulse_cloud_schema.rb

@@ -0,0 +1,58 @@
+# Rails Pulse Cloud Database Schema
+# The tables Rails Pulse Cloud's sync needs, kept apart from
+# db/rails_pulse_schema.rb so an install that does not use Cloud never has
+# them. Installed by `rails generate rails_pulse:install_cloud`; loaded by its
+# migration, and by db:prepare on a separate Rails Pulse database.
+
+RailsPulse::CloudSchema = lambda do |connection|
+  required_tables = [ :rails_pulse_cloud_installations, :rails_pulse_cloud_batches ]
+
+  missing_tables = required_tables.reject { |table| connection.table_exists?(table) }
+  if missing_tables.empty?
+    puts "[RailsPulse::CloudSchema] All Rails Pulse Cloud tables already exist. Skipping schema load."
+    return
+  end
+
+  puts "[RailsPulse::CloudSchema] Creating missing tables: #{missing_tables.join(', ')}"
+
+  unless connection.table_exists?(:rails_pulse_cloud_installations)
+    connection.create_table :rails_pulse_cloud_installations do |t|
+      t.string   :installation_id, limit: 36, null: false, comment: "UUID naming this Rails Pulse database to Rails Pulse Cloud, generated once"
+      t.datetime :last_hour_sent_at,                    comment: "Start of the newest hour whose summaries were queued for Cloud"
+      t.datetime :exception_groups_sent_through,        comment: "Exception groups updated before this were queued for Cloud"
+      t.datetime :deployments_sent_through,             comment: "Deployments updated before this were queued for Cloud"
+      t.datetime :last_success_at,                      comment: "When Cloud last accepted a batch or health update"
+      t.datetime :last_health_at,                       comment: "When the last health update was sent"
+      t.text     :last_error,                           comment: "The most recent failure, for rails_pulse:status"
+      t.datetime :last_error_at
+      t.datetime :paused_until,                         comment: "No sending before this, after Cloud refused the key, plan, application or contract"
+      t.text     :pause_reason,                         comment: "Cloud's message for the pause"
+      t.string   :contract_deprecated_on,               comment: "Date from Cloud's Rails-Pulse-Contract-Deprecated header"
+      t.timestamps
+    end
+
+    connection.add_index :rails_pulse_cloud_installations, :installation_id, unique: true,
+      name: "index_rp_cloud_installations_on_installation_id"
+  end
+
+  unless connection.table_exists?(:rails_pulse_cloud_batches)
+    connection.create_table :rails_pulse_cloud_batches do |t|
+      t.string   :batch_id,        limit: 36, null: false, comment: "The batch's UUID, resent unchanged on every retry"
+      t.binary   :payload,         limit: 16.megabytes, null: false, comment: "The batch as gzipped JSON"
+      t.integer  :byte_size,       null: false, comment: "Size of the gzipped payload, for the buffer limit"
+      t.integer  :item_count,      null: false
+      t.integer  :attempts,        null: false, default: 0
+      t.datetime :next_attempt_at, null: false, comment: "Not sent before this; set by backoff and Retry-After"
+      t.text     :last_error
+      t.timestamps
+    end
+
+    connection.add_index :rails_pulse_cloud_batches, :batch_id, unique: true, name: "index_rp_cloud_batches_on_batch_id"
+    connection.add_index :rails_pulse_cloud_batches, :next_attempt_at, name: "index_rp_cloud_batches_on_next_attempt_at"
+    connection.add_index :rails_pulse_cloud_batches, :created_at, name: "index_rp_cloud_batches_on_created_at"
+  end
+end unless defined?(RailsPulse::CloudSchema)
+
+if defined?(RailsPulse::ApplicationRecord)
+  RailsPulse::CloudSchema.call(RailsPulse::ApplicationRecord.connection)
+end