adbc_spanner/
lib.rs

1//! # adbc-spanner
2//!
3//! An [ADBC](https://arrow.apache.org/adbc/) (Arrow Database Connectivity) driver for
4//! [Google Cloud Spanner](https://cloud.google.com/spanner), built on top of the official
5//! `google-cloud-spanner` preview client and the native Rust [`adbc_core`] traits.
6//!
7//! The driver exposes Spanner through the standard ADBC object hierarchy:
8//!
9//! ```text
10//! SpannerDriver ──> SpannerDatabase ──> SpannerConnection ──> SpannerStatement
11//! ```
12//!
13//! Query results are returned as Arrow [`RecordBatch`](arrow_array::RecordBatch)es, so they can be
14//! consumed by any Arrow-native tool without an intermediate row-by-row copy.
15//!
16//! ## Configuration
17//!
18//! A database is configured through ADBC options. The Spanner database path is required and can be
19//! supplied either through the standard [`OptionDatabase::Uri`](adbc_core::options::OptionDatabase::Uri)
20//! option or the driver-specific [`OPTION_DATABASE`] key:
21//!
22//! ```text
23//! projects/<project>/instances/<instance>/databases/<database>
24//! ```
25//!
26//! To talk to a Spanner emulator, either set the `SPANNER_EMULATOR_HOST` environment variable (the
27//! driver picks it up automatically and uses anonymous credentials) or set the [`OPTION_ENDPOINT`]
28//! and [`OPTION_EMULATOR`] options explicitly.
29//!
30//! ## Example
31//!
32//! ```no_run
33//! use adbc_core::{Driver, Database, Connection, Statement};
34//! use adbc_core::options::{OptionDatabase, OptionValue};
35//! use adbc_spanner::{SpannerDriver, OPTION_DATABASE};
36//! use arrow_array::RecordBatchReader;
37//!
38//! # fn main() -> adbc_core::error::Result<()> {
39//! let mut driver = SpannerDriver::try_new()?;
40//! let database = driver.new_database_with_opts([(
41//!     OptionDatabase::Other(OPTION_DATABASE.into()),
42//!     OptionValue::String("projects/p/instances/i/databases/d".into()),
43//! )])?;
44//! let mut connection = database.new_connection()?;
45//! let mut statement = connection.new_statement()?;
46//! statement.set_sql_query("SELECT 1 AS one")?;
47//! let reader = statement.execute()?;
48//! for batch in reader {
49//!     let batch = batch?;
50//!     println!("got {} rows", batch.num_rows());
51//! }
52//! # Ok(())
53//! # }
54//! ```
55
56mod connection;
57mod conversion;
58mod driver;
59mod error;
60#[cfg(feature = "ffi")]
61mod ffi;
62mod runtime;
63mod statement;
64
65pub use connection::SpannerConnection;
66pub use driver::{SpannerDatabase, SpannerDriver};
67pub use statement::SpannerStatement;
68
69/// Driver-specific database option: the fully-qualified Spanner database path,
70/// `projects/<project>/instances/<instance>/databases/<database>`.
71///
72/// Equivalent to setting [`OptionDatabase::Uri`](adbc_core::options::OptionDatabase::Uri).
73pub const OPTION_DATABASE: &str = "adbc.spanner.database";
74
75/// Driver-specific database option: an explicit gRPC endpoint (for example the address of a
76/// Spanner emulator, `http://localhost:9010`). When unset the client connects to the production
77/// Spanner service.
78pub const OPTION_ENDPOINT: &str = "adbc.spanner.endpoint";
79
80/// Driver-specific database option: when set to `true`, connect with anonymous credentials
81/// (the mode used by the Spanner emulator). Automatically enabled when `SPANNER_EMULATOR_HOST`
82/// is present in the environment.
83pub const OPTION_EMULATOR: &str = "adbc.spanner.emulator";
84
85/// The vendor name reported by [`Connection::get_info`](adbc_core::Connection::get_info).
86pub const VENDOR_NAME: &str = "Google Cloud Spanner";
87
88/// The driver name reported by [`Connection::get_info`](adbc_core::Connection::get_info).
89pub const DRIVER_NAME: &str = "adbc-spanner";
90
91/// The version of this driver.
92pub const DRIVER_VERSION: &str = env!("CARGO_PKG_VERSION");
adbc_spanner/lib.rs

adbc_spanner/
lib.rs
