Struct DatabaseClient

Source

pub struct DatabaseClient { /* private fields */ }

Expand description

A client for interacting with a specific Spanner database.

DatabaseClient provides methods to execute transactions and queries.

§Example

    let spanner = Spanner::builder().build().await?;
    let database_client = spanner
        .database_client("projects/my-project/instances/my-instance/databases/my-db")
        .build()
        .await?;

DatabaseClient provides methods to execute transactions and queries. It holds a single multiplexed session for the database.

A DatabaseClient is intended to be a long-lived object, and normally an application will have a single DatabaseClient per database. The client is thread-safe and should be reused for all operations on the database.

Cloning a DatabaseClient is cheap, as it shares the underlying session and channel.

Implementations§

Source §

impl DatabaseClient

Source

pub fn single_use(&self) -> SingleUseReadOnlyTransactionBuilder

Returns a builder for a single-use read-only transaction.

§Example

let db_client = spanner.database_client("projects/p/instances/i/databases/d").build().await?;
let tx = db_client.single_use().build();
let stmt = Statement::builder("SELECT * FROM users WHERE id = @id")
    .add_param("id", &42)
    .build();
let mut rs = tx.execute_query(stmt).await?;

A single-use read-only transaction is optimized for the case where only a single read or query is needed. This is more efficient than using a read-only transaction for a single read or query.

Source

pub fn read_only_transaction(&self) -> MultiUseReadOnlyTransactionBuilder

Returns a builder for a multi-use read-only transaction.

§Example

let db_client = spanner.database_client("projects/p/instances/i/databases/d").build().await?;
let tx = db_client.read_only_transaction().build().await?;
let stmt = Statement::builder("SELECT * FROM users WHERE id = @id")
    .add_param("id", &42)
    .build();
let mut rs = tx.execute_query(stmt).await?;

A read-only transaction can be used to execute multiple reads or queries. These transactions guarantee data consistency across multiple read operations, but don’t permit data modifications. Read-only transactions do not take locks.

Source

pub fn batch_read_only_transaction(&self) -> BatchReadOnlyTransactionBuilder

Returns a builder for a batch read-only transaction.

§Example

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

A batch read-only transaction is similar to a read-only transaction, but it allows for partitioning a read or query request. Run tasks in parallel over the partitions to execute a large read or query.

Source

pub fn partitioned_dml_transaction(&self) -> PartitionedDmlTransactionBuilder

Returns a builder for a partitioned DML transaction.

§Example

let db_client = spanner.database_client("projects/p/instances/i/databases/d").build().await?;
let transaction = db_client.partitioned_dml_transaction().build().await?;
let statement = Statement::builder("UPDATE users SET active = true WHERE TRUE").build();
let modified_rows = transaction.execute_update(statement).await?;

Partitioned DML is used to execute a single DML statement that may modify a large number of rows. The execution of the statement will automatically be partitioned into smaller transactions by Spanner, which may execute in parallel.

Source

pub fn read_write_transaction(&self) -> TransactionRunnerBuilder

Returns a builder for a read-write transaction runner.

§Example

let db_client = spanner.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 users SET active = true WHERE id = 1").build();
    transaction.execute_update(statement).await?;
    Ok(())
}).await?;

Read-write transactions can be used to execute multiple queries and updates atomically. If the transaction is aborted by Spanner, the run method will automatically retry the transaction.

Source

pub fn write_only_transaction(&self) -> WriteOnlyTransactionBuilder

Returns a builder for a write-only transaction.

§Example

let client = Spanner::builder().build().await?;
let db = client.database_client("projects/p/instances/i/databases/d").build().await?;

let mutation = Mutation::new_insert_builder("Users")
    .set("UserId").to(&1)
    .set("UserName").to(&"Alice")
    .build();

let response = db.write_only_transaction()
    .set_transaction_tag("my-tag")
    .build()
    .write(vec![mutation])
    .await?;

A write-only transaction is used to execute blind writes using mutations.

Source

pub fn batch_write_transaction(&self) -> BatchWriteTransactionBuilder

Returns a builder for a batch write transaction.

§Example

let client = Spanner::builder().build().await?;
let db = client.database_client("projects/p/instances/i/databases/d").build().await?;

let mutation1a = Mutation::new_insert_builder("Users")
    .set("UserId").to(&1)
    .build();
let mutation1b = Mutation::new_insert_builder("UserRoles")
    .set("UserId").to(&1)
    .set("Role").to(&"Admin")
    .build();
let group1 = MutationGroup::new(vec![mutation1a, mutation1b]);

let mutation2 = Mutation::new_insert_builder("Users")
    .set("UserId").to(&2)
    .build();
let group2 = MutationGroup::new(vec![mutation2]);

let transaction = db.batch_write_transaction().build();
let mut stream = transaction.execute_streaming(vec![group1, group2]).await?;

while let Some(response) = stream.next().await {
    let response = response?;
    if let Some(status) = response.status.as_ref().filter(|s| s.code != Code::Ok as i32) {
        eprintln!("Error applying groups {:?}: {}", response.indexes, status.message);
    } else {
        println!("Applied groups: {:?}", response.indexes);
    }
}

A batch write transaction is used to execute non-atomic writes using mutations. Related mutations should be placed in a group. For example, two mutations inserting rows with the same primary key prefix in both parent and child tables are related. All mutations within a group are applied atomically, but the entire batch is not guaranteed to be atomic.