railwatch 0.8.6 → 0.8.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c483283faabf8cf2552cedbd8568e6d06f815c8e5bdf4f2cdffe1909a82fa80b
-  data.tar.gz: 2f56eb2aed77f09e55d869117c3f9bf1d6140f00fa93ebd2a5c2c89e4da62b7b
+  metadata.gz: f9e80ca205e8ad9435148ba6b185c3de1796f8ffe489f1208876f38e21686181
+  data.tar.gz: '09028109bb2da10a48db010d19f126a5e406bcbe50d2991ebcc303e4c4d74318'
 SHA512:
-  metadata.gz: a80ac73b1c0e36d6fb681da86848ac37f3bde8d6b867fbd0a5134087da9c134344595fd1407f49f72f00d8573d2304b9944b2e667ae44fa63cd9c2337527da5a
-  data.tar.gz: a3e7028f181c255b69d0831f9e9a56c163b48bdacccca8464b3d05f6233976a2d412d06d11f3ad5320430186e2c067830e96ee048f415281933da5a6bc41a22f
+  metadata.gz: 75c81cb580e0948629948f8be59ccaf81e175239e2d268ae7b8cf9f5f6a42073e930881fc2ac5fe7700806c925684f9defd297f47673a2b2470754d688858554
+  data.tar.gz: 8603393804ca3cdd96c5406fb313b1dca1ff7b378c780b7b42765c14d2b76c4e2d0895f8766c0a50fcbe14e0ea5f9ec1381fb7d330737d4ab50b950c76e84e56

data/CHANGELOG.md

@@ -6,6 +6,24 @@
      filled in by the release commit, which is also the only commit that
      touches lib/railwatch/version.rb and Gemfile.lock. See CONTRIBUTING.md. -->
 
+## 0.8.7 (2026-10-06)
+
+- A migration of the railwatch databases waits up to 60 s for SQLite's
+  write lock instead of the database's own `timeout` (5 s in the generated
+  `database.yml`). A deploy migrates while the previous release is still
+  serving, and on an embedded install that release's writer keeps
+  committing telemetry to the same file: about a second per transaction on
+  a warm 15 GB file, several seconds while the deploy's image build has the
+  disk. rebulk-system's container entrypoint ran `db:prepare` into that,
+  got `SQLite3::BusyException: database is locked` from the first
+  migration that needed a write, and crash-looped until the health check
+  gave up. Only the connection Active Record migrates with is changed, only
+  while it migrates, and only for a database whose `migrations_paths` are
+  this gem's; the app's requests keep failing fast. It applies with
+  Railwatch disabled, which is how an entrypoint migrates.
+  `RAILWATCH_MIGRATION_BUSY_TIMEOUT` (`c.migration_busy_timeout`, seconds)
+  sets it; keep it inside the deploy's health-check window.
+
 ## 0.8.6 (2026-10-06)
 
 - An install upgrading from 0.5.0 or older can migrate again. 0.5.1

data/lib/railwatch/configuration.rb

@@ -76,7 +76,7 @@ module Railwatch
                   :buffer_size, :buffer_bytes, :execution_buffer_bytes, :batch_bytes,
                   :backpressure,
                   :flush_interval, :flush_threshold,
-                  :connect_timeout, :timeout, :shutdown_timeout,
+                  :connect_timeout, :timeout, :shutdown_timeout, :migration_busy_timeout,
                   :slow_query_threshold_ms, :n_plus_one_threshold,
                   :max_view_renders_per_execution, :ignored_cache_key_prefixes,
                   :beacon_enabled, :beacon_rate_limit, :beacon_global_rate_limit, :beacon_allowed_origins,
@@ -187,6 +187,13 @@ module Railwatch
       @connect_timeout = env_float("RAILWATCH_CONNECT_TIMEOUT", 1.0)
       @timeout = env_float("RAILWATCH_TIMEOUT", 3.0)
       @shutdown_timeout = env_float("RAILWATCH_SHUTDOWN_TIMEOUT", 2.0)
+      # Seconds a migration of the railwatch databases waits for SQLite's
+      # write lock (Patches::MigrationBusyTimeout). A deploy migrates while
+      # the old release's writer is still committing to the same file; the
+      # database's own `timeout` (5 s) is too short to get between its
+      # transactions when the disk is busy. Kept under a typical health-check
+      # window (Kamal's deploy_timeout defaults to 30 s and is often 90 s).
+      @migration_busy_timeout = env_float("RAILWATCH_MIGRATION_BUSY_TIMEOUT", 60.0)
       @slow_query_threshold_ms = env_float("RAILWATCH_SLOW_QUERY_MS", 5.0)
       @n_plus_one_threshold = env_int("RAILWATCH_N_PLUS_ONE_THRESHOLD", 5)
       @max_view_renders_per_execution = 20

data/lib/railwatch/patches/migration_busy_timeout.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Railwatch
+  module Patches
+    # Gives the migration connection to a Railwatch database a long SQLite
+    # busy timeout, for the migration only.
+    #
+    # A deploy migrates while the previous release is still serving, and on
+    # an embedded install that release's writer process is committing
+    # telemetry to the same file the whole time. Each of its transactions
+    # takes SQLite's single write lock: about a second on a warm 15 GB file
+    # (the export sender's claim scans the destination's whole delivery
+    # history), several seconds while a deploy's image build has the disk.
+    # The migration connection waited only the database's configured
+    # `timeout` -- 5 s in the generated database.yml -- and then raised
+    # SQLite3::BusyException, which db:prepare reports as a failed migration
+    # and the container entrypoint as a failed boot. That is how a deploy of
+    # rebulk-system crash-looped eight times without one migration running.
+    #
+    # The configured timeout is the right one for the app's own requests,
+    # which should fail fast rather than queue behind ingest. A migration is
+    # the opposite: it runs once, before the server binds, and waiting is the
+    # only way through. So only the connection Active Record migrates with is
+    # changed, only while it migrates, and only for a database whose
+    # migrations_paths include this gem's. The host's own databases keep
+    # their timeouts.
+    module MigrationBusyTimeout
+      def migrate(*, **)
+        pool = migration_connection_pool
+        raw = Railwatch::Patches::MigrationBusyTimeout.lengthen(pool)
+        super
+      ensure
+        Railwatch::Patches::MigrationBusyTimeout.restore(pool, raw) if raw
+      end
+
+      class << self
+        # The raw SQLite connection whose timeout was lengthened, or nil when
+        # this is not a Railwatch database (or not SQLite).
+        def lengthen(pool)
+          return unless railwatch_database?(pool.db_config)
+
+          raw = pool.lease_connection.raw_connection
+          return unless raw.respond_to?(:busy_handler_timeout=)
+
+          raw.busy_handler_timeout = (Railwatch.config.migration_busy_timeout.to_f * 1000).to_i
+          raw
+        rescue StandardError => e
+          Railwatch.debug { "migration busy timeout not applied: #{e.class}: #{e.message}" }
+          nil
+        end
+
+        # Back to what database.yml says, so a connection that outlives the
+        # migration (db:migrate in a long-lived process, a spec) behaves as
+        # configured afterwards.
+        def restore(pool, raw)
+          timeout = pool.db_config.configuration_hash[:timeout]
+          if timeout
+            raw.busy_handler_timeout = Integer(timeout)
+          else
+            raw.busy_handler(nil)
+          end
+        rescue StandardError => e
+          Railwatch.debug { "migration busy timeout not restored: #{e.class}: #{e.message}" }
+        end
+
+        def railwatch_database?(db_config)
+          ours = %i[railwatch railwatch_telemetry].map { |name| File.expand_path(Railwatch.migrations_path(name)) }
+          Array(db_config.migrations_paths).any? { |path| ours.include?(File.expand_path(path.to_s, Rails.root.to_s)) }
+        end
+      end
+    end
+  end
+end

data/lib/railwatch/patches.rb

@@ -4,6 +4,7 @@ require "railwatch/patches/net_http"
 require "railwatch/patches/rake_task"
 require "railwatch/patches/runner_command"
 require "railwatch/patches/inertia"
+require "railwatch/patches/migration_busy_timeout"
 
 module Railwatch
   module Patches
@@ -22,6 +23,16 @@ module Railwatch
     # From Rails::Engine#load_tasks, which has already required rake.
     def install_rake_task!
       ::Rake::Task.prepend(RakeTask) unless ::Rake::Task.ancestors.include?(RakeTask)
+      install_migration_busy_timeout!
+    end
+
+    # db:prepare and db:migrate run as rake tasks, so this goes in with the
+    # rake patch. Unlike it, this one is not gated on Railwatch.enabled?: a
+    # container entrypoint migrates with Railwatch switched off, and that is
+    # exactly the migration that has to wait out the old release's writer.
+    def install_migration_busy_timeout!
+      tasks = ::ActiveRecord::Tasks::DatabaseTasks.singleton_class
+      tasks.prepend(MigrationBusyTimeout) unless tasks.ancestors.include?(MigrationBusyTimeout)
     end
 
     # From Rails::Application#load_runner, which RunnerCommand#perform calls

data/lib/railwatch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Railwatch
-  VERSION = "0.8.6"
+  VERSION = "0.8.7"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: railwatch
 version: !ruby/object:Gem::Version
-  version: 0.8.6
+  version: 0.8.7
 platform: ruby
 authors:
 - Cole Robertson
@@ -453,6 +453,7 @@ files:
 - lib/railwatch/minitest.rb
 - lib/railwatch/patches.rb
 - lib/railwatch/patches/inertia.rb
+- lib/railwatch/patches/migration_busy_timeout.rb
 - lib/railwatch/patches/net_http.rb
 - lib/railwatch/patches/rake_task.rb
 - lib/railwatch/patches/runner_command.rb