Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

updated documentation

This commit is contained in:
Jan Steemann 2013-09-24 15:40:37 +02:00
parent 5fb61e7020
commit 46895b4ec2
9 changed files with 134 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
Documentation/ImplementorManual/HttpDatabase.md
View File

@ -7,6 +7,62 @@ HTTP Interface for Databases {#HttpDatabase}
Databases {#HttpDatabaseIntro}
==============================
Any operation triggered via ArangoDB's HTTP REST API is executed in the context of exactly
one database. To explicitly specify the database in a request, the request URI must contain
the database name in front of the actual path:
http://localhost:8529/_db/mydb/...
where `...` is the actual path to the accessed resource. In the example, the resource will be
accessed in the context of the database `mydb`. Actual URLs in the context of `mydb` could look
like this:
http://localhost:8529/_db/mydb/_api/version
http://localhost:8529/_db/mydb/_api/document/test/12345
http://localhost:8529/_db/mydb/myapp/get
If a database name is present in the URI as above, ArangoDB will consult the database-to-endpoint
mapping for the current endpoint, and validate if access to the database is allowed on the
endpoint.
If the endpoint is not restricted to a list of databases, ArangoDB will continue with the
regular authentication procedure. If the endpoint is restricted to a list of specified databases,
ArangoDB will check if the requested database is in the list. If not, the request will be turned
down instantly. If yes, then ArangoDB will continue with the regular authentication procedure.
If the request URI was `http://localhost:8529/_db/mydb/...`, then the request to `mydb` will be
allowed (or disallowed) in the following situations:
Endpoint-to-database mapping Access to `mydb` allowed (subject to further authentication)
---------------------------- ------------------------------------------------------------
[ ] yes
[ "_system" ] no
[ "_system", "mydb" ] yes
[ "mydb" ] yes
[ "mydb", "_system" ] yes
[ "test1", "test2" ] no
In case no database name is specified in the request URI, ArangoDB will derive the database
name from the endpoint-to-database mapping (see @ref NewFeatures14Endpoints} of the endpoint
the connection was coming in on.
If the endpoint is not restricted to a list of databases, ArangoDB will assume the `_system`
database. If the endpoint is restricted to one or multiple databases, ArangoDB will assume
the first name from the list.
Following is an overview of which database name will be assumed for different endpoint-to-database
mappings in case no database name is specified in the URI:
Endpoint-to-database mapping Database
---------------------------- --------
[ ] _system
[ "_system" ] _system
[ "_system", "mydb" ] _system
[ "mydb" ] mydb
[ "mydb", "_system" ] mydb
Database Management {#HttpDatabaseManagement}
=============================================
This is an introduction to ArangoDB's Http interface for managing databases.
@copydoc GlossaryDatabase

1
Documentation/ImplementorManual/HttpDatabaseTOC.md
View File

@ -3,6 +3,7 @@ TOC {#HttpDatabaseTOC}
- @ref HttpDatabase
- @ref HttpDatabaseIntro
- @ref HttpDatabaseManagement
- @ref HttpDatabaseHttp
- @ref HttpDatabaseCreate "POST /_api/database"
- @ref HttpDatabaseDelete "DELETE /_api/database/database-name"

2
Documentation/ImplementorManual/NamingConventions.md
View File

@ -17,7 +17,7 @@ names conform to the following 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 collection names are not allowed.
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.

13
Documentation/Manual/GlossaryDatabase.md
View File

@ -2,9 +2,14 @@ Database {#GlossaryDatabase}
============================
@GE{Database}: ArangoDB can handle multiple databases in the same server
instance. Databases can be used to logically separate data. An ArangoDB
instance. Databases can be used to logically group and separate data. An ArangoDB
database consists of collections and dedicated database-specific worker processes.
There will always be at least one database in ArangoDB. This is the default
database, named `_system`. Users can create additional databases and give them
unique names to access them later.
Any databases but the default database can be dropped.
database, named `_system`. This database cannot be dropped, and provides special
operations for creating, dropping, and enumerating databases.
Users 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.
When ArangoDB is accessed via its HTTP REST API, the database name is read from the
request URI. If the request URI does not contain a database name, the database name
is automatically determined by some algorithm.

6
Documentation/Manual/GlossaryDatabaseName.md
View File

@ -5,13 +5,7 @@ DatabaseName {#GlossaryDatabaseName}
in the same server instance. When multiple databases are used, each
database must be given a unique name. This name is used to uniquely
identify a database. The default database in ArangoDB is named `_system`.
The `_system` database will always be there, and cannot be dropped.
When ArangoDB is accessed and no database name is explicitly specified,
ArangoDB will automatically assume the default database `_system` is
accessed. This is done for downwards-compatibility reasons.
The database name is a string consisting of only letters, digits
and the `_` (underscore) and `-` (dash) characters. User-defined database
names must always start with a letter.
Please refer to @ref NamingConventions for more information on valid
database names.

57
Documentation/Manual/NewFeatures14.md
View File

@ -9,7 +9,8 @@ Features and Improvements {#NewFeatures14Introduction}
The following list shows in detail which features have been added or improved in
ArangoDB 1.4. ArangoDB 1.4 also contains several bugfixes that are not listed
here - see the CHANGELOG for details.
here - see the @EXTREF{https://github.com/triAGENS/ArangoDB/blob/devel/CHANGELOG,CHANGELOG}
for details.
Multiple Databases {#NewFeatures14MultipleDatabases}
----------------------------------------------------
@ -84,60 +85,6 @@ to the database have been garbage-collected. This is similar to how collections
dropped.
Any operation triggered via ArangoDB's HTTP REST API is executed in the context of exactly
one database. To explicitly specify the database in the request, the request URI must contain
the database name in front of the actual path:
http://localhost:8529/_db/mydb/...
where `...` is the actual path to the accessed resource. In the example, the resource will be
accessed in the context of the database `mydb`. Actual URLs in the context of `mydb` could look
like this:
http://localhost:8529/_db/mydb/_api/version
http://localhost:8529/_db/mydb/_api/document/test/12345
http://localhost:8529/_db/mydb/myapp/get
If a database name is present in the URI as above, ArangoDB will consult the database-to-endpoint
mapping for the current endpoint, and validate if access to the database is allowed on the
endpoint.
If the endpoint is not restricted to a list of databases, ArangoDB will continue with the
regular authentication procedure. If the endpoint is restricted to a list of specified databases,
ArangoDB will check if the requested database is in the list. If not, the request will be turned
down instantly. If yes, then ArangoDB will continue with the regular authentication procedure.
If the request URI was `http://localhost:8529/_db/mydb/...`, then the request to `mydb` will be
allowed (or disallowed) in the following situations:
Endpoint-to-database mapping Access to `mydb` allowed (subject to further authentication)
---------------------------- ------------------------------------------------------------
[ ] yes
[ "_system" ] no
[ "_system", "mydb" ] yes
[ "mydb" ] yes
[ "mydb", "_system" ] yes
[ "test1", "test2" ] no
In case no database name is specified in the request URI, ArangoDB will derive the database
name from the endpoint-to-database mapping (see @ref NewFeatures14Endpoints} of the endpoint
the connection was coming in on.
If the endpoint is not restricted to a list of databases, ArangoDB will assume the `_system`
database. If the endpoint is restricted to one or multiple databases, ArangoDB will assume
the first name from the list.
Following is an overview of which database name will be assumed for different endpoint-to-database
mappings in case no database name is specified in the URI:
Endpoint-to-database mapping Database
---------------------------- --------
[ ] _system
[ "_system" ] _system
[ "_system", "mydb" ] _system
[ "mydb" ] mydb
[ "mydb", "_system" ] mydb
@copydoc GlossaryDatabaseName
Runtime Endpoint Management {#NewFeatures14Endpoints}

47
Documentation/UserManual/HandlingDatabases.md
View File

@ -8,9 +8,7 @@ JavaScript Interface to Databases {#HandlingDatabasesIntro}
===========================================================
This is an introduction to managing databases in ArangoDB from within
JavaScript. By default (i.e. if not specified otherwise), ArangoDB
will use the default database (`_system`) for all incoming connections,
including connections from arangosh.
JavaScript.
While being in an established connection to ArangoDB, the current
database can be changed explicity by using the `db._useDatabase()`
@ -19,18 +17,24 @@ exists and the user can connect to it). From this point on, any
following actions in the same shell or connection will use the
specified database unless otherwise specified.
Note: 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.
Connecting to a specific database from arangosh is possible with
the above command after arangosh has been started, but it is also
possible to specify a database name when invoking arangosh.
For this purpose, use the command-line parameter `--server.database`,
e.g.
arangosh --server.database test
> arangosh --server.database test
Please note that no commands, actions, or scripts should ever
Please 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 have a command, an action or a
script use one database at a time.
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.
@copydoc GlossaryDatabase
@ -43,6 +47,27 @@ Working with Databases {#HandlingDatabasesShell}
Database Methods {#HandlingDatabasesMethods}
--------------------------------------------
To following methods are available to manage databases via JavaScript.
Please note that several of these methods can be used from the `_system`
database only.
@anchor HandlingDatabasesName
@copydetails JS_NameDatabase
@CLEARPAGE
@anchor HandlingDatabasesPath
@copydetails JS_PathDatabase
@CLEARPAGE
@anchor HandlingDatabasesIsSystem
@copydetails JS_IsSystemDatabase
@CLEARPAGE
@anchor HandlingDatabasesUse
@copydetails JS_UseDatabase
@CLEARPAGE
@anchor HandlingDatabasesList
@copydetails JS_ListDatabases
@ -50,15 +75,7 @@ Database Methods {#HandlingDatabasesMethods}
@anchor HandlingDatabasesCreate
@copydetails JS_CreateDatabase
@CLEARPAGE
@anchor HandlingDatabasesUse
@copydetails JS_UseDatabase
@CLEARPAGE
@anchor HandlingDatabasesDrop
@copydetails JS_DropDatabase
@CLEARPAGE
@anchor HandlingDatabasesName
@copydetails JS_NameDatabase

6
Documentation/UserManual/HandlingDatabasesTOC.md
View File

@ -5,8 +5,10 @@ TOC {#HandlingDatabasesTOC}
- @ref HandlingDatabasesIntro
- @ref HandlingDatabasesShell
- @ref HandlingDatabasesMethods
- @ref HandlingDatabasesName "db._name"
- @ref HandlingDatabasesPath "db._path"
- @ref HandlingDatabasesIsSystem "db._isSystem"
- @ref HandlingDatabasesUse "db._useDatabase"
- @ref HandlingDatabasesList "db._listDatabases"
- @ref HandlingDatabasesCreate "db._createDatabase"
- @ref HandlingDatabasesUse "db._useDatabase"
- @ref HandlingDatabasesDrop "db._dropDatabase"
- @ref HandlingDatabasesName "db._name"

47
arangod/V8Server/v8-vocbase.cpp
View File

@ -7641,7 +7641,7 @@ static v8::Handle<v8::Value> JS_VersionServer (v8::Arguments const& argv) {
///
/// @FUN{@FA{db}._path()}
///
/// Returns the path.
/// Returns the filesystem path of the current database as a string.
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_PathDatabase (v8::Arguments const& argv) {
@ -7661,7 +7661,7 @@ static v8::Handle<v8::Value> JS_PathDatabase (v8::Arguments const& argv) {
///
/// @FUN{@FA{db}._name()}
///
/// Returns the name of the current database.
/// Returns the name of the current database as a string.
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_NameDatabase (v8::Arguments const& argv) {
@ -7681,8 +7681,11 @@ static v8::Handle<v8::Value> JS_NameDatabase (v8::Arguments const& argv) {
///
/// @FUN{@FA{db}._isSystem()}
///
/// Returns whether the currently used database is the default (`_system`)
/// database.
/// 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.
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_IsSystemDatabase (v8::Arguments const& argv) {
@ -7705,11 +7708,16 @@ static v8::Handle<v8::Value> JS_IsSystemDatabase (v8::Arguments const& argv) {
/// Changes the current database to the database specified by @FA{name}. Note
/// that the database specified by @FA{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 @FA{name}. In this case, arangosh
/// should be closed, and re-started with different username and password
/// credentials.
/// connect to the database specified by @FA{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.
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_UseDatabase (v8::Arguments const& argv) {
@ -7749,7 +7757,8 @@ static v8::Handle<v8::Value> JS_UseDatabase (v8::Arguments const& argv) {
///
/// @FUN{@FA{db}._listDatabases()}
///
/// Returns the list of all databases.
/// Returns the list of all databases. This method can only be used from within
/// the `_system` database.
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_ListDatabases (v8::Arguments const& argv) {
@ -7793,17 +7802,17 @@ static v8::Handle<v8::Value> JS_ListDatabases (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief create a new database
///
/// @FUN{@FA{db}._createDatabase(@FA{name}, @FA{options})}
/// @FUN{@FA{db}._createDatabase(@FA{name})}
///
/// Creates a new database with the name specified by @FA{name}. This method
/// can only be used from within the default (`_system`) database.
/// Creates a new database with the name specified by @FA{name}.
/// There are restrictions for database names (see @ref DatabaseNames}.
///
/// Note that even if the database is created successfully, there will be no
/// change of the current database to the new database. Changing the current
/// database must explicitly be requested by using the @ref JS_UseDatabase
/// method.
/// change into the current database to the new database. Changing the current
/// database must explicitly be requested by using the @ref HandlingDatabasesUse
/// "db._useDatabase" method.
///
/// Returns the new database as an object.
/// This method can only be used from within the `_system` database.
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_CreateDatabase (v8::Arguments const& argv) {
@ -7909,9 +7918,11 @@ static v8::Handle<v8::Value> JS_CreateDatabase (v8::Arguments const& argv) {
/// Drops the database specified by @FA{name}. The database specified by
/// @FA{name} must exist.
///
/// Note that dropping databases is only possible from within the default
/// database (`_system`). The method will fail when not called from within the
/// default database. The default database itself cannot be dropped.
/// Note that 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.
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_DropDatabase (v8::Arguments const& argv) {