google-cloud-spanner 0.34.1-preview

// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// Code generated by sidekick. DO NOT EDIT.
#![allow(rustdoc::redundant_explicit_links)]
#![allow(rustdoc::broken_intra_doc_links)]

/// Implements a client for the Cloud Spanner API.
#[derive(Clone, Debug)]
pub struct Spanner {
    inner: std::sync::Arc<dyn super::stub::dynamic::Spanner>,
}

impl Spanner {
    /// Creates a new client from the provided stub.
    ///
    /// The most common case for calling this function is in tests mocking the
    /// client's behavior.
    pub fn from_stub<T>(stub: impl Into<std::sync::Arc<T>>) -> Self
    where
        T: super::stub::Spanner + 'static,
    {
        Self { inner: stub.into() }
    }

    pub(crate) async fn new(
        config: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<Self> {
        let inner = Self::build_inner(config).await?;
        Ok(Self { inner })
    }

    async fn build_inner(
        conf: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<std::sync::Arc<dyn super::stub::dynamic::Spanner>> {
        if gaxi::options::tracing_enabled(&conf) {
            return Ok(std::sync::Arc::new(Self::build_with_tracing(conf).await?));
        }
        Ok(std::sync::Arc::new(Self::build_transport(conf).await?))
    }

    async fn build_transport(
        conf: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<impl super::stub::Spanner> {
        super::transport::Spanner::new(conf).await
    }

    async fn build_with_tracing(
        conf: gaxi::options::ClientConfig,
    ) -> crate::ClientBuilderResult<impl super::stub::Spanner> {
        Self::build_transport(conf)
            .await
            .map(super::tracing::Spanner::new)
    }

    /// Creates a new session. A session can be used to perform
    /// transactions that read and/or modify data in a Cloud Spanner database.
    /// Sessions are meant to be reused for many consecutive
    /// transactions.
    ///
    /// Sessions can only execute one transaction at a time. To execute
    /// multiple concurrent read-write/write-only transactions, create
    /// multiple sessions. Note that standalone reads and queries use a
    /// transaction internally, and count toward the one transaction
    /// limit.
    ///
    /// Active sessions use additional server resources, so it's a good idea to
    /// delete idle and unneeded sessions.
    /// Aside from explicit deletes, Cloud Spanner can delete sessions when no
    /// operations are sent for more than an hour. If a session is deleted,
    /// requests to it return `NOT_FOUND`.
    ///
    /// Idle sessions can be kept alive by sending a trivial SQL query
    /// periodically, for example, `"SELECT 1"`.
    pub(crate) fn create_session(&self) -> super::builder::spanner::CreateSession {
        super::builder::spanner::CreateSession::new(self.inner.clone())
    }

    /// Creates multiple new sessions.
    ///
    /// This API can be used to initialize a session cache on the clients.
    /// See <https://goo.gl/TgSFN2> for best practices on session cache management.
    pub(crate) fn batch_create_sessions(&self) -> super::builder::spanner::BatchCreateSessions {
        super::builder::spanner::BatchCreateSessions::new(self.inner.clone())
    }

    /// Gets a session. Returns `NOT_FOUND` if the session doesn't exist.
    /// This is mainly useful for determining whether a session is still
    /// alive.
    pub(crate) fn get_session(&self) -> super::builder::spanner::GetSession {
        super::builder::spanner::GetSession::new(self.inner.clone())
    }

    /// Lists all sessions in a given database.
    pub(crate) fn list_sessions(&self) -> super::builder::spanner::ListSessions {
        super::builder::spanner::ListSessions::new(self.inner.clone())
    }

    /// Ends a session, releasing server resources associated with it. This
    /// asynchronously triggers the cancellation of any operations that are running
    /// with this session.
    pub(crate) fn delete_session(&self) -> super::builder::spanner::DeleteSession {
        super::builder::spanner::DeleteSession::new(self.inner.clone())
    }

    /// Executes an SQL statement, returning all results in a single reply. This
    /// method can't be used to return a result set larger than 10 MiB;
    /// if the query yields more data than that, the query fails with
    /// a `FAILED_PRECONDITION` error.
    ///
    /// Operations inside read-write transactions might return `ABORTED`. If
    /// this occurs, the application should restart the transaction from
    /// the beginning. See [Transaction][google.spanner.v1.Transaction] for more
    /// details.
    ///
    /// Larger result sets can be fetched in streaming fashion by calling
    /// [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql]
    /// instead.
    ///
    /// The query string can be SQL or [Graph Query Language
    /// (GQL)](https://cloud.google.com/spanner/docs/reference/standard-sql/graph-intro).
    ///
    /// [google.spanner.v1.Transaction]: crate::model::Transaction
    pub(crate) fn execute_sql(&self) -> super::builder::spanner::ExecuteSql {
        super::builder::spanner::ExecuteSql::new(self.inner.clone())
    }

    /// Executes a batch of SQL DML statements. This method allows many statements
    /// to be run with lower latency than submitting them sequentially with
    /// [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql].
    ///
    /// Statements are executed in sequential order. A request can succeed even if
    /// a statement fails. The
    /// [ExecuteBatchDmlResponse.status][google.spanner.v1.ExecuteBatchDmlResponse.status]
    /// field in the response provides information about the statement that failed.
    /// Clients must inspect this field to determine whether an error occurred.
    ///
    /// Execution stops after the first failed statement; the remaining statements
    /// are not executed.
    ///
    /// [google.spanner.v1.ExecuteBatchDmlResponse.status]: crate::model::ExecuteBatchDmlResponse::status
    /// [google.spanner.v1.Spanner.ExecuteSql]: crate::client::Spanner::execute_sql
    pub(crate) fn execute_batch_dml(&self) -> super::builder::spanner::ExecuteBatchDml {
        super::builder::spanner::ExecuteBatchDml::new(self.inner.clone())
    }

    /// Reads rows from the database using key lookups and scans, as a
    /// simple key/value style alternative to
    /// [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. This method can't be
    /// used to return a result set larger than 10 MiB; if the read matches more
    /// data than that, the read fails with a `FAILED_PRECONDITION`
    /// error.
    ///
    /// Reads inside read-write transactions might return `ABORTED`. If
    /// this occurs, the application should restart the transaction from
    /// the beginning. See [Transaction][google.spanner.v1.Transaction] for more
    /// details.
    ///
    /// Larger result sets can be yielded in streaming fashion by calling
    /// [StreamingRead][google.spanner.v1.Spanner.StreamingRead] instead.
    ///
    /// [google.spanner.v1.Spanner.ExecuteSql]: crate::client::Spanner::execute_sql
    /// [google.spanner.v1.Transaction]: crate::model::Transaction
    pub(crate) fn read(&self) -> super::builder::spanner::Read {
        super::builder::spanner::Read::new(self.inner.clone())
    }

    /// Begins a new transaction. This step can often be skipped:
    /// [Read][google.spanner.v1.Spanner.Read],
    /// [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and
    /// [Commit][google.spanner.v1.Spanner.Commit] can begin a new transaction as a
    /// side-effect.
    ///
    /// [google.spanner.v1.Spanner.Commit]: crate::client::Spanner::commit
    /// [google.spanner.v1.Spanner.ExecuteSql]: crate::client::Spanner::execute_sql
    /// [google.spanner.v1.Spanner.Read]: crate::client::Spanner::read
    pub(crate) fn begin_transaction(&self) -> super::builder::spanner::BeginTransaction {
        super::builder::spanner::BeginTransaction::new(self.inner.clone())
    }

    /// Commits a transaction. The request includes the mutations to be
    /// applied to rows in the database.
    ///
    /// `Commit` might return an `ABORTED` error. This can occur at any time;
    /// commonly, the cause is conflicts with concurrent
    /// transactions. However, it can also happen for a variety of other
    /// reasons. If `Commit` returns `ABORTED`, the caller should retry
    /// the transaction from the beginning, reusing the same session.
    ///
    /// On very rare occasions, `Commit` might return `UNKNOWN`. This can happen,
    /// for example, if the client job experiences a 1+ hour networking failure.
    /// At that point, Cloud Spanner has lost track of the transaction outcome and
    /// we recommend that you perform another read from the database to see the
    /// state of things as they are now.
    pub(crate) fn commit(&self) -> super::builder::spanner::Commit {
        super::builder::spanner::Commit::new(self.inner.clone())
    }

    /// Rolls back a transaction, releasing any locks it holds. It's a good
    /// idea to call this for any transaction that includes one or more
    /// [Read][google.spanner.v1.Spanner.Read] or
    /// [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] requests and ultimately
    /// decides not to commit.
    ///
    /// `Rollback` returns `OK` if it successfully aborts the transaction, the
    /// transaction was already aborted, or the transaction isn't
    /// found. `Rollback` never returns `ABORTED`.
    ///
    /// [google.spanner.v1.Spanner.ExecuteSql]: crate::client::Spanner::execute_sql
    /// [google.spanner.v1.Spanner.Read]: crate::client::Spanner::read
    pub(crate) fn rollback(&self) -> super::builder::spanner::Rollback {
        super::builder::spanner::Rollback::new(self.inner.clone())
    }

    /// Creates a set of partition tokens that can be used to execute a query
    /// operation in parallel. Each of the returned partition tokens can be used
    /// by [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] to
    /// specify a subset of the query result to read. The same session and
    /// read-only transaction must be used by the `PartitionQueryRequest` used to
    /// create the partition tokens and the `ExecuteSqlRequests` that use the
    /// partition tokens.
    ///
    /// Partition tokens become invalid when the session used to create them
    /// is deleted, is idle for too long, begins a new transaction, or becomes too
    /// old. When any of these happen, it isn't possible to resume the query, and
    /// the whole operation must be restarted from the beginning.
    pub(crate) fn partition_query(&self) -> super::builder::spanner::PartitionQuery {
        super::builder::spanner::PartitionQuery::new(self.inner.clone())
    }

    /// Creates a set of partition tokens that can be used to execute a read
    /// operation in parallel. Each of the returned partition tokens can be used
    /// by [StreamingRead][google.spanner.v1.Spanner.StreamingRead] to specify a
    /// subset of the read result to read. The same session and read-only
    /// transaction must be used by the `PartitionReadRequest` used to create the
    /// partition tokens and the `ReadRequests` that use the partition tokens.
    /// There are no ordering guarantees on rows returned among the returned
    /// partition tokens, or even within each individual `StreamingRead` call
    /// issued with a `partition_token`.
    ///
    /// Partition tokens become invalid when the session used to create them
    /// is deleted, is idle for too long, begins a new transaction, or becomes too
    /// old. When any of these happen, it isn't possible to resume the read, and
    /// the whole operation must be restarted from the beginning.
    pub(crate) fn partition_read(&self) -> super::builder::spanner::PartitionRead {
        super::builder::spanner::PartitionRead::new(self.inner.clone())
    }
}