CLI Reference

The particledb binary provides subcommands for starting the server, managing data, running backups, and more.

particledb <COMMAND> [OPTIONS]

Commands Overview

Command	Description
start	Start the database server
init	Initialize a new data directory
dump	Export schema and data as SQL (logical backup)
load	Import a SQL dump into a running server
migrate	Migrate data from PostgreSQL to ParticleDB
backup	Create, restore, list, and validate backup archives
snapshot	Snapshot lifecycle management (create, list, delete, prune, restore)
bench	Run built-in benchmarks
verify	Check data integrity of a data directory
deploy	Cloud deployment management
version	Print version information

---

start

Start the ParticleDB server.

particledb start [OPTIONS]

Network

Flag	Default	Description
--pg-addr	0.0.0.0:5432	PostgreSQL wire protocol listen address
--pg-unix-socket	(disabled)	Unix domain socket path (e.g., /tmp/.s.PGSQL.5432)
--http-addr	0.0.0.0:8080	HTTP server (dashboard, health, REST API)
--grpc-addr	0.0.0.0:26257	gRPC listen address
--metrics-port	9090	Prometheus metrics endpoint port
--health-port	8080	Health check endpoint port (Kubernetes probes)
--max-connections	100	Maximum concurrent connections
--connection-timeout	300	Idle connection timeout in seconds (0 = disabled)

Storage

Flag	Default	Description
-c, --config	config.toml	Path to configuration file
-d, --data-dir	./data	Data storage directory
--cold-storage-path	(disabled)	Cold storage path for tiered storage offloading (local dir, S3 mount, or NFS)
--tier-after-level	3	LSM level at which SSTables move to cold storage

Security

Flag	Default	Description
--auth-method	trust	Authentication method: trust, password, md5
--pg-password	(none)	Password for PG client authentication
--no-auth	false	Disable all authentication (local development only)
--tls-cert	(none)	TLS certificate file (PEM) for PG wire, Redis, and gRPC
--tls-key	(none)	TLS private key file (PEM) for PG wire, Redis, and gRPC
--audit-log	false	Enable audit logging (query with SELECT * FROM __pdb_audit_log)
--audit-log-selects	false	Also log SELECT queries in the audit log (high volume)

Transactions and Durability

Flag	Default	Description
--wal-sync-mode	groupsync	WAL durability mode: sync, groupsync, nosync
--txn-mode	(inferred)	Transaction isolation mode: fast, occ, row-2pl, table-2pl
--oltp-partitions	0	Number of OLTP partition workers (0 = disabled)

WAL Sync Modes

Mode	Durability	Performance	Use Case
sync	Full (per-transaction fsync)	Baseline	Mission-critical data
groupsync	~14ms batch window	3-6x faster	Production default
nosync	None	Maximum throughput	Benchmarks, ephemeral data

Transaction Modes

Mode	Behavior	Jepsen-Safe
fast	No locks, maximum OLTP throughput	No
occ	Optimistic concurrency control with buffered writes and commit-time validation	Yes
row-2pl	Alias for occ	Yes
table-2pl	Exclusive table locks, lowest concurrency	Yes

If --txn-mode is omitted, ParticleDB infers it from the WAL mode: nosync/groupsync defaults to fast, sync defaults to occ.

OLTP Partitions

When --oltp-partitions is set to a value greater than 0, data is partitioned across that many dedicated OS threads by primary key hash. Each partition worker owns its data exclusively, eliminating lock contention for single-partition transactions. Set this to the number of CPU cores for TPC-C-style warehouse-affine workloads.

Snapshots

Flag	Default	Description
--snapshot-enabled	false	Enable automated periodic snapshots
--snapshot-interval	3600	Snapshot interval in seconds
--snapshot-max	10	Maximum number of snapshots to retain
--snapshot-retention-days	(none)	Delete snapshots older than this many days
--snapshot-dir	./snapshots	Directory for storing snapshots

Datasets

Flag	Default	Description
--load-datasets	(none)	Comma-separated list of datasets to preload (e.g., netflix,airline,yandex)
--dataset-scale	10000000	Number of rows per dataset

Example

# Production startup with groupsync durability and OCC transactions
particledb start \
    --data-dir /var/lib/particledb \
    --pg-addr 0.0.0.0:5432 \
    --http-addr 0.0.0.0:8080 \
    --wal-sync-mode groupsync \
    --txn-mode occ \
    --auth-method password \
    --pg-password mysecretpassword \
    --tls-cert /etc/particledb/cert.pem \
    --tls-key /etc/particledb/key.pem

# Local development with no auth
particledb start --no-auth --data-dir ./mydata

# High-throughput benchmark mode
particledb start \
    --wal-sync-mode nosync \
    --txn-mode fast \
    --oltp-partitions 32

# Preload Netflix dataset at 10M rows
particledb start --load-datasets netflix --dataset-scale 10000000

---

init

Initialize a new data directory with the required file structure.

particledb init [OPTIONS]

Flag	Default	Description
-d, --data-dir	./data	Data directory to initialize
--shards	1	Number of initial shards
--replication-factor	1	Replication factor

particledb init --data-dir /var/lib/particledb --shards 4 --replication-factor 3

---

dump

Export database schema and data as SQL statements (logical backup). Connects to a running ParticleDB instance via PG wire protocol.

particledb dump [OPTIONS]

Flag	Default	Description
--pg-addr	127.0.0.1:5432	Server address to connect to
-o, --output	(stdout)	Output file path
--tables	(all)	Comma-separated list of tables to dump

# Dump all tables to a file
particledb dump --output backup.sql

# Dump specific tables
particledb dump --tables users,orders --output partial.sql

---

load

Load a SQL dump into a running ParticleDB server.

particledb load [OPTIONS]

Flag	Default	Description
--pg-addr	127.0.0.1:5432	Server address to connect to
-i, --input	(required)	Input SQL file to load

particledb load --input backup.sql

---

migrate

Migrate data directly from a PostgreSQL database to a running ParticleDB server.

particledb migrate [OPTIONS]

Flag	Default	Description
--source	(required)	Source PostgreSQL connection URL
--target	127.0.0.1:5432	Target ParticleDB server address
--tables	(all)	Comma-separated list of tables to migrate
--batch-size	10000	Number of rows per batch

# Migrate all tables
particledb migrate --source postgres://user:pass@pghost:5432/mydb

# Migrate specific tables with custom batch size
particledb migrate \
    --source postgres://user:pass@pghost:5432/mydb \
    --tables users,orders,products \
    --batch-size 50000

---

backup

Manage compressed .tar.gz backup archives.

backup create

particledb backup create --output /backups/pdb_backup.tar.gz [--data-dir ./data]

backup restore

particledb backup restore --input /backups/pdb_backup.tar.gz [--data-dir ./data] [--force]

backup list

particledb backup list [--dir /backups] [--format table|json]

backup validate

particledb backup validate --input /backups/pdb_backup.tar.gz

---

snapshot

Snapshot lifecycle management for point-in-time recovery.

snapshot create

Create a point-in-time snapshot. The database must be stopped (or use --force).

particledb snapshot create [--data-dir ./data] [--snapshot-dir ./snapshots] [--cold-storage-path /mnt/cold] [--force]

snapshot list

particledb snapshot list [--snapshot-dir ./snapshots] [--format table|json]

snapshot delete

particledb snapshot delete <SNAPSHOT_ID> [--snapshot-dir ./snapshots]

snapshot prune

Remove expired snapshots according to retention policy.

particledb snapshot prune [--snapshot-dir ./snapshots] [--max-snapshots 10] [--retention-days 30]

snapshot restore

Restore from a snapshot, optionally with point-in-time recovery.

# Restore a specific snapshot
particledb snapshot restore snap_20260309_120000 --target-dir /var/lib/particledb

# Point-in-time recovery
particledb snapshot restore --target-dir /var/lib/particledb --pitr '2026-03-09T14:30:00Z'

snapshot archive-wal

Archive WAL segments for PITR capability.

particledb snapshot archive-wal --wal-dir ./data/wal --snapshot-dir ./snapshots

snapshot status

particledb snapshot status [--snapshot-dir ./snapshots]

---

verify

Check data integrity of a ParticleDB data directory (offline).

particledb verify [--data-dir ./data] [--consistency true]

The --consistency flag enables full data recovery and consistency checks (slower but more thorough).

---

bench

Run built-in benchmarks.

bench generate

Generate test data for benchmarks.

particledb bench generate [--users 10000] [--orders 100000] [--events 1000000]

bench run

particledb bench run \
    [--workload point-reads|range-scans|writes|transactions|mixed|analytical] \
    [--duration 30] \
    [--concurrency 8] \
    [--report table|json|csv] \
    [--compare previous_run.json]

---

Environment Variables

Every configuration option can be set via an environment variable with the PDB_ prefix:

PDB_PG_ADDR=0.0.0.0:5432
PDB_WAL_SYNC_MODE=groupsync
PDB_AUTH_METHOD=password
PDB_TLS_CERT=/path/to/cert.pem

Diagnostic Variables

Variable	Values	Description
PDB_WIRE_TRACE	1	Log every PG wire message (Parse, Bind, Execute, Sync) with timing
PDB_WIRE_DUMP	1	Dump raw wire bytes for protocol debugging
PDB_REDIS_PROFILE	1 or N	Log Redis commands with timing (N = sample every Nth command)
PDB_OLTP_PROFILE	1 or N	Log OLTP operations with timing (N = sample every Nth)
PDB_AGG_TELEMETRY	1	Log which aggregation strategy was chosen per query

# Enable wire trace and aggregate telemetry
PDB_WIRE_TRACE=1 PDB_AGG_TELEMETRY=1 particledb start

# Profile every 100th Redis command
PDB_REDIS_PROFILE=100 particledb start

Log Level

ParticleDB uses the RUST_LOG environment variable for log filtering:

# Default info level
RUST_LOG=info particledb start

# Debug logging for the SQL planner
RUST_LOG=info,spanner_sql::planner=debug particledb start

# Trace-level WAL logging
RUST_LOG=info,spanner_wal=trace particledb start