Skip to content

feat(spanner): Add PostgreSQL INSERT DML RETURNING sample - #14863

Open
iennae wants to merge 3 commits into
feat/spanner-postgresql-dml-last-statementfrom
feat/spanner-postgresql-insert-dml-returning
Open

iennae wants to merge 3 commits into
feat/spanner-postgresql-dml-last-statementfrom
feat/spanner-postgresql-insert-dml-returning

Conversation

@iennae

@iennae iennae commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Description

PostgreSQL-dialect Spanner databases use standard PostgreSQL INSERT ... RETURNING syntax to return generated columns in a single round trip.

Adds spanner_postgresql_insert_dml_returning using the canonical cross-language region tag.

Note: Stacked on #14851 (feat/spanner-postgresql-dml-last-statement) so this PR shows only this sample's diff. It will merge into main after #14851.

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

PostgreSQL-dialect Spanner uses RETURNING rather than THEN RETURN to read generated columns from inserted rows.
@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, postgresql_insert_dml_returning.py, along with its unit and integration tests, to demonstrate how to insert rows into a PostgreSQL-dialect Spanner database and return values using the RETURNING clause. The review feedback suggests a couple of improvements to make the transaction callback more idiomatic and robust: replacing the row_counts list with a nonlocal integer variable and adding a safety check to ensure results.stats is not None before accessing row_count_exact.

Comment on lines +35 to +51
inserted_names: list[str] = []
row_counts: list[int] = []

def insert_singers(transaction: spanner_v1.Transaction) -> None:
inserted_names.clear()
row_counts.clear()
results = transaction.execute_sql(
"INSERT INTO Singers (SingerId, FirstName, LastName) VALUES "
"(21, 'Luann', 'Chizoba'), "
"(22, 'Denis', 'Patricio'), "
"(23, 'Felix', 'Ronan'), "
"(24, 'Dominik', 'Martyna') "
"RETURNING FullName"
)
for row in results:
inserted_names.append(str(row[0]))
row_counts.append(int(results.stats.row_count_exact))

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

Using a list (row_counts) to store a single integer value across the transaction callback scope is non-idiomatic in Python and can be simplified using the nonlocal keyword.

Additionally, to adhere to defensive programming practices, we should safeguard against cases where results.stats might be None (or not yet populated) before accessing row_count_exact. Accessing results.stats.row_count_exact directly without a None check could raise an AttributeError, and subsequently accessing row_counts[-1] could raise an IndexError if the list remains empty.

We can refactor this to use a simple row_count integer variable with nonlocal and a safe None check.

Suggested change
inserted_names: list[str] = []
row_counts: list[int] = []
def insert_singers(transaction: spanner_v1.Transaction) -> None:
inserted_names.clear()
row_counts.clear()
results = transaction.execute_sql(
"INSERT INTO Singers (SingerId, FirstName, LastName) VALUES "
"(21, 'Luann', 'Chizoba'), "
"(22, 'Denis', 'Patricio'), "
"(23, 'Felix', 'Ronan'), "
"(24, 'Dominik', 'Martyna') "
"RETURNING FullName"
)
for row in results:
inserted_names.append(str(row[0]))
row_counts.append(int(results.stats.row_count_exact))
inserted_names: list[str] = []
row_count = 0
def insert_singers(transaction: spanner_v1.Transaction) -> None:
nonlocal row_count
inserted_names.clear()
results = transaction.execute_sql(
"INSERT INTO Singers (SingerId, FirstName, LastName) VALUES "
"(21, 'Luann', 'Chizoba'), "
"(22, 'Denis', 'Patricio'), "
"(23, 'Felix', 'Ronan'), "
"(24, 'Dominik', 'Martyna') "
"RETURNING FullName"
)
for row in results:
inserted_names.append(str(row[0]))
row_count = int(results.stats.row_count_exact) if results.stats else 0

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.

print(f"Resource ID: {database.name}")
for full_name in inserted_names:
print(f"Full Name: {full_name}")
print(f"Inserted Rows: {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

Update the print statement to use the simplified row_count variable instead of accessing the last element of the row_counts list.

Suggested change
print(f"Inserted Rows: {row_counts[-1]}")
print(f"Inserted Rows: {row_count}")

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.

Uses a nonlocal row counter with a defensive results.stats check and omits project identifiers from stdout and stderr.
…l_returning

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/postgresql/src/spanner_postgresql/postgresql_insert_dml_returning.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