Skip to content

feat(spanner): Add transaction exclusion from change streams sample - #14867

Open
iennae wants to merge 4 commits into
feat/spanner-create-change-streamfrom
feat/spanner-set-exclude-txn-from-change-streams
Open

iennae wants to merge 4 commits into
feat/spanner-create-change-streamfrom
feat/spanner-set-exclude-txn-from-change-streams

Conversation

@iennae

@iennae iennae commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Description

Change stream guides show Go and Java tabs for excluding specific read-write transactions from capture, leaving Python developers without a reference for exclude_txn_from_change_streams=True on run_in_transaction.

Adds spanner_set_exclude_txn_from_change_streams.

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

Excluding administrative or backfill read-write transactions from change streams had Go and Java samples without a Python reference.
@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 sample script and corresponding tests to demonstrate how to run a read-write Spanner transaction that is excluded from change stream capture. The review feedback suggests a more idiomatic Python implementation by returning the statement modification count directly from the transaction callback and run_in_transaction rather than using a mutable list in the outer scope, along with a corresponding update to the unit test mocks.

Comment on lines +39 to +73
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]}")

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

Instead of using a mutable list (row_counts) in the outer scope and clearing/appending to it inside the transaction callback, you can leverage the fact that database.run_in_transaction returns the return value of the callback function. This is more idiomatic, cleaner, and avoids side-effects on outer-scope variables during transaction retries.

    def insert_and_update_singer(transaction: spanner_v1.Transaction) -> int:
        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"
        )
        return int(inserted) + int(updated)

    try:
        modified_statements = 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: {modified_statements}")

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! This comment refers to an earlier revision of this file; the code here has since been reworked in later commits, so this thread no longer applies to the current diff.

Comment on lines +45 to +52
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

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

Update the transaction runner mock to return the result of the callback function, aligning with the updated implementation of set_exclude_txn_from_change_streams.

Suggested change
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
def run_txn(
fn: Callable[[mock.MagicMock], int],
exclude_txn_from_change_streams: bool = False,
) -> int:
assert exclude_txn_from_change_streams is True
return fn(transaction)
database.run_in_transaction.side_effect = run_txn

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! The sample records the count in an enclosing variable rather than returning it from the callback, so the mock doesn't need to return the callback result.

Replaces the outer list cell with a nonlocal integer and omits project identifiers from stdout and stderr.
Prints only runtime resource and query results instead of hardcoded string literals.
…_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
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