{"id":870,"library":"google-cloud-spanner","title":"Google Cloud Spanner Client Library","description":"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.","status":"active","version":"3.63.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/python-spanner","tags":["google cloud","spanner","database","sql","client library","serverless","transactional"],"install":[{"cmd":"pip install google-cloud-spanner","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"This is the primary high-level client for interacting with Spanner.","symbol":"Client","correct":"from google.cloud import spanner"},{"note":"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.","wrong":"from google.cloud import spanner_v1","symbol":"Connection (DB-API)","correct":"from google.cloud.spanner_v1.database import SpannerConnection"}],"quickstart":{"code":"import os\nfrom google.cloud import spanner\n\nproject_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-project-id')\ninstance_id = os.environ.get('SPANNER_INSTANCE_ID', 'your-instance-id')\ndatabase_id = os.environ.get('SPANNER_DATABASE_ID', 'your-database-id')\n\n\ndef query_data(project_id, instance_id, database_id):\n    spanner_client = spanner.Client(project=project_id)\n    instance = spanner_client.instance(instance_id)\n    database = instance.database(database_id)\n\n    with database.snapshot() as snapshot:\n        results = snapshot.execute_sql('SELECT 1').fields\n        for row in results:\n            print(row)\n\n    print(f'Successfully queried data from {database_id} in {instance_id}.')\n\n# Example usage (uncomment to run, ensure environment variables are set or replace placeholders)\n# if __name__ == '__main__':\n#     query_data(project_id, instance_id, database_id)","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or a newer supported version.","message":"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.","severity":"breaking","affected_versions":">=3.58.0"},{"fix":"Wrap your data modification logic within `database.run_in_transaction` callback functions.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Develop against the Spanner emulator, but ensure thorough testing on a cloud Spanner instance before deployment. Be aware of potential behavioral discrepancies.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade `google-cloud-spanner` to version 3.63.0 or higher to benefit from the fix.","message":"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.","severity":"bug","affected_versions":"<3.63.0"}],"env_vars":null,"last_verified":"2026-05-12T20:35:37.496Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"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.","cause":"The Spanner operation exceeded the configured timeout, often due to heavy load, unoptimized queries, schema issues, or network latency.","error":"google.api_core.exceptions.DeadlineExceeded: 504 Deadline Exceeded"},{"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.","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.","error":"com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found"},{"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`).","cause":"The application failed to locate valid Google Cloud authentication credentials, or the authenticated principal lacks the necessary IAM permissions for Spanner access.","error":"google.auth.exceptions.DefaultCredentialsError: Could not find default credentials."},{"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.","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.","error":"google.api_core.exceptions.NotFound: 404 Instance not found: projects/<project-id>/instances/<instance-id>"}],"ecosystem":"pypi","meta_description":null,"install_score":95,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.66.0","cli_name":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":3.4,"mem_mb":47,"disk_size":"84.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.37,"mem_mb":46.7,"disk_size":"83.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":7.4,"import_time_s":1.61,"mem_mb":34.2,"disk_size":"82M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.61,"mem_mb":33.9,"disk_size":"81M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":3.85,"mem_mb":49.1,"disk_size":"91.0M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.7,"mem_mb":48.9,"disk_size":"89.8M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.9,"import_time_s":2.42,"mem_mb":37.6,"disk_size":"89M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.57,"mem_mb":37.3,"disk_size":"88M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":3.7,"mem_mb":48.6,"disk_size":"82.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.59,"mem_mb":48.3,"disk_size":"81.0M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.7,"import_time_s":2.65,"mem_mb":37.4,"disk_size":"80M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.67,"mem_mb":37.1,"disk_size":"79M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":3.42,"mem_mb":49.1,"disk_size":"81.7M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":5.05,"mem_mb":49.9,"disk_size":"80.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.8,"import_time_s":2.5,"mem_mb":37.6,"disk_size":"80M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4,"mem_mb":38.4,"disk_size":"78M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":3.19,"mem_mb":47.2,"disk_size":"84.7M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.14,"mem_mb":47,"disk_size":"83.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":8.7,"import_time_s":1.97,"mem_mb":34.4,"disk_size":"83M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.69,"mem_mb":34.2,"disk_size":"81M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}