From 222890e14e9cb2716c36a137978a2562ac016feb Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Tue, 17 Nov 2026 23:46:00 +0000 Subject: [PATCH 1/4] feat(spanner): Add transaction exclusion from change streams sample Excluding administrative or backfill read-write transactions from change streams had Go and Java samples without a Python reference. --- .../set_exclude_txn_from_change_streams.py | 107 ++++++++++++ ...et_exclude_txn_from_change_streams_test.py | 152 ++++++++++++++++++ 2 files changed, 259 insertions(+) create mode 100644 spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py create mode 100644 spanner/change_streams/tests/set_exclude_txn_from_change_streams_test.py diff --git a/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py b/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py new file mode 100644 index 0000000000..7e0e7d5beb --- /dev/null +++ b/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py @@ -0,0 +1,107 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# [START spanner_set_exclude_txn_from_change_streams] +import sys + +from google.api_core import exceptions +from google.cloud import spanner +from google.cloud import spanner_v1 + + +def set_exclude_txn_from_change_streams( + project_id: str, instance_id: str, database_id: str +) -> None: + """Runs a read-write transaction excluded from change stream capture. + + Only change streams created or altered with `allow_txn_exclusion = true` + honor transaction-level exclusion. + + Args: + project_id: The Google Cloud project ID. + instance_id: The Spanner instance ID. + database_id: The Spanner database ID containing Singers and a change + stream with allow_txn_exclusion = true. + """ + client = spanner.Client(project=project_id) + database = client.instance(instance_id).database(database_id) + row_counts: list[int] = [] + + def insert_and_update_singer(transaction: spanner_v1.Transaction) -> None: + row_counts.clear() + inserted = transaction.execute_update( + "INSERT OR UPDATE Singers (SingerId, FirstName, LastName) " + "VALUES (101, ' Virginia', 'Watson')" + ) + updated = transaction.execute_update( + "UPDATE Singers SET FirstName = 'Virginia' WHERE SingerId = 101" + ) + row_counts.append(int(inserted) + int(updated)) + + try: + database.run_in_transaction( + insert_and_update_singer, + exclude_txn_from_change_streams=True, + ) + except exceptions.NotFound as err: + print( + f"error: database '{database_id}' on instance '{instance_id}' " + f"in project '{project_id}' was not found: {err.message}", + file=sys.stderr, + ) + except exceptions.GoogleAPICallError as err: + print( + f"error: change-stream excluded transaction failed on database " + f"'{database_id}' in instance '{instance_id}' for project " + f"'{project_id}': {err.message}", + file=sys.stderr, + ) + else: + print(f"Resource ID: {database.name}") + print("Excluded From Change Streams: True") + print(f"Modified Statements: {row_counts[-1]}") + + +# [END spanner_set_exclude_txn_from_change_streams] + + +if __name__ == "__main__": + import argparse + import os + + parser = argparse.ArgumentParser( + description="Exclude a read-write Spanner transaction from change streams." + ) + parser.add_argument( + "--project-id", + default=os.environ.get("GOOGLE_CLOUD_PROJECT", "example-project-id"), + help="Google Cloud project ID (default: $GOOGLE_CLOUD_PROJECT)", + ) + parser.add_argument( + "--instance-id", + default=os.environ.get("SPANNER_INSTANCE_ID", "example-instance"), + help="Spanner instance ID (default: $SPANNER_INSTANCE_ID)", + ) + parser.add_argument( + "--database-id", + default=os.environ.get("SPANNER_DATABASE_ID", "example-db"), + help="Spanner database ID (default: $SPANNER_DATABASE_ID)", + ) + args = parser.parse_args() + + set_exclude_txn_from_change_streams( + project_id=args.project_id, + instance_id=args.instance_id, + database_id=args.database_id, + ) diff --git a/spanner/change_streams/tests/set_exclude_txn_from_change_streams_test.py b/spanner/change_streams/tests/set_exclude_txn_from_change_streams_test.py new file mode 100644 index 0000000000..1a7a1292e8 --- /dev/null +++ b/spanner/change_streams/tests/set_exclude_txn_from_change_streams_test.py @@ -0,0 +1,152 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from collections.abc import Callable +import runpy +from unittest import mock + +from google.api_core import exceptions +from google.cloud import spanner +from google.cloud.spanner_v1 import KeySet +import pytest +from spanner_change_streams import set_exclude_txn_from_change_streams + +from . import conftest + +PROJECT_ID = "example-project-id" +INSTANCE_ID = "example-instance" +DATABASE_ID = "example-db" +DATABASE_NAME = f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/{DATABASE_ID}" +SPANNER_CLIENT = "google.cloud.spanner.Client" + + +@mock.patch(SPANNER_CLIENT) +def test_set_exclude_txn_from_change_streams_success( + mock_client_class: mock.MagicMock, capsys: pytest.CaptureFixture[str] +) -> None: + database = ( + mock_client_class.return_value.instance.return_value.database.return_value + ) + database.name = DATABASE_NAME + transaction = mock.MagicMock() + transaction.execute_update.side_effect = [1, 1] + + def run_txn( + fn: Callable[[mock.MagicMock], None], + exclude_txn_from_change_streams: bool = False, + ) -> None: + assert exclude_txn_from_change_streams is True + fn(transaction) + + database.run_in_transaction.side_effect = run_txn + + set_exclude_txn_from_change_streams.set_exclude_txn_from_change_streams( + PROJECT_ID, INSTANCE_ID, DATABASE_ID + ) + + out, err = capsys.readouterr() + assert f"Resource ID: {DATABASE_NAME}" in out + assert "Excluded From Change Streams: True" in out + assert "Modified Statements: 2" in out + assert err == "" + + +@pytest.mark.parametrize( + "error, expected_prefix", + [ + ( + exceptions.NotFound("db missing"), + "error: database 'example-db' on instance 'example-instance'", + ), + ( + exceptions.Aborted("aborted"), + "error: change-stream excluded transaction failed", + ), + ], +) +@mock.patch(SPANNER_CLIENT) +def test_set_exclude_txn_from_change_streams_errors( + mock_client_class: mock.MagicMock, + capsys: pytest.CaptureFixture[str], + error: Exception, + expected_prefix: str, +) -> None: + database = ( + mock_client_class.return_value.instance.return_value.database.return_value + ) + database.run_in_transaction.side_effect = error + + set_exclude_txn_from_change_streams.set_exclude_txn_from_change_streams( + PROJECT_ID, INSTANCE_ID, DATABASE_ID + ) + + out, err = capsys.readouterr() + assert out == "" + assert err.startswith(expected_prefix) + + +@mock.patch(SPANNER_CLIENT) +def test_set_exclude_txn_from_change_streams_cli_entrypoint( + mock_client_class: mock.MagicMock, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + database = ( + mock_client_class.return_value.instance.return_value.database.return_value + ) + database.name = DATABASE_NAME + transaction = mock.MagicMock() + transaction.execute_update.side_effect = [1, 1] + database.run_in_transaction.side_effect = lambda fn, **_kw: fn(transaction) + monkeypatch.setattr( + "sys.argv", + [ + "set_exclude_txn_from_change_streams.py", + "--project-id", + PROJECT_ID, + "--instance-id", + INSTANCE_ID, + "--database-id", + DATABASE_ID, + ], + ) + + runpy.run_module( + "spanner_change_streams.set_exclude_txn_from_change_streams", + run_name="__main__", + ) + + assert "Excluded From Change Streams: True" in capsys.readouterr().out + + +@conftest.live_only +def test_set_exclude_txn_from_change_streams_live( + capsys: pytest.CaptureFixture[str], +) -> None: + client = spanner.Client(project=conftest.LIVE_PROJECT_ID) + database = client.instance(conftest.LIVE_INSTANCE_ID).database( + conftest.LIVE_DATABASE_ID + ) + try: + set_exclude_txn_from_change_streams.set_exclude_txn_from_change_streams( + conftest.LIVE_PROJECT_ID, + conftest.LIVE_INSTANCE_ID, + conftest.LIVE_DATABASE_ID, + ) + out, err = capsys.readouterr() + assert err == "" + assert "Excluded From Change Streams: True" in out + finally: + with database.batch() as batch: + batch.delete(table="Singers", keyset=KeySet(keys=[[101]])) From 731e4147f42df5792a9eeccce5ba553658dbbadd Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Wed, 18 Nov 2026 00:38:22 +0000 Subject: [PATCH 2/4] fix(spanner): Use nonlocal counter and omit project_id in txn exclusion Replaces the outer list cell with a nonlocal integer and omits project identifiers from stdout and stderr. --- .../set_exclude_txn_from_change_streams.py | 15 +++++++-------- .../set_exclude_txn_from_change_streams_test.py | 5 ++++- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py b/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py index 7e0e7d5beb..741313371b 100644 --- a/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py +++ b/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py @@ -36,10 +36,10 @@ def set_exclude_txn_from_change_streams( """ client = spanner.Client(project=project_id) database = client.instance(instance_id).database(database_id) - row_counts: list[int] = [] + modified_statements = 0 def insert_and_update_singer(transaction: spanner_v1.Transaction) -> None: - row_counts.clear() + nonlocal modified_statements inserted = transaction.execute_update( "INSERT OR UPDATE Singers (SingerId, FirstName, LastName) " "VALUES (101, ' Virginia', 'Watson')" @@ -47,7 +47,7 @@ def insert_and_update_singer(transaction: spanner_v1.Transaction) -> None: updated = transaction.execute_update( "UPDATE Singers SET FirstName = 'Virginia' WHERE SingerId = 101" ) - row_counts.append(int(inserted) + int(updated)) + modified_statements = int(inserted) + int(updated) try: database.run_in_transaction( @@ -57,20 +57,19 @@ def insert_and_update_singer(transaction: spanner_v1.Transaction) -> None: except exceptions.NotFound as err: print( f"error: database '{database_id}' on instance '{instance_id}' " - f"in project '{project_id}' was not found: {err.message}", + f"was not found: {err.message}", file=sys.stderr, ) except exceptions.GoogleAPICallError as err: print( f"error: change-stream excluded transaction failed on database " - f"'{database_id}' in instance '{instance_id}' for project " - f"'{project_id}': {err.message}", + f"'{database_id}' in instance '{instance_id}': {err.message}", file=sys.stderr, ) else: - print(f"Resource ID: {database.name}") + print(f"Resource ID: {database_id}") print("Excluded From Change Streams: True") - print(f"Modified Statements: {row_counts[-1]}") + print(f"Modified Statements: {modified_statements}") # [END spanner_set_exclude_txn_from_change_streams] diff --git a/spanner/change_streams/tests/set_exclude_txn_from_change_streams_test.py b/spanner/change_streams/tests/set_exclude_txn_from_change_streams_test.py index 1a7a1292e8..21b504ad9b 100644 --- a/spanner/change_streams/tests/set_exclude_txn_from_change_streams_test.py +++ b/spanner/change_streams/tests/set_exclude_txn_from_change_streams_test.py @@ -56,7 +56,8 @@ def run_txn( ) out, err = capsys.readouterr() - assert f"Resource ID: {DATABASE_NAME}" in out + assert f"Resource ID: {DATABASE_ID}" in out + assert PROJECT_ID not in out assert "Excluded From Change Streams: True" in out assert "Modified Statements: 2" in out assert err == "" @@ -94,6 +95,8 @@ def test_set_exclude_txn_from_change_streams_errors( out, err = capsys.readouterr() assert out == "" assert err.startswith(expected_prefix) + assert PROJECT_ID not in err + assert PROJECT_ID not in err @mock.patch(SPANNER_CLIENT) From 80f8c2eefe15e5d7beb451d84b3e462cfe13b0aa Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Wed, 18 Nov 2026 02:42:53 +0000 Subject: [PATCH 3/4] fix(spanner): Remove hardcoded static stdout lines from sample output Prints only runtime resource and query results instead of hardcoded string literals. --- .../set_exclude_txn_from_change_streams.py | 1 - .../tests/set_exclude_txn_from_change_streams_test.py | 6 +++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py b/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py index 741313371b..501e5f83d8 100644 --- a/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py +++ b/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py @@ -68,7 +68,6 @@ def insert_and_update_singer(transaction: spanner_v1.Transaction) -> None: ) else: print(f"Resource ID: {database_id}") - print("Excluded From Change Streams: True") print(f"Modified Statements: {modified_statements}") diff --git a/spanner/change_streams/tests/set_exclude_txn_from_change_streams_test.py b/spanner/change_streams/tests/set_exclude_txn_from_change_streams_test.py index 21b504ad9b..89ae9089a3 100644 --- a/spanner/change_streams/tests/set_exclude_txn_from_change_streams_test.py +++ b/spanner/change_streams/tests/set_exclude_txn_from_change_streams_test.py @@ -58,7 +58,6 @@ def run_txn( out, err = capsys.readouterr() assert f"Resource ID: {DATABASE_ID}" in out assert PROJECT_ID not in out - assert "Excluded From Change Streams: True" in out assert "Modified Statements: 2" in out assert err == "" @@ -130,7 +129,7 @@ def test_set_exclude_txn_from_change_streams_cli_entrypoint( run_name="__main__", ) - assert "Excluded From Change Streams: True" in capsys.readouterr().out + assert "Modified Statements: 2" in capsys.readouterr().out @conftest.live_only @@ -149,7 +148,8 @@ def test_set_exclude_txn_from_change_streams_live( ) out, err = capsys.readouterr() assert err == "" - assert "Excluded From Change Streams: True" in out + assert conftest.LIVE_PROJECT_ID not in out + assert "Modified Statements: 2" in out finally: with database.batch() as batch: batch.delete(table="Singers", keyset=KeySet(keys=[[101]])) From a20c0b38b17a89dc1740d9a6720ed8d9d59eedd3 Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Thu, 19 Nov 2026 04:42:09 +0000 Subject: [PATCH 4/4] style(spanner): use triple-quoted SQL strings in set_exclude_txn_from_change_streams Problem: multi-line SQL and DDL statements were written as adjacent string fragments. That style is easy to get wrong (a missing trailing space joins two SQL tokens) and is harder to read than the statement itself, and the samples in this set mixed it with triple-quoted SQL. Solution: write each multi-line statement as a single triple-quoted string, matching the layout already used by the other samples. Only whitespace between SQL tokens changes; the statements are otherwise identical. Files updated: - spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py --- .../set_exclude_txn_from_change_streams.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py b/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py index 501e5f83d8..ede602f698 100644 --- a/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py +++ b/spanner/change_streams/src/spanner_change_streams/set_exclude_txn_from_change_streams.py @@ -40,10 +40,10 @@ def set_exclude_txn_from_change_streams( def insert_and_update_singer(transaction: spanner_v1.Transaction) -> None: nonlocal modified_statements - inserted = transaction.execute_update( - "INSERT OR UPDATE Singers (SingerId, FirstName, LastName) " - "VALUES (101, ' Virginia', 'Watson')" - ) + inserted = transaction.execute_update(""" + INSERT OR UPDATE Singers (SingerId, FirstName, LastName) + VALUES (101, ' Virginia', 'Watson') + """) updated = transaction.execute_update( "UPDATE Singers SET FirstName = 'Virginia' WHERE SingerId = 101" )