Sign In

Python SDK Version

AsyncSurrealTransaction / BlockingSurrealTransaction

A transaction wraps a connection with both a session ID and a transaction ID, scoping all operations to a single atomic unit. Changes are applied only when the transaction is committed, and can be rolled back with cancel.

Transactions are created by calling .begin_transaction() on a session. They are not available on HTTP or embedded connections.

Source: async_ws.py · blocking_ws.py

Creating a Transaction

Method Syntax

txn = session.begin_transaction()

Returns (sync): BlockingSurrealTransaction Returns (async): AsyncSurrealTransaction

Examples

Synchronous

from surrealdb import Surreal

db = Surreal("ws://localhost:8000")
db.connect()
db.signin({"username": "root", "password": "root"})
db.use("my_namespace", "my_database")

session = db.new_session()
session.use("my_namespace", "my_database")

txn = session.begin_transaction()
txn.create("users", {"name": "Alice"})
txn.commit()

Asynchronous

from surrealdb import AsyncSurreal

db = AsyncSurreal("ws://localhost:8000")
await db.connect()
await db.signin({"username": "root", "password": "root"})
await db.use("my_namespace", "my_database")

session = await db.new_session()
await session.use("my_namespace", "my_database")

txn = await session.begin_transaction()
await txn.create("users", {"name": "Alice"})
await txn.commit()

Inherited Methods

A transaction exposes query and CRUD methods that mirror the parent connection's interface. All operations are scoped to this transaction and are not visible outside it until committed. For full parameter tables and examples, see the Surreal reference.

MethodReturnsDescription
.query(query, vars)ValueExecute a SurrealQL query within the transaction.
.select(record)ValueSelect records.
.create(record, data)ValueCreate a record.
.update(record, data)ValueReplace a record.
.merge(record, data)ValueMerge data into a record.
.patch(record, data)ValueApply JSON Patch operations.
.delete(record)ValueDelete records.
.insert(table, data)ValueInsert records.
.insert_relation(table, data)ValueInsert relation records.
.upsert(record, data)ValueUpsert a record.

Transaction-Specific Methods

.commit()

Commits the transaction, applying all changes made within it to the database. After committing, the transaction object should not be used.

Method Syntax

txn.commit()

Returns: None

Examples

Synchronous

txn = session.begin_transaction()
txn.create("users", {"name": "Alice", "email": "alice@example.com"})
txn.create("users", {"name": "Bob", "email": "bob@example.com"})
txn.commit()

Asynchronous

txn = await session.begin_transaction()
await txn.create("users", {"name": "Alice", "email": "alice@example.com"})
await txn.create("users", {"name": "Bob", "email": "bob@example.com"})
await txn.commit()

.cancel()

Cancels the transaction, discarding all changes made within it. No data is written to the database. After cancelling, the transaction object should not be used.

Method Syntax

txn.cancel()

Returns: None

Examples

Synchronous

txn = session.begin_transaction()
txn.delete("users")
txn.cancel()

Asynchronous

txn = await session.begin_transaction()
await txn.delete("users")
await txn.cancel()

Rollback on error

txn = session.begin_transaction()
try:
    txn.create("orders", {"product": "Laptop", "qty": 1})
    txn.update(RecordID("inventory", "laptop"), {"stock": -1})
    txn.commit()
except Exception:
    txn.cancel()

Complete Example

Atomic transfer (sync)

from surrealdb import Surreal, RecordID

with Surreal("ws://localhost:8000") as db:
    db.use("bank", "ledger")
    db.signin({"username": "root", "password": "root"})

    session = db.new_session()
    session.use("bank", "ledger")

    session.create(RecordID("accounts", "alice"), {"balance": 1000})
    session.create(RecordID("accounts", "bob"), {"balance": 500})

    txn = session.begin_transaction()
    try:
        txn.query(
            "UPDATE accounts:alice SET balance = balance - $amount",
            {"amount": 200},
        )
        txn.query(
            "UPDATE accounts:bob SET balance = balance + $amount",
            {"amount": 200},
        )
        txn.commit()
        print("Transfer committed")
    except Exception:
        txn.cancel()
        print("Transfer rolled back")

    accounts = session.select("accounts")
    print("Accounts:", accounts)

    session.close_session()

Atomic transfer (async)

import asyncio
from surrealdb import AsyncSurreal, RecordID

async def main():
    async with AsyncSurreal("ws://localhost:8000") as db:
        await db.use("bank", "ledger")
        await db.signin({"username": "root", "password": "root"})

        session = await db.new_session()
        await session.use("bank", "ledger")

        await session.create(RecordID("accounts", "alice"), {"balance": 1000})
        await session.create(RecordID("accounts", "bob"), {"balance": 500})

        txn = await session.begin_transaction()
        try:
            await txn.query(
                "UPDATE accounts:alice SET balance = balance - $amount",
                {"amount": 200},
            )
            await txn.query(
                "UPDATE accounts:bob SET balance = balance + $amount",
                {"amount": 200},
            )
            await txn.commit()
            print("Transfer committed")
        except Exception:
            await txn.cancel()
            print("Transfer rolled back")

        accounts = await session.select("accounts")
        print("Accounts:", accounts)

        await session.close_session()

asyncio.run(main())

See Also

  • SurrealSession — Session management reference

  • Surreal — Connection reference with full method documentation

  • Data Types — Type aliases and value types

  • Errors — Error classes reference

Was this page helpful?

Previous

SurrealSession

Next

Errors