Databases

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. _users, _graphs, …).

There is always at least one database in ArangoDB. This is the default database named _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. You need to be in the _system database for executing database management operations. They cannot be initiated while in a user-defined database.

Database names

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 restrictions for database names are as follows:

• For the traditional naming constraints:

  • Database names must only consist of the letters a to z (both lower and upper case allowed), the numbers 0 to 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.

• 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 / or : at any position, nor any control characters (below ASCII code 32), such as \n, \t, \r, and \0.
  • Spaces are accepted, but only in between characters of the name. Leading or trailing spaces are not allowed.
  • . (dot), _ (underscore) and the numeric digits 0-9 are 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: España, 😀, 犬, كلب, @abc123, København, München, Бишкек, abc? <> 123!

Notes

• 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 engine-rocksdb 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 databases folder.

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.

Database interfaces

The following sections show examples of how you can use the APIs of ArangoDB and the official drivers, as well as the ArangoDB Shell and the built-in web interface, to perform common operations related to databases. For less common operations and other drivers, see the corresponding reference documentation.

Set the database context

Connections in ArangoDB do not contain any state information. All state information is contained in the request/response data of the HTTP API that all clients use under the hood. If the database is changed, client drivers need to store the current database name on their side to later make requests with the selected database as the context.

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.

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 (the web interface) and no other Foxx applications until they are explicitly installed for a particular database.

db._useDatabase("mydb");

true

arangosh --server.database mydb

curl http://localhost:8529/_db/mydb/...

// Default host and the _system database
const db = new Database();

// New connection pool
const myDb = new Database("http://localhost:8529", "mydb");

// Same connection pool
const otherDb = myDb.database("other");

ctx := context.Background()
db, err := client.GetDatabase(ctx, "_system", /* options */ nil)
if err != nil {
  fmt.Println(err)
} else {
  _ = db // Use db here
}

ArangoDatabase db = arangoDB.db(); // Default _system database
ArangoDatabase mydb = arangoDB.db("mydb");

sys_db = client.db() // Default _system database

db = client.db("mydb")

Create a database

Each database contains its own system collections, which need to be set up when a database is created. The creation of a database can therefore take a moment.

var ok = db._useDatabase("_system"); // _system database context required
db._createDatabase("mydb");

true

curl -d '{"name":"mydb"}' http://localhost:8529/_api/database

const myDb = await db.createDatabase("mydb");

ctx := context.Background()
mydb, err := client.CreateDatabase(ctx, "mydb", /* options */ nil)
_ = mydb

Boolean ok = arangoDB.createDatabase("mydb");
// -- or --
ArangoDatabase db = arangoDB.db("mydb");
Boolean ok = db.create(); 

sys_db = client.db("_system") # _system database context required
ok = sys_db.create_database("mydb")
db = client.db("mydb")

Get a database

var ok = db._useDatabase("mydb");
db._properties();

{ 
  "id" : "67493", 
  "name" : "mydb", 
  "isSystem" : false, 
  "path" : "none" 
}

curl http://localhost:8529/_db/mydb/_api/database/current

const myDb = db.database("mydb");
const info = await myDb.get();

ctx := context.Background()
db, err := client.GetDatabase(ctx, "mydb", nil)
if err != nil {
  fmt.Println(err)
} else {
  info, err := db.Info(ctx)
  if err != nil {
    fmt.Println(err)
  } else {
    fmt.Printf("%+v", info)
  }
}

ArangoDatabase db = arangoDB.db("mydb");
DatabaseEntity info = db.getInfo();

db = client.db("mydb")
info = db.properties()

List all databases

var ok = db._useDatabase("_system"); // _system database context required
db._databases();

[ 
  "_system", 
  "mydb" 
]

curl http://localhost:8529/_api/database

const dbs = await db.databases();
console.log(dbs.map(d => d.name))

ctx := context.Background()
dbs, err := client.Databases(ctx)
if err != nil {
  fmt.Println(err)
} else {
  for _, d := range dbs {
    fmt.Println(d.Name())
  }
}

Collection<String> dbNames = arangoDB.getDatabases();

sys_db = client.db("_system") # _system database context required
db_names = sys_db.databases()

Remove a database

var ok = db._useDatabase("_system"); // _system database context required
db._dropDatabase("mydb");

true

curl -XDELETE http://localhost:8529/_api/database/mydb

const ok = await db.dropDatabase("mydb");

ctx := context.Background()
db, err := client.GetDatabase(ctx, "mydb", nil)
if err != nil {
  fmt.Println(err)
} else {
  err = db.Remove(ctx)
  if err != nil {
    fmt.Println(err)
  }
}

ArangoDatabase db = arangoDB.db("mydb");
Boolean ok = db.drop();

sys_db = client.db("_system") # _system database context required
ok = sys_db.delete_database("mydb")