mirror of https://gitee.com/bigwinds/arangodb
781 lines
19 KiB
Markdown
781 lines
19 KiB
Markdown
---
|
|
layout: default
|
|
description: Managing Foxx services
|
|
---
|
|
|
|
# Managing Foxx services
|
|
|
|
## database.listServices
|
|
|
|
`async database.listServices([excludeSystem]): Array<Object>`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Fetches a list of all installed service.
|
|
|
|
**Arguments**
|
|
|
|
- **excludeSystem**: `boolean` (Default: `true`)
|
|
|
|
Whether system services should be excluded.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const services = await db.listServices();
|
|
|
|
// -- or --
|
|
|
|
const services = await db.listServices(false);
|
|
```
|
|
|
|
## database.installService
|
|
|
|
`async database.installService(mount, source, [options]): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Installs a new service.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
- **source**: `Buffer | Readable | File | string`
|
|
|
|
The service bundle to install.
|
|
|
|
- **options**: `Object` (optional)
|
|
|
|
An object with any of the following properties:
|
|
|
|
- **configuration**: `Object` (optional)
|
|
|
|
An object mapping configuration option names to values.
|
|
|
|
- **dependencies**: `Object` (optional)
|
|
|
|
An object mapping dependency aliases to mount points.
|
|
|
|
- **development**: `boolean` (Default: `false`)
|
|
|
|
Whether the service should be installed in development mode.
|
|
|
|
- **legacy**: `boolean` (Default: `false`)
|
|
|
|
Whether the service should be installed in legacy compatibility mode.
|
|
|
|
This overrides the `engines` option in the service manifest (if any).
|
|
|
|
- **setup**: `boolean` (Default: `true`)
|
|
|
|
Whether the setup script should be executed.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const source = fs.createReadStream("./my-foxx-service.zip");
|
|
const info = await db.installService("/hello", source);
|
|
|
|
// -- or --
|
|
|
|
const source = fs.readFileSync("./my-foxx-service.zip");
|
|
const info = await db.installService("/hello", source);
|
|
|
|
// -- or --
|
|
|
|
const element = document.getElementById("my-file-input");
|
|
const source = element.files[0];
|
|
const info = await db.installService("/hello", source);
|
|
```
|
|
|
|
## database.replaceService
|
|
|
|
`async database.replaceService(mount, source, [options]): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Replaces an existing service with a new service by completely removing the old
|
|
service and installing a new service at the same mount point.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
- **source**: `Buffer | Readable | File | string`
|
|
|
|
The service bundle to replace the existing service with.
|
|
|
|
- **options**: `Object` (optional)
|
|
|
|
An object with any of the following properties:
|
|
|
|
- **configuration**: `Object` (optional)
|
|
|
|
An object mapping configuration option names to values.
|
|
|
|
This configuration will replace the existing configuration.
|
|
|
|
- **dependencies**: `Object` (optional)
|
|
|
|
An object mapping dependency aliases to mount points.
|
|
|
|
These dependencies will replace the existing dependencies.
|
|
|
|
- **development**: `boolean` (Default: `false`)
|
|
|
|
Whether the new service should be installed in development mode.
|
|
|
|
- **legacy**: `boolean` (Default: `false`)
|
|
|
|
Whether the new service should be installed in legacy compatibility mode.
|
|
|
|
This overrides the `engines` option in the service manifest (if any).
|
|
|
|
- **teardown**: `boolean` (Default: `true`)
|
|
|
|
Whether the teardown script of the old service should be executed.
|
|
|
|
- **setup**: `boolean` (Default: `true`)
|
|
|
|
Whether the setup script of the new service should be executed.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const source = fs.createReadStream("./my-foxx-service.zip");
|
|
const info = await db.replaceService("/hello", source);
|
|
|
|
// -- or --
|
|
|
|
const source = fs.readFileSync("./my-foxx-service.zip");
|
|
const info = await db.replaceService("/hello", source);
|
|
|
|
// -- or --
|
|
|
|
const element = document.getElementById("my-file-input");
|
|
const source = element.files[0];
|
|
const info = await db.replaceService("/hello", source);
|
|
```
|
|
|
|
## database.upgradeService
|
|
|
|
`async database.upgradeService(mount, source, [options]): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Replaces an existing service with a new service while retaining the old
|
|
service's configuration and dependencies.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
- **source**: `Buffer | Readable | File | string`
|
|
|
|
The service bundle to replace the existing service with.
|
|
|
|
- **options**: `Object` (optional)
|
|
|
|
An object with any of the following properties:
|
|
|
|
- **configuration**: `Object` (optional)
|
|
|
|
An object mapping configuration option names to values.
|
|
|
|
This configuration will be merged into the existing configuration.
|
|
|
|
- **dependencies**: `Object` (optional)
|
|
|
|
An object mapping dependency aliases to mount points.
|
|
|
|
These dependencies will be merged into the existing dependencies.
|
|
|
|
- **development**: `boolean` (Default: `false`)
|
|
|
|
Whether the new service should be installed in development mode.
|
|
|
|
- **legacy**: `boolean` (Default: `false`)
|
|
|
|
Whether the new service should be installed in legacy compatibility mode.
|
|
|
|
This overrides the `engines` option in the service manifest (if any).
|
|
|
|
- **teardown**: `boolean` (Default: `false`)
|
|
|
|
Whether the teardown script of the old service should be executed.
|
|
|
|
- **setup**: `boolean` (Default: `true`)
|
|
|
|
Whether the setup script of the new service should be executed.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const source = fs.createReadStream("./my-foxx-service.zip");
|
|
const info = await db.upgradeService("/hello", source);
|
|
|
|
// -- or --
|
|
|
|
const source = fs.readFileSync("./my-foxx-service.zip");
|
|
const info = await db.upgradeService("/hello", source);
|
|
|
|
// -- or --
|
|
|
|
const element = document.getElementById("my-file-input");
|
|
const source = element.files[0];
|
|
const info = await db.upgradeService("/hello", source);
|
|
```
|
|
|
|
## database.uninstallService
|
|
|
|
`async database.uninstallService(mount, [options]): void`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Completely removes a service from the database.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
- **options**: `Object` (optional)
|
|
|
|
An object with any of the following properties:
|
|
|
|
- **teardown**: `boolean` (Default: `true`)
|
|
|
|
Whether the teardown script should be executed.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
await db.uninstallService("/my-service");
|
|
// service was uninstalled
|
|
```
|
|
|
|
## database.getService
|
|
|
|
`async database.getService(mount): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Retrieves information about a mounted service.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const info = await db.getService("/my-service");
|
|
// info contains detailed information about the service
|
|
```
|
|
|
|
## database.getServiceConfiguration
|
|
|
|
`async database.getServiceConfiguration(mount, [minimal]): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Retrieves an object with information about the service's configuration options
|
|
and their current values.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
- **minimal**: `boolean` (Default: `false`)
|
|
|
|
Only return the current values.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const config = await db.getServiceConfiguration("/my-service");
|
|
// config contains information about the service's configuration
|
|
```
|
|
|
|
## database.replaceServiceConfiguration
|
|
|
|
`async database.replaceServiceConfiguration(mount, configuration, [minimal]): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Replaces the configuration of the given service.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
- **configuration**: `Object`
|
|
|
|
An object mapping configuration option names to values.
|
|
|
|
- **minimal**: `boolean` (Default: `false`)
|
|
|
|
Only return the current values and warnings (if any).
|
|
|
|
**Note:** when using ArangoDB 3.2.8 or older, enabling this option avoids
|
|
triggering a second request to the database.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const config = { currency: "USD", locale: "en-US" };
|
|
const info = await db.replaceServiceConfiguration("/my-service", config);
|
|
// info.values contains information about the service's configuration
|
|
// info.warnings contains any validation errors for the configuration
|
|
```
|
|
|
|
## database.updateServiceConfiguration
|
|
|
|
`async database.updateServiceConfiguration(mount, configuration, [minimal]): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Updates the configuration of the given service my merging the new values into
|
|
the existing ones.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
- **configuration**: `Object`
|
|
|
|
An object mapping configuration option names to values.
|
|
|
|
- **minimal**: `boolean` (Default: `false`)
|
|
|
|
Only return the current values and warnings (if any).
|
|
|
|
**Note:** when using ArangoDB 3.2.8 or older, enabling this option avoids
|
|
triggering a second request to the database.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const config = { locale: "en-US" };
|
|
const info = await db.updateServiceConfiguration("/my-service", config);
|
|
// info.values contains information about the service's configuration
|
|
// info.warnings contains any validation errors for the configuration
|
|
```
|
|
|
|
## database.getServiceDependencies
|
|
|
|
`async database.getServiceDependencies(mount, [minimal]): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Retrieves an object with information about the service's dependencies and their
|
|
current mount points.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
- **minimal**: `boolean` (Default: `false`)
|
|
|
|
Only return the current values and warnings (if any).
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const deps = await db.getServiceDependencies("/my-service");
|
|
// deps contains information about the service's dependencies
|
|
```
|
|
|
|
## database.replaceServiceDependencies
|
|
|
|
`async database.replaceServiceDependencies(mount, dependencies, [minimal]): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Replaces the dependencies for the given service.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
- **dependencies**: `Object`
|
|
|
|
An object mapping dependency aliases to mount points.
|
|
|
|
- **minimal**: `boolean` (Default: `false`)
|
|
|
|
Only return the current values and warnings (if any).
|
|
|
|
**Note:** when using ArangoDB 3.2.8 or older, enabling this option avoids
|
|
triggering a second request to the database.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const deps = { mailer: "/mailer-api", auth: "/remote-auth" };
|
|
const info = await db.replaceServiceDependencies("/my-service", deps);
|
|
// info.values contains information about the service's dependencies
|
|
// info.warnings contains any validation errors for the dependencies
|
|
```
|
|
|
|
## database.updateServiceDependencies
|
|
|
|
`async database.updateServiceDependencies(mount, dependencies, [minimal]): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Updates the dependencies for the given service by merging the new values into
|
|
the existing ones.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
- **dependencies**: `Object`
|
|
|
|
An object mapping dependency aliases to mount points.
|
|
|
|
- **minimal**: `boolean` (Default: `false`)
|
|
|
|
Only return the current values and warnings (if any).
|
|
|
|
**Note:** when using ArangoDB 3.2.8 or older, enabling this option avoids
|
|
triggering a second request to the database.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const deps = { mailer: "/mailer-api" };
|
|
const info = await db.updateServiceDependencies("/my-service", deps);
|
|
// info.values contains information about the service's dependencies
|
|
// info.warnings contains any validation errors for the dependencies
|
|
```
|
|
|
|
## database.enableServiceDevelopmentMode
|
|
|
|
`async database.enableServiceDevelopmentMode(mount): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Enables development mode for the given service.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const info = await db.enableServiceDevelopmentMode("/my-service");
|
|
// the service is now in development mode
|
|
// info contains detailed information about the service
|
|
```
|
|
|
|
## database.disableServiceDevelopmentMode
|
|
|
|
`async database.disableServiceDevelopmentMode(mount): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Disabled development mode for the given service and commits the service state to
|
|
the database.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const info = await db.disableServiceDevelopmentMode("/my-service");
|
|
// the service is now in production mode
|
|
// info contains detailed information about the service
|
|
```
|
|
|
|
## database.listServiceScripts
|
|
|
|
`async database.listServiceScripts(mount): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Retrieves a list of the service's scripts.
|
|
|
|
Returns an object mapping each name to a more readable representation.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const scripts = await db.listServiceScripts("/my-service");
|
|
// scripts is an object listing the service scripts
|
|
```
|
|
|
|
## database.runServiceScript
|
|
|
|
`async database.runServiceScript(mount, name, [scriptArg]): any`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Runs a service script and returns the result.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
- **name**: `string`
|
|
|
|
Name of the script to execute.
|
|
|
|
- **scriptArg**: `any`
|
|
|
|
Value that will be passed as an argument to the script.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const result = await db.runServiceScript("/my-service", "setup");
|
|
// result contains the script's exports (if any)
|
|
```
|
|
|
|
## database.runServiceTests
|
|
|
|
`async database.runServiceTests(mount, [reporter]): any`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Runs the tests of a given service and returns a formatted report.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database
|
|
|
|
- **options**: `Object` (optional)
|
|
|
|
An object with any of the following properties:
|
|
|
|
- **reporter**: `string` (Default: `default`)
|
|
|
|
The reporter to use to process the test results.
|
|
|
|
As of ArangoDB 3.2 the following reporters are supported:
|
|
|
|
- **stream**: an array of event objects
|
|
- **suite**: nested suite objects with test results
|
|
- **xunit**: JSONML representation of an XUnit report
|
|
- **tap**: an array of TAP event strings
|
|
- **default**: an array of test results
|
|
|
|
- **idiomatic**: `boolean` (Default: `false`)
|
|
|
|
Whether the results should be converted to the apropriate `string`
|
|
representation:
|
|
|
|
- **xunit** reports will be formatted as XML documents
|
|
- **tap** reports will be formatted as TAP streams
|
|
- **stream** reports will be formatted as JSON-LD streams
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const opts = { reporter: "xunit", idiomatic: true };
|
|
const result = await db.runServiceTests("/my-service", opts);
|
|
// result contains the XUnit report as a string
|
|
```
|
|
|
|
## database.downloadService
|
|
|
|
`async database.downloadService(mount): Buffer | Blob`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Retrieves a zip bundle containing the service files.
|
|
|
|
Returns a `Buffer` in Node or `Blob` in the browser version.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const bundle = await db.downloadService("/my-service");
|
|
// bundle is a Buffer/Blob of the service bundle
|
|
```
|
|
|
|
## database.getServiceReadme
|
|
|
|
`async database.getServiceReadme(mount): string?`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Retrieves the text content of the service's `README` or `README.md` file.
|
|
|
|
Returns `undefined` if no such file could be found.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const readme = await db.getServiceReadme("/my-service");
|
|
// readme is a string containing the service README's
|
|
// text content, or undefined if no README exists
|
|
```
|
|
|
|
## database.getServiceDocumentation
|
|
|
|
`async database.getServiceDocumentation(mount): Object`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Retrieves a Swagger API description object for the service installed at the
|
|
given mount point.
|
|
|
|
**Arguments**
|
|
|
|
- **mount**: `string`
|
|
|
|
The service's mount point, relative to the database.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
const spec = await db.getServiceDocumentation("/my-service");
|
|
// spec is a Swagger API description of the service
|
|
```
|
|
|
|
## database.commitLocalServiceState
|
|
|
|
`async database.commitLocalServiceState([replace]): void`
|
|
|
|
{% hint 'info' %}
|
|
This method is only available when targeting ArangoDB 3.2 or later,
|
|
see [Compatibility](js-getting-started.html#compatibility).
|
|
{% endhint %}
|
|
|
|
Writes all locally available services to the database and updates any service
|
|
bundles missing in the database.
|
|
|
|
**Arguments**
|
|
|
|
- **replace**: `boolean` (Default: `false`)
|
|
|
|
Also commit outdated services.
|
|
|
|
This can be used to solve some consistency problems when service bundles are
|
|
missing in the database or were deleted manually.
|
|
|
|
**Examples**
|
|
|
|
```js
|
|
await db.commitLocalServiceState();
|
|
// all services available on the coordinator have been written to the db
|
|
|
|
// -- or --
|
|
|
|
await db.commitLocalServiceState(true);
|
|
// all service conflicts have been resolved in favor of this coordinator
|
|
```
|