Settings

ArcadeDB allows changing settings at JVM (server or embedded) and per database level.

Server/Embedded (JVM) Level Database Level

Those settings are valid for all the databases open in the same Server or JVM when run embedded. If defined, they override the default value (look at the table below to see the default values). They are used only if a database does not override them. Such settings are not saved, so you need to set them everytime.

Database level settings are stored in the database and override the Server/Embedded (JVM) settings if present. You can change these settings via SQL or API when run embedded.

JVM startup (server/embedded only)

All the settings modified at JVM startup are not persistent and need to be set everytime you’re running ArcadeDB server or your embedded application. If you’re updating a setting at JVM level, prefix the setting name with arcadedb. by using this syntax:

$ java ... -Darcadedb.<name>=<value> ...

Where <name> is the name of the setting and <value> the value you want to override. Example to change the server mode from development (default) to production:

$ java ... -Darcadedb.server.mode=production ...

Example to increase the default page size for buckets to 1 MB:

$ java ... -Darcadedb.bucketDefaultPageSize=1048576 ...

Alternatively, these settings can be set via the environment variable JAVA_OPTS:

JAVA_OPTS="-Darcadedb.server.rootPassword=playwithdata" java ...

SQL (Database Level)

All the changes executed via SQL Alter Database command are relative to the current database only and are persistent. Here is an example to increase the default page size for buckets to 1 MB:

ALTER DATABASE `arcadedb.bucketDefaultPageSize` 1048576

The current settings can be listed from SQL using:

SELECT expand(settings) FROM schema:database

Programmatically (Server/Embedded and Database levels)

You can access to the database configuration with database.getConfiguration() to read and write per database settings. Example to increase the default page size for all the buckets to 1 MB on the current database:

database.getConfiguration().setValue(GlobalConfiguration.BUCKET_DEFAULT_PAGE_SIZE, 1048576);

To change a setting at Server/Embedded (JVM) level, set the value in the GlobalConfiguration enum. Example to increase the default page size for buckets to 1 MB for all the databases open in the current JVM (server/embedded):

GlobalConfiguration.BUCKET_DEFAULT_PAGE_SIZE.setValue(1048576);

Available settings by scope (in alphabetic order):

The tables that follow contains all the available settings in ArcadeDB separated by scope:

  • JVM, as the settings applied at the JVM level, so to both clients and servers

  • SERVER, as the settings that only apply to the ArcadeDB Server. If you’re embedding a server in your Java application you can use these settings

  • DATABASE are all the settings that can be saved in the database configuration and are restored once the database is open

JVM

Name Description Type Default Value

dumpConfigAtStartup

Dumps the configuration at startup

Boolean

false

dumpMetricsEvery

Dumps the metrics at startup, shutdown and every configurable amount of time (in seconds)

Long

0

profile

Specify the preferred profile among: default, high-performance, low-ram, low-cpu

String

default

test

Tells if it is running in test mode. This enables the calling of callbacks for testing purpose

Boolean

false

Available Plugins

The following plugins are available for ArcadeDB Server:

  • MongoDB (com.arcadedb.mongo.MongoDBProtocolPlugin) - Implements the MongoDB wire protocol

  • Postgres (com.arcadedb.postgres.PostgresProtocolPlugin) - Implements the Postgres wire protocol

  • Redis (com.arcadedb.redis.RedisProtocolPlugin) - Implements the Redis wire protocol

  • Http (com.arcadedb.server.http.HttpServerPlugin) - Implements the HTTP/REST API

SERVER

Name Description Type Default Value

backup.enabled

State of backup lock. Disable for increased performance of massive insertions.

Boolean

True

ha.appendBufferSize

AppendEntries batch byte limit for replication (e.g. '4MB'). Since v26.4.1

String

4MB

ha.clientElectionRetryCount

Number of retries performed by RemoteDatabase after receiving HTTP 503 NeedRetryException during an election. Since v26.4.1

Integer

3

ha.clientElectionRetryDelayMs

Delay in ms between RemoteDatabase election retries. Since v26.4.1

Long

2000

ha.clusterName

Cluster name. Useful in case of multiple clusters in the same network

String

arcadedb

ha.clusterToken

Shared secret for inter-node authentication. If empty, auto-generated at first startup and persisted under raft-storage/. Since v26.4.1

String

ha.electionTimeoutMin

Minimum Raft election timeout in ms. Increase for high-latency WAN clusters. Since v26.4.1

Integer

2000

ha.electionTimeoutMax

Maximum Raft election timeout in ms. Increase for high-latency WAN clusters. Since v26.4.1

Integer

5000

ha.enabled

True if HA is enabled for the current server

Boolean

false

ha.errorRetries

Number of automatic retries in case of IO errors with a specific server. 0 (default) is to retry against all the configured servers

Integer

0

ha.grpcAllowlistRefreshMs

Rate-limiting interval in ms for DNS re-resolution in the gRPC peer address allowlist filter. Since v26.4.1

Long

30000

ha.grpcFlowControlWindow

gRPC flow control window size in bytes for Raft AppendEntries traffic. Larger values help catch-up replication after partitions. Since v26.4.1

Long

4194304

ha.groupCommitBatchSize

Maximum number of Raft log entries to batch in a single group commit flush. Higher values improve throughput under concurrent load. Since v26.4.1

Integer

500

ha.groupCommitOfferTimeout

Timeout in ms waiting for space in the group-commit queue before throwing ReplicationQueueFullException. Since v26.4.1

Integer

100

ha.groupCommitQueueSize

Maximum pending transactions allowed in the Raft group-commit queue. When full, the server sheds load by throwing ReplicationQueueFullException (NeedRetryException). Since v26.4.1

Integer

10000

ha.healthCheckInterval

Interval in ms for the Raft health monitor to check for CLOSED/EXCEPTION state and auto-recover. 0 disables. Since v26.4.1

Long

3000

ha.idempotencyCacheMaxEntries

Maximum number of entries in the HTTP idempotency cache. Since v26.4.1

Integer

10000

ha.idempotencyCacheTtlMs

Time-to-live in ms for entries in the HTTP idempotency cache. Since v26.4.1

Long

60000

ha.k8s

The server is running inside Kubernetes (enables auto-join on scale-up)

Boolean

false

ha.k8sSuffix

When running inside Kubernetes use this suffix to reach the other servers. Example: arcadedb.default.svc.cluster.local

String

ha.logPurgeGap

Number of Raft log entries retained after a snapshot as a buffer for slightly lagging followers. Lower values free disk faster but raise the chance a slow follower needs a full snapshot resync. Since v26.4.1

Integer

1024

ha.logPurgeUptoSnapshot

When true, deletes old Raft log segments after each snapshot to bound disk growth. Set to false to retain full log history for debugging/auditing. Since v26.4.1

Boolean

true

ha.logSegmentSize

Maximum Raft log segment size (e.g. '64MB', '128MB'). Since v26.4.1

String

64MB

ha.logVerbose

Verbose HA logging: 0=off, 1=basic (elections), 2=detailed (replication), 3=trace (every state machine apply). Since v26.4.1

Integer

0

ha.peerAllowlist.enabled

Reject inbound Raft gRPC connections whose remote address does not resolve to a host in ha.serverList. Loopback is always allowed. Not a substitute for mTLS on untrusted networks. Since v26.4.1

Boolean

true

ha.proxyConnectTimeout

Connect timeout in ms for the leader proxy (replica-to-leader forwarding). Since v26.4.1

Long

5000

ha.proxyMaxBodySize

Maximum request body size in bytes the leader proxy will buffer and forward. Since v26.4.1

Integer

16777216

ha.proxyReadTimeout

Read timeout in ms for the leader proxy. Covers long-running queries forwarded from a replica. Since v26.4.1

Long

30000

ha.quorum

Write quorum: majority or all. Legacy values none, one, two, three removed in v26.4.1

String

majority

ha.quorumTimeout

Timeout in ms waiting for the quorum acknowledgment

Long

10000

ha.raftPort

TCP/IP port for Raft gRPC communication. Used as the default when HA_SERVER_LIST entries do not specify an explicit port. Since v26.4.1

Integer

2434

ha.raftPersistStorage

If true, the Raft storage directory is preserved across restarts, enabling node rejoin without a full snapshot resync. Since v26.4.1

Boolean

false

ha.ratisRestartMaxRetries

Maximum consecutive Ratis restart attempts by the health monitor before the server shuts down for cluster-level recovery. Since v26.4.1

Integer

10

ha.readConsistency

Default read consistency for replica reads: eventual, read_your_writes, linearizable. Since v26.4.1

String

read_your_writes

ha.replicationChunkMaxSize

Maximum channel chunk size for replicating messages between servers

Integer

16777216

ha.replicationLagWarning

Raft log index gap threshold for replication lag warnings. 0 to disable. Since v26.4.1

Long

1000

ha.serverList

Servers in the cluster as a list of <[name@]host:raftPort:httpPort[:priority]> items separated by comma. The httpPort is required for replica-to-leader HTTP forwarding. The optional name@ prefix (since v26.5.1) gives the peer a human-readable name used in logs and Studio. The optional priority (default 0) prefers higher-valued nodes during elections. Example: frankfurt@localhost:2434:2480:10,[email protected]:2434:2480:0

String

ha.serverRole

Node role in the cluster: any (default, eligible for leader election) or replica (never elected leader; Raft priority set to 0). Useful for witness/read-scale nodes. Since v26.4.1

String

any

ha.snapshotDownloadTimeout

Read timeout in ms for downloading a database snapshot from the leader during follower resync. Since v26.4.1

Integer

300000

ha.snapshotGapTolerance

Maximum acceptable gap between the snapshot index and persisted applied index before triggering a snapshot download. Since v26.4.1

Long

10

ha.snapshotInstallRetries

Maximum retry attempts for snapshot download from the leader during snapshot installation. Since v26.4.1

Integer

3

ha.snapshotInstallRetryBaseMs

Base delay in ms for exponential backoff between snapshot download retries. Actual delay is baseMs * 2^attempt. Since v26.4.1

Long

5000

ha.snapshotMaxConcurrent

Maximum number of concurrent snapshot downloads served by the leader. Requests over this limit receive HTTP 503. Since v26.4.1

Integer

2

ha.snapshotMaxEntrySize

Maximum uncompressed size in bytes for a single entry in a snapshot ZIP. Decompression-bomb guard. Since v26.4.1

Long

10737418240

ha.snapshotThreshold

Number of Raft log entries after which the leader automatically takes a snapshot. Since v26.4.1

Long

100000

ha.snapshotWatchdogTimeout

Delay in ms before the snapshot-gap watchdog triggers a download. Floored at 4x ha.electionTimeoutMax. Since v26.4.1

Long

30000

ha.snapshotWriteTimeout

Timeout in ms for writing a snapshot to a follower. If the transfer stalls beyond this duration, the connection is force-closed. Since v26.4.1

Long

300000

ha.stopServerOnReplicationFailure

After a phase-2 replication failure, step-down is attempted first. If every step-down fails and this flag is true, the JVM exits so an orchestrator can restart. Default is false: the server keeps running and logs CRITICAL. Since v26.4.1

Boolean

false

ha.writeBufferSize

Raft log write buffer size (e.g. '8MB'). Must be at least ha.appendBufferSize + 8 bytes; otherwise the server fails to start with ConfigurationException. Since v26.4.1

String

8MB

network.sameServerErrorRetry

Number of automatic retries in case of IO errors with a specific server. If replica servers are configured, look also at HA_ERROR_RETRY setting. 0 (default) = no retry

Integer

0

network.socketTimeout

TCP/IP Socket timeout (in ms)

Integer

30000

ssl.keyStore

Path where the SSL certificates are stored

String

null

ssl.keyStorePass

Password to open the SSL key store

String

null

ssl.trustStore

Path to the SSL trust store

String

null

ssl.trustStorePass

Password to open the SSL trust store

String

null

ssl.enabled

Use SSL for client connections

Boolean

false

postgres.debug

Enables the printing of Postgres protocol to the console. Default is false

Boolean

false

postgres.host

TCP/IP host name used for incoming connections for Postgres plugin. Default is '0.0.0.0'

String

0.0.0.0

postgres.port

TCP/IP port number used for incoming connections for Postgres plugin. Default is 5432

Integer

5432

redis.defaultDatabase

Default database name for Redis protocol connections. If set, RAM commands (SET, GET, etc.) will use this database’s globalVariables. Empty means no default (requires SELECT command or key prefix)

String

redis.host

TCP/IP host name used for incoming connections for Redis plugin. Default is '0.0.0.0'

String

0.0.0.0

redis.port

TCP/IP port number used for incoming connections for Redis plugin. Default is 6379

Integer

6379

mongo.host

TCP/IP host name used for incoming connections for Mongo plugin. Default is '0.0.0.0'

String

0.0.0.0

mongo.port

TCP/IP port number used for incoming connections for Mongo plugin. Default is 27017

Integer

27017

server.databaseLoadAtStartup

Open all the available databases at server startup

Boolean

true

server.databaseDirectory

Directory containing the database

String

${arcadedb.server.rootPath}/databases

server.backupDirectory

Directory containing the backups

String

${arcadedb.server.rootPath}/backups

server.defaultDatabases

The default databases created when the server starts. The format is (<database-name>[(<user-name>:<user-passwd>[:<user-group>])])[{import|restore:<URL>}][;]'. Pay attention on using `; to separate databases and , to separate credentials. The supported actions are import and restore. Example: Universe[albert:einstein:admin];Amiga[Jay:Miner,Jack:Tramiel]{import:/tmp/movies.tgz}

String

server.defaultDatabaseMode

The default mode to load pre-existing databases. The value must match a com.arcadedb.engine.PaginatedFile.MODE enum value: {READ_ONLY, READ_WRITE}Databases which are newly created will always be opened READ_WRITE.

String

READ_WRITE

server.httpIncomingHost

TCP/IP host name used for incoming HTTP connections

String

0.0.0.0

server.httpIncomingPort

TCP/IP port number used for incoming HTTP connections. Specify a single port or a range <from>-<to>. Default is 2480-2489 to accept a range of ports in case they are occupied.

String

2480-2489

server.httpsIncomingPort

TCP/IP port number used for incoming HTTPS connections. Specify a single port or a range <from>-<to>. Default is 2490-2499 to accept a range of ports in case they are occupied.

String

2490-2499

server.httpsIoThreads

Number of threads to use in the HTTP server

Integer

2 per core

server.httpTxExpireTimeout

Timeout in seconds for a HTTP transaction to expire. This timeout is computed from the latest command against the transaction

Long

30

server.httpBodyContentMaxSize

Maximum size in bytes for HTTP request body content. Set to -1 for unlimited size. Default is 100MB

Integer

100

server.httpAuthSessionExpireTimeout

Timeout in seconds for a HTTP authentication session to expire. This timeout is computed from the latest request using the auth token. See Token-Based Authentication. (Available since v26.2.1)

Long

1800

server.mode

Server mode between 'development', 'test' and 'production'

String

development

server.name

Server name

String

ArcadeDB_0

server.plugins

Server plugins to load, see available plugins. Format as comma separated list of: <pluginName>:<pluginFullClass>.

String

server.rootPassword

Password for root user to use at first startup of the server. Set this to avoid asking the password to the user

String

null

server.rootPasswordPath

Path to file with password for root user to use at first startup of the server. Set this to avoid asking the password to the user

String

null

server.rootPath

Root path in the file system where the server is looking for files. By default is the current directory

String

null

server.securityAlgorithm

Default encryption algorithm used for passwords hashing

String

PBKDF2WithHmacSHA256

server.reloadEvery

Time in milliseconds of checking if the server security files have been modified to be reloaded

Integer

5000

server.securitySaltCacheSize

Cache size of hashed salt passwords. The cache works as LRU. Use 0 to disable the cache

Integer

64

server.saltIterations

Number of iterations to generate the salt or user password. Changing this setting does not affect stored passwords

Integer

65536

server.eventBusQueueSize

Size of the queue used as a buffer for unserviced database change events.

Integer

1000

serverMetrics

True to enable metrics

Boolean

true

serverMetrics.logging

True to enable metrics logging

Boolean

true

DATABASE

Name Description Type Default Value

asyncOperationsQueueImpl

Queue implementation to use between 'standard' and 'fast'. 'standard' consumes less CPU than the 'fast' implementation, but it could be slower with high loads

String

standard

asyncOperationsQueueSize

Size of the total asynchronous operation queues (it is divided by the number of parallel threads in the pool)

Integer

1024

asyncBackPressure

When the asynchronous queue is full at a certain percentage, back pressure is applied

Integer

0

asyncTxBatchSize

Maximum number of operations to commit in batch by async thread

Integer

10240

asyncWorkerThreads

Number of asynchronous worker threads. By default it is cores minus 1, but at least 1

Integer

(machine dependent)

bucketDefaultPageSize

Default page size in bytes for buckets. Default is 65536

Integer

65536

bucketReuseSpaceMode

Mode used to reuse space in pages. Use 'low' to have faster updates consuming more space on disk, medium for balance. Default is 'high'

String

high

bucketWipeOutOnDelete

Wipe out record content on delete. If enabled, assures deleted records cannot be analyzed by parsing the raw files and backups will be more compressed, but it also makes deletes a little bit slower

Boolean

true

command.timeout

Default timeout for commands (in ms)

Long

0

command.warningsEvery

Reduce warnings in commands to print in console only every X occurrences. Use 0 to disable warnings with commands

Integer

100

commitLockTimeout

Timeout in ms to lock resources during commit

Long

5000

cypher.statementCache

Max number of entries in the cypher statement cache. Use 0 to disable. Caching statements speeds up execution of the same cypher queries

Integer

1000

opencypher.loadCsv.allowFileUrls

Allow LOAD CSV to access local files via file:/// URLs and bare file paths. Disable for security in multi-tenant server deployments. In production server mode, this is automatically set to false if not explicitly configured. See how-to/operations/server.adoc#production-mode-defaults

Boolean

true

opencypher.loadCsv.importDirectory

Root directory for LOAD CSV file:/// URLs. When set, file paths are resolved relative to this directory and path traversal (../) is blocked. Empty string means no restriction

String

(empty)

dateFormat

Default date format using Java SimpleDateFormat syntax

String

yyyy-MM-dd

dateImplementation

Default date implementation to use on deserialization. By default java.util.Date is used, but the following are supported: java.util.Calendar, java.time.LocalDate

Class

class java.util.Date

dateTimeFormat

Default date time format using Java SimpleDateFormat syntax

String

yyyy-MM-dd HH:mm:ss

dateTimeImplementation

Default datetime implementation to use on deserialization. By default java.util.Date is used, but the following are supported: java.util.Calendar, java.time.LocalDateTime, java.time.ZonedDateTime

Class

class java.util.Date

flushOnlyAtClose

Never flushes pages on disk until the database closing

Boolean

false

freePageRAM

Percentage (0-100) of memory to free when Page RAM is full

Integer

50

gremlin.engine

Gremlin engine to use. By default the auto setting uses the legacy groovy engine in case parameters are set, otherwise, the new native java is preferred. If you have compatibility issues with gremlin statements that use lambdas or in general, switch to the groovy one

String

auto

gremlin.timeout

Default timeout for gremlin commands (in ms)

Long

8000

indexCompactionMinPagesSchedule

Minimum number of mutable pages for an index to be schedule for automatic compaction. 0 = disabled

Integer

10

indexCompactionRAM

Maximum amount of RAM to use for index compaction, in MB

Long

300

initialPageCacheSize

Initial number of entries for page cache

Integer

65535

vectorIndex.graphBuildCacheSize

Maximum number of vectors to cache in memory during HNSW graph building. Higher values speed up construction but use more RAM. RAM usage = cacheSize × (dimensions × 4 + 64) bytes

Integer

10000

vectorIndex.locationCacheSize

Maximum number of vector locations to cache in memory per vector index. Set to -1 for unlimited. Each entry uses ~56 bytes. Recommended: 100000 for datasets with 1M+ vectors

Integer

-1

vectorIndex.mutationsBeforeRebuild

Number of mutations (inserts/updates/deletes) before rebuilding the HNSW graph index. Higher values reduce rebuild cost but may return slightly stale results. Recommended: 50-200 for read-heavy, 200-500 for write-heavy workloads

Integer

100

vectorIndex.inactivityRebuildTimeoutMs

Inactivity timeout in milliseconds before flushing buffered vectors and rebuilding the HNSW graph. When mutations exist but haven’t reached the rebuild threshold, a timer starts after the last mutation. If no new mutations arrive within this window, the graph is rebuilt asynchronously. Set to 0 to disable. Recommended: 10000-30000 for low-volume ingestion

Integer

15000

maxPageRAM

Maximum amount of pages (in MB) to keep in RAM

Long

4096

pageFlushQueue

Size of the asynchronous page flush queue

Integer

512

polyglotCommand.timeout

Default timeout for polyglot commands (in ms)

Long

10000

queryMaxHeapElementsAllowedPerOp

Maximum number of elements (records) allowed in a single query for memory-intensive operations (eg. ORDER BY in heap). If exceeded, the query fails with an OCommandExecutionException. Negative number means no limit.This setting is intended as a safety measure against excessive resource consumption from a single query (eg. prevent OutOfMemory)

Long

500000

sqlStatementCache

Maximum number of parsed statements to keep in cache

Integer

300

txRetries

Number of retries in case of MVCC exception

Integer

3

txRetryDelay

Maximum amount of milliseconds to compute a random number to wait for the next retry. This setting is helpful in case of high concurrency on the same pages (multi-thread insertion over the same bucket

Integer

100

txWAL

Uses the WAL

Boolean

true

txWalFiles

Number of concurrent files to use for tx log. 0 (default) = available cores

Integer

(machine dependent)

txWalFlush

Flushes the WAL on disk at commit time. It can be 0 = no flush, 1 = flush without metadata and 2 = full flush (fsync). In production server mode, this is automatically set to 1 if not explicitly configured. See concepts/transactions.adoc#wal-flush-durability

Integer

0

typeDefaultBuckets

Default number of buckets to create per type

Integer

1

Available Plugins

Name server.plugins-String

Gremlin

GremlinServer:com.arcadedb.server.gremlin.GremlinServerPlugin

MongoDB

MongoDB:com.arcadedb.mongo.MongoDBProtocolPlugin

Postgres

Postgres:com.arcadedb.postgres.PostgresProtocolPlugin

Prometheus

Prometheus:com.arcadedb.metrics.prometheus.PrometheusMetricsPlugin

Redis

Redis:com.arcadedb.redis.RedisProtocolPlugin