Cloud Spanner Client - Class Transaction (1.85.0)

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();

Namespace

Google \ Cloud \ Spanner

Methods

__construct

Parameters
Name Description
operation Google\Cloud\Spanner\Operation

The Operation instance.
session Google\Cloud\Spanner\Session\Session

The session to use for spanner interactions.
transactionId string

[optional] The Transaction ID. If no ID is provided, the Transaction will be a Single-Use Transaction.
isRetry bool

Whether the transaction will automatically retry or not.
tag string

A transaction tag. Requests made using this transaction will use this as the transaction tag.
options array

Configuration Options.
↳ begin array

The begin Transaction options. Refer
mapper Google\Cloud\Spanner\ValueMapper

Consumed internally for properly map mutation data.

getCommitStats

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();
Returns
Type Description
array The commit stats

executeUpdate

See also:

Parameters
Name Description
sql string

The query string to execute.
options array

Configuration Options.
↳ parameters array

A key/value array of Query Parameters, where the key is represented in the query string prefixed by a @ symbol.
↳ types array

A key/value array of Query Parameter types. Generally, Google Cloud PHP can infer types. Explicit type declarations are required in the case of struct parameters, or when a null value exists as a parameter. Accepted values for primitive types are defined as constants on Google\Cloud\Spanner\Database, and are as follows: Database::TYPE_BOOL, Database::TYPE_INT64, Database::TYPE_FLOAT64, Database::TYPE_TIMESTAMP, Database::TYPE_DATE, Database::TYPE_STRING, Database::TYPE_BYTES. If the value is an array, use Google\Cloud\Spanner\ArrayType to declare the array parameter types. Likewise, for structs, use Google\Cloud\Spanner\StructType.
↳ requestOptions array

Request options. For more information on available options, please see the upstream documentation. Please note, if using the priority setting you may utilize the constants available on Google\Cloud\Spanner\V1\RequestOptions\Priority to set a value. Please note, the transactionTag setting will be ignored as the transaction tag should have already been set when creating the transaction.
Returns
Type Description
int The number of rows modified.

executeUpdateBatch

See also:

Parameters
Name Description
statements array[]

A list of DML statements to run. Each statement must contain a sql key, where the value is a DML string. If the DML contains placeholders, values are provided as a key/value array in key parameters. If parameter types are required, they must be provided in key types. Generally, Google Cloud PHP can infer types. Explicit type declarations are required in the case of struct parameters, or when a null value exists as a parameter. Accepted values for primitive types are defined as constants on Google\Cloud\Spanner\Database, and are as follows: Database::TYPE_BOOL, Database::TYPE_INT64, Database::TYPE_FLOAT64, Database::TYPE_TIMESTAMP, Database::TYPE_DATE, Database::TYPE_STRING, Database::TYPE_BYTES. If the value is an array, use Google\Cloud\Spanner\ArrayType to declare the array parameter types. Likewise, for structs, use Google\Cloud\Spanner\StructType.
options array

Configuration Options.
↳ requestOptions array

Request options. For more information on available options, please see the upstream documentation. Please note, if using the priority setting you may utilize the constants available on Google\Cloud\Spanner\V1\RequestOptions\Priority to set a value. Please note, the transactionTag setting will be ignored as the transaction tag should have already been set when creating the transaction.
Returns
Type Description
Google\Cloud\Spanner\BatchDmlResult

rollback

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();
Parameter
Name Description
options array

[optional] Configuration Options.
Returns
Type Description
void

commit

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();
Parameters
Name Description
options array

Configuration Options.
↳ mutations array

An array of mutations to commit. May be used instead of or in addition to enqueing mutations separately.
↳ returnCommitStats bool

If true, commit statistics will be returned and accessible via Google\Cloud\Spanner\Transaction::getCommitStats(). Defaults to false.
↳ maxCommitDelay Duration

The amount of latency this request is willing to incur in order to improve throughput. Defaults to null.
↳ requestOptions array

Request options. For more information on available options, please see the upstream documentation. Please note, if using the priority setting you may utilize the constants available on Google\Cloud\Spanner\V1\RequestOptions\Priority to set a value. Please note, the requestTag setting will be ignored as it is not supported for commit requests.
Returns
Type Description
Google\Cloud\Spanner\Timestamp The commit timestamp.

state

Retrieve the Transaction State.

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

Example:

$state = $transaction->state();
Returns
Type Description
int

isRetry

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!';
}
Returns
Type Description
bool