# Transaction

The Transaction struct represents an interactive SurrealDB transaction that allows executing statements one at a time with commit or cancel control.

The `Transaction` struct represents an interactive SurrealDB transaction on a WebSocket connection. Unlike text-based transactions, interactive transactions allow executing statements one at a time and conditionally committing or canceling based on results. Transactions require SurrealDB v3+ and a WebSocket connection.

`Transaction` satisfies the [`sendable`](/docs/reference/golang/api/types.md#sendable) constraint, so all generic functions like [`Query`](/docs/reference/golang/api/core/db.md#query), [`Select`](/docs/reference/golang/api/core/db.md#select), [`Create`](/docs/reference/golang/api/core/db.md#create), etc. accept `*Transaction` directly. However, transactions do not support session state changes (authentication, namespace selection, variables) or [live queries](/docs/reference/golang/concepts/live-queries.md).

**Source:** [transaction.go](https://github.com/surrealdb/surrealdb.go/blob/main/transaction.go)

---

## Creating a transaction

### `db.Begin()` {#db-begin}

Starts a transaction on the default session.

```go title="Syntax"
tx, err := db.Begin(ctx)
```

**Returns:** `(*Transaction, error)`

Returns [`ErrTransactionsNotSupported`](/docs/reference/golang/api/errors.md#sentinel-errors) if the connection is not WebSocket.

### `session.Begin()` {#session-begin}

Starts a transaction within a specific session.

```go title="Syntax"
tx, err := session.Begin(ctx)
```

**Returns:** `(*Transaction, error)`

Returns [`ErrSessionClosed`](/docs/reference/golang/api/errors.md#sentinel-errors) if the session has been detached.

#### Examples

```go
tx, err := db.Begin(ctx)
if err != nil {
    log.Fatal(err)
}
defer tx.Cancel(ctx)

_, err = surrealdb.Create[any](ctx, tx, models.Table("events"), map[string]any{
    "type": "transfer",
    "amount": 100,
})
if err != nil {
    log.Fatal(err)
}

if err := tx.Commit(ctx); err != nil {
    log.Fatal(err)
}
```

---

## Properties

### `.ID()` {#id}

Returns the transaction's UUID.

```go title="Syntax"
id := tx.ID()
```

**Returns:** [`*models.UUID`](/docs/reference/golang/api/values/uuid.md)

### `.SessionID()` {#sessionid}

Returns the session UUID if the transaction was started within a [`Session`](/docs/reference/golang/api/core/session.md). Returns `nil` for transactions started on the default session.

```go title="Syntax"
sessionID := tx.SessionID()
```

**Returns:** [`*models.UUID`](/docs/reference/golang/api/values/uuid.md)

### `.IsClosed()` {#isclosed}

Returns whether the transaction has been committed or cancelled.

```go title="Syntax"
closed := tx.IsClosed()
```

**Returns:** `bool`

---

## Methods

### `.Commit()` {#commit}

Commits the transaction, making all changes permanent. After calling `.Commit()`, the transaction cannot be used.

```go title="Syntax"
err := tx.Commit(ctx)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>ctx</code> _(required)_</td>
            <td><code>context.Context</code></td>
            <td>Context for the operation.</td>
        </tr>
    </tbody>
</table>

**Returns:** `error`

Returns [`ErrTransactionClosed`](/docs/reference/golang/api/errors.md#sentinel-errors) if the transaction has already been committed or cancelled.

### `.Cancel()` {#cancel}

Cancels the transaction, discarding all changes. After calling `.Cancel()`, the transaction cannot be used.

It is safe to call `.Cancel()` on an already committed or cancelled transaction. It returns [`ErrTransactionClosed`](/docs/reference/golang/api/errors.md#sentinel-errors) but causes no harm, making it safe for use with `defer`.

```go title="Syntax"
err := tx.Cancel(ctx)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>ctx</code> _(required)_</td>
            <td><code>context.Context</code></td>
            <td>Context for the operation.</td>
        </tr>
    </tbody>
</table>

**Returns:** `error`

---

## See also

- [DB](/docs/reference/golang/api/core/db.md) for starting transactions from the main client
- [Session](/docs/reference/golang/api/core/session.md) for starting transactions from sessions
- [Transactions](/docs/reference/golang/concepts/transactions.md) for transaction usage patterns
- [Errors](/docs/reference/golang/api/errors.md) for `ErrTransactionClosed` and `ErrTransactionsNotSupported`