Configuration

CLI Flags

particledb start [FLAGS]

Flag	Default	Description
--config	config.toml	Path to configuration file
--data-dir	./data	Data storage directory
--pg-addr	0.0.0.0:5432	PostgreSQL wire protocol listen address
--pg-unix-socket	—	Unix socket path (e.g., /tmp/.s.PGSQL.5432)
--http-addr	0.0.0.0:8080	HTTP server (dashboard, health, REST)
--grpc-addr	0.0.0.0:26257	gRPC listen address
--metrics-port	9090	Prometheus metrics port
--health-port	8080	Health check port
--max-connections	100	Maximum concurrent connections
--connection-timeout	300	Idle connection timeout (seconds)
--auth-method	trust	Authentication: trust, password, md5
--pg-password	—	Password for PG authentication
--tls-cert	—	TLS certificate file (PEM)
--tls-key	—	TLS private key file (PEM)
--wal-sync-mode	groupsync	WAL durability: sync, groupsync, nosync
--snapshot-enabled	false	Enable automated snapshots
--snapshot-interval	3600	Snapshot interval (seconds)
--audit-log	false	Enable audit logging
--txn-mode	table-2pl	Transaction isolation: fast, row-2pl, table-2pl
--oltp-partitions	0	Partition workers by PK hash (0 = disabled)

WAL Sync Modes

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

Config File

All CLI flags can be set in config.toml:

[network]
pg_addr = "0.0.0.0:5432"
pg_unix_path = "/tmp/.s.PGSQL.5432"
http_addr = "0.0.0.0:8080"
grpc_addr = "0.0.0.0:26257"
redis_port = 6379
max_connections = 100

[security]
auth_method = "trust"
tls_cert_path = "/path/to/cert.pem"
tls_key_path = "/path/to/key.pem"

[storage]
memtable_size = 67108864      # 64 MB
block_cache_size = 536870912  # 512 MB
bloom_bits_per_key = 10

[wal]
sync_mode = "groupsync"

Environment Variables

Every config option can be set via 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 and Profiling Variables

These environment variables enable runtime diagnostics and profiling. They are read at server start (or, where noted, per-connection).

Variable	Values	Description
PDB_WIRE_TRACE	1	Per-query protocol sequence logging — logs every PG wire message (Parse, Bind, Execute, Sync) with timing
PDB_WIRE_DUMP	1	Byte-level message framing diagnostic — dumps raw wire bytes for protocol debugging
PDB_REDIS_PROFILE	1 or N	Redis command profiling — logs every Redis command with execution time. Set to N to sample every Nth command
PDB_OLTP_PROFILE	1 or N	OLTP operation profiling — logs each OLTP operation (SELECT, INSERT, UPDATE, DELETE) with timing. Set to N for sampling
PDB_AGG_TELEMETRY	1	Aggregate dispatch path logging — logs which aggregation strategy (zone stats, dense array, hash, SIMD masks) was chosen for each query

# Example: 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