spanner_rs/
lib.rs

1//! An asynchronous client for the Cloud Spanner database.
2//!
3//! # Example
4//!
5//! ```no_run
6//! use spanner_rs::{Client, Error, ReadContext, TransactionContext};
7//!
8//! #[tokio::main]
9//! async fn main() -> Result<(), Error> {
10//!     let mut client = Client::configure()
11//!         .project("my-gcp-project")
12//!         .instance("my-instance")
13//!         .database("my-database")
14//!         .connect()
15//!         .await?;
16//!
17//!     // assuming the following table:
18//!     //   person(id INT64, name STRING(MAX), data BYTES(MAX))
19//!     client
20//!         .read_write()
21//!         .run(|tx| {
22//!             tx.execute_update(
23//!                 "INSERT INTO person(id, name, data) VALUES(@id, @name, NULL)",
24//!                 &[("id", &42), ("name", &"ferris")],
25//!             )
26//!         })
27//!         .await?;
28//!
29//!     let result_set = client
30//!         .read_only()
31//!         .execute_query("SELECT * FROM person", &[])
32//!         .await?;
33//!
34//!     for row in result_set.iter() {
35//!         let id: u32 = row.get("id")?;
36//!         let name: &str = row.get("name")?;
37//!         let data: Option<&[u8]> = row.get("data")?;
38//!
39//!         println!("found person: {} {} {:?}", id, name, data);
40//!     }
41//!
42//!     Ok(())
43//! }
44//! ```
45//!
46//! # Transactions
47//!
48//! Cloud Spanner [supports](https://cloud.google.com/spanner/docs/transactions) several transaction "modes":
49//!
50//! * read-only: provides guaranteed consistency between several reads, cannot write;
51//! * read-write: the only way to write into Cloud Spanner they use a combination of locking and retries and are typically more expensive;
52//! * partitioned DML: these are unsupported by this client at the moment.
53//!
54//! ## Read Only
55//!
56//! Reads are done within "single-use" transactions and can be bounded to determine what data is visible to them, see [`TimestampBound`].
57//! Reading is done using [`ReadContext`] which can be obtained using [`Client::read_only()`] or [`Client::read_only_with_bound()`].
58//!
59//! Example:
60//!
61//! ```no_run
62//! # use spanner_rs::*;
63//! #[tokio::main]
64//! # async fn main() -> Result<(), crate::Error> {
65//! # let mut client = Client::configure().connect().await?;
66//! let result_set = client
67//!     .read_only()
68//!     .execute_query("SELECT COUNT(*) AS people FROM person", &[])
69//!     .await?;
70//! let people: u32 = result_set.iter().next().unwrap().get("people")?;
71//! # Ok(()) }
72//! ```
73//!
74//! ## Read Write
75//!
76//! Read / write transactions are done through [`TransactionContext`] which extends [`ReadContext`] to allow writes.
77//! When a transaction that conflicts with another tries to commit, Cloud Spanner will reject one of them let the client know it may retry.
78//! This client encapsulates the necessary retry logic such that applications do not need to implement it themselves.
79//!
80//! Example:
81//!
82//! ```no_run
83//! # use spanner_rs::*;
84//! #[tokio::main]
85//! # async fn main() -> Result<(), crate::Error> {
86//! # let mut client = Client::configure().connect().await?;
87//! client
88//!     .read_write()
89//!     .run(|tx| {
90//!         // this closure may be invoked more than once
91//!         Box::pin(async move {
92//!             // read
93//!             let rs = tx.execute_query("...", &[]).await?;
94//!             // write
95//!             tx.execute_update("...", &[]).await?;
96//!             Ok(())
97//!         })
98//!     })
99//!     .await?;
100//! # Ok(()) }
101//! ```
102//!
103//! ## Authentication
104//!
105//! Authentication uses the [`gcp_auth`] crate which supports several authentication methods.
106
107pub use crate::client::*;
108pub use crate::config::*;
109pub(crate) use crate::connection::Connection;
110pub use crate::error::Error;
111pub use crate::from_spanner::*;
112pub use crate::resource::*;
113pub use crate::result_set::*;
114pub(crate) use crate::session::*;
115pub use crate::statement::*;
116pub use crate::to_spanner::*;
117pub use crate::transaction::*;
118pub use crate::types::*;
119pub use crate::value::*;
120
121mod auth;
122mod client;
123mod config;
124mod connection;
125mod error;
126mod from_spanner;
127mod resource;
128mod result_set;
129mod session;
130mod statement;
131mod to_spanner;
132mod transaction;
133mod types;
134mod value;
spanner_rs/lib.rs

spanner_rs/
lib.rs
