CLI Reference¶
Complete reference for the pgqrs command-line interface.
Installation¶
The CLI is included when you install the pgqrs Rust crate:
Global Options¶
All commands accept these global options:
| Option | Short | Description |
|---|---|---|
--dsn <DSN> |
-d |
Database URL (highest priority, overrides all config sources) |
--schema <SCHEMA> |
-s |
Schema name (default: public, must exist before install) |
--config <CONFIG> |
-c |
Config file path (overrides environment variables and defaults) |
--log-dest <LOG_DEST> |
Log destination: stderr or file path [default: stderr] | |
--log-level <LOG_LEVEL> |
Log level: error, warn, info, debug, trace [default: info] | |
--format <FORMAT> |
Output format: json, table [default: table] | |
--out <OUT> |
Output destination: stdout or file path [default: stdout] |
Configuration¶
pgqrs loads configuration in priority order:
- Command-line arguments (highest priority)
- Environment variables
- Configuration file
- Defaults
Environment Variables¶
# Required
export PGQRS_DSN="postgresql://user:pass@localhost/db"
# Optional
export PGQRS_SCHEMA="pgqrs"
export PGQRS_MAX_CONNECTIONS=32
export PGQRS_CONNECTION_TIMEOUT=60
export PGQRS_DEFAULT_LOCK_TIME=10
export PGQRS_DEFAULT_BATCH_SIZE=200
export PGQRS_CONFIG_FILE="path/to/config.yaml"
Configuration File¶
Create pgqrs.yaml or pgqrs.yml:
dsn: "postgresql://user:pass@localhost/db"
schema: "pgqrs"
max_connections: 16
connection_timeout_seconds: 30
default_lock_time_seconds: 5
default_max_batch_size: 100
Admin Commands¶
Administrative operations for managing the pgqrs installation and system-wide state.
install¶
Install the pgqrs schema in your database.
Warning
The target schema (e.g., public or your custom schema) must already exist.
verify¶
Verify the pgqrs installation by checking that all required tables and indexes exist.
stats¶
Get system-wide statistics across all queues and workers.
reclaim¶
Reclaim messages from zombie workers (workers that have stopped sending heartbeats).
Queue Commands¶
Commands for managing queues and viewing queue-level metrics.
create¶
Create a new queue.
Example:
list¶
List all queues in the database.
get¶
Show details for a specific queue.
messages¶
List messages currently in the queue.
archive-dlq¶
Move dead letter queue messages to the archive.
delete¶
Delete a queue.
Warning
This deletes the queue and all its messages.
purge¶
Remove all messages from a queue without deleting the queue itself.
metrics¶
Show detailed metrics for one or all queues.
Output attributes include: - Pending and Locked message counts - Archived metrics - Error rates
Worker Commands¶
Commands for managing, monitoring, and cleaning up workers.
list¶
List all active workers.
get¶
Get details for a specific worker by its ID.
messages¶
Get messages currently assigned to a specific worker.
release-messages¶
Force-release all messages currently held by a worker back to the queue.
suspend¶
Suspend a worker (Ready -> Suspended). It will stop processing new messages but finish current ones.
resume¶
Resume a suspended worker (Suspended -> Ready).
shutdown¶
Shutdown a worker. The worker must be suspended first.
purge¶
Purge old stopped workers from the database to save space.
delete¶
Delete a specific worker record.
heartbeat¶
Manually update a worker's heartbeat.
stats¶
Get statistics for a specific worker.
health¶
Check the health status of a specific worker or workers.
Output Formats¶
Table Format (Default)¶
┌────┬────────────┬─────────────────────┐
│ ID │ Name │ Created At │
├────┼────────────┼─────────────────────┤
│ 1 │ emails │ 2024-01-15 10:30:00 │
│ 2 │ reminders │ 2024-01-15 10:31:00 │
└────┴────────────┴─────────────────────┘
JSON Format¶
[
{"id": 1, "name": "emails", "created_at": "2024-01-15T10:30:00Z"},
{"id": 2, "name": "reminders", "created_at": "2024-01-15T10:31:00Z"}
]
Exit Codes¶
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Configuration error |
| 3 | Database connection error |
| 4 | Command not found |