Server

To start the server from a location different than the ArcadeDB folder, for example, if starting the server as a service, set the environment variable ARCADEDB_HOME to the ArcadeDB folder:

The server can be started in one of three modes, which affect the studio, logging, and security defaults:

The mode is controlled by the server.mode setting with a default mode development.

In production mode the Studio web tool is not served by default, to reduce the attack surface. If you need it (for example to inspect a database running in production), force-enable it with the studio.enabled setting:

When enabling Studio in production, restrict network access to the HTTP port (for example with a firewall, a reverse proxy, or by enabling SSL), since it exposes a web UI on the public-facing server.

(Since v26.10.2.) A long-lived connection keeps the user it authenticated as, but the server checks that user again against the current security configuration on every request, as it does for every HTTP call. A user deleted, given a new password, or stripped of a database grant after the connection logged in loses access on its next request instead of keeping it for the life of the connection:

In v26.10.1 and earlier these connections kept the access they had at login until they disconnected.

Instead of starting a server and then connect to it, to create the default databases, ArcadeDB Server takes an initial default databases list by using the setting server.defaultDatabases.

With the example above the database "Universe" will be created if doesn’t exist, with user "albert", password "einstein".

: separates the fields of a credential, , the credentials, ; the databases and [/] the credentials block, so a user name, password or group that contains one of them writes it percent-encoded, as in the user part of a URI: %3A for :, %2C for ,, %3B for ;, %5B for [, %5D for ] and %25 for %. Only a % followed by two hexadecimal digits is decoded, so a password that merely contains a % or a + reads as written. For example -Darcadedb.server.defaultDatabases=Universe[albert:e%3Dmc%3A2:admin] gives "albert" the password e=mc:2 in the admin group.

Since 26.12.1 (issue #11269) a credential with more than three :-separated fields is refused with a warning, and neither creates the user nor grants it the database: before, a password written with a raw : was cut at it, the text after it became the group (mypass:admin meant the password mypass in the admin group) and the rest was dropped. A credential with an empty user name or password is refused the same way, and so is an entry with text after its ] that does not open a {…​} command list, which is what a raw ] inside a password leaves behind. A password containing a sequence like %41 now decodes to a different password: an existing user is then reported with the already exists with a different password warning and keeps its password, so write such a % as %25.

The users are written to config/server-users.jsonl before they take effect. Since 26.11.1 (issue #10535) a start that has to add a user, or to give an existing user access to the database or one more group, and cannot write that file (a read-only configuration directory, such as a Kubernetes ConfigMap mount) stops with an error naming the file, and nothing is granted in memory that is not on disk. A user that already holds the database under the group the entry names is left alone and nothing is written, so once the first start has made the grants the same entry starts on a read-only directory. Before, the grant of an existing user stayed in force in memory and the failed write was logged as already exists with a different password.

An entry the server cannot parse (no […​] block, a [ or a { never closed) stops the list there: that entry and the ones after it are not loaded, and the server logs a WARNING naming the malformed entry. Since 26.10.2 the WARNING quotes only that entry, with its passwords masked the same way the settings reports mask them (Universe[albert:*], and from the first : on for an entry written without brackets), and an unclosed [ is reported this way instead of aborting the server start.

A database entry may be followed by {restore:<URL>}, which restores that database from a backup archive at start-up, replacing any copy already on disk (e.g. -Darcadedb.server.defaultDatabases=Universe[albert:einstein]{restore:/tmp/universe.zip}).

A client can reach the server while it is still booting and start a backup, restore or import of the same database. Since 26.10.1 the restore: command waits for that operation to finish instead of refusing at once, for up to arcadedb.server.startupRestoreSlotWaitMs (60000 ms by default). While it waits the server logs at INFO:

If the other operation is still running when the wait runs out, the command refuses, the database on disk is left untouched, and the server boot fails. Set the value to 0 (or a negative number) to refuse immediately, as earlier versions did.

Once the server is started, multiple clients can be connected to the server by using one of the supported protocols:

(Since v26.11.1.) A server that hosts one database per tenant can hold thousands of them, and every open database keeps its data files, its caches and, once written, a WAL file. The server can close the databases nobody is using and reopen each one on its next request, so the open files and the heap follow the active tenants only. Closing is off by default: set arcadedb.server.databaseIdleTimeout, arcadedb.server.maxOpenDatabases, or both.

With the example above the server opens no database at start, closes a database nobody has used for 30 minutes, keeps at most 500 open at once, and never closes catalog and audit.

The settings are read at each check, so a change made with SET SERVER SETTING or the set server setting server command applies at the next check, without a restart.

What counts as used. Any query, command, transaction, record operation, scan or count, from any protocol. The server samples the engine’s own counters of each database, so no protocol has to report anything. A database is never closed, however long it has been quiet, while:

An open connection without a transaction does not keep a database open: a connection pool would otherwise keep every tenant open for good. The next request on that connection reopens the database. A database in use is never closed for the cap either, so the cap can be exceeded while more databases than that are busy.

Reopening. A database closed for idleness or for the cap keeps its files, and is closed without the mark that the close database server command sets. Unlike a database closed with that command, which stays closed until open database, it is reopened transparently by the next request of any protocol: HTTP, gRPC, PostgreSQL, Bolt, Redis, MongoDB, Gremlin and MCP. A request that resolved the database a moment before it was closed fails with a retryable error (DatabaseIsReopeningException, a retryable 503 over HTTP), and its retry finds the database reopened. The database listings include it while it is closed, see Databases on disk that are not open.

Metrics. Two counters are exported with the other server meters (see Cloud Observability): arcadedb.server.databases.idle_closed, tagged reason idle or cap, counts the databases closed, and arcadedb.server.databases.reopened counts the databases a request opened again after such a close. A reopen rate close to the close rate means the timeout is shorter than the gap between a tenant’s requests. arcadedb.server.databases.idle_close_failed counts the closes that failed (the server log has the cause): such a database is deregistered anyway, and the next request opens it from its files again.

The log files are created in the folder ./log with the filenames arcadedb.log.X, where X is a number between 0 to 9, set up for log rotate. The current log file has the number 0, and is rotated based on server starts or file size.

By default ArcadeDB does not log debug messages into the console and file. You can change this settings by editing the file config/arcadedb-log.properties. The file is a standard logging configuration file.

The default configuration is the following.

Where:

If you’re running ArcadeDB in embedded mode, make sure you’re using the logging setting by specifying the arcadedb-log.properties file at JVM startup:

You can also use your own configuration for logging. In this case replace the path above with your own file.

You can extend ArcadeDB server by creating custom plugins. A plugin is a Java class that implements the interface com.arcadedb.server.ServerPlugin:

(Since v26.11.1) A plugin should declare its HTTP routes through the overload registerAPI(HttpServer, PluginRoutes), which takes each route together with its HTTP methods: a request with any other method answers 405 with an Allow header, before authentication. The registerAPI(HttpServer, PathHandler) shown above is deprecated for removal: a plugin that still implements it keeps working and answers every method on its routes, and the server logs a WARNING at startup that names the plugin. Implement only one of the two overloads: a plugin that implements both gets both called, with a separate WARNING, and a path registered in both is registered twice, the later raw registration winning.

Once registered, the plugin (see below), ArcadeDB Server will instantiate your plugin class and will call the method configure() passing the server configuration. At startup of the server, the startService() method will be invoked. When the server is shut down, the stopService() will be invoked where you can free any resources used by the plugin. The method registerAPI(), if implemented, will be invoked when the HTTP server is initializing where one’s own HTTP commands can be registered. For more information about how to create custom HTTP commands, look at Custom HTTP commands.

Example:

To register your plugin, register the name and add your class (with full package name) in arcadedb.server.plugins setting:

Example:

In case of multiple plugins, use a comma (,) to separate them.

The ArcadeDB server can collect, log and publish metrics. To activate the collection of metrics use the setting:

To log the metrics to the standard output use the setting:

To publish the metrics as Prometheus via HTTP, add the plugin:

Then, under http://localhost:2480/prometheus (or the respective ArcadeDB host) the metrics can be requested given server credentials. For details about the response format see the Prometheus docs.