BEGIN

Each statement within SurrealDB is run within its own transaction by default. The BEGIN statement can be used to modify this behaviour by running a group of statements inside a single transaction, either succeeding as a whole, or failing. Once all of the statements within a transaction succeed, then all of the data modifications can be made permanent by finalizing the transaction with a COMMIT statement at the end. If any statement within a transaction encounters an error or the transaction is manually cancelled (CANCEL), then any data modification made within the transaction is rolled back, and will not become a permanent part of the database.

Transactions run under snapshot isolation. Concurrent transactions do not block each other, and when two of them write the same record or the same unique index value, the one that commits second fails with a transaction conflict error and can be retried. See Transactions for the full isolation rules, and Unique indexes under concurrent writes for inserting a record exactly once.

Statement syntax

BEGIN [ TRANSACTION ];

Example usage

The following query shows example usage of this statement.

-- Start a new database transaction. Transactions are a way to ensure multiple operations
-- either all succeed or all fail, maintaining data integrity.
BEGIN TRANSACTION;

-- Create a new account with the ID 'one' and set its initial balance to 135605.16
CREATE account:one SET balance = 135605.16;

-- Create another new account with the ID 'two' and set its initial balance to 91031.31
CREATE account:two SET balance = 91031.31;

-- Update the balance of account 'one' by adding 300.00 to the current balance.
-- This could represent a deposit or other form of credit on the balance property.
UPDATE account:one SET balance += 300.00;

-- Update the balance of account 'two' by subtracting 300.00 from the current balance.
-- This could represent a withdrawal or other form of debit on the balance property.
UPDATE account:two SET balance -= 300.00;

-- Finalize the transaction. This will apply the changes to the database. If there was an error
-- during any of the previous steps within the transaction, all changes would be rolled back and
-- the database would remain in its initial state.
COMMIT TRANSACTION;

Returning early from a transaction

While all transactions require a final COMMIT or CANCEL statement in order to run, an early return can take place via the following:

• •

  An error inside one of the statements inside the transaction,

• •

  A THROW statement to return early with an error,

• •

  A RETURN statement to return early. This is often used to customise the output of a transaction.

An example of the above:

BEGIN;

CREATE account:one SET balance = 135605.16;
CREATE account:two SET balance = 91031.31, wants_to_send_money = true;

-- Read the field into a parameter before testing it. As of SurrealDB
-- 3.2.x, reading a record field directly inside an IF condition fails
-- with "Specify a database to use".
LET $wants_to_send = account:two.wants_to_send_money;

IF !$wants_to_send {
    THROW "Customer doesn't want to send any money!";
};

LET $first = UPDATE ONLY account:one SET balance += 300.00;
LET $second = UPDATE ONLY account:two SET balance -= 300.00;

RETURN "Money sent! Status:\n" + <string>$first + '\n' +
  <string>$second;

COMMIT;

'Money sent! Status:
{ balance: 135905.16f, id: account:one }
{ balance: 90731.31f, id: account:two, wants_to_send_money: true }'