async-background 1.0.0 → 1.0.2

data/README.md

@@ -1,36 +1,67 @@
 # Async::Background
 
-A lightweight cron, interval, and job-queue scheduler for Ruby's [Async](https://github.com/socketry/async) ecosystem. Built for [Falcon](https://github.com/socketry/falcon), works with any Async app.
+A lightweight cron, interval, and job-queue scheduler for Ruby's
+[Async](https://github.com/socketry/async) ecosystem. Built for
+[Falcon](https://github.com/socketry/falcon), works with any Async app.
+
+- **Cron & interval scheduling** on a single event loop with a min-heap.
+- **Dynamic job queue** backed by SQLite, with delayed jobs
+  (`perform_in` / `perform_at`).
+- **Cross-process wake-ups** over Unix domain sockets — web workers can
+  enqueue and instantly wake background workers.
+- **Multi-process safe** — deterministic worker sharding, no duplicate
+  execution.
+- **Per-job timeouts**, skip-on-overlap, startup jitter, optional metrics.
 
-- **Cron & interval scheduling** on a single event loop with a min-heap
-- **Dynamic job queue** backed by SQLite, with delayed jobs (`perform_in` / `perform_at`)
-- **Cross-process wake-ups** over Unix domain sockets — web workers can enqueue and instantly wake background workers
-- **Multi-process safe** — deterministic worker sharding, no duplicate execution
-- **Per-job timeouts**, skip-on-overlap, startup jitter, optional metrics
+---
+
+## Why Async? Why fibers?
+
+The whole gem is built around the assumption that Falcon's reactor schedules
+many fibers on top of one OS thread per process — so the dashboard's SSE
+stream, the cron scheduler, and the queue worker all share that one thread
+cooperatively. A blocked fiber yields; a blocked thread doesn't.
+
+![Threads vs fibers under different Ruby web servers](docs/fibers-vs-threads.svg)
+
+That's also why the dashboard (since 1.0.1) runs its SSE loop entirely inside
+the request fiber: zero extra threads, zero `ConditionVariable`, ~4 KB per
+open tab.
+
+---
 
 ## Requirements
 
-- Ruby >= 3.3
-- `async ~> 2.0`, `fugit ~> 1.0`
-- `sqlite3 ~> 2.0` (optional, storage)
-- `async-utilization >= 0.3, < 0.5` (optional, for metrics)
+| Dependency           | Version          | Required?            |
+| -------------------- | ---------------- | -------------------- |
+| Ruby                 | `>= 3.3`         | yes                  |
+| `async`              | `~> 2.0`         | yes                  |
+| `fugit`              | `~> 1.0`         | yes                  |
+| `sqlite3`            | `~> 2.0`         | for the queue & dashboard |
+| `async-utilization`  | `>= 0.3, < 0.5`  | for metrics          |
+
+---
 
 ## Install
 
 ```ruby
 # Gemfile
 gem "async-background"
-gem "sqlite3", "~> 2.0"  # optional
-gem "async-utilization", ">= 0.3", "< 0.5"  # optional
+
+gem "sqlite3",           "~> 2.0"          # if you use the queue or dashboard
+gem "async-utilization", ">= 0.3", "< 0.5" # if you want worker metrics
 ```
 
-## ➡️ [Get Started](docs/GET_STARTED.md)
+---
+
+## ➡️ [Get started](docs/GET_STARTED.md)
 
-Full setup walkthrough: schedule config, Falcon integration, Docker, queue, delayed jobs.
+A four-step walkthrough: schedule config, Falcon integration, Docker, queue,
+delayed jobs.
 
 ---
 
-## Quick Look
+## Quick look
 
 ```ruby
 class SendEmailJob
@@ -59,114 +90,71 @@ daily_report:
   timeout: 120
 ```
 
-| Key | Description |
-|---|---|
-| `class` | Job class — must include `Async::Background::Job` |
-| `every` / `cron` | One of: interval in seconds, or cron expression |
-| `timeout` | Max execution time in seconds (default: 30) |
-| `worker` | Pin to a specific worker. Default: `crc32(name) % total_workers` |
+| Key              | Description                                                     |
+| ---------------- | --------------------------------------------------------------- |
+| `class`          | Job class — must include `Async::Background::Job`.              |
+| `every` / `cron` | Interval in seconds, or a cron expression. Exactly one.         |
+| `timeout`        | Max execution time in seconds. Default: 30.                     |
+| `worker`         | Pin to a specific worker. Default: `crc32(name) % total_workers`. |
 
 ---
 
 ## Gotchas
 
-### Docker: SQLite requires a named volume
-
-The SQLite database **must not** live on Docker's `overlay2` filesystem. The `overlay2` driver breaks coherence between `write()` and `mmap()`, which corrupts SQLite WAL under concurrent access.
-
-```yaml
-# docker-compose.yml
-services:
-  app:
-    volumes:
-      - queue-data:/app/tmp/queue   # ← named volume, NOT overlay2
-
-volumes:
-  queue-data:
-```
-
-Without this, you will get database crashes in multi-process mode. See [Get Started → Step 3](docs/GET_STARTED.md#step-3-docker) for details. If you can't use a named volume, pass `queue_mmap: false` to disable mmap entirely.
-
-### Other gotchas
+**Docker + SQLite — use a named volume.**
+SQLite's database must not live on Docker's default `overlay2` filesystem:
+`overlay2` breaks coherence between `write()` and `mmap()`, which corrupts
+the WAL under concurrent access. Mount the queue directory as a named volume,
+or pass `mmap: false` to `Store.new`. See
+[Get Started → Docker](docs/GET_STARTED.md#step-3--docker-setup).
 
-**Don't share SQLite connections across `fork()`.** The gem opens connections lazily after fork, but if you create a `Queue::Store` manually for schema setup, close it before forking:
-
-```ruby
-Async::Background::Queue.migrate!(path: db_path) # ← once, before fork
-# Every process opens its own Store lazily after fork.
-```
+**Don't share SQLite connections across `fork()`.**
+The gem opens connections lazily after fork. If you build a `Store` manually
+for schema setup, close it before forking.
 
-**Two clocks, on purpose.** Interval jobs use `CLOCK_MONOTONIC` (immune to NTP drift). Cron jobs use wall-clock time, because "every day at 3am" needs to mean 3am.
+**Two clocks, on purpose.**
+Interval jobs use `CLOCK_MONOTONIC` so NTP drift can't fire them twice. Cron
+jobs use wall-clock time, because "every day at 3am" needs to mean 3am.
 
 ---
 
 ## How it works
 
+A single Async task sleeps until the next entry is due, then dispatches it
+under a semaphore that caps concurrency. Overlapping ticks are skipped and
+rescheduled.
+
 ```
-schedule.yml ─► build_heap ─► MinHeap<Entry> ─► scheduler loop ─► Semaphore ─► run_job
+schedule.yml → build_heap → MinHeap<Entry> → scheduler loop → Semaphore → run_job
 ```
 
-A single Async task sleeps until the next entry is due, then dispatches it under a semaphore that caps concurrency. Overlapping ticks are skipped and rescheduled.
-
 The dynamic queue runs alongside it:
 
 ```
-   Producer (web/console)              Consumer (background worker)
-          │                                       │
-          ▼                                       ▼
-    Queue::Client                          Queue::Store#fetch
-   push / push_in / push_at                (run_at <= now)
-          │                                       ▲
-          ▼                                       │
-    Queue::Store ──── SQLite (jobs) ──── SocketWaker
-          │                                       ▲
-          └───────► SocketNotifier ───────────────┘
-                    (UNIX socket wake-up, ~80µs)
-```
-
-Jobs are persisted in SQLite, so a missed wake-up is never a lost job — workers also poll every 5 seconds as a safety net.
-
-### Queue-only workers
-
-Recurring schedules are optional. A worker that serves only dynamic jobs starts with
-`config_path: nil` and a `queue_socket_dir`; it does not need a placeholder schedule file.
-A supplied schedule path stays strict and raises when the file is missing or empty.
-
-### Schema migration during deploy
-
-Run queue migrations once in the release/pre-deploy step, before starting new web or worker
-processes. This serializes the schema upgrade with `BEGIN IMMEDIATE`, records the version in
-SQLite, and avoids a first producer doing DDL under live queue traffic:
-
-```ruby
-Async::Background::Queue.migrate!(path: ENV.fetch("QUEUE_DB_PATH"))
+   Producer (web / console)                Consumer (background worker)
+          │                                          │
+          ▼                                          ▼
+    Queue::Client                            Queue::Store#fetch
+   push / push_in / push_at                  (run_at <= now)
+          │                                          ▲
+          ▼                                          │
+    Queue::Store ──── SQLite (jobs) ──── SocketWaker │
+          │                                          ▲
+          └─────────► SocketNotifier ────────────────┘
+                      (UNIX socket wake-up, ~80µs)
 ```
 
-A fresh database still self-initializes on first use for local development, but explicit
-migration is the production path. For an existing queue, finish or stop 0.7.1 producers/workers,
-run the migration once, then start 0.7.2 processes.
-
-### Dashboard indexes
-
-The queue does **not** install dashboard indexes by default. They slow every enqueue even though
-pending rows never enter terminal or in-flight read-model indexes. Enable them once before
-mounting the dashboard:
-
-```ruby
-Async::Background::Queue.prepare_dashboard!(path: ENV.fetch("QUEUE_DB_PATH"))
-```
+Jobs are persisted in SQLite, so a missed wake-up is never a lost job —
+workers also poll every 5 seconds as a safety net.
 
-It adds four compact indexes: cursor-sorted `done` / `failed` history plus separate
-`executing` / `claimed` in-flight lists. It does not change queue behavior or rerun the core migration.
+---
 
 ## Metrics
 
-Metrics are an optional integration with `async-utilization` (`>= 0.3`, `< 0.5`). The
-background worker remains fully functional when that gem is absent. With it installed, each
-worker publishes counters to a shared-memory segment.
+Metrics are an optional integration with `async-utilization`. With the gem
+installed, each worker publishes counters to a shared-memory segment:
 
 ```ruby
-runner.metrics.enabled?
 runner.metrics.values
 # => { total_runs: 142, total_successes: 140, total_failures: 2,
 #      total_timeouts: 0, total_skips: 5, active_jobs: 1, ... }
@@ -175,19 +163,13 @@ Async::Background::Metrics.read_all(total_workers: 2)
 # => [{ worker: 1, ... }, { worker: 2, ... }]
 ```
 
-`Metrics.read_all` returns `[]` until the optional gem is installed and a worker has created
-the file, so an observer can render an unavailable state without rescuing `LoadError`. Its
-snapshot is lock-free best effort: cumulative fields (`total_runs`, `total_successes`,
-`total_failures`, `total_timeouts`, `total_skips`) are counters; `active_jobs`,
-`last_run_at`, and `last_duration_ms` are gauges. Fields can describe adjacent moments in time
-rather than one globally atomic instant.
-
-By default the file is `/tmp/async-background.shm`. Set `ASYNC_BACKGROUND_METRICS_PATH`
-or pass `metrics_shm_path:` to `Runner.new` when another observer runs in a separate process
-or container; both sides must see the same mounted file.
-
+Without the gem, `runner.metrics.enabled?` is `false` and `read_all` returns
+`[]` — no `LoadError` to rescue. Configuration and the cross-container
+shared-memory path are covered in
+[Get Started → Optional metrics](docs/GET_STARTED.md#appendix-optional-metrics).
 
+---
 
 ## License
 
-MIT
+MIT.

data/lib/async/background/metrics.rb

@@ -127,9 +127,7 @@ module Async
         end
 
         def decode_workers(buffer, schema, segment, total_workers)
-          (1..total_workers).map do |worker|
-            decode_worker(buffer, schema, segment, worker)
-          end.freeze
+          (1..total_workers).map { |worker| decode_worker(buffer, schema, segment, worker) }.freeze
         end
 
         def decode_worker(buffer, schema, segment, worker)

data/lib/async/background/queue/socket_notifier.rb

@@ -2,10 +2,14 @@
 
 require 'socket'
 
+require_relative '../clock'
+
 module Async
   module Background
     module Queue
       class SocketNotifier
+        include Clock
+
         # Errors that indicate a worker is unavailable - silently skip and try the next.
         UNAVAILABLE = [
           Errno::ENOENT,        # Socket file doesn't exist (worker hasn't started yet)
@@ -14,41 +18,68 @@ module Async
           Errno::ECONNRESET     # Connection reset by peer
         ].freeze
 
+        DEAD_WORKER_TTL = 5.0
+        WAKE_BYTE = "\x01".freeze
+
         def initialize(socket_dir:, total_workers:)
           @socket_dir = socket_dir
           @total_workers = total_workers
+          @paths = build_paths
+          @dead_until = Array.new([@total_workers, 0].max, 0.0)
+          @cursor = 0
         end
 
         def notify_all
-          return if @total_workers <= 0
+          return false if @total_workers <= 0
+
+          now = monotonic_now
+          start = advance_cursor
 
-          start = rand(@total_workers)
-          @total_workers.times do |i|
-            worker_index = ((start + i) % @total_workers) + 1
-            return if notify_one(worker_index)
+          @total_workers.times do |offset|
+            index = (start + offset) % @total_workers
+            return true if notify_one(index, now)
           end
+
+          false
         end
 
         private
 
-        def notify_one(worker_index)
-          path = socket_path(worker_index)
-          sock = UNIXSocket.new(path)
+        def build_paths
+          return [].freeze if @total_workers <= 0
+
+          Array.new(@total_workers) do |index|
+            File.join(@socket_dir, "async_bg_worker_#{index + 1}.sock").freeze
+          end.freeze
+        end
+
+        def advance_cursor
+          @cursor = (@cursor + 1) % @total_workers
+        end
+
+        def notify_one(index, now)
+          return false if @dead_until[index] > now
+
+          socket = UNIXSocket.new(@paths[index])
           begin
-            sock.write_nonblock("\x01")
+            socket.write_nonblock(WAKE_BYTE)
           ensure
-            sock.close rescue nil
+            socket.close rescue nil
           end
           true
+        rescue IO::WaitWritable
+          true
         rescue *UNAVAILABLE
+          mark_dead(index, now)
           false
         rescue => e
-          Console.logger.warn(self) { "SocketNotifier#notify_one(#{worker_index}) failed: #{e.class} #{e.message}" } rescue nil
+          mark_dead(index, now)
+          Console.logger.warn(self) { "SocketNotifier#notify_one(#{index + 1}) failed: #{e.class} #{e.message}" } rescue nil
           false
         end
 
-        def socket_path(worker_index)
-          File.join(@socket_dir, "async_bg_worker_#{worker_index}.sock")
+        def mark_dead(index, now)
+          @dead_until[index] = now + DEAD_WORKER_TTL
         end
       end
     end

data/lib/async/background/queue/socket_waker.rb

@@ -80,12 +80,15 @@ module Async
           parent_task.async do
             begin
               loop do
-                client.read_nonblock(256)
-              rescue IO::WaitReadable
-                client.wait_readable
-                retry
-              rescue EOFError, Errno::ECONNRESET
-                break
+                begin
+                  client.read_nonblock(256)
+                  @notification.signal
+                rescue IO::WaitReadable
+                  client.wait_readable
+                  retry
+                rescue EOFError, Errno::ECONNRESET
+                  break
+                end
               end
             rescue => e
               Console.logger.warn(self) { "SocketWaker client handler error: #{e.class} #{e.message}" }

data/lib/async/background/queue/sql.rb

@@ -9,7 +9,8 @@ module Async
         BUSY_TIMEOUT = 'PRAGMA busy_timeout'.freeze
         TABLE_INFO = 'PRAGMA table_info(jobs)'.freeze
         OPTIMIZE = 'PRAGMA optimize'.freeze
-        INCREMENTAL_VACUUM = 'PRAGMA incremental_vacuum'.freeze
+        INCREMENTAL_VACUUM_PAGES = 64
+        INCREMENTAL_VACUUM = "PRAGMA incremental_vacuum(#{INCREMENTAL_VACUUM_PAGES})".freeze
         AUTO_VACUUM_INCREMENTAL = 'PRAGMA auto_vacuum = INCREMENTAL'.freeze
         BEGIN_IMMEDIATE = 'BEGIN IMMEDIATE'.freeze
         COMMIT = 'COMMIT'.freeze

data/lib/async/background/queue/store.rb

@@ -22,6 +22,7 @@ module Async
         CLEANUP_INTERVAL = 300
         CLEANUP_AGE = 3600
         FAILED_RETENTION_AGE = 7 * 24 * 3600
+        CLEANUP_VACUUM_THRESHOLD = 100
         ERROR_MESSAGE_MAX_LEN = 2_000
         EMPTY_ARGS_JSON = '[]'.freeze
 
@@ -80,7 +81,13 @@ module Async
         def enqueue(class_name, args = EMPTY_ARGS, run_at = nil, options: EMPTY_OPTIONS)
           ensure_connection
           now = realtime_now
-          @enqueue_stmt.execute(class_name, dump_args(args), dump_options(options), now, run_at || now)
+          stepped(@enqueue_stmt) do |statement|
+            statement.bind_param(1, class_name)
+            statement.bind_param(2, dump_args(args))
+            statement.bind_param(3, dump_options(options))
+            statement.bind_param(4, now)
+            statement.bind_param(5, run_at || now)
+          end
           @db.last_insert_row_id
         end
 
@@ -90,9 +97,14 @@ module Async
           now = realtime_now
 
           row = transaction do
-            with_statement(@fetch_stmt) { |statement| statement.execute(worker_id, now, token, now).first }
+            stepped(@fetch_stmt) do |statement|
+              statement.bind_param(1, worker_id)
+              statement.bind_param(2, now)
+              statement.bind_param(3, token)
+              statement.bind_param(4, now)
+            end
           end
-          return unless row
+          return if row.nil? || row.empty?
 
           maybe_cleanup
           job_from_row(row, token)
@@ -100,26 +112,28 @@ module Async
 
         def mark_started!(job_id, claim_token:, started_at: realtime_now)
           ensure_connection
-          @mark_started_stmt.execute(started_at, job_id, claim_token)
+          stepped(@mark_started_stmt) do |statement|
+            statement.bind_param(1, started_at)
+            statement.bind_param(2, job_id)
+            statement.bind_param(3, claim_token)
+          end
           @db.changes.positive?
         end
 
         def complete(job_id, claim_token:, finished_at: realtime_now, duration_ms: nil)
           ensure_connection
-          @complete_stmt.execute(finished_at, duration_ms, job_id, claim_token)
+          stepped(@complete_stmt) do |statement|
+            statement.bind_param(1, finished_at)
+            statement.bind_param(2, duration_ms)
+            statement.bind_param(3, job_id)
+            statement.bind_param(4, claim_token)
+          end
           @db.changes.positive?
         end
 
         def fail(job_id, claim_token:, error_class: nil, error_message: nil, finished_at: realtime_now, duration_ms: nil)
           ensure_connection
-          @fail_stmt.execute(
-            finished_at,
-            duration_ms,
-            error_class&.to_s,
-            truncate_message(error_message),
-            job_id,
-            claim_token
-          )
+          bind_failure(@fail_stmt, finished_at, duration_ms, error_class, error_message, job_id, claim_token)
           @db.changes.positive?
         end
 
@@ -146,13 +160,13 @@ module Async
 
         def recover(worker_id)
           ensure_connection
-          @requeue_stmt.execute(worker_id)
+          stepped(@requeue_stmt) { |statement| statement.bind_param(1, worker_id) }
           @db.changes
         end
 
         def next_pending_run_at
           ensure_connection
-          with_statement(@next_pending_stmt) { |statement| statement.execute.first&.first }
+          stepped(@next_pending_stmt)&.first
         end
 
         def data_version
@@ -243,9 +257,11 @@ module Async
         end
 
         def stored_options_for(job_id, claim_token)
-          with_statement(@retry_state_stmt) do |statement|
-            load_options(statement.execute(job_id, claim_token).first&.first)
+          row = stepped(@retry_state_stmt) do |statement|
+            statement.bind_param(1, job_id)
+            statement.bind_param(2, claim_token)
           end
+          load_options(row&.first)
         end
 
         def retry_policy(stored_options, fallback_options)
@@ -260,29 +276,33 @@ module Async
 
         def retry_job!(job_id, claim_token, policy, error_class, error_message)
           advanced = policy.with_attempt(policy.next_attempt)
-          @retry_stmt.execute(
-            realtime_now + advanced.next_retry_delay(advanced.attempt),
-            dump_options(advanced.to_h.compact),
-            error_class&.to_s,
-            truncate_message(error_message),
-            job_id,
-            claim_token
-          )
+          stepped(@retry_stmt) do |statement|
+            statement.bind_param(1, realtime_now + advanced.next_retry_delay(advanced.attempt))
+            statement.bind_param(2, dump_options(advanced.to_h.compact))
+            statement.bind_param(3, error_class&.to_s)
+            statement.bind_param(4, truncate_message(error_message))
+            statement.bind_param(5, job_id)
+            statement.bind_param(6, claim_token)
+          end
           @db.changes.positive? ? :retried : nil
         end
 
         def fail_job!(job_id, claim_token, error_class, error_message, finished_at, duration_ms)
-          @fail_stmt.execute(
-            finished_at,
-            duration_ms,
-            error_class&.to_s,
-            truncate_message(error_message),
-            job_id,
-            claim_token
-          )
+          bind_failure(@fail_stmt, finished_at, duration_ms, error_class, error_message, job_id, claim_token)
           @db.changes.positive? ? :failed : nil
         end
 
+        def bind_failure(statement, finished_at, duration_ms, error_class, error_message, job_id, claim_token)
+          stepped(statement) do |s|
+            s.bind_param(1, finished_at)
+            s.bind_param(2, duration_ms)
+            s.bind_param(3, error_class&.to_s)
+            s.bind_param(4, truncate_message(error_message))
+            s.bind_param(5, job_id)
+            s.bind_param(6, claim_token)
+          end
+        end
+
         def generate_claim_token = SecureRandom.hex(16)
 
         def truncate_message(message)
@@ -293,23 +313,30 @@ module Async
         end
 
         def lease_alive?(job_id, claim_token)
-          with_statement(@lease_check_stmt) do |statement|
-            !statement.execute(job_id, claim_token).first.nil?
-          end
+          !stepped(@lease_check_stmt) do |statement|
+            statement.bind_param(1, job_id)
+            statement.bind_param(2, claim_token)
+          end.nil?
         end
 
         def transaction
-          @db.execute(SQL::BEGIN_IMMEDIATE)
+          stepped(@begin_stmt)
           result = yield
-          @db.execute(SQL::COMMIT)
+          stepped(@commit_stmt)
           result
         rescue StandardError
-          @db.execute(SQL::ROLLBACK) rescue nil
+          begin
+            stepped(@rollback_stmt)
+          rescue StandardError
+            nil
+          end
           raise
         end
 
-        def with_statement(statement)
-          yield statement
+        def stepped(statement)
+          statement.reset!
+          yield statement if block_given?
+          statement.step
         ensure
           statement.reset! rescue nil
         end
@@ -346,6 +373,9 @@ module Async
           @cleanup_done_stmt = @db.prepare(SQL::CLEANUP_DONE)
           @cleanup_failed_stmt = @db.prepare(SQL::CLEANUP_FAILED)
           @next_pending_stmt = @db.prepare(SQL::NEXT_PENDING_RUN_AT)
+          @begin_stmt = @db.prepare(SQL::BEGIN_IMMEDIATE)
+          @commit_stmt = @db.prepare(SQL::COMMIT)
+          @rollback_stmt = @db.prepare(SQL::ROLLBACK)
         end
 
         def finalize_statements
@@ -366,7 +396,10 @@ module Async
             @requeue_stmt,
             @cleanup_done_stmt,
             @cleanup_failed_stmt,
-            @next_pending_stmt
+            @next_pending_stmt,
+            @begin_stmt,
+            @commit_stmt,
+            @rollback_stmt
           ]
         end
 
@@ -376,6 +409,7 @@ module Async
           @retry_stmt = @requeue_stmt = nil
           @cleanup_done_stmt = @cleanup_failed_stmt = nil
           @next_pending_stmt = nil
+          @begin_stmt = @commit_stmt = @rollback_stmt = nil
         end
 
         def maybe_cleanup
@@ -387,9 +421,15 @@ module Async
         end
 
         def cleanup_finished_jobs(now)
-          @cleanup_done_stmt.execute(now - CLEANUP_AGE)
-          @cleanup_failed_stmt.execute(now - FAILED_RETENTION_AGE)
-          @db.execute(SQL::INCREMENTAL_VACUUM) if @db.changes > 100
+          deleted = 0
+
+          stepped(@cleanup_done_stmt) { |statement| statement.bind_param(1, now - CLEANUP_AGE) }
+          deleted += @db.changes
+          stepped(@cleanup_failed_stmt) { |statement| statement.bind_param(1, now - FAILED_RETENTION_AGE) }
+          deleted += @db.changes
+
+          @db.execute(SQL::INCREMENTAL_VACUUM) if deleted > CLEANUP_VACUUM_THRESHOLD
+          deleted
         end
       end
     end