mirror of https://gitee.com/bigwinds/arangodb
206 lines
5.6 KiB
Markdown
206 lines
5.6 KiB
Markdown
Working with Databases
|
|
======================
|
|
|
|
Database Methods
|
|
----------------
|
|
|
|
The following methods are available to manage databases via JavaScript.
|
|
Please note that several of these methods can be used from the _system
|
|
database only.
|
|
|
|
### Name
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
return the database name
|
|
`db._name()`
|
|
|
|
Returns the name of the current database as a string.
|
|
|
|
|
|
**Examples**
|
|
|
|
|
|
@startDocuBlockInline dbName
|
|
@EXAMPLE_ARANGOSH_OUTPUT{dbName}
|
|
require("@arangodb").db._name();
|
|
@END_EXAMPLE_ARANGOSH_OUTPUT
|
|
@endDocuBlock dbName
|
|
|
|
|
|
### ID
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
return the database id
|
|
`db._id()`
|
|
|
|
Returns the id of the current database as a string.
|
|
|
|
|
|
**Examples**
|
|
|
|
|
|
@startDocuBlockInline dbId
|
|
@EXAMPLE_ARANGOSH_OUTPUT{dbId}
|
|
require("@arangodb").db._id();
|
|
@END_EXAMPLE_ARANGOSH_OUTPUT
|
|
@endDocuBlock dbId
|
|
|
|
|
|
### Path
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
return the path to database files
|
|
`db._path()`
|
|
|
|
Returns the filesystem path of the current database as a string.
|
|
|
|
|
|
**Examples**
|
|
|
|
|
|
@startDocuBlockInline dbPath
|
|
@EXAMPLE_ARANGOSH_OUTPUT{dbPath}
|
|
require("@arangodb").db._path();
|
|
@END_EXAMPLE_ARANGOSH_OUTPUT
|
|
@endDocuBlock dbPath
|
|
|
|
|
|
### isSystem
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
return the database type
|
|
`db._isSystem()`
|
|
|
|
Returns whether the currently used database is the *_system* database.
|
|
The system database has some special privileges and properties, for example,
|
|
database management operations such as create or drop can only be executed
|
|
from within this database. Additionally, the *_system* database itself
|
|
cannot be dropped.
|
|
|
|
|
|
### Use Database
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
change the current database
|
|
`db._useDatabase(name)`
|
|
|
|
Changes the current database to the database specified by *name*. Note
|
|
that the database specified by *name* must already exist.
|
|
|
|
Changing the database might be disallowed in some contexts, for example
|
|
server-side actions (including Foxx).
|
|
|
|
When performing this command from arangosh, the current credentials (username
|
|
and password) will be re-used. These credentials might not be valid to
|
|
connect to the database specified by *name*. Additionally, the database
|
|
only be accessed from certain endpoints only. In this case, switching the
|
|
database might not work, and the connection / session should be closed and
|
|
restarted with different username and password credentials and/or
|
|
endpoint data.
|
|
|
|
|
|
### List Databases
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
return the list of all existing databases
|
|
`db._databases()`
|
|
|
|
Returns the list of all databases. This method can only be used from within
|
|
the *_system* database.
|
|
|
|
|
|
### Create Database
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
create a new database
|
|
`db._createDatabase(name, options, users)`
|
|
|
|
Creates a new database with the name specified by *name*.
|
|
There are restrictions for database names
|
|
(see [DatabaseNames](../NamingConventions/DatabaseNames.md)).
|
|
|
|
Note that even if the database is created successfully, there will be no
|
|
change into the current database to the new database. Changing the current
|
|
database must explicitly be requested by using the
|
|
*db._useDatabase* method.
|
|
|
|
The *options* attribute currently has no meaning and is reserved for
|
|
future use.
|
|
|
|
The optional *users* attribute can be used to create initial users for
|
|
the new database. If specified, it must be a list of user objects. Each user
|
|
object can contain the following attributes:
|
|
|
|
* *username*: the user name as a string. This attribute is mandatory.
|
|
* *passwd*: the user password as a string. If not specified, then it defaults
|
|
to an empty string.
|
|
* *active*: a boolean flag indicating whether the user account should be
|
|
active or not. The default value is *true*.
|
|
* *extra*: an optional JSON object with extra user information. The data
|
|
contained in *extra* will be stored for the user but not be interpreted
|
|
further by ArangoDB.
|
|
|
|
If no initial users are specified, a default user *root* will be created
|
|
with an empty string password. This ensures that the new database will be
|
|
accessible via HTTP after it is created.
|
|
|
|
You can create users in a database if no initial user is specified. Switch
|
|
into the new database (username and password must be identical to the current
|
|
session) and add or modify users with the following commands.
|
|
|
|
```js
|
|
require("@arangodb/users").save(username, password, true);
|
|
require("@arangodb/users").update(username, password, true);
|
|
require("@arangodb/users").remove(username);
|
|
```
|
|
Alternatively, you can specify user data directly. For example:
|
|
|
|
```js
|
|
db._createDatabase("newDB", {}, [{ username: "newUser", passwd: "123456", active: true}])
|
|
```
|
|
|
|
Those methods can only be used from within the *_system* database.
|
|
|
|
|
|
### Drop Database
|
|
<!-- arangod/V8Server/v8-vocbase.cpp -->
|
|
|
|
|
|
drop an existing database
|
|
`db._dropDatabase(name)`
|
|
|
|
Drops the database specified by *name*. The database specified by
|
|
*name* must exist.
|
|
|
|
**Note**: Dropping databases is only possible from within the *_system*
|
|
database. The *_system* database itself cannot be dropped.
|
|
|
|
Databases are dropped asynchronously, and will be physically removed if
|
|
all clients have disconnected and references have been garbage-collected.
|
|
|
|
### Engine
|
|
|
|
retrieve the storage engine type used by the server
|
|
`db._engine()`
|
|
|
|
Returns the name of the storage engine in use (`mmfiles` or `rocksdb`), as well
|
|
as a list of supported features (types of indexes and
|
|
[dfdb](../../Programs/Arango-dfdb/README.md)).
|
|
|
|
### Engine statistics
|
|
|
|
retrieve statistics related to the storage engine (rocksdb)
|
|
`db._engineStats()`
|
|
|
|
Returns some statistics related to the storage engine activity, including figures
|
|
about data size, cache usage, etc.
|
|
|
|
**Note**: Currently this only produces useful output for the RocksDB engine.
|