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	occ	fast, occ, serializable
--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

WAL sync modes

Mode	Durable when COMMIT returns?	Batching policy
sync	Yes	fsync forced at the commit site
groupsync (default)	Yes	Concurrent commits share one fsync
nosync	No	no fsync

Transaction mode defaults

--txn-mode sets the server-wide default transaction mode. There are three supported modes:

Mode	Isolation level
fast	No isolation guarantee — writes apply in place, concurrent writers overwrite each other silently. Bulk load / single-writer ingest only.
occ (default)	Snapshot Isolation — commit-time read-set validation also catches item write skew; allows predicate anti-dependency cycles (G2)
serializable	Strict Serializable — allows nothing

These are the only three accepted values. The earlier spellings — occ-v3, zero-copy-occ, serializable-ssi, ssi, strict-serializable, table-2pl, and 2pl — have been removed, not deprecated: the server refuses to start and names the replacement. See CLI Reference for the full mapping, and Transaction Engine for the engine detail.

If --txn-mode is omitted the mode is occ, whatever the WAL sync mode. A durability flag does not change your isolation level.

The one exception is --wal-sync-mode sync with --txn-mode omitted. That combination used to select a serializable engine through an inference that no longer exists, so defaulting it to occ would quietly weaken an existing deployment to snapshot isolation. The server refuses to start and asks you to state the isolation level.

Individual sessions can override the default with SET TRANSACTION ISOLATION LEVEL; see Transaction Engine.

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