Transaction invocation

ArangoDB transactions are different from transactions in SQL.

In SQL, transactions are started with explicit BEGIN or START TRANSACTION command. Following any series of data retrieval or modification operations, an SQL transaction is finished with a COMMIT command, or rolled back with a ROLLBACK command. There may be client/server communication between the start and the commit/rollback of an SQL transaction.

In ArangoDB, a transaction is always a server-side operation, and is executed on the server in one go, without any client interaction. All operations to be executed inside a transaction need to be known by the server when the transaction is started.

There are no individual BEGIN, COMMIT or ROLLBACK transaction commands in ArangoDB. Instead, a transaction in ArangoDB is started by providing a description of the transaction to the db._executeTransaction JavaScript function:

  1. db._executeTransaction(description);

This function will then automatically start a transaction, execute all required data retrieval and/or modification operations, and at the end automatically commit the transaction. If an error occurs during transaction execution, the transaction is automatically aborted, and all changes are rolled back.

Execute transaction

executes a transaction db._executeTransaction(object)

Executes a server-side transaction, as specified by object.

object must have the following attributes:

  • collections: a sub-object that defines which collections will be used in the transaction. collections can have these attributes:
    • read: a single collection or a list of collections that will be used in the transaction in read-only mode
    • write: a single collection or a list of collections that will be used in the transaction in write or read mode.
  • action: a Javascript function or a string with Javascript code containing all the instructions to be executed inside the transaction. If the code runs through successfully, the transaction will be committed at the end. If the code throws an exception, the transaction will be rolled back and all database operations will be rolled back.

Additionally, object can have the following optional attributes:

  • waitForSync: boolean flag indicating whether the transaction is forced to be synchronous.
  • lockTimeout: a numeric value that can be used to set a timeout for waiting on collection locks. If not specified, a default value will be used. Setting lockTimeout to 0 will make ArangoDB not time out waiting for a lock.
  • params: optional arguments passed to the function specified in action.
  • maxTransactionSize: transaction size limit in bytes

Declaration of collections

All collections which are to participate in a transaction need to be declared beforehand. This is a necessity to ensure proper locking and isolation.

Collections can be used in a transaction in write mode or in read-only mode.

If any data modification operations are to be executed, the collection must be declared for use in write mode. The write mode allows modifying and reading data from the collection during the transaction (i.e. the write mode includes the read mode).

Contrary, using a collection in read-only mode will only allow performing read operations on a collection. Any attempt to write into a collection used in read-only mode will make the transaction fail.

Collections for a transaction are declared by providing them in the collections attribute of the object passed to the _executeTransaction function. The collections attribute has the sub-attributes read and write:

  1. db._executeTransaction({
  2.   collections: {
  3.     write: [ "users", "logins" ],
  4.     read: [ "recommendations" ]
  5.   }
  6. });

read and write are optional attributes, and only need to be specified if the operations inside the transactions demand for it.

The contents of read or write can each be lists arrays collection names or a single collection name (as a string):

  1. db._executeTransaction({
  2.   collections: {
  3.     write: "users",
  4.     read: "recommendations"
  5.   }
  6. });

Note: It is currently optional to specify collections for read-only access. Even without specifying them, it is still possible to read from such collections from within a transaction, but with relaxed isolation. Please refer to Transactions Locking for more details.

In order to make a transaction fail when a non-declared collection is used inside for reading, the optional allowImplicit sub-attribute of collections can be set to false:

  1. db._executeTransaction({
  2.   collections: {
  3.     read: "recommendations",
  4.     allowImplicit: false  /* this disallows read access to other collections
  5.                              than specified */
  6.   },
  7.   action: function () {
  8.     var db = require("@arangodb").db;
  9.     return db.foobar.toArray(); /* will fail because db.foobar must not be accessed
  10.                                    for reading inside this transaction */
  11.   }
  12. });

The default value for allowImplicit is true. Write-accessing collections that have not been declared in the collections array is never possible, regardless of the value of allowImplicit.

Declaration of data modification and retrieval operations

All data modification and retrieval operations that are to be executed inside the transaction need to be specified in a Javascript function, using the action attribute:

  1. db._executeTransaction({
  2.   collections: {
  3.     write: "users"
  4.   },
  5.   action: function () {
  6.     // all operations go here
  7.   }
  8. });

Any valid Javascript code is allowed inside action but the code may only access the collections declared in collections. action may be a Javascript function as shown above, or a string representation of a Javascript function:

  1. db._executeTransaction({
  2.   collections: {
  3.     write: "users"
  4.   },
  5.   action: "function () { doSomething(); }"
  6. });

Please note that any operations specified in action will be executed on the server, in a separate scope. Variables will be bound late. Accessing any JavaScript variables defined on the client-side or in some other server context from inside a transaction may not work. Instead, any variables used inside action should be defined inside action itself:

  1. db._executeTransaction({
  2.   collections: {
  3.     write: "users"
  4.   },
  5.   action: function () {
  6.     var db = require(...).db;
  7.     db.users.save({ ... });
  8.   }
  9. });

When the code inside the action attribute is executed, the transaction is already started and all required locks have been acquired. When the code inside the action attribute finishes, the transaction will automatically commit. There is no explicit commit command.

To make a transaction abort and roll back all changes, an exception needs to be thrown and not caught inside the transaction:

  1. db._executeTransaction({
  2.   collections: {
  3.     write: "users"
  4.   },
  5.   action: function () {
  6.     var db = require("@arangodb").db;
  7.     db.users.save({ _key: "hello" });
  8.     // will abort and roll back the transaction
  9.     throw "doh!";
  10.   }
  11. });

There is no explicit abort or roll back command.

As mentioned earlier, a transaction will commit automatically when the end of the action function is reached and no exception has been thrown. In this case, the user can return any legal JavaScript value from the function:

  1. db._executeTransaction({
  2.   collections: {
  3.     write: "users"
  4.   },
  5.   action: function () {
  6.     var db = require("@arangodb").db;
  7.     db.users.save({ _key: "hello" });
  8.     // will commit the transaction and return the value "hello"
  9.     return "hello";
  10.   }
  11. });

Throwing Arango Exceptions

If you catch errors in your transaction, try to get them solved, but fail you may want to mimic original arangodb error messages to ease the control flow of your invoking environment. This can be done like this:

  1. db._executeTransaction({
  2.   collections: {},
  3.   action: function () {
  4.     const arangodb = require('@arangodb');
  5.     var err = new arangodb.ArangoError();
  6.     err.errorNum = arangodb.ERROR_BAD_PARAMETER;
  7.     err.errorMessage = "who's bad?";
  8.     throw err;
  9.   }
  10. });

The documentation contains a complete list of used arangodb errors in the appendix

Custom exceptions

One may wish to define custom exceptions inside of a transaction. To have the exception propagate upwards properly, please throw an an instance of base JavaScript Error class or a derivative. To specify an error number, include it as the errorNumber field. As an example:

  1. db._executeTransaction({
  2.   collections: {},
  3.   action: function () {
  4.     var err = new Error('My error context');
  5.     err.errorNum = 1234;
  6.     throw err;
  7.   }
  8. });

Note: In previous versions, custom exceptions which did not have an Error-like form were simply converted to strings and exposed in the exception field of the returned error. This is no longer the case, as it had the potential to leak unwanted information if improperly used.

Note: In some versions the above example wouldn’t propagate the errorNum to the invoking party, you may need to upgrade your ArangoDB.

Examples

The first example will write 3 documents into a collection named c1. The c1 collection needs to be declared in the write attribute of the collections attribute passed to the executeTransaction function.

The action attribute contains the actual transaction code to be executed. This code contains all data modification operations (3 in this example).

  1. // setup
  2. db._create("c1");
  4. db._executeTransaction({
  5.   collections: {
  6.     write: [ "c1" ]
  7.   },
  8.   action: function () {
  9.     var db = require("@arangodb").db;
  10.     db.c1.save({ _key: "key1" });
  11.     db.c1.save({ _key: "key2" });
  12.     db.c1.save({ _key: "key3" });
  13.   }
  14. });
  15.     db.c1.count(); // 3

Aborting the transaction by throwing an exception in the action function will revert all changes, so as if the transaction never happened:

  1. // setup
  2. db._create("c1");
  4. db._executeTransaction({
  5.   collections: {
  6.     write: [ "c1" ]
  7.   },
  8.   action: function () {
  9.     var db = require("@arangodb").db;
  10.     db.c1.save({ _key: "key1" });
  11.     db.c1.count(); // 1
  12.     db.c1.save({ _key: "key2" });
  13.     db.c1.count(); // 2
  14.     throw "doh!";
  15.   }
  16. });
  18. db.c1.count(); // 0

The automatic rollback is also executed when an internal exception is thrown at some point during transaction execution:

  1. // setup
  2. db._create("c1");
  4. db._executeTransaction({
  5.   collections: {
  6.     write: [ "c1" ]
  7.   },
  8.   action: function () {
  9.     var db = require("@arangodb").db;
  10.     db.c1.save({ _key: "key1" });
  11.     // will throw duplicate a key error, not explicitly requested by the user
  12.     db.c1.save({ _key: "key1" });  
  13.     // we'll never get here...
  14.   }
  15. });
  17. db.c1.count(); // 0

As required by the consistency principle, aborting or rolling back a transaction will also restore secondary indexes to the state at transaction start.

Cross-collection transactions

There’s also the possibility to run a transaction across multiple collections. In this case, multiple collections need to be declared in the collections attribute, e.g.:

  1. // setup
  2. db._create("c1");
  3. db._create("c2");
  5. db._executeTransaction({
  6.   collections: {
  7.     write: [ "c1", "c2" ]
  8.   },
  9.   action: function () {
  10.     var db = require("@arangodb").db;
  11.     db.c1.save({ _key: "key1" });
  12.     db.c2.save({ _key: "key2" });
  13.   }
  14. });
  16. db.c1.count(); // 1
  17. db.c2.count(); // 1

Again, throwing an exception from inside the action function will make the transaction abort and roll back all changes in all collections:

  1. // setup
  2. db._create("c1");
  3. db._create("c2");
  5. db._executeTransaction({
  6.   collections: {
  7.     write: [ "c1", "c2" ]
  8.   },
  9.   action: function () {
  10.     var db = require("@arangodb").db;
  11.     for (var i = 0; i < 100; ++i) {
  12.       db.c1.save({ _key: "key" + i });
  13.       db.c2.save({ _key: "key" + i });
  14.     }
  15.     db.c1.count(); // 100
  16.     db.c2.count(); // 100
  17.     // abort
  18.     throw "doh!"
  19.   }
  20. });
  22. db.c1.count(); // 0
  23. db.c2.count(); // 0