Server configuration

Wiki / Operations

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.

EnvironmentImage defaultMeaning
GDB_BIND0.0.0.0:7687Bolt TCP/WebSocket listener
GDB_DATA/data/gdbInstance directory in the data volume; empty means volatile
GDB_INITIAL_USERgdbBootstrapped administrator
GDB_INITIAL_PASSWORDRequiredAdministrator password; at least 12 characters in release images
GDB_REQUIRE_PASSWORDtrueEnforce the release image's password requirement
GDB_INITIAL_DATABASEgalactusHome 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_DURABILITYbufferedbuffered, group or sync
GDB_SYNC_INTERVAL_MS50Positive buffered-flush period in milliseconds
GDB_READ_AFTER_DURABLEtrueGroup-mode read durability barrier
GDB_SNAPSHOT_READStrueReads 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_BYTES67108864Memory 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_THRESHOLD67108864Active log bytes before automatic maintenance; 0, off, none disable
GDB_STORAGE_ENGINEpagedEngine for new user databases: paged, hybrid or resident. Existing databases keep their own. From version 2.0.0
GDB_AUTO_UPGRADEfalseMove 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_BACKUPtrueBefore an automatic upgrade, dump the database to its backup folder. From version 2.0.0
GDB_MEMORY_LIMITHalf the container's or machine's memoryMemory budget for the server in bytes; the page cache takes half of it. From version 2.0.0
GDB_PAGE_CACHE_BYTESHalf of GDB_MEMORY_LIMITPage cache shared by Paged databases, pinned pages included. From version 2.0.0
GDB_PIN_BYTES268435456Pages 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_BYTES16777216Per-database hybrid cache budget; encoded-record accounting; 0 disables
GDB_PROPERTY_SHAPEStrueStore 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_VALUEStrueShare repeated property strings in resident/volatile mode
GDB_QUERY_THREADSautoIntra-query read workers; auto uses logical CPUs capped at 8, 1 disables
GDB_MAX_INPUT_BYTES67108864Positive incoming-message/frame byte cap
GDB_MAX_CONNECTIONS1024Connections served at once; further connections are closed on accept. 0 removes the limit
GDB_QUERY_TIMEOUT_MSunsetTime 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_CERTunsetPEM certificate chain, leaf first. Set with GDB_TLS_KEY to enable TLS on the Bolt port
GDB_TLS_KEYunsetPEM private key for the certificate
GDB_TLS_REQUIREDtrueWith a certificate configured, refuse plaintext connections. false serves both on one port
GDB_METRICS_BINDunsethost:port for the Prometheus metrics endpoint; unauthenticated, so keep it private
GDB_BOLT_MAX_VERSION5.4Newest Bolt version offered: 4.4, or 5.0 to 5.4
GDB_NEO4J_AGENTfalseReport 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_ROWS4096Smallest plain result read as it is pulled rather than held in memory; 0 holds every result whole. From version 1.2.0
GDB_CHANGE_STREAMSoffTurns on change streams, subscriptions and replica databases; each database also opts in. From version 1.4.0
GDB_REPLICATIONoffAllows 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_PASSWORDunsetThe user a replica connects to its source instance as. Read at each connection, never stored. From version 1.6.5
GDB_REPLICA_SOURCE_CA_FILEunsetPEM certificate authorities to trust for bolt+s:// sources, instead of the public ones. From version 1.6.5
GDB_REPLICATION_HOLD_MS86400000How 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_RETENTIONunsetDefault stream retention, e.g. 24h, 7d. From version 1.4.0
GDB_STREAM_MAX_BYTESunsetDefault stream size limit, e.g. 10GiB. From version 1.4.0
GDB_STREAM_SEGMENT_BYTES64MiBStream segment roll size. From version 1.4.0
GDB_STREAM_SYNC_MS1000How often buffered stream writes are synced. From version 1.4.0
GDB_STREAM_MAX_LAG_BYTES64MiBBacklog beyond which a lagging stream stops rather than grows. From version 1.4.0
GDB_LOGinfoJSON log threshold: debug, info, warn, error, critical
GDB_TRACEunsetDeprecated 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.

Commit durability and recovery · Backup, restore and transfer

Planning a deployment? Review compatibility and licence setup for your instance.