Spanner#

Google Cloud Spanner adapter using the Spanner client library with session pool management.

Request And Session Controls#

Spanner request behavior stays on the existing execution APIs. SQLSpec does not expose public execute_with_options(), execute_partitioned_dml(), apply_mutations(), or provide_batch_snapshot() methods.

Default request controls can be configured through SpannerSyncConfig.driver_features:

request_options: Forwarded to Spanner execute_sql(), execute_update(), and batch_update() calls. Use this for request tags, transaction tags, and priority options supported by the Google Cloud Spanner client.
directed_read_options: Forwarded only to read calls that use execute_sql(). Directed reads are not forwarded to DML calls.
retry and timeout: Forwarded to Spanner statement execution calls when provided.
query_options: Forwarded to execute_sql() and execute_update(). Batch DML does not accept query options.

Per-call overrides use the existing execute(), execute_many(), and execute_script() methods:

result = driver.execute(
    "SELECT id FROM users WHERE id = @id",
    id="u-1",
    request_options={"request_tag": "users.lookup"},
    directed_read_options=directed_read_options,
    timeout=10.0,
)

directed_read_options only applies to read statements. The driver accepts the argument for a DML statement so call sites can share option plumbing, but it does not forward directed-read options to execute_update() or batch_update().

Pass last_statement=True to mark the final DML request in a transaction. For scripts, SQLSpec forwards it only when the final statement is DML. This option does not commit the transaction; commit through the normal transaction context or driver API.

Session-Scoped Controls#

SpannerSyncConfig.provide_session() also accepts explicit Spanner controls for the returned session context:

with config.provide_session(
    request_options={"transaction_tag": "orders.write"},
    retry=retry,
    timeout=20.0,
) as driver:
    driver.execute("UPDATE orders SET status = @status WHERE id = @id", status="paid", id="o-1")

The explicit provide_session() arguments are copied into the returned driver's feature set and do not mutate config.driver_features. They also do not hide a database_provider feature for unrelated database-level methods.

provide_read_session() is the read-only helper for single-use snapshot reads. For DDL, DML, and write-capable transactions, use provide_session() or provide_write_session().

Configuration#

With google-cloud-spanner==3.71.0, closing a database that used multiplexed sessions can wait up to ten minutes for the SDK's maintenance thread. The upstream shutdown fix is merged but has not yet been released. Allow for this delay during application shutdown until a fixed SDK is available.

class sqlspec.adapters.spanner.SpannerSyncConfig[source]#

Bases: SyncDatabaseConfig[SpannerConnection, AbstractSessionPool, SpannerSyncDriver]

Spanner configuration and session management.

driver_type#: alias of SpannerSyncDriver

connection_type#: alias of Any

__init__(*, connection_config=None, connection_instance=None, migration_config=None, statement_config=None, driver_features=None, bind_key=None, extension_config=None, observability_config=None, **kwargs)[source]#

create_connection()[source]#

Return a read-only snapshot checkout owned by the caller.

The result is the database's own checkout object: it borrows a pooled session when entered and returns it on exit. Returning an already-entered snapshot instead would borrow a session that nothing could give back.

Return type:: Any
Returns:: A snapshot checkout to be used as a context manager.

provide_connection(*args, transaction=True, **kwargs)[source]#

Yield a Transaction (default) or Snapshot context from the configured pool.

Parameters:

*args¶ (Any) -- Additional positional arguments (unused, for interface compatibility).
transaction¶ (bool) -- If True (default), yields a Transaction context that supports execute_update() for DML statements. If False, yields a read-only Snapshot context for SELECT queries.
**kwargs¶ (Any) -- Additional keyword arguments (unused, for interface compatibility).

Return type:

SpannerConnectionContext

provide_session(*args, statement_config=None, transaction=True, request_options=None, directed_read_options=None, query_options=None, retry=None, timeout=None, **kwargs)[source]#

Provide a Spanner driver session context manager.

Returns a write-capable Transaction session by default, matching every other sqlspec adapter. Pass transaction=False or use provide_read_session() to obtain a read-only Snapshot session.

Parameters:

*args¶ -- Additional arguments.
statement_config¶ -- Optional statement configuration override.
transaction¶ -- Whether to use a Transaction (True, default) or Snapshot (False).
request_options¶ -- Session-scoped RequestOptions for Spanner statements.
directed_read_options¶ -- Session-scoped DirectedReadOptions for reads.
query_options¶ -- Session-scoped QueryOptions for Spanner statements.
retry¶ -- Session-scoped retry policy for Spanner statement calls.
timeout¶ -- Session-scoped timeout for Spanner statement calls.
**kwargs¶ -- Additional keyword arguments.

Returns:

A Spanner driver session context manager.

provide_write_session(*args, statement_config=None, request_options=None, directed_read_options=None, query_options=None, retry=None, timeout=None, **kwargs)[source]#: Provide a write-capable Spanner session (alias for provide_session()).

provide_read_session(*args, statement_config=None, request_options=None, directed_read_options=None, query_options=None, retry=None, timeout=None, **kwargs)[source]#

Provide a read-only Snapshot Spanner session.

Use for query workloads that benefit from Spanner's snapshot reads. For DDL/DML, use provide_session() (write-capable by default).

get_signature_namespace()[source]#

Get the signature namespace for SpannerSyncConfig types.

Return type:: dict[str, typing.Any]
Returns:: Dictionary mapping type names to types.

get_event_runtime_hints()[source]#

Return queue defaults for Spanner JSON handling.

Return type:: EventRuntimeHints

Connection Parameters#

class sqlspec.adapters.spanner.SpannerConnectionParams[source]#

Bases: TypedDict

Spanner connection parameters.

Pool Parameters#

class sqlspec.adapters.spanner.SpannerPoolParams[source]#

Bases: SpannerConnectionParams

Session pool configuration.

Driver Features#

class sqlspec.adapters.spanner.SpannerDriverFeatures[source]#

Bases: TypedDict

Driver feature flags for Spanner.

enable_uuid_conversion#: Enable automatic UUID string conversion.

json_serializer#: Custom JSON serializer for parameter conversion.

json_deserializer#: Custom JSON deserializer for result conversion.

retry#: Per-request retry policy passed to execute_sql(), execute_update(), and batch_update().

timeout#: Per-request timeout in seconds passed to execute_sql(), execute_update(), and batch_update().

request_options#: Default RequestOptions forwarded to execute_sql(), execute_update(), and batch_update(). Per-call overrides are available through normal driver execution methods.

directed_read_options#: Default DirectedReadOptions forwarded to execute_sql().

session_labels#: Deprecated compatibility alias for pool session labels. Prefer connection_config["session_labels"].

enable_events#: Enable database event channel support. Defaults to True when extension_config["events"] is configured.

events_backend#: Backend type for event handling. Spanner only supports "poll_queue" (no native pub/sub).

enable_batch_write_api#: Route load_from_arrow through the Spanner Batch Write API (Database.mutation_groups().batch_write()) for high-throughput, independently committed mutation groups instead of a single in-transaction insert_or_update. Defaults to False.

Custom Dialects#

Spanner uses the Spanner and Spangres dialects for SQL compilation. See the Dialects reference for details.

Driver#

class sqlspec.adapters.spanner.SpannerSyncDriver[source]#

Bases: SyncDriverAdapterBase

Synchronous Spanner driver operating on Snapshot or Transaction contexts.

__init__(connection, statement_config=None, driver_features=None)[source]#

Initialize driver adapter with connection and configuration.

Parameters:

connection¶ (Any) -- Database connection instance
statement_config¶ (StatementConfig | None) -- Statement configuration for the driver
driver_features¶ (dict[str, typing.Any] | None) -- Driver-specific features like extensions, secrets, and connection callbacks
observability¶ -- Optional runtime handling lifecycle hooks, observers, and spans

dispatch_execute(cursor, statement)[source]#

Execute a single SQL statement.

Must be implemented by each driver for database-specific execution logic.

Parameters:

cursor¶ (Any) -- Database cursor/connection object
statement¶ (SQL) -- SQL statement object with all necessary data and configuration

Return type:

ExecutionResult

Returns:

ExecutionResult with execution data

dispatch_select_stream(statement, chunk_size)[source]#

Adapter hook returning a native row stream, or None when unsupported.

Return type:: Optional[SyncRowStream[dict[str, typing.Any]]]

dispatch_execute_many(cursor, statement)[source]#

Execute SQL with multiple parameter sets (executemany).

Must be implemented by each driver for database-specific executemany logic.

Parameters:

cursor¶ (Any) -- Database cursor/connection object
statement¶ (SQL) -- SQL statement object with all necessary data and configuration

Return type:

ExecutionResult

Returns:

ExecutionResult with execution data for the many operation

dispatch_execute_script(cursor, statement)[source]#

Execute a SQL script containing multiple statements.

Default implementation splits the script and executes statements individually. Drivers can override for database-specific script execution methods.

Parameters:

cursor¶ (Any) -- Database cursor/connection object
statement¶ (SQL) -- SQL statement object with all necessary data and configuration

Return type:

ExecutionResult

Returns:

ExecutionResult with script execution data including statement counts

begin()[source]#

Begin a database transaction on the current connection.

Return type:: None

commit()[source]#

Commit the current transaction on the current connection.

Return type:: None

rollback()[source]#

Rollback the current transaction on the current connection.

Return type:: None

create_savepoint(name)[source]#

Raise because Spanner does not support savepoints.

Raises:: NotImplementedError -- Always.
Return type:: None

release_savepoint(name)[source]#

Raise because Spanner does not support savepoints.

Raises:: NotImplementedError -- Always.
Return type:: None

rollback_to_savepoint(name)[source]#

Raise because Spanner does not support savepoints.

Raises:: NotImplementedError -- Always.
Return type:: None

with_cursor(connection)[source]#

Create and return a context manager for cursor acquisition and cleanup.

Returns a context manager that yields a cursor for database operations. Concrete implementations handle database-specific cursor creation and cleanup.

Return type:: SpannerSyncCursor

handle_database_exceptions()[source]#

Handle database-specific exceptions and wrap them appropriately.

Return type:: SpannerExceptionHandler
Returns:: Exception handler with deferred exception pattern for mypyc compatibility. The handler stores mapped exceptions in pending_exception rather than raising from __exit__ to avoid ABI boundary violations.

execute(statement, /, *parameters, statement_config=None, **kwargs)[source]#: Execute a statement with optional Spanner per-call request options.

execute_many(statement, /, parameters, *filters, statement_config=None, **kwargs)[source]#: Execute a batch statement with optional Spanner per-call request options.

execute_script(statement, /, *parameters, statement_config=None, **kwargs)[source]#: Execute a multi-statement script with optional Spanner per-call request options.

select_stream(statement, /, *parameters, schema_type=None, statement_config=None, chunk_size=1000, native_only=False, **kwargs)[source]#

Execute a query and stream rows with optional Spanner per-call options.

Overloads:

self, statement (SQL | Statement | QueryBuilder), parameters (StatementParameters | StatementFilter), schema_type (type[SchemaT]), statement_config (StatementConfig | None), chunk_size (int), native_only (bool), kwargs (Any) → SyncRowStream[SchemaT]
self, statement (SQL | Statement | QueryBuilder), parameters (StatementParameters | StatementFilter), schema_type (None), statement_config (StatementConfig | None), chunk_size (int), native_only (bool), kwargs (Any) → SyncRowStream[dict[str, Any]]

select_to_storage(statement, destination, /, *parameters, statement_config=None, partitioner=None, format_hint=None, telemetry=None, **kwargs)[source]#

Execute query and stream Arrow results to storage.

Return type:: StorageBridgeJob

load_from_arrow(table, source, *, partitioner=None, overwrite=False, telemetry=None)[source]#

Load Arrow data into Spanner table via batch mutations.

Return type:: StorageBridgeJob

load_from_storage(table, source, *, file_format, partitioner=None, overwrite=False)[source]#

Load artifacts from storage into Spanner table.

Return type:: StorageBridgeJob

property data_dictionary: SpannerDataDictionary#

Get the data dictionary for this driver.

Returns:: Data dictionary instance for metadata queries

collect_rows(cursor, fetched)[source]#

Collect Spanner rows for the direct execution path.

Note: Spanner's collect_rows requires result set fields and a type converter. The direct execution path may not always have this metadata available, so this falls back to basic collection.

For the direct path, if result set fields metadata is not available, it returns raw data with no column names. If rows are dicts, it attempts to extract column names from dict keys. For tuple rows without metadata, it returns them as-is.

Return type:: tuple[list[typing.Any], list[str], int]

resolve_rowcount(cursor)[source]#

Resolve rowcount from Spanner cursor for the direct execution path.

Spanner uses execute_update return value, not cursor.rowcount, so this returns 0.

Return type:: int

Data Dictionary#

class sqlspec.adapters.spanner.data_dictionary.SpannerDataDictionary[source]#

Bases: SyncDataDictionaryBase

Fetch table, column, and index metadata from Spanner.

dialect: ClassVar[str] = 'spanner'#: Dialect identifier. Must be defined by subclasses as a class attribute.

__init__(mode='googlesql')[source]#

get_query(domain, operation, *, mode=None)[source]#

Return an exact domain query for this dialect.

Return type:: SQL

get_version(driver=None)[source]#

Get Spanner version information.

Parameters:: driver¶ (SpannerSyncDriver | None) -- Spanner driver instance.
Return type:: VersionInfo | None
Returns:: None since Spanner does not expose version information.

get_feature_flag(driver=None, feature='')[source]#

Check if Spanner supports a specific feature.

Parameters:

driver¶ (SpannerSyncDriver | None) -- Spanner driver instance.
feature¶ (str) -- Feature name to check.

Return type:

bool

Returns:

True if feature is supported, False otherwise.

get_optimal_type(driver=None, type_category='')[source]#

Get optimal Spanner type for a category.

Parameters:

driver¶ (SpannerSyncDriver | None) -- Spanner driver instance.
type_category¶ (str) -- Type category.

Return type:

str

Returns:

Spanner-specific type name.

get_tables(driver, schema=None)[source]#

Get tables using INFORMATION_SCHEMA.

Return type:: list[TableMetadata]

get_columns(driver, table=None, schema=None)[source]#

Get column information for a table or schema.

Return type:: list[ColumnMetadata]

get_indexes(driver, table=None, schema=None)[source]#

Get index metadata for a table or schema.

Return type:: list[IndexMetadata]

get_foreign_keys(driver, table=None, schema=None)[source]#

Get foreign key metadata.

Return type:: list[ForeignKeyMetadata]

get_constraints(driver, table=None, schema=None)[source]#

Get constraint metadata for a table or schema.

Return type:: MetadataResult

get_sequences(driver, schema=None, sequence_name=None)[source]#

Get sequence metadata.

Return type:: MetadataResult

get_change_streams(driver, schema=None, stream_name=None)[source]#

Get change stream metadata.

Return type:: MetadataResult

get_system_metadata(driver, request=None, **kwargs)[source]#

Get opt-in Spanner system metadata from SPANNER_SYS.

Return type:: SystemMetadataResult

get_metadata_capabilities(driver, domains=None, *, mode=None)[source]#

Get Spanner data-dictionary capability profile.

Return type:: MetadataCapabilityProfile

get_ddl(driver, object_name, schema=None, *, object_type='table', include_dependencies=True, prefer_native=True, redact=True)[source]#

Get Spanner DDL through the Database Admin API.

Return type:: DDLResult

Extension Settings#

Use the configuration types below in their corresponding extension_config namespace: "litestar", "events", or "adk" as supported by this adapter.

class sqlspec.adapters.spanner.litestar.SpannerLitestarConfig[source]#

Bases: LitestarConfig

Spanner-specific Litestar settings.

Use inside extension_config["litestar"] with this adapter's session store.

shard_count: NotRequired[int]#: Number of session key shards.

table_options: NotRequired[str]#: Table DDL options.

index_options: NotRequired[str]#: Index DDL options.

class sqlspec.adapters.spanner.adk.SpannerADKConfig[source]#

Bases: ADKConfig

Spanner-specific ADK extension settings.

shard_count: NotRequired[int]#: Generated shard count for hot key mitigation.

session_table_options: NotRequired[str]#: Raw Spanner OPTIONS clause content for the ADK session table.

events_table_options: NotRequired[str]#: Raw Spanner OPTIONS clause content for the ADK events table.

memory_table_options: NotRequired[str]#: Raw Spanner OPTIONS clause content for the ADK memory table.

expires_index_options: NotRequired[str]#: Raw Spanner OPTIONS clause content for expiration indexes.

retention: NotRequired[SpannerADKRetentionConfig]#: Spanner row-deletion retention policy settings.

class sqlspec.adapters.spanner.adk.SpannerADKRetentionConfig[source]#

Bases: TypedDict

Spanner-specific ADK row-deletion policy settings.

session_ttl_seconds: NotRequired[int]#: Session row retention in seconds.

event_ttl_seconds: NotRequired[int]#: Event row retention in seconds.

memory_ttl_seconds: NotRequired[int]#: Memory row retention in seconds.

Native execution controls#

query_options can be configured on the driver, supplied when opening a session, or overridden per call. They apply to queries and single DML operations; native batch DML does not accept them. last_statement=True marks final transaction DML, including only the final statement of a script.

Opt-in Arrow Batch Write ingestion works from database-backed read sessions. Mutation groups commit independently. Arrow overwrite retains transactional delete-and-insert behavior without partitioned DML or Batch Write.