Maintenance & CLI

To maintain peak performance, the outbox table must be periodically cleaned. The Open Outbox Relay includes a built-in CLI designed for maintenance, cleanup, and manual intervention.

Scaling & Maintenance

Open Outbox is designed to handle tables with thousands of records efficiently using standard indexes. However, regular maintenance is required to keep indexes lean and prevent database bloat.

When to Consider Partitioning

While the Relay handles high-volume workloads, if your dataset grows into the hundreds of millions or billions of records, standard DELETE operations will eventually become a bottleneck.

At this scale, we recommend implementing Table Partitioning (e.g., by date) at the database level. This allows you to manage data by dropping old partitions rather than executing row-by-row deletions. Note that partition rotation must be managed externally, as Open Outbox does not natively manage database partitions.

Pruning Historical Data

Successfully delivered or exhausted (dead) events should be removed periodically to maintain query speed.

Performance Requirement

Pruning high-volume tables can be resource-intensive. Before running your first prune, ensure you have applied the specialized maintenance indexes found in: schema/postgres/maintenance.sql.

Pruning Strategy

You can prune events based on their age and status:

• Delivered Events: Successfully processed messages.
• Dead Events: Messages that have exhausted all retry attempts.

---

CLI Configuration & Usage

The maintenance CLI is bundled within the standard Relay image. To use it with Docker Compose, you must first define a cli service in your docker-compose.yaml with the correct entrypoint and profile.

services:
  # Main Relay Service
  relay:
    image: openoutbox/relay:latest
    # ... other config

  # Maintenance CLI Service
  cli:
    image: openoutbox/relay:latest
    entrypoint: ["/app/cli"]
    environment:
      - STORAGE_TYPE=postgres
      - STORAGE_URL=postgres://user:pass@db-host:5432/db
    profiles: ["tools"] # Prevents the CLI from starting with 'up'

Usage Examples

Once configured, use the docker compose run command to invoke the pruning tool.

Docker Compose

Dry Run (Simulation): Verify the impact before deleting data

docker compose run --rm cli prune --delivered-age 7d --dead-age 30d --dry-run

Execute Pruning: Remove successfully delivered events older than 7 days and dead events older than 30 days.

docker compose run --rm cli prune --delivered-age 7d --dead-age 30d

Docker CLI

Use this for one-off tasks or scripts without docker ompose. Note that you must explicitly map the network and environment variables.

docker run --rm \
  --network open-outbox-network \
  -e STORAGE_URL="postgres://user:pass@host:5432/db" \
  --entrypoint "/app/cli" \
  openoutbox/relay:latest \
  prune --delivered-age 7d --dead-age 30d

---

Automation via Cron

For production environments, automate maintenance using a system crontab.

# Run daily at 2:00 AM
0 2 * * * cd /path/to/project && docker compose run --rm -T cli prune --delivered-age 7d --dead-age 30d