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 (overrides all config) |
--schema <SCHEMA> |
-s |
Schema name (default: public) |
--config <FILE> |
-c |
Config file path |
--log-dest <DEST> |
stderr | file | |
--log-level <LEVEL> |
error | warn | info | debug | trace | |
--format <FORMAT> |
json | table (default: table) | |
--out <OUT> |
stdout | file |
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
Schema Commands¶
install¶
Install the pgqrs schema (schema must already exist).
uninstall¶
Remove the pgqrs schema and all data.
Warning
This permanently deletes all queues, messages, and workers.
verify¶
Verify the pgqrs installation.
Queue Commands¶
queue create¶
Create a new queue.
Example:
queue list¶
List all queues.
queue get¶
Show details for a queue.
queue delete¶
Delete a queue.
Warning
This deletes the queue and all its messages.
queue purge¶
Remove all messages from a queue without deleting the queue.
queue metrics¶
Show metrics for one or all queues.
Output:
| Field | Description |
|---|---|
pending |
Messages waiting to be processed |
locked |
Messages currently being processed |
archived |
Successfully processed messages |
total |
Total messages |
Message Commands¶
message enqueue¶
Add a message to a queue.
Options:
| Option | Required | Description |
|---|---|---|
--queue |
Yes | Queue name |
--payload |
Yes | JSON payload |
--delay |
No | Delay in seconds |
Examples:
# Immediate message
pgqrs message enqueue --queue emails --payload '{"to": "user@example.com"}'
# Delayed message (1 hour)
pgqrs message enqueue --queue reminders --payload '{"type": "follow_up"}' --delay 3600
message dequeue¶
Fetch a message for processing.
Options:
| Option | Required | Description |
|---|---|---|
--queue |
Yes | Queue name |
--worker |
Yes | Worker ID |
--lock-time |
No | Lock duration in seconds |
message archive¶
Archive a processed message.
message delete¶
Delete a message without archiving.
message get¶
Show message details.
message count¶
Count pending messages in a queue.
Worker Commands¶
worker create¶
Register a new worker.
Example:
worker list¶
List all workers.
worker get¶
Show worker details.
worker stats¶
Show worker statistics for a queue.
worker stop¶
Mark a worker as stopped.
worker messages¶
Show messages assigned to a worker.
worker release¶
Release all messages from a worker.
worker delete¶
Delete a worker (must have no messages).
worker purge¶
Remove old stopped workers.
Duration format: 7d, 30d, 24h, etc.
Example:
worker health¶
Check worker health.
Example:
Archive Commands¶
archive list¶
List archived messages.
archive count¶
Count archived messages.
archive delete¶
Delete archived messages.
Archive Best Practices
- Regularly purge old archived messages
- Monitor archive growth
- Set retention policies
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"}
]
Common Workflows¶
Setup¶
# Set connection
export PGQRS_DSN="postgresql://localhost/mydb"
# Install schema
pgqrs install
pgqrs verify
# Create queue
pgqrs queue create tasks
Send and Process Messages¶
# Send message
pgqrs message enqueue --queue tasks --payload '{"job": "process_order", "order_id": 123}'
# Process (in worker)
pgqrs message dequeue --queue tasks --worker 1 --lock-time 60
# Archive after processing
pgqrs message archive --queue tasks --id 1
Monitor¶
# Queue status
pgqrs queue metrics tasks
# Worker health
pgqrs worker health --queue tasks
# Check backlog
pgqrs message count --queue tasks
Cleanup¶
# Purge old workers
pgqrs worker purge --older-than 30d
# Clean archive
pgqrs archive delete tasks --older-than 90d
# Empty queue
pgqrs queue purge tasks
Exit Codes¶
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Configuration error |
| 3 | Database connection error |
| 4 | Command not found |