CLI Reference

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

particledb <COMMAND> [OPTIONS]

The examples on this page use the installed release binary name, particledb. If you are running directly from a local Cargo build in this repo, use target/release/spanner instead.

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	config default (/tmp/.s.PGSQL.5433)	Unix domain socket path; pass an empty string to disable
--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	occ	Transaction mode: fast, occ, serializable
--oltp-partitions	0	Number of OLTP partition workers (0 = disabled)

WAL Sync Modes

Mode	Durable when COMMIT returns?	Batching policy	Use case
sync	Yes	fsync forced at the commit site	Lowest commit latency variance
groupsync	Yes	Concurrent commits share one fsync	Production default
nosync	No	no fsync	Benchmarks, ephemeral data

sync and groupsync are both durable-on-return; they differ only in when the fsync is issued. Under concurrency groupsync amortizes one fsync across many committers, so most commits perform no disk I/O of their own.

Transaction Modes

Exactly two modes, one name each:

Mode	Isolation level	Allows
fast	None	concurrent writers overwriting each other
occ (default)	Snapshot Isolation	predicate anti-dependency cycles (G2)
serializable	Strict Serializable	nothing

If --txn-mode is omitted the server runs occ. A durability flag never changes your isolation level.

The one exception: with --wal-sync-mode sync and no --txn-mode, the server refuses to start (exit 1). That combination once implied a serializable engine, so defaulting it to occ would quietly downgrade an existing deployment. State the mode explicitly.

See Transaction Engine for the full anomaly matrix and for per-session SET TRANSACTION ISOLATION LEVEL behavior.

Removed spellings

Earlier releases accepted eighteen --txn-mode values for five isolation levels. Every removed spelling now exits non-zero and names its replacement:

Removed	Use instead	Note
occ-v3, occv3, occ-v2, occv2, zero-copy-occ, zcocc, serializable-occ	occ	Same engine — these were already aliases of one mode
strict-serializable, strict-ser	serializable	Same mode, single canonical name
serializable-ssi, ssi	serializable	Strict serializable is strictly stronger
table-2pl, 2pl, row-2pl, row_2pl	serializable	table-2pl had already stopped being two-phase locking and delivered serializable isolation instead
fast	occ	fast provided no isolation guarantee. occ is not a drop-in performance equivalent — it is a real isolation level

The per-session SET txn_mode = '…' GUC still accepts the historical names, so existing sessions keep the level they had. It is therefore broader than --txn-mode and does not match it: it accepts spellings the CLI rejects (occ-v3, serializable-ssi, table-2pl) and rejects serializable, the CLI’s own canonical name. Prefer setting the mode at startup, and use the standard SET TRANSACTION ISOLATION LEVEL spellings per session.

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 occ \
    --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

Runtime configuration is driven primarily by CLI flags and config.toml. The PDB_* variables below are diagnostic/runtime toggles that exist in the current codebase; there is not a full environment-variable mirror for every CLI flag.

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_PARTITION_PROFILE	1 or N	Log OLTP partition-worker timings (N = reporting interval in seconds)

# Enable wire trace
PDB_WIRE_TRACE=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