Server configuration
On this page
The server resolves built-in defaults, then environment variables, then flags. Every supplied recognized setting is validated even when a flag overrides it. Invalid settings, missing values and unknown flags fail startup. Error messages name the setting without echoing its supplied value.
Settings
Set these values in the database service's environment block. The defaults
below apply to the server image; the Compose example
explicitly chooses group durability and the Developer edition.
| Environment | Image default | Meaning |
|---|---|---|
GDB_BIND | 0.0.0.0:7687 | Bolt TCP/WebSocket listener |
GDB_DATA | /data/gdb | Instance directory in the data volume; empty means volatile |
GDB_INITIAL_USER | gdb | Bootstrapped administrator |
GDB_INITIAL_PASSWORD | Required | Administrator password; at least 12 characters in release images |
GDB_REQUIRE_PASSWORD | true | Enforce the release image's password requirement |
GDB_INITIAL_DATABASE | neo4j | Home database, created if absent; customer Compose sets galactus. Native drivers use this configured default when their database setting is empty. |
GDB_DURABILITY | buffered | buffered, group or sync |
GDB_SYNC_INTERVAL_MS | 50 | Positive buffered-flush period in milliseconds |
GDB_READ_AFTER_DURABLE | true | Group-mode read durability barrier |
GDB_CHECKPOINT_THRESHOLD | 67108864 | Active log bytes before automatic maintenance; 0, off, none disable |
GDB_PROPERTY_CACHE_BYTES | 16777216 | Per-database hybrid cache budget; encoded-record accounting; 0 disables |
GDB_INTERN_VALUES | true | Share repeated property strings in resident/volatile mode |
GDB_QUERY_THREADS | auto | Intra-query read workers; auto uses logical CPUs capped at 8, 1 disables |
GDB_MAX_INPUT_BYTES | 67108864 | Positive incoming-message/frame byte cap |
GDB_LOG | info | JSON log threshold: debug, info, warn, error, critical |
GDB_TRACE | unset | Deprecated debug-logging alias |
The image healthcheck probes the Bolt listener; it does not validate login or query success. Recreate containers after changing their environment. Changing the home name creates/selects that database; it does not rename existing directories. The administrator is bootstrapped only when initializing the security catalog. Changing startup credentials does not reset persisted users. See existing installations. The system database always remains resident, with synchronous security commits independent of user-database durability settings.
For edition selection, licence files and instance binding, see licensing.
Input limits
The default 64 MiB limit applies to each de-chunked Bolt message, including parameters, and each WebSocket frame payload. A Bolt message spread across several WebSocket frames is still bounded as a whole. Oversized input closes the connection before allocating the oversized body. PackStream rejects impossible collection counts and nesting beyond 64 value levels.
This does not cap query memory or outgoing results. Large restores must fit this limit as well as the Explorer upload cap. Prefer batched imports and chunked backup downloads for large data.
Durability and concurrency settings
Buffered mode acknowledges the OS-cache append; a power/kernel failure can lose acknowledged changes since the last sync. Group and sync modes wait for a covering sync before acknowledgement. Checksums detect invalid bytes; they do not make storage immune to corruption. See recovery rules.
GDB_READ_AFTER_DURABLE makes group-mode readers wait for the pending sync barrier.
It does not guarantee the writing client receives its network response first.
GDB_QUERY_THREADS controls read-query workers; GDS FastRP/PageRank parallelism
uses a separate, opt-in concurrency setting.
Related articles
Commit durability and recovery · Backup, restore and transfer