Scripts and scheduling
In addition to the main entry point which defines your service’sroutes andexports you can define scriptsthat need to be invoked directly and can be used to implement one-off tasksor scheduled and recurring jobs using queues.
These scripts can be declared in the scripts
section ofthe service manifest:
"scripts": {
"setup": "scripts/setup.js",
"send-mail": "scripts/send-mail.js"
}
Invoking scripts
Scripts can be invoked manually usingthe web interface,the Foxx CLI orthe Foxx HTTP API.
Additionally the special setup
and teardown
lifecycle scripts canbe invoked automatically by Foxx as part of a service’s lifecycle (see below).
Script arguments and return values
When invoking a script any arguments will be exposed to the script as theargv
array property of the service context.
Any value exported by the script using module.exports
will be the script’sreturn value. Please note that this data will be converted to JSON.
Any errors raised by the script will be handled depending on howthe script was invoked:
if the script was invoked manually (e.g. using the Foxx CLI), it will returnan error response using the exception’s
statusCode
property or500
.if the script was invoked from a Foxx job queue, the job’s failure counterwill be incremented and the job will be rescheduled ormarked as failed if no attempts remain.
Examples
The following script will use its argument to generate a personal greeting:
'use strict';
const { argv } = module.context;
module.exports = `Hello ${argv[0]}!`;
Lifecycle Scripts
Scripts named setup
or teardown
are considered lifecycle scripts andwill (by default) be invoked automatically by Foxx:
when a service is installed, upgraded or replaced, the new service’s
setup
script will be executed before it is mountedwhen a service is removed or replaced, the old service’s
teardown
script will be executed before it is unmountedwhen a service is upgraded, the old service’s
teardown
script _can_optionally be executed before it is unmounted
However it’s possible to override this behavior as needed.
Note that in these cases the scripts will always be invoked without argumentsand their exports will be ignored.
Setup Script
The setup script is typically used to create collections a service needs,to define indexes or to initialize collections with necessary datalike administrative accounts.
As the setup script may be executed more than once it should be treatedas reentrant: running the setup script again should not result in any errorsor duplicate data:
const { db } = require("@arangodb");
const users = module.context.collectionName("users");
if (!db._collection(users)) {
// This won't be run if the collection exists
const collection = db._createDocumentCollection(users);
collection.ensureIndex({
type: "hash",
unique: true,
fields: ["username"]
});
collection.save({
username: "admin",
password: auth.create("hunter2")
});
}
Teardown Script
The teardown script typically removes the collections and/ordocuments created by the service’s setup script.
In practice teardown scripts are rarely used due to the risk ofcatastrophic data loss when accidentally running the scriptwhile managing the service.
Migrations
Depending on the amount of data managed by the service and the amount of workthat needs to be done to prepare collections for the service,running a setup
script on every upgrade can be very expensive.
An alternative approach is to perform incremental steps in separatemigration scripts and run them manually after the service is installed.
A setup
script should always create all the collections a service usesbut any additional steps like creating indexes, importing data fixtures ormigrating existing data can safely be performed in separate scripts.
Queues
Services can schedule scripts of any service mounted in the same databaseusing Foxx queues:
"use strict";
const queues = require("@arangodb/foxx/queues");
const queue = queues.get("default");
// later
router.post("/signup", (req, res) => {
const user = performSignup(req.body);
// schedule sending welcome e-mail using a script
queue.push(
{
mount: module.context.mount, // i.e. this current service
name: "send-mail" // script name in the service manifest
},
{ to: user.email, body: welcomeEmailText } // arguments
);
});