Struct TransactionRunnerBuilder 

pub struct TransactionRunnerBuilder { /* private fields */ }

A builder for a TransactionRunner for a read/write transaction.

Example

let db_client = client.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client.read_write_transaction().build().await?;

let result = runner.run(async |transaction| {
    let statement = Statement::builder("UPDATE MyTable SET MyColumn = 'MyValue' WHERE Id = 1").build();
    transaction.execute_update(statement).await?;
    Ok(42)
}).await?;

Spanner can abort any read/write transaction at any time. A TransactionRunner automatically retries aborted transactions according to the configured retry policy.

Implementations

impl TransactionRunnerBuilder

pub fn with_transaction_timeout(self, timeout: StdDuration) -> Self

Sets the timeout for the entire transaction.

Example

let runner = db_client.read_write_transaction()
    .with_transaction_timeout(Duration::from_secs(5))
    .build()
    .await?;

This timeout applies to the total time spent executing the transaction, including all statements and automatic retries. Each individual RPC within the transaction is automatically assigned a deadline derived from the remaining time of this overall timeout.

pub fn with_begin_attempt_timeout(self, timeout: StdDuration) -> Self

Sets the per-attempt timeout for the BeginTransaction RPC.

Example

let db_client = spanner.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client.read_write_transaction()
    .with_begin_attempt_timeout(Duration::from_secs(5))
    .build()
    .await?;

Note: This timeout is only used if the transaction uses the ExplicitBegin transaction option.

pub fn with_begin_retry_policy(self, policy: impl Into<RetryPolicyArg>) -> Self

Sets the retry policy for the BeginTransaction RPC.

Example

let db_client = spanner.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client.read_write_transaction()
    .with_begin_retry_policy(NeverRetry)
    .build()
    .await?;

Note: This policy is only used if the transaction uses the ExplicitBegin transaction option.

pub fn with_begin_backoff_policy( self, policy: impl Into<BackoffPolicyArg>, ) -> Self

Sets the backoff policy for the BeginTransaction RPC.

Example

let db_client = spanner.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client.read_write_transaction()
    .with_begin_backoff_policy(ExponentialBackoff::default())
    .build()
    .await?;

Note: This policy is only used if the transaction uses the ExplicitBegin transaction option.

pub fn with_commit_attempt_timeout(self, timeout: StdDuration) -> Self

Sets the per-attempt timeout for the Commit RPC.

Example

let db_client = spanner.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client.read_write_transaction()
    .with_commit_attempt_timeout(Duration::from_secs(5))
    .build()
    .await?;

pub fn with_commit_retry_policy(self, policy: impl Into<RetryPolicyArg>) -> Self

Sets the retry policy for the Commit RPC.

Example

let db_client = spanner.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client.read_write_transaction()
    .with_commit_retry_policy(NeverRetry)
    .build()
    .await?;

pub fn with_commit_backoff_policy( self, policy: impl Into<BackoffPolicyArg>, ) -> Self

Sets the backoff policy for the Commit RPC.

Example

let db_client = spanner.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client.read_write_transaction()
    .with_commit_backoff_policy(ExponentialBackoff::default())
    .build()
    .await?;

pub fn set_isolation_level(self, isolation_level: IsolationLevel) -> Self

Sets the isolation level for the transaction.

Example

let db_client = client.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client
    .read_write_transaction()
    .set_isolation_level(IsolationLevel::Serializable)
    .build()
    .await?;

See also: https://docs.cloud.google.com/spanner/docs/isolation-levels

pub fn set_read_lock_mode(self, read_lock_mode: ReadLockMode) -> Self

Sets the read lock mode for the transaction.

Example

let db_client = client.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client
    .read_write_transaction()
    .set_read_lock_mode(ReadLockMode::Pessimistic)
    .build()
    .await?;

See also: https://docs.cloud.google.com/spanner/docs/concurrency-control

pub fn set_transaction_tag(self, tag: impl Into<String>) -> Self

Sets the transaction tag for the transaction.

Example

let db_client = spanner.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client.read_write_transaction()
    .set_transaction_tag("my-tag")
    .build()
    .await?;

The tag is applied to all statements executed within the transaction.

See also: Troubleshooting with tags

pub fn with_begin_transaction_option( self, option: BeginTransactionOption, ) -> Self

Sets the option for how to start a transaction.

Example

let db_client = client.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client
    .read_write_transaction()
    .with_begin_transaction_option(BeginTransactionOption::ExplicitBegin)
    .build()
    .await?;

By default, the Spanner client will inline the BeginTransaction call with the first query or DML statement in the transaction. This reduces the number of round-trips to Spanner that are needed for a transaction. Setting this option to ExplicitBegin can be beneficial for specific transaction shapes:

1. When the transaction executes multiple parallel queries at the start of the transaction. Only one query can include a BeginTransaction option, and all other queries must wait for the first query to return the first result before they can proceed to execute. A BeginTransaction RPC will quickly return a transaction ID and allow all queries to start execution in parallel once the transaction ID has been returned.
2. When the first statement in the transaction could fail. If the statement fails, then it will also not start a transaction and return a transaction ID. The transaction will then fall back to executing a BeginTransaction RPC and retry the first statement.

Default is BeginTransactionOption::InlineBegin.

pub fn set_commit_priority(self, priority: Priority) -> Self

Sets the RPC priority to use for the commit of this transaction.

Example

let db_client = client.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client
    .read_write_transaction()
    .set_commit_priority(Priority::Low)
    .build()
    .await?;

pub fn set_max_commit_delay(self, delay: Duration) -> Self

Sets the maximum commit delay for the transaction.

Example

let db_client = client.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client
    .read_write_transaction()
    .set_max_commit_delay(Duration::try_from("0.2s").unwrap())
    .build()
    .await?;

This option allows you to specify the maximum amount of time Spanner can adjust the commit timestamp of the transaction to allow for commit batching. Increasing this value can increase throughput at the expense of latency. The value must be between 0 and 500 milliseconds. If not set, or set to 0, Spanner does not delay the commit.

pub fn set_exclude_txn_from_change_streams(self, exclude: bool) -> Self

Sets whether to exclude the transaction from change streams.

Example

let db_client = spanner.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client.read_write_transaction()
    .set_exclude_txn_from_change_streams(true)
    .build()
    .await?;

When set to true, it prevents modifications from this transaction from being tracked in change streams. Note that this only affects change streams that have been created with the DDL option allow_txn_exclusion = true. If allow_txn_exclusion is not set or set to false for a change stream, updates made within this transaction are recorded in that change stream regardless of this setting.

When set to false or not specified, modifications from this transaction are recorded in all change streams tracking columns modified by this transaction.

pub fn set_return_commit_stats(self, return_stats: bool) -> Self

Sets whether to return commit stats for the transaction.

Example

let runner = db_client.read_write_transaction()
    .set_return_commit_stats(true)
    .build()
    .await?;

let result = runner.run(async |transaction| {
    let statement = Statement::builder("UPDATE MyTable SET MyColumn = 'MyValue' WHERE Id = 1").build();
    transaction.execute_update(statement).await?;
    Ok(42)
}).await?;

if let Some(stats) = result.commit_response.commit_stats {
    println!("Mutation count: {}", stats.mutation_count);
}

See also: https://docs.cloud.google.com/spanner/docs/commit-statistics

pub fn with_retry_policy<P: TransactionRetryPolicy + 'static>( self, policy: P, ) -> Self

Sets the retry policy for the transaction.

Example

let db_client = client.database_client("projects/p/instances/i/databases/d").build().await?;

let retry_policy = BasicTransactionRetryPolicy::new()
    .with_max_attempts(5)
    .with_total_timeout(Duration::from_secs(60));

let runner = db_client
    .read_write_transaction()
    .with_retry_policy(retry_policy)
    .build()
    .await?;

pub async fn build(self) -> Result<TransactionRunner>

Builds a TransactionRunner for a read/write transaction.

Example

let db_client = client.database_client("projects/p/instances/i/databases/d").build().await?;
let runner = db_client.read_write_transaction().build().await?;

let result = runner.run(async |transaction| {
    let statement = Statement::builder("UPDATE MyTable SET MyColumn = 'MyValue' WHERE Id = 1").build();
    transaction.execute_update(statement).await?;
    Ok(42)
}).await?;