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. A fresh instance runs Community with no
licence configuration.
| 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 | galactus | Home database, created if absent. A data directory created before 1.3.0 keeps its existing neo4j database when this is unset. 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_SNAPSHOT_READS | true | Reads and read transactions read the last committed state instead of waiting for open write transactions (snapshot reads). From version 1.6.1 |
GDB_SNAPSHOT_MAX_BYTES | 67108864 | Memory old values may hold per database for open read transactions; past it the oldest fail with a transient SnapshotTooOld and are retried. 0 removes the cap. From version 1.6.1 |
GDB_CHECKPOINT_THRESHOLD | 67108864 | Active log bytes before automatic maintenance; 0, off, none disable |
GDB_STORAGE_ENGINE | paged | Engine for new user databases: paged, hybrid or resident. Existing databases keep their own. From version 2.0.0 |
GDB_AUTO_UPGRADE | false | Move each user database still on a 1.x engine to Paged as it opens, after a dump of it; see upgrading to 2.0. From version 2.0.0 |
GDB_AUTO_UPGRADE_BACKUP | true | Before an automatic upgrade, dump the database to its backup folder. From version 2.0.0 |
GDB_MEMORY_LIMIT | Half the container's or machine's memory | Memory budget for the server in bytes; the page cache takes half of it. From version 2.0.0 |
GDB_PAGE_CACHE_BYTES | Half of GDB_MEMORY_LIMIT | Page cache shared by Paged databases, pinned pages included. From version 2.0.0 |
GDB_PIN_BYTES | 268435456 | Pages each Paged database keeps pinned, within the page cache: topology, label lookups and the upper levels of indexes first, then, from version 2.4.3, the property stores that fit. From version 2.0.0 |
GDB_PROPERTY_CACHE_BYTES | 16777216 | Per-database hybrid cache budget; encoded-record accounting; 0 disables |
GDB_PROPERTY_SHAPES | true | Store each distinct set of property keys once and share it between the elements that have it; false uses the flat layout. In memory only, so it can change at any restart; data files and replicas are unaffected. From version 1.5.5 |
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_MAX_CONNECTIONS | 1024 | Connections served at once; further connections are closed on accept. 0 removes the limit |
GDB_QUERY_TIMEOUT_MS | unset | Time limit for a statement, or for a transaction from its BEGIN; 0, off, none disable. A driver's shorter tx_timeout wins. See time limits |
GDB_TLS_CERT | unset | PEM certificate chain, leaf first. Set with GDB_TLS_KEY to enable TLS on the Bolt port |
GDB_TLS_KEY | unset | PEM private key for the certificate |
GDB_TLS_REQUIRED | true | With a certificate configured, refuse plaintext connections. false serves both on one port |
GDB_METRICS_BIND | unset | host:port for the Prometheus metrics endpoint; unauthenticated, so keep it private |
GDB_BOLT_MAX_VERSION | 5.4 | Newest Bolt version offered: 4.4, or 5.0 to 5.4 |
GDB_NEO4J_AGENT | false | Report the agent as Neo4j/4.4.0-GDB-<version> for drivers that refuse other agents, and send Neo4j's spelling (Neo.*) of the error codes the Neo4j drivers turn into specific exceptions. From 2.1.7 |
GDB_STREAM_MIN_ROWS | 4096 | Smallest plain result read as it is pulled rather than held in memory; 0 holds every result whole. From version 1.2.0 |
GDB_CHANGE_STREAMS | off | Turns on change streams, subscriptions and replica databases; each database also opts in. From version 1.4.0 |
GDB_REPLICATION | off | Allows replicas on another instance: following a source on another server, and being one. Both instances need it. From version 1.6.5 |
GDB_REPLICA_SOURCE_USER, GDB_REPLICA_SOURCE_PASSWORD | unset | The user a replica connects to its source instance as. Read at each connection, never stored. From version 1.6.5 |
GDB_REPLICA_SOURCE_CA_FILE | unset | PEM certificate authorities to trust for bolt+s:// sources, instead of the public ones. From version 1.6.5 |
GDB_REPLICATION_HOLD_MS | 86400000 | How long a source keeps its change stream for a replica on another instance that has stopped reading (24 hours). From version 1.6.5 |
GDB_STREAM_RETENTION | unset | Default stream retention, e.g. 24h, 7d. From version 1.4.0 |
GDB_STREAM_MAX_BYTES | unset | Default stream size limit, e.g. 10GiB. From version 1.4.0 |
GDB_STREAM_SEGMENT_BYTES | 64MiB | Stream segment roll size. From version 1.4.0 |
GDB_STREAM_SYNC_MS | 1000 | How often buffered stream writes are synced. From version 1.4.0 |
GDB_STREAM_MAX_LAG_BYTES | 64MiB | Backlog beyond which a lagging stream stops rather than grows. From version 1.4.0 |
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. A connection must authenticate within 30 seconds. These settings apply from version 1.1.0. 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.
For a server with several clients whose acknowledged writes must survive a power
cut, GDB_DURABILITY=group is the recommended mode; see
choosing a mode.
GDB_READ_AFTER_DURABLE makes a group-mode reader that saw a commit still being
synced wait for that sync before replying (after releasing its locks).
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