Database Management

This is an introduction to ArangoDB's HTTP interface for managing databases.

The HTTP interface for databases provides operations to create and drop individual databases. These are mapped to the standard HTTP methods POST and DELETE. There is also the GET method to retrieve an array of existing databases.

Please note that all database management operations can only be accessed via the default database (_system) and none of the other databases.

Managing Databases using HTTP

Information of the database

retrieves information about the current database

GET /_api/database/current

Retrieves information about the current database

The response is a JSON object with the following attributes:

  • name: the name of the current database

  • id: the id of the current database

  • path: the filesystem path of the current database

  • isSystem: whether or not the current database is the _system database

Example:

shell> curl --dump - http://localhost:8529/_api/database/current

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : { 
    "name" : "_system", 
    "id" : "1", 
    "path" : "/var/folders/sb/5_j9t5wx4d7bpprydjdb0xtc0000gn/T/arangosh_gjSf8U/tmp-97572-2763310941/data/databases/database-1", 
    "isSystem" : true 
  } 
}

Return Codes

  • 200: is returned if the information was retrieved successfully.
  • 400: is returned if the request is invalid.
  • 404: is returned if the database could not be found.

Examples

shell> curl --dump - http://localhost:8529/_api/database/current

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

List of accessible databases

retrieves a list of all databases the current user can access

GET /_api/database/user

Retrieves the list of all databases the current user can access without specifying a different username or password.

Example:

shell> curl --dump - http://localhost:8529/_api/database/user

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : [ 
    "_system" 
  ] 
}

Return Codes

  • 200: is returned if the list of database was compiled successfully.
  • 400: is returned if the request is invalid.

Examples

shell> curl --dump - http://localhost:8529/_api/database/user

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

List of databases

retrieves a list of all existing databases

GET /_api/database

Retrieves the list of all existing databases

Note: retrieving the list of databases is only possible from within the _system database.

Note: You should use the GET user API to fetch the list of the available databases now.

Example:

shell> curl --dump - http://localhost:8529/_api/database

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : [ 
    "_system" 
  ] 
}

Return Codes

  • 200: is returned if the list of database was compiled successfully.
  • 400: is returned if the request is invalid.
  • 403: is returned if the request was not executed in the _system database.

Examples

shell> curl --dump - http://localhost:8529/_api/database

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Create database

creates a new database

POST /_api/database

A JSON object with these properties is required:

  • name: Has to contain a valid database name.
  • users: Has to be an array of user objects to initially create for the new database. User information will not be changed for users that already exist. If users is not specified or does not contain any users, a default user root will be created with an empty string password. This ensures that the new database will be accessible after it is created. Each user object can contain the following attributes:
    • username: Loginname of the user to be created
    • passwd: The user password as a string. If not specified, it will default to an empty string.
    • active: A flag indicating whether the user account should be activated or not. The default value is true. If set to false, the user won't be able to log into the database.
    • extra: A JSON object with extra user information. The data contained in extra will be stored for the user but not be interpreted further by ArangoDB.

Creates a new database

The response is a JSON object with the attribute result set to true.

Note: creating a new database is only possible from within the _system database.

Example:

Creating a database named example.

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/database <<EOF
{ 
  "name" : "example" 
}
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 201, 
  "result" : true 
}

Example:

Creating a database named mydb with two users.

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/database <<EOF
{ 
  "name" : "mydb", 
  "users" : [ 
    { 
      "username" : "admin", 
      "passwd" : "secret", 
      "active" : true 
    }, 
    { 
      "username" : "tester", 
      "passwd" : "test001", 
      "active" : false 
    } 
  ] 
}
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 201, 
  "result" : true 
}

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/database <<EOF
{ 
  "name" : "example" 
}
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Creating a database named mydb with two users.

shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/database <<EOF
{ 
  "name" : "mydb", 
  "users" : [ 
    { 
      "username" : "admin", 
      "passwd" : "secret", 
      "active" : true 
    }, 
    { 
      "username" : "tester", 
      "passwd" : "test001", 
      "active" : false 
    } 
  ] 
}
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Drop database

drop an existing database

DELETE /_api/database/{database-name}

Path Parameters

  • database-name (required): The name of the database

Drops the database along with all data stored in it.

Note: dropping a database is only possible from within the _system database. The _system database itself cannot be dropped.

Example:

shell> curl -X DELETE --dump - http://localhost:8529/_api/database/example

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : true 
}

Return Codes

  • 200: is returned if the database was dropped successfully.
  • 400: is returned if the request is malformed.
  • 403: is returned if the request was not executed in the _system database.
  • 404: is returned if the database could not be found.

Examples

shell> curl -X DELETE --dump - http://localhost:8529/_api/database/example

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

© ArangoDB - the native multi-model NoSQL database