Configuration

CLI Flags

particledb start [OPTIONS]

These examples use the installed release binary name, particledb. If you are running directly from a local Cargo build in this repo, the executable is target/release/spanner.

Flag	Default	Description
--config	config.toml	Path to configuration file
--data-dir	./data	Data directory
--pg-addr	0.0.0.0:5432	PostgreSQL wire listener
--pg-unix-socket	config default (/tmp/.s.PGSQL.5433)	Unix socket path; pass an empty string to disable
--http-addr	0.0.0.0:8080	HTTP/status/API listener
--grpc-addr	0.0.0.0:26257	gRPC listener
--metrics-port	9090	Prometheus metrics port
--health-port	8080	Health-check port
--max-connections	100	Max PG + Redis connections
--connection-timeout	300	Idle timeout in seconds (0 disables)
--auth-method	trust	trust, password, or md5
--pg-password	(none)	PG/role password bootstrap
--tls-cert	(none)	TLS certificate file
--tls-key	(none)	TLS private key file
--wal-sync-mode	groupsync	sync, groupsync, nosync
--txn-mode	(inferred)	fast, occ, row-2pl, table-2pl
--oltp-partitions	0	OLTP partition workers
--snapshot-enabled	false	Enable periodic snapshots
--snapshot-interval	3600	Snapshot interval (seconds)
--snapshot-max	10	Max retained snapshots
--snapshot-retention-days	(none)	Age-based pruning
--snapshot-dir	./snapshots	Snapshot directory
--audit-log	false	Enable __pdb_audit_log
--audit-log-selects	false	Also log SELECT statements

Transaction mode defaults

If --txn-mode is omitted:

• --wal-sync-mode sync defaults to occ
• --wal-sync-mode groupsync or nosync defaults to fast

Config File

[network]
pg_addr = "0.0.0.0:5432"
pg_unix_path = "/tmp/.s.PGSQL.5433"
http_addr = "0.0.0.0:8080"
grpc_addr = "0.0.0.0:26257"
redis_port = 6379
metrics_port = 9090
health_port = 8080
max_connections = 100
tls_cert_path = "/path/to/cert.pem"
tls_key_path = "/path/to/key.pem"

[security]
auth_method = "trust"
audit_logging = false

[wal]
sync_mode = "groupsync"

There is not a broad PDB_* configuration mirror for the network flags today. The stable configuration surfaces are:

• CLI flags such as --pg-addr, --http-addr, and --grpc-addr
• config.toml
• diagnostic environment variables documented below

Diagnostic / Profiling Variables

Variable	Values	Description
PDB_WIRE_TRACE	1	Log PG wire message flow with timing
PDB_WIRE_DUMP	1	Dump raw PG wire frames
PDB_REDIS_PROFILE	1 or N	Profile Redis commands; N = sample every Nth
PDB_OLTP_PROFILE	1 or N	Profile OLTP operations
PDB_PARTITION_PROFILE	1 or N	Profile OLTP partition workers when partition mode is enabled

PDB_WIRE_TRACE=1 particledb start
PDB_REDIS_PROFILE=100 particledb start