Google Cloud Spanner Client Library

3.63.0 verified Tue May 12 auth: no python install: verified

The `google-cloud-spanner` client library for Python enables developers to interact with Google Cloud Spanner, a fully managed, horizontally scalable, relational database service. It provides high-level APIs for creating instances and databases, executing SQL queries, managing transactions, and performing schema updates. The library maintains a rapid release cadence, with updates typically occurring on a monthly basis, introducing new features and bug fixes.

pip install google-cloud-spanner

Common errors

error google.api_core.exceptions.DeadlineExceeded: 504 Deadline Exceeded ↓

cause The Spanner operation exceeded the configured timeout, often due to heavy load, unoptimized queries, schema issues, or network latency.

fix

Investigate Spanner instance CPU utilization and query statistics, optimize SQL queries and database schema, check for lock contention, and ensure client library default timeouts are not overridden with overly aggressive values.

error com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found ↓

cause The application attempted to use a Spanner session that no longer exists, typically due to explicit deletion, prolonged inactivity, or an exhausted session pool caused by uncommitted transactions.

fix

Ensure all transactions (read-only and read-write) are explicitly committed or rolled back; if using client libraries, avoid prematurely closing database clients. If the session pool is consistently exhausted, review session pool configurations (e.g., max_sessions) and consider adding simple 'keep-alive' queries for idle connections.

error google.auth.exceptions.DefaultCredentialsError: Could not find default credentials. ↓

cause The application failed to locate valid Google Cloud authentication credentials, or the authenticated principal lacks the necessary IAM permissions for Spanner access.

fix

For local development, run gcloud auth application-default login or set the GOOGLE_APPLICATION_CREDENTIALS environment variable to a service account key file path. For deployed applications, ensure the associated service account has the required Spanner IAM roles (e.g., roles/spanner.databaseUser).

error google.api_core.exceptions.NotFound: 404 Instance not found: projects/<project-id>/instances/<instance-id> ↓

cause The specified Spanner instance or database ID is incorrect, misspelled, or the authenticated identity does not have permission to view it in the specified Google Cloud project.

fix

Verify that the project ID, instance ID, and database ID are correct and free of typos. Ensure the authenticated Google Cloud identity (user or service account) has appropriate IAM permissions to view and interact with the Spanner instance and database.

Warnings

breaking Python 3.7 and 3.8 are no longer supported since version 3.58.0. Users on these Python versions must upgrade to Python 3.9 or higher. ↓

fix Upgrade your Python environment to 3.9 or a newer supported version.

gotcha Spanner's DML and mutations, especially within read-write transactions, require careful transaction management to ensure strong consistency and handle retries for aborted transactions. It is highly recommended to use `database.run_in_transaction` for operations that modify data to automatically handle retry logic. ↓

fix Wrap your data modification logic within `database.run_in_transaction` callback functions.

gotcha Cloud Spanner does not offer a fully functional local development instance. Developers typically use the Spanner emulator, which mimics Spanner's behavior but might have subtle differences. Full integration testing should be performed against a live Spanner instance. ↓

fix Develop against the Spanner emulator, but ensure thorough testing on a cloud Spanner instance before deployment. Be aware of potential behavioral discrepancies.

gotcha Poorly optimized SQL queries or schema designs, such as DML statements not conditioned on primary keys, can lead to full table scans, lock contention, and significant performance degradation, even though Spanner supports live schema updates. ↓

fix Follow Spanner best practices for schema design, including primary key choices and interleaved tables. Use query plans and Spanner monitoring tools to identify and optimize slow queries, leveraging secondary indexes where appropriate (explicitly with `FORCE_INDEX` if needed).

bug A thread leak bug related to singleton initialization was present in versions prior to 3.63.0, potentially leading to resource exhaustion over long-running applications. ↓

fix Upgrade `google-cloud-spanner` to version 3.63.0 or higher to benefit from the fix.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 3.40s 84.6M

3.10 alpine (musl) - - 3.37s 83.4M

3.10 slim (glibc) wheel 7.4s 1.61s 82M

3.10 slim (glibc) - - 1.61s 81M

3.11 alpine (musl) wheel - 3.85s 91.0M

3.11 alpine (musl) - - 4.70s 89.8M

3.11 slim (glibc) wheel 6.9s 2.42s 89M

3.11 slim (glibc) - - 2.57s 88M

3.12 alpine (musl) wheel - 3.70s 82.2M

3.12 alpine (musl) - - 4.59s 81.0M

3.12 slim (glibc) wheel 5.7s 2.65s 80M

3.12 slim (glibc) - - 3.67s 79M

3.13 alpine (musl) wheel - 3.42s 81.7M

3.13 alpine (musl) - - 5.05s 80.4M

3.13 slim (glibc) wheel 5.8s 2.50s 80M

3.13 slim (glibc) - - 4.00s 78M

3.9 alpine (musl) wheel - 3.19s 84.7M

3.9 alpine (musl) - - 3.14s 83.5M

3.9 slim (glibc) wheel 8.7s 1.97s 83M

3.9 slim (glibc) - - 1.69s 81M

Imports

Client
```
from google.cloud import spanner
```
This is the primary high-level client for interacting with Spanner.
Connection (DB-API)
wrong
```
from google.cloud import spanner_v1
```
correct
```
from google.cloud.spanner_v1.database import SpannerConnection
```
While `spanner_v1` contains lower-level client components, the DB-API `connect` function or `SpannerConnection` class from `spanner_v1.database` is typically used for a PEP 249-compliant interface. Direct usage of `spanner_v1` without a specific class is not the common pattern for establishing a connection.

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to initialize a Cloud Spanner client, connect to an existing instance and database, and execute a simple SQL query. Ensure you have authenticated your Google Cloud environment (e.g., via `gcloud auth application-default login`) and set the `GOOGLE_CLOUD_PROJECT`, `SPANNER_INSTANCE_ID`, and `SPANNER_DATABASE_ID` environment variables or replace the placeholders.

import os
from google.cloud import spanner

project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-project-id')
instance_id = os.environ.get('SPANNER_INSTANCE_ID', 'your-instance-id')
database_id = os.environ.get('SPANNER_DATABASE_ID', 'your-database-id')


def query_data(project_id, instance_id, database_id):
    spanner_client = spanner.Client(project=project_id)
    instance = spanner_client.instance(instance_id)
    database = instance.database(database_id)

    with database.snapshot() as snapshot:
        results = snapshot.execute_sql('SELECT 1').fields
        for row in results:
            print(row)

    print(f'Successfully queried data from {database_id} in {instance_id}.')

# Example usage (uncomment to run, ensure environment variables are set or replace placeholders)
# if __name__ == '__main__':
#     query_data(project_id, instance_id, database_id)