Managing Foxx services

database.listServices

async database.listServices([excludeSystem]): Array<Object>

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

Fetches a list of all installed service.

Arguments

• excludeSystem: boolean (Default: true)

  Whether system services should be excluded.

Examples

const services = await db.listServices();

// -- or --

const services = await db.listServices(false);

database.installService

async database.installService(mount, source, [options]): Object

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

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

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

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

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

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

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

await db.uninstallService("/my-service");
// service was uninstalled

database.getService

async database.getService(mount): Object

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

Retrieves information about a mounted service.

Arguments

• mount: string

  The service’s mount point, relative to the database.

Examples

const info = await db.getService("/my-service");
// info contains detailed information about the service

database.getServiceConfiguration

async database.getServiceConfiguration(mount, [minimal]): Object

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

const config = await db.getServiceConfiguration("/my-service");
// config contains information about the service's configuration

database.replaceServiceConfiguration

async database.replaceServiceConfiguration(mount, configuration, [minimal]): Object

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

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

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

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

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

const deps = await db.getServiceDependencies("/my-service");
// deps contains information about the service's dependencies

database.replaceServiceDependencies

async database.replaceServiceDependencies(mount, dependencies, [minimal]): Object

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

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

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

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

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

Enables development mode for the given service.

Arguments

• mount: string

  The service’s mount point, relative to the database.

Examples

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

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

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

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

const scripts = await db.listServiceScripts("/my-service");
// scripts is an object listing the service scripts

database.runServiceScript

async database.runServiceScript(mount, name, [scriptArg]): any

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

const result = await db.runServiceScript("/my-service", "setup");
// result contains the script's exports (if any)

database.runServiceTests

async database.runServiceTests(mount, [reporter]): any

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

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

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

const bundle = await db.downloadService("/my-service");
// bundle is a Buffer/Blob of the service bundle

database.getServiceReadme

async database.getServiceReadme(mount): string?

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

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

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

const spec = await db.getServiceDocumentation("/my-service");
// spec is a Swagger API description of the service

database.commitLocalServiceState

async database.commitLocalServiceState([replace]): void

Note: This method is only available when targeting ArangoDB 3.2 or later, see Compatibility.

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

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