# Server configuration

[Wiki](../README.md) / [Operations](README.md)

**On this page**

- [Settings](#settings)
- [Input limits](#input-limits)
- [Durability and concurrency settings](#durability-and-concurrency-settings)

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](docker.md#container-defaults)
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](transactions.md#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](upgrade-2.0.md). 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](transactions.md#time-limits) |
| `GDB_TLS_CERT` | unset | PEM certificate chain, leaf first. Set with `GDB_TLS_KEY` to enable [TLS](authentication.md#encrypted-connections) 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](monitoring.md); 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](transactions.md#reading-large-results) rather than held in memory; `0` holds every result whole. From version 1.2.0 |
| `GDB_CHANGE_STREAMS` | `off` | Turns on [change streams](streams.md), [subscriptions](subscriptions.md) and [replica databases](replicas.md); each database also opts in. From version 1.4.0 |
| `GDB_REPLICATION` | `off` | Allows [replicas on another instance](replicas.md#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](authentication.md#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](licensing.md).

## 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](../explorer/databases.md).
Prefer [batched imports](../imports/bolt-batches.md) and
[chunked backup downloads](backups.md#backup--durability-maintenance) 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](durability.md#segment-and-record-integrity).
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](durability.md#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](../gds/resources.md#parallel-execution-and-result-memory).

## Related articles

[Commit durability and recovery](durability.md) · [Backup, restore and transfer](backups.md)
