Databases let you create fully isolated sets of collections for multi-tenancy applications
ArangoDB can handle multiple databases in the same server instance. Databases
can be used to logically group and separate data. An ArangoDB database consists
of collections and dedicated database-specific worker processes. A database
contains its own collections (which cannot be accessed from other databases),
Foxx applications, and replication loggers and appliers. Each ArangoDB database
contains its own system collections (e.g.
There is always at least one database in ArangoDB. This is the default
_system. This database cannot be dropped and provides special
operations for creating, dropping, and enumerating databases.
You can create additional databases and give them unique names to access them
later. Database management operations cannot be initiated from out of user-defined
databases. You need to use the
_system database as context.
When ArangoDB is accessed via its HTTP REST API, the database name is read from
the first part of the request URI path (e.g.
/_db/myDB/...). If the request
URI does not contain a database name, it defaults to
If a database name is provided in the request URI, the name must be properly URL-encoded, and,
if it contains UTF-8 characters, these must be NFC-normalized. Any non-NFC-normalized
database names are rejected by the server.
You can give each database you create a name to identify and access it. The name needs to be unique and conform to the naming constraints for databases.
There are two naming constraints available for database names: the traditional
and the extended naming constraints. Whether the former or the latter are
active depends on the
--database.extended-names startup option.
The extended naming constraints are used if enabled, allowing many special and
UTF-8 characters in database names. If set to
false (default), the traditional
naming constraints are enforced.
The extended naming constraints are an experimental feature but they will become the norm in a future version. Check if your drivers and client applications are prepared for this feature before enabling it.
The restrictions for database names are as follows:
- For the traditional naming constraints:
- Database names must only consist of the letters
z(both lower and upper case allowed), the numbers
9, and the underscore (
_) or dash (
-) symbols. This also means that any non-ASCII database names are not allowed.
- Database names must always start with a letter. Database names starting with an underscore are considered to be system databases, and users should not create or delete those.
- The maximum allowed length of a database name is 64 bytes.
- Database names are case-sensitive.
- Database names must only consist of the letters
- For the extended naming constraints:
- Names can consist of most UTF-8 characters, such as Japanese or Arabic letters, emojis, letters with accentuation. Some ASCII characters are disallowed, but less compared to the traditional naming constraints.
- Names cannot contain the characters
:at any position, nor any control characters (below ASCII code 32), such as
- Spaces are accepted, but only in between characters of the name. Leading or trailing spaces are not allowed.
_(underscore) and the numeric digits
9are not allowed as first character, but at later positions.
- Database names are case sensitive.
- Database names containing UTF-8 characters must be NFC-normalized. Non-normalized names will be rejected by arangod.
- The maximum length of a database name is 128 bytes after normalization. As a UTF-8 character may consist of multiple bytes, this does not necessarily equate to 128 characters.
Example database names that can be used with the extended naming constraints:
abc? <> 123!
While it is possible to change the value of the
--database.extended-names option from
true to enable extended names, the reverse is not true. Once the extended names have been enabled, they remain permanently enabled so that existing databases, collections, Views, and indexes with extended names remain accessible.
Please be aware that dumps containing extended names cannot be restored into older versions that only support the traditional naming constraints. In a cluster setup, it is required to use the same naming constraints for all Coordinators and DB-Servers of the cluster. Otherwise, the startup is refused. In DC2DC setups it is also required to use the same naming constraints for both datacenters to avoid incompatibilities.
- Each database contains its own system collections, which ArangoDB has to set up when a database is created. This makes the creation of a database take a while.
- Replication can be configured globally or on a per-database level. In the latter case, you need to configure any replication logging or applying for new databases explicitly after they have been created.
- Foxx applications are only available in the context of the database they have been installed in. A new database only provides access to the system applications shipped with ArangoDB (mainly the web interface). You need to explicitly install other Foxx applications.
Database organization on disk
Data is physically stored in
.sst files in a sub-directory
that resides in the instance’s data directory. A single file can contain
documents of various collections and databases.
ArangoSearch stores data in database-specific directories underneath the
Foxx applications are also organized in database-specific directories but inside the application path. The filesystem layout could look like this:
apps/ # the instance's application directory system/ # system applications (can be ignored) _db/ # sub-directory containing database-specific applications <database-dir>/ # sub-directory for a single database <mountpoint>/APP # sub-directory for a single application <mountpoint>/APP # sub-directory for a single application <database-dir>/ # sub-directory for another database <mountpoint>/APP # sub-directory for a single application
The name of
<database-dir> will be the database’s original name or the
database’s ID if its name contains special characters.
Set the database context
When you have an established connection to ArangoDB, the current
database can be changed explicitly using the
method. This switches to the specified database (provided it
exists and the user can connect to it). From this point on, any
following action in the same shell or connection uses the
specified database, unless otherwise specified.
If the database is changed, client drivers need to store the current database name on their side, too. This is because connections in ArangoDB do not contain any state information. All state information is contained in the HTTP request/response data.
To connect to a specific database after arangosh has started use the command
described above. It is also possible to specify a database name when invoking
arangosh. For this purpose, use the command-line parameter
arangosh --server.database test
Note that commands, actions, scripts or AQL queries should never access multiple databases, even if they exist. The only intended and supported way in ArangoDB is to use one database at a time for a command, an action, a script or a query. Operations started in one database must not switch the database later and continue operating in another.
Please keep in mind that each database contains its own system collections, which need to be set up when a database is created. This makes the creation of a database take a while.
Foxx applications are also available only in the context of the database they have been installed in. A new database only provides access to the system applications shipped with ArangoDB (that is the web interface at the moment) and no other Foxx applications until they are explicitly installed for the particular database.