Cloud Spanner Client - Class Transaction (1.76.1)

Reference documentation and code samples for the Cloud Spanner Client class Transaction.

Manages interaction with Cloud Spanner inside a Transaction.

Transactions can be started via Google\Cloud\Spanner\Database::runTransaction() (recommended) or via Google\Cloud\Spanner\Database::transaction(). Transactions should always call Google\Cloud\Spanner\Transaction::commit() or Google\Cloud\Spanner\Transaction::rollback() to ensure that locks are released in a timely manner.

If you do not plan on performing any writes in your transaction, a Google\Cloud\Spanner\Snapshot is a better solution which does not require a commit or rollback and does not lock any data.

Transactions may raise Google\Cloud\Core\Exception\AbortedException errors when the transaction cannot complete for any reason. In this case, the entire operation (all reads and writes) should be reapplied atomically. Google Cloud PHP handles this transparently when using Google\Cloud\Spanner\Database::runTransaction(). In other cases, it is highly recommended that applications implement their own retry logic.

Example:

use Google\Cloud\Spanner\SpannerClient;

$spanner = new SpannerClient();

$database = $spanner->connect('my-instance', 'my-database');

$database->runTransaction(function (Transaction $t) {
    // do stuff.

    $t->commit();
});

// Get a transaction to manage manually.
$transaction = $database->transaction();

Get the commit stats for this transaction. Commit stats are only available after commit has been called with return_commit_stats => true. If commit is called multiple times, only the commitStats for the last commit will be available.

Example:

$transaction->commit(["returnCommitStats" => true]);
$commitStats = $transaction->getCommitStats();

Enqueue an insert mutation.

Example:

$transaction->insert('Posts', [
    'ID' => 10,
    'title' => 'My New Post',
    'content' => 'Hello World'
]);

Enqueue one or more insert mutations.

Example:

$transaction->insertBatch('Posts', [
    [
        'ID' => 10,
        'title' => 'My New Post',
        'content' => 'Hello World'
    ]
]);

Enqueue an update mutation.

Example:

$transaction->update('Posts', [
    'ID' => 10,
    'title' => 'My New Post [Updated!]',
    'content' => 'Modified Content'
]);

Enqueue one or more update mutations.

Example:

$transaction->updateBatch('Posts', [
    [
        'ID' => 10,
        'title' => 'My New Post [Updated!]',
        'content' => 'Modified Content'
    ]
]);

Enqueue an insert or update mutation.

Example:

$transaction->insertOrUpdate('Posts', [
    'ID' => 10,
    'title' => 'My New Post',
    'content' => 'Hello World'
]);

Enqueue one or more insert or update mutations.

Example:

$transaction->insertOrUpdateBatch('Posts', [
    [
        'ID' => 10,
        'title' => 'My New Post',
        'content' => 'Hello World'
    ]
]);

Enqueue an replace mutation.

Example:

$transaction->replace('Posts', [
    'ID' => 10,
    'title' => 'My New Post [Replaced]',
    'content' => 'Hello Moon'
]);

Enqueue one or more replace mutations.

Example:

$transaction->replaceBatch('Posts', [
    [
        'ID' => 10,
        'title' => 'My New Post [Replaced]',
        'content' => 'Hello Moon'
    ]
]);

Enqueue an delete mutation.

Example:

$keySet = new KeySet([
    'keys' => [10]
]);

$transaction->delete('Posts', $keySet);

See also:

• ExecuteSqlRequest
• DML Syntax Guide

See also:

• ExecuteBatchDmlRequest

Roll back a transaction.

Rolls back a transaction, releasing any locks it holds. It is a good idea to call this for any transaction that includes one or more Read or ExecuteSql requests and ultimately decides not to commit.

This closes the transaction, preventing any future API calls inside it.

Rollback will NOT error if the transaction is not found or was already aborted.

Example:

$transaction->rollback();

Commit and end the transaction.

It is advised that transactions be run inside Google\Cloud\Spanner\Database::runTransaction() in order to take advantage of automated transaction retry in case of a transaction aborted error.

Example:

$transaction->commit();

Retrieve the Transaction State.

Will be one of Transaction::STATE_ACTIVE, Transaction::STATE_COMMITTED, or Transaction::STATE_ROLLED_BACK.

Example:

$state = $transaction->state();

Check whether the current transaction is a retry transaction.

When using Google\Cloud\Spanner\Database::runTransaction(), transactions are automatically retried when a conflict causes it to abort. In such cases, subsequent invocations of the transaction callable will provide a transaction where $transaction->isRetry() is true. This can be useful for debugging and understanding how code is working.

Example:

if ($transaction->isRetry()) {
    echo 'This is a retry transaction!';
}