Configuration Reference

A consolidated reference for the server’s knobs.

Server (patinadb-raft)

Environment: PATINADB_AUTH_PASSWORD sets the auth password (preferred over a shell flag).

More server flags (RBAC, Bolt/transaction limits, telemetry, ops)

The table above covers the flags you’ll set on day one. These round out the full surface — most have safe defaults and only need touching for a specific requirement (multi-tenant RBAC, transaction-buffer bounds, dead-voter auto-repair, telemetry/licensing). Every one is also settable via PATINADB_* env var and/or the YAML config file, same precedence rules.

Also note PATINADB_MAX_CONCURRENT_RAFT_RPCS — a separate, env-var-only backpressure cap (default 1024, 0 = unlimited) on inbound peer /raft/* RPCs, distinct from --max-concurrent-requests (which governs client traffic) so a peer-RPC flood and a client-request flood can’t shed each other’s capacity.

YAML config file (--config)

Instead of (or alongside) flags, point the server at a YAML file mirroring the settings above:

# node.yaml
id: 1
addr: "127.0.0.1:21001"
db: "/var/lib/patinadb"
bootstrap: true
bolt_addr: "0.0.0.0:7687"
auth_user: "neo4j"
# auth_password: prefer the PATINADB_AUTH_PASSWORD env var over the file
query_timeout_secs: 30
max_concurrent_requests: 256

patinadb-raft --config node.yaml

Every field is optional; an absent key falls back to the CLI flag, then to the built-in default. The YAML key names match the long flag names with - replaced by _ (e.g. --bolt-addr → bolt_addr). Unknown keys are rejected so a typo fails loudly.

Precedence (highest wins): an explicitly-passed CLI flag (or its bound env var, e.g. PATINADB_AUTH_PASSWORD) > the config file > the built-in default. A flag left at its clap default does not override a value set in the file — only flags the operator actually typed do. The required settings (id, addr, db) may come from either the file or flags; if neither supplies one, startup fails with a clear error.

Config JSON Schema (--print-config-schema)

patinadb-raft --print-config-schema prints a JSON Schema (Draft 7) for the config file — every property carries its description (lifted from the Rust doc-comments) so editors can offer autocompletion and validation. It works without any other arguments:

patinadb-raft --print-config-schema > patinadb-config.schema.json

Config dry run (--check-config)

patinadb-raft --check-config is an nginx -t for patinaDB: it resolves the effective configuration exactly the way a real boot does — CLI/env > <VAR>_FILE/_COMMAND > --config file > default — prints what it understood, validates it, and exits without starting the node. Exit code 0 means valid, 1 means a setting is invalid or a runtime env knob is set to a value the engine would silently ignore. Drop it into a deploy script or CI gate:

patinadb-raft --id 1 --addr 127.0.0.1:21001 --db /var/lib/patinadb \
  --bootstrap --auth-password "$PW" --cache-limit 40% --check-config || exit 1

It prints the resolved node identity, cluster mode, security posture (flagging auth-on-without-TLS), every limit with its effective value, the resolved cache budget in bytes (so you can see the caches are actually enabled and with how much), the telemetry/licensing state, and the filesystem sandbox.

Its most valuable job is the runtime env-knob scan. Several engine knobs (PATINADB_MAX_AGG_ROWS, PATINADB_CACHE_LIMIT, …) are read lazily deep in the engine and fall back to their default if the value doesn’t parse — silently. So PATINADB_MAX_AGG_ROWS=5M looks like five million but is ignored (the runtime wants a plain integer, 5000000), and — the case that motivated this feature — a PATINADB_CACHE_LIMIT typo could silently leave the cache off. --check-config resolves each set knob with the same parser the runtime uses and fails the check on any set-but-unparseable value, naming it:

Runtime env knobs (curated — set values only)
  PATINADB_CACHE_LIMIT               512MiB → 536870912 bytes
  PATINADB_MAX_AGG_ROWS              5M ✗ expected a plain integer, got '5M'

configuration INVALID — 1 problem(s):
  ✗ PATINADB_MAX_AGG_ROWS is set to '5M' but expected a plain integer … SILENTLY IGNORED

Secrets management

The three sensitive server settings — PATINADB_AUTH_PASSWORD (root-admin credential), PATINADB_CLUSTER_SECRET (peer /raft/* shared secret), and PATINADB_LICENSE — can be sourced without ever putting the plaintext value in a -e env var or a config file. patinaDB embeds no secrets-manager SDK; two conventions integrate one while keeping its client out of the binary (the server only ever sees the resolved value at startup):

• <VAR>_FILE — names a file whose contents are the real value (mirrors POSTGRES_PASSWORD_FILE). Point it at a Docker Compose secrets: file, a Kubernetes Secret volume, or a tmpfs file a Vault Agent / AWS or GCP Secrets Store CSI-driver sidecar keeps refreshed — the DB reads the file, the sidecar owns the fetch + rotation. This is the pattern to prefer when you need auto-rotation. A trailing newline is trimmed.

• <VAR>_COMMAND — names a shell command whose stdout (trailing newline trimmed) is the value, for a direct dynamic fetch with no sidecar:

  PATINADB_AUTH_PASSWORD_COMMAND="vault kv get -field=pw secret/patinadb"
  # AWS: "aws secretsmanager get-secret-value --secret-id patinadb/pw \
  #        --query SecretString --output text"
  # GCP: "gcloud secrets versions access latest --secret=patinadb-pw"
  

  The command runs via sh -c "<cmd>" once at startup (the fetch CLI must be present + authenticated). Fail-closed: a command that can’t spawn, exits non-zero, or produces empty output aborts startup with a loud error — it never silently falls back to “no secret” (which would look like --insecure-disable-auth). The fetched value is never logged.

Precedence (most specific wins): direct flag/env > <VAR>_FILE > <VAR>_COMMAND > config file > built-in default. Both _FILE and _COMMAND are only consulted when the direct flag/env is unset. See deploy/README.md for the sidecar + command examples.

Resource limits & quotas

Guards that bound the cost of a single query so one statement can’t exhaust memory or run unbounded. The engine budgets are environment variables; the two server request limits are flags (see the patinadb-raft table above).

Write pipelining

Pipelining is what makes the optimistic concurrency model in Production Deployment the one you actually get: with it on, a write–write conflict between concurrent writers is detected and reported as the driver-retryable Neo.TransientError.Transaction.LockClientStopped rather than being avoided by serializing everyone. There are no lost updates either way — a client (or, better, a driver’s managed transaction) simply retries the transient.

The trade-off is isolation: pipelined autocommit writes run at snapshot isolation, the same level Bolt’s explicit transactions already use, so write skew is possible — two writers each reading a value and writing disjoint rows based on it leave no write–write overlap to detect. That matters only for a multi-row invariant that genuinely needs serializability; the sentinel-node pattern in Concurrency & retries turns such a case back into a detectable conflict. Turning the knob off restores serialized execution per database at a real throughput cost (measured ~4–5× on a disjoint-write workload).

Time-travel performance knobs

These change only how an AS OF read is served, never what it returns — a historical result is byte-identical whichever path runs. Both are read-path accelerations with a fallback that is always correct, so they are safe to flip either way; see Time Travel for the full picture.

Why PATINADB_INDEXED_SNAPSHOTS is opt-in. It earns its keep on repeated historical point reads: the read that triggers a build is served by the scan path, so the sidecar only helps later reads. If your backend time-travels rarely, or reads a different point each time, leave it off — you’d pay the disk without the win. Turn it on when a known set of historical points is read repeatedly. | --query-timeout-secs | server flag | 300 | Per-request wall-clock budget for a REST read; overrun → 503. 0 = off. | | --max-concurrent-requests | server flag | 512 | Max in-flight HTTP requests; excess shed with 503. 0 = unlimited. |

Set an env budget to 0 (or unset) to fall back to the built-in default. Tighten them as DoS guards on a shared node, or raise PATINADB_MAX_HOPS for a genuinely deep graph. A RETURN … LIMIT k is the normal way to bound result size — there is no implicit result cap (an unlimited query streams every row).

For observability, set PATINADB_SLOW_QUERY_MS (server env, off by default) to log a WARN for any REST query slower than that many milliseconds — carrying the query’s normalized shape (literals + $params folded to ?), not raw values. Per-shape latency stats are also served at GET /mgmt/queries.

Commercial entitlements

The server resolves a set of commercial caps (cluster HA size, combined node+edge scale, database count, history-retention window, and two feature gates) either from the hard-coded Community ceiling or from a signed license token’s entitlement claims. This is configured entirely by which license you install (--license / PATINADB_LICENSE / <db-root>/license.key — see Licensing & Telemetry), not by a server flag. See Editions & Limits for the full Community/Pro/Enterprise table, what each limit does when you hit it, and how to read a running node’s resolved tier + live usage via GET /version (also scraped onto patinadb_entitlement_usage_ratio{axis} / patinadb_entitlement_limit{axis} Prometheus gauges).

Cache memory budget

patinaDB can keep a governed, RAM-budgeted cache of decoded objects / adjacency / query results above the OS page cache. The server defaults it ON, at PATINADB_CACHE_LIMIT=40% of the resolved memory limit, when you leave the flag/env var/config key unset — so a fresh node ships with caching already engaged. Set PATINADB_CACHE_LIMIT=0 (or the equivalent flag/config key) explicitly and the cache is entirely off — only the OS page cache and the existing plan/stats caches are used, at zero residual cost.

The budget derives from a cgroup-aware total (the real ceiling the kernel OOM-kills at in a container, not the host’s RAM): cgroup v2 memory.max → v1 memory.limit_in_bytes → host MemTotal, taking min(cgroup, MemTotal). From that total, PATINADB_MEMORY_LIMIT is patinaDB’s own-heap ceiling (not including the OS page cache), and four regions are carved from it. Each knob is an absolute size (8GiB), a fraction of its parent (40%), or auto; precedence is explicit-absolute > fraction > default, and fractions compose against the resolved parent.

Every knob is also a patinadb-raft flag (--memory-limit, --cache-limit, --work-mem-limit, --mem-headroom, --cache-min-free) and a YAML config key (memory_limit, cache_limit, work_mem_limit, mem_headroom, cache_min_free), with the same explicit-flag/env > file > default precedence as every other setting.

The budget is validated at startup and fails loud (the node refuses to boot) when it over-commits — CACHE_LIMIT + WORK_MEM_LIMIT + HEADROOM ≤ MEMORY_LIMIT and MEMORY_LIMIT + CACHE_MIN_FREE ≤ TOTAL — with an error naming the offending knobs and the resolved bytes. When enabled, the fully-resolved budget (bytes per region) is logged at startup so it is never a mystery.

Example — a container with memory.max=16GiB, PATINADB_CACHE_LIMIT=40% and otherwise defaults: TOTAL=16GiB, min_free≈1.6GiB, MEMORY_LIMIT≈14.4GiB (TOTAL − min_free), then Cache ≈5.8GiB · Actions ≈6.5GiB · Headroom ≈2.2GiB. Set PATINADB_MEMORY_LIMIT=10GiB to leave more RAM to the page cache on a read-heavy deployment.

Internal defaults (informational)

These are not user-configurable flags today, but are useful to know:

On-disk layout

The --db directory contains the B-tree tables for the graph, the property/compound indexes, the engram log and snapshots, the full-text catalog and index data, and the persistent Raft log and state-machine metadata. Back up the whole directory as a unit. Each database is a subdirectory of --db.