Skip to content

feat(spanner): Add change stream TVF streaming read sample - #14868

Open
iennae wants to merge 3 commits into
feat/spanner-create-change-streamfrom
feat/spanner-read-change-stream
Open

iennae wants to merge 3 commits into
feat/spanner-create-change-streamfrom
feat/spanner-read-change-stream

Conversation

@iennae

@iennae iennae commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Description

Querying READ_<ChangeStream> requires a single-use strong read over ExecuteStreamingSql, and Spanner returns a sentinel read_timestamp in change stream metadata that overflows datetime conversion in high-level database.snapshot() calls.

Adds spanner_read_change_stream using spanner_v1.SpannerClient.execute_streaming_sql on a multiplexed session.

Note: Stacked on #14855 (feat/spanner-create-change-stream) so this PR shows only this sample's diff. It will merge into main after #14855.

Checklist

Testing

  • I have tested this change on a live environment and verified it works as intended. Unit and live integration tests pass on Python 3.13.

Compliance & Style


Post-Approval Actions

  • Please merge this PR for me once it is approved

Change stream TVF queries return a sentinel read_timestamp that overflows veneer snapshots, requiring single-use ExecuteStreamingSql via GAPIC.
@iennae
iennae requested review from a team as code owners November 17, 2026 23:48
@product-auto-label product-auto-label Bot added api: spanner Issues related to the Spanner API. samples Issues that are directly related to samples. labels Nov 17, 2026
@snippet-bot

snippet-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Here is the summary of changes.

You are about to add 1 region tag.

This comment is generated by snippet-bot.
If you find problems with this result, please file an issue at:
https://github.com/googleapis/repo-automation-bots/issues.
To update this comment, add snippet-bot:force-run label or use the checkbox below:

  • Refresh this comment

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a new script and corresponding tests to stream initial partition records from a Spanner change stream TVF. The review feedback correctly identifies a potential session leak because the created Spanner session is never deleted. It is recommended to wrap the streaming SQL execution in a try...finally block to ensure the session is cleaned up, and to add a corresponding assertion in the unit tests.

Comment on lines +60 to +73
try:
session_req = spanner_v1.CreateSessionRequest(
database=database_name,
session=spanner_v1.Session(multiplexed=True),
)
session = client.create_session(request=session_req)
sql_req = spanner_v1.ExecuteSqlRequest(
session=session.name,
sql=sql,
params=params,
param_types={"start_ts": ts_type, "end_ts": ts_type},
transaction=selector,
)
chunks = list(client.execute_streaming_sql(request=sql_req))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The created session is not deleted or cleaned up after the streaming SQL query finishes. In Cloud Spanner, sessions are limited resources, and failing to delete them can lead to session leaks. Wrap the query execution in a try...finally block to ensure client.delete_session is called to clean up the session.

    session_req = spanner_v1.CreateSessionRequest(
        database=database_name,
        session=spanner_v1.Session(multiplexed=True),
    )
    session = client.create_session(request=session_req)
    try:
        sql_req = spanner_v1.ExecuteSqlRequest(
            session=session.name,
            sql=sql,
            params=params,
            param_types={"start_ts": ts_type, "end_ts": ts_type},
            transaction=selector,
        )
        chunks = list(client.execute_streaming_sql(request=sql_req))
    finally:
        try:
            client.delete_session(name=session.name)
        except Exception:
            pass

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for flagging session cleanup! Here the sample creates a multiplexed session (spanner_v1.Session(multiplexed=True)), whose lifecycle is managed automatically by Cloud Spanner (DeleteSession is not supported on multiplexed sessions). We added an inline comment clarifying this behavior.

Comment on lines +48 to +52
out, err = capsys.readouterr()
assert f"Resource ID: {DATABASE_NAME}" in out
assert "Change Stream: SingersAndAlbumsStream" in out
assert "Stream Chunks Received: 1" in out
assert err == ""

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Add an assertion to verify that the created session is properly deleted after the streaming SQL query completes.

Suggested change
out, err = capsys.readouterr()
assert f"Resource ID: {DATABASE_NAME}" in out
assert "Change Stream: SingersAndAlbumsStream" in out
assert "Stream Chunks Received: 1" in out
assert err == ""
out, err = capsys.readouterr()
assert f"Resource ID: {DATABASE_NAME}" in out
assert "Change Stream: SingersAndAlbumsStream" in out
assert "Stream Chunks Received: 1" in out
assert err == ""
client.delete_session.assert_called_once_with(name=SESSION_NAME)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Since multiplexed sessions are managed automatically by Cloud Spanner and are not deleted via delete_session, we are skipping this mock assertion.

Documents that multiplexed sessions are Spanner-managed and omits project identifiers from stdout and stderr.
Prints only runtime resource and query results instead of hardcoded string literals.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

api: spanner Issues related to the Spanner API. samples Issues that are directly related to samples.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants