Crate spanner_rs

Expand description

An asynchronous client for the Cloud Spanner database.

§Example

use spanner_rs::{Client, Error, ReadContext, TransactionContext};

#[tokio::main]
async fn main() -> Result<(), Error> {
    let mut client = Client::configure()
        .project("my-gcp-project")
        .instance("my-instance")
        .database("my-database")
        .connect()
        .await?;

    // assuming the following table:
    //   person(id INT64, name STRING(MAX), data BYTES(MAX))
    client
        .read_write()
        .run(|tx| {
            tx.execute_update(
                "INSERT INTO person(id, name, data) VALUES(@id, @name, NULL)",
                &[("id", &42), ("name", &"ferris")],
            )
        })
        .await?;

    let result_set = client
        .read_only()
        .execute_query("SELECT * FROM person", &[])
        .await?;

    for row in result_set.iter() {
        let id: u32 = row.get("id")?;
        let name: &str = row.get("name")?;
        let data: Option<&[u8]> = row.get("data")?;

        println!("found person: {} {} {:?}", id, name, data);
    }

    Ok(())
}

§Transactions

Cloud Spanner supports several transaction “modes”:

read-only: provides guaranteed consistency between several reads, cannot write;
read-write: the only way to write into Cloud Spanner they use a combination of locking and retries and are typically more expensive;
partitioned DML: these are unsupported by this client at the moment.

§Read Only

Reads are done within “single-use” transactions and can be bounded to determine what data is visible to them, see TimestampBound. Reading is done using ReadContext which can be obtained using Client::read_only() or Client::read_only_with_bound().

Example:

#[tokio::main]
let result_set = client
    .read_only()
    .execute_query("SELECT COUNT(*) AS people FROM person", &[])
    .await?;
let people: u32 = result_set.iter().next().unwrap().get("people")?;

§Read Write

Read / write transactions are done through TransactionContext which extends ReadContext to allow writes. When a transaction that conflicts with another tries to commit, Cloud Spanner will reject one of them let the client know it may retry. This client encapsulates the necessary retry logic such that applications do not need to implement it themselves.

Example:

#[tokio::main]
client
    .read_write()
    .run(|tx| {
        // this closure may be invoked more than once
        Box::pin(async move {
            // read
            let rs = tx.execute_query("...", &[]).await?;
            // write
            tx.execute_update("...", &[]).await?;
            Ok(())
        })
    })
    .await?;

§Authentication

Authentication uses the gcp_auth crate which supports several authentication methods.

Structs§

Client: An asynchronous Cloud Spanner client.
Config: Configuration for building a Client.
ConfigBuilder: Builder for Config.
DatabaseId: The resource that identifies a Cloud Spanner database in a particular Cloud Spanner instance.
InstanceId: The resource that identifies a Cloud Spanner instance in a particular GCP project.
ProjectId: The resource that identifies a particular GCP project.
ResultSet: A result set is returned by Cloud Spanner when executing SQL queries.
Row: A row of a result set returned by Cloud Spanner.
SessionPoolConfig: Configuration for the internal Cloud Spanner session pool.
SessionPoolConfigBuilder: Builder for SessionPoolConfig.
Statement: A single DML statement that can be used in a batch of DML statements using TransactionContext::execute_updates
Struct: The Cloud Spanner value for the Struct type.
StructType: The Cloud Spanner Struct type which is composed of optionally named fields and their data type.
TxRunner: Allows running read/write transactions against Cloud Spanner.

Enums§

Error
TimestampBound: Specifies the bounds withing wich to make reads in Spanner.
Type: An enumeration of all Cloud Spanner data types.
Value: An enumeration of the Cloud Spanner values for each supported data type.

Traits§

FromSpanner: A trait for Rust types that can be converted from Cloud Spanner values.
ReadContext: Defines the interface to read data out of Cloud Spanner.
RowIndex: A trait implemented by types that can index into a row.
SpannerResource: A trait for identifiable resources within Cloud Spanner.
ToSpanner: A trait for Rust types that can be converted to Cloud Spanner values.
TransactionContext: Defines the interface to read from and write into Cloud Spanner.

Crate spanner_rsCopy item path