Transactions

These functions implement the HTTP API for JS transactions. Also see ArangoDB Transactions.

database.executeTransaction

async database.executeTransaction(collections, action, [options]): Object

Performs a server-side transaction and returns its return value.

Arguments

If collections is an array, string or Collection, it will be treated as collections.write.

Please note that while action should be a string evaluating to a well-formed JavaScript function, it’s not possible to pass in a JavaScript function directly because the function needs to be evaluated on the server and will be transmitted in plain text.

Examples

const db = new Database();

const action = String(function (params) {
  // This code will be executed inside ArangoDB!
  const { query } = require("@arangodb");
  return query`
      FOR user IN _users
      FILTER user.age > ${params.age}
      RETURN u.user
    `.toArray();
});

const result = await db.executeTransaction("_users", action, {
  params: { age: 12 },
});
// result contains the return value of the action

database.transaction

database.transaction(id): Transaction

Returns a Transaction instance for an existing transaction with the given id.

Warning: For backwards-compatibility with arangojs 6.10 and earlier, this method will behave like executeTransaction when passed the following arguments:

If params or options is a number, it will be treated as options.lockTimeout.

This behavior is deprecated and will be removed in arangojs 7.

Examples

const trx1 = await db.beginTransaction(collections);
const id = trx1.id;
// later
const trx2 = db.transaction(id);
await trx2.commit();

database.beginTransaction

async database.beginTransaction(collections, [options]): Transaction

Begins a new streaming transaction for the given collections, then returns a Transaction instance for the transaction.

Arguments

If collections is an array, string or Collection, it will be treated as collections.write.

Examples

const vertices = db.collection("vertices");
const edges = db.collection("edges");
const trx = await db.beginTransaction({
  read: ["vertices"],
  write: [edges], // collection instances can be passed directly
});
const start = await trx.run(() => vertices.document("a"));
const end = await trx.run(() => vertices.document("b"));
await trx.run(() => edges.save({ _from: start._id, _to: end._id }));
await trx.commit();

database.listTransactions

async database.listTransactions(): Array<Object>

Fetches all transactions visible in the database and returns an array of transaction descriptions.

Examples

const collection = db.collection("data");
const trx = await db.beginTransaction(collection);
const info = await db.listTransactions();
// [{id: "1234", state: "running"}]

database.transactions

async database.transactions(): Array<Transaction>

Fetches all transactions visible in the database and returns an array of Transaction instances for those transactions.

Examples

const collection = db.collection("data");
await db.beginTransaction(collection);
const transactions = await db.transactions();
for (const trx of transactions) {
  const info = await trx.get();
  // {id: "1234", status: "running"}
}

transaction.exists

async transaction.exists(): boolean

Checks whether the transaction exists.

Examples

const db = new Database();
const transaction = db.transaction("some-transaction");
const result = await transaction.exists();
// result indicates whether the transaction exists

transaction.get

async transaction.get(): Object

Retrieves general information about the transaction.

Examples

const db = new Database();
const transaction = db.transaction("some-transaction");
const result = await transaction.get();
// result indicates the transaction id and status

transaction.commit

async transaction.commit(): Object

Attempts to commit the transaction to the database, then returns an object indicating the transaction’s id and updated status.

Examples

const db = new Database();
const transaction = db.transaction("some-transaction");
const result = await transaction.commit();
// result indicates the transaction id and updated status

transaction.abort

async transaction.abort(): Object

Attempts to abort the transaction in the database, then returns an object indicating the transaction’s id and updated status.

Examples

const db = new Database();
const transaction = db.transaction("some-transaction");
const result = await transaction.abort();
// result indicates the transaction id and updated status

transaction.run

async transaction.run(fn): any

Executes the given function locally within the transaction and returns a promise for its result.

Arguments

Unlike executeTransaction, functions passed to run will be executed locally on the client, not on the server.

Examples

const col1 = db.collection(name1);
const col2 = db.collection(name2);
const trx = await db.beginTransaction(collections);

// The following code will run in the transaction
const meta1 = await trx.run(() => col1.save({ data: "doc1" }));
const meta2 = await trx.run(() => col1.save({ data: "doc2" }));

// Results from preceding actions can be used normally
await trx.run(() =>
  col2.save({ _from: meta1._id, to: meta2._id, data: "edge1" })
);

// Promise.all can be used to run multiple actions in parallel
await Promise.all([
  trx.run(() => col2.save({ _from: meta1._id, _to: meta2._id, data: "edge2" })),
  trx.run(() => col2.save({ _from: meta1._id, _to: meta2._id, data: "edge3" })),
]);
await trx.run(() =>
  Promise.all([
    col2.save({ _from: meta1._id, _to: meta2._id, data: "edge4" }),
    col2.save({ _from: meta1._id, _to: meta2._id, data: "edge5" }),
  ])
);

// DANGER! The following examples demonstrate common mistakes!

await trx.run(async () => {
  // The first line runs in the transaction
  await col1.save({ data: "doc3" });
  // The next line will run outside the transaction because it comes
  // after the first await and is executed asynchronously!
  await col1.save({ data: "doc4" });
});

await trx.run(() =>
  // The first line runs in the transaction
  col1
    .save({ data: "doc5" })
    // The next line will run outside the transaction because
    // it is executed in an asynchronous callback!
    .then(() => col1.save({ data: "doc6" }))
);

// While not an error, wrapping synchronous methods in "run" is unnecessary.
await trx.run(() => db.collection(name1));

await trx.run(() => {
  // This method returns a promise but we forget to return it. Note that the
  // request will still be executed, we just don't know when/if it completed.
  col1.save({ data: "doc7" });
});

// Remember to always wait for all actions to resolve before committing.
// The following line is missing the "await" and creates a race condition.
trx.run(() => col1.save({ data: "doc8" }));

// All actions run as part of a stream transaction will only take effect if
// the transaction is committed. Make sure to always call "commit" or "abort".
await trx.commit();