# Transactions

The .NET SDK supports atomic transactions for executing multiple queries that succeed or fail together.

Transactions allow you to execute a group of queries atomically, meaning either all changes are applied or none are. This is essential for maintaining data consistency when performing related operations that must not be partially applied.

<table>
  <thead>
    <tr>
      <th scope="col">Method</th>
      <th scope="col">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td scope="row" data-label="Method">
        <a href="#begintransaction">
          <code> session.BeginTransaction() </code>
        </a>
      </td>
      <td scope="row" data-label="Description">
        Create a new transaction scoped to the current session.
      </td>
    </tr>
    <tr>
      <td scope="row" data-label="Method">
        <a href="#commit">
          <code> txn.Commit() </code>
        </a>
      </td>
      <td scope="row" data-label="Description">
        Commit the transaction to the database, applying all changes made within
        the transaction scope.
      </td>
    </tr>
    <tr>
      <td scope="row" data-label="Method">
        <a href="#cancel">
          <code> txn.Cancel() </code>
        </a>
      </td>
      <td scope="row" data-label="Description">
        Cancel and discard all changes made in the transaction.
      </td>
    </tr>
  </tbody>
</table>

## `.BeginTransaction()` {#begintransaction}

Creates a new transaction scoped to the current session. Transactions allow you to execute multiple queries atomically.

```csharp title="Method Syntax"
await session.BeginTransaction(cancellationToken)
```

### Arguments

<table>
  <thead>
    <tr>
      <th colspan="2" scope="col">
        Arguments
      </th>
      <th colspan="2" scope="col">
        Description
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td colspan="2" scope="row" data-label="Arguments">
        <code>cancellationToken</code>
        <label label="optional" />
      </td>
      <td colspan="2" scope="row" data-label="Description">
        The cancellationToken enables graceful cancellation of asynchronous
        operations.
      </td>
    </tr>
  </tbody>
</table>

### Example usage

```csharp
// Begin a new transaction on the current session
await using var txn = await db.BeginTransaction();

// Execute queries within the transaction
await txn.Create("person", new { Name = "John" });
await txn.Create("person", new { Name = "Jane" });

// Commit all changes atomically
await txn.Commit();
```

<br />

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

Commits the transaction to the database, applying all changes made within the transaction scope.

> [!NOTE]
> After committing, the transaction cannot be used again.

```csharp title="Method Syntax"
await txn.Commit(cancellationToken)
```

### Arguments

<table>
  <thead>
    <tr>
      <th colspan="2" scope="col">
        Arguments
      </th>
      <th colspan="2" scope="col">
        Description
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td colspan="2" scope="row" data-label="Arguments">
        <code>cancellationToken</code>
        <label label="optional" />
      </td>
      <td colspan="2" scope="row" data-label="Description">
        The cancellationToken enables graceful cancellation of asynchronous
        operations.
      </td>
    </tr>
  </tbody>
</table>

### Example usage

```csharp
await using var txn = await db.BeginTransaction();

await txn.Create("order", new { Total = 99.99 });
await txn.Create("invoice", new { OrderId = "order:1" });

// Commit all changes - either both succeed or neither does
await txn.Commit();
```

<br />

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

Cancels and discards all changes made in the transaction.

> [!NOTE]
> After canceling, the transaction cannot be used again.

```csharp title="Method Syntax"
await txn.Cancel(cancellationToken)
```

### Arguments

<table>
  <thead>
    <tr>
      <th colspan="2" scope="col">
        Arguments
      </th>
      <th colspan="2" scope="col">
        Description
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td colspan="2" scope="row" data-label="Arguments">
        <code>cancellationToken</code>
        <label label="optional" />
      </td>
      <td colspan="2" scope="row" data-label="Description">
        The cancellationToken enables graceful cancellation of asynchronous
        operations.
      </td>
    </tr>
  </tbody>
</table>

### Example usage

```csharp
await using var txn = await db.BeginTransaction();

try
{
    await txn.Create("order", new { Total = 99.99 });

    // ... more operations

    await txn.Commit();
}
catch
{
    // Discard all changes on error
    await txn.Cancel();
}
```