Summary

Add a timeout property to Connection and pass timeout= to execute_sql() in the three DBAPI code paths that currently omit it: snapshot reads, transaction statements, and autocommit DML.

Fixes googleapis/google-cloud-python#16492

Background

_SnapshotBase.execute_sql() accepts a timeout parameter that controls the gRPC deadline for the ExecuteStreamingSql RPC. When not provided, it defaults to gapic_v1.method.DEFAULT, which resolves to default_timeout=3600.0 in the transport layer.

The DBAPI calls execute_sql() in three locations, none of which pass timeout=:

1. Snapshot reads — cursor._handle_DQL_with_snapshot() calls snapshot.execute_sql(sql, params, param_types, request_options=...) without timeout=
2. Transaction reads/writes — connection.run_statement() calls transaction.execute_sql(sql, params, param_types=..., request_options=...) without timeout=
3. Autocommit DML — cursor._do_execute_update_in_autocommit() calls transaction.execute_sql(sql, params=..., param_types=..., last_statement=True) without timeout=

This means DBAPI consumers (SQLAlchemy, Django, raw DBAPI) cannot control the gRPC deadline for individual statements — all queries use the 3600-second default.

Timeline

Other execution parameters (request_options, request_priority, transaction_tag, request_tag) were each wired through the DBAPI incrementally. The timeout parameter was not included in any of these additions.

Changes

connection.py

• Add self._timeout = None to __init__
• Add timeout property and setter
• Pass timeout=self._timeout in run_statement() when set

cursor.py

• Pass timeout=self.connection._timeout in _handle_DQL_with_snapshot() when set
• Pass timeout=self.connection._timeout in _do_execute_update_in_autocommit() when set

When timeout is None (the default), timeout= is not passed, preserving the existing behavior of using gapic_v1.method.DEFAULT.

Usage

from google.cloud.spanner_dbapi import connect

conn = connect(instance_id, database_id, project=project)
conn.timeout = 60  # 60-second gRPC deadline for subsequent statements

cursor = conn.cursor()
cursor.execute("SELECT * FROM my_table")

Tests

Added 7 unit tests:

• test_timeout_default_none — verifies default is None
• test_timeout_property — verifies getter/setter
• test_timeout_passed_to_run_statement — verifies timeout= is passed in run_statement()
• test_timeout_not_passed_when_none — verifies timeout= is omitted when None
• test_do_execute_update_with_timeout — verifies timeout= in autocommit DML path
• test_handle_DQL_with_snapshot_timeout — verifies timeout= in snapshot read path
• test_handle_DQL_with_snapshot_no_timeout — verifies omission in snapshot read path

All 205 existing DBAPI tests continue to pass.

Related

• Companion dialect change: feat(sqlalchemy-spanner): wire timeout execution option through to DBAPI Connection.timeout google-cloud-python#16467
• Google's own samples demonstrate timeout= on execute_sql(): PR chore: add samples for transaction timeout configuration #1380 (spanner_set_statement_timeout), PR feat: add retry and timeout for batch dml #1107 (spanner_set_custom_timeout_and_retry)