From a4d812075d1c960112c1d544c23e720077f00be3 Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Tue, 17 Nov 2026 23:45:56 +0000 Subject: [PATCH 1/6] feat(spanner): Add PostgreSQL DML last_statement optimization sample PostgreSQL-dialect Spanner transactions support last_statement=True with positional $1/$2 parameters, replacing an untagged inline documentation snippet. --- spanner/postgresql/README.md | 27 ++++ spanner/postgresql/noxfile_config.py | 21 +++ spanner/postgresql/pyproject.toml | 30 ++++ spanner/postgresql/requirements-test.txt | 2 + spanner/postgresql/requirements.txt | 2 + .../src/spanner_postgresql/__init__.py | 13 ++ .../postgresql_dml_last_statement.py | 103 +++++++++++++ spanner/postgresql/tests/__init__.py | 13 ++ spanner/postgresql/tests/conftest.py | 38 +++++ .../postgresql_dml_last_statement_test.py | 137 ++++++++++++++++++ 10 files changed, 386 insertions(+) create mode 100644 spanner/postgresql/README.md create mode 100644 spanner/postgresql/noxfile_config.py create mode 100644 spanner/postgresql/pyproject.toml create mode 100644 spanner/postgresql/requirements-test.txt create mode 100644 spanner/postgresql/requirements.txt create mode 100644 spanner/postgresql/src/spanner_postgresql/__init__.py create mode 100644 spanner/postgresql/src/spanner_postgresql/postgresql_dml_last_statement.py create mode 100644 spanner/postgresql/tests/__init__.py create mode 100644 spanner/postgresql/tests/conftest.py create mode 100644 spanner/postgresql/tests/postgresql_dml_last_statement_test.py diff --git a/spanner/postgresql/README.md b/spanner/postgresql/README.md new file mode 100644 index 00000000000..6806e1a22eb --- /dev/null +++ b/spanner/postgresql/README.md @@ -0,0 +1,27 @@ +# Cloud Spanner PostgreSQL-Dialect Samples + +Python samples demonstrating PostgreSQL-dialect Spanner queries, DML `RETURNING` clauses, and `last_statement=True` transaction optimizations. + +## Setup + +1. Create and activate a Python 3.13+ virtual environment: + + ```sh + python3 -m venv env + source env/bin/activate + ``` + +2. Install dependencies: + + ```sh + pip install -r requirements.txt + ``` + +## Running Tests + +Run unit tests offline: + +```sh +pip install -r requirements-test.txt +pytest tests +``` diff --git a/spanner/postgresql/noxfile_config.py b/spanner/postgresql/noxfile_config.py new file mode 100644 index 00000000000..fe371aaf480 --- /dev/null +++ b/spanner/postgresql/noxfile_config.py @@ -0,0 +1,21 @@ +# 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. + +TEST_CONFIG_OVERRIDE = { + "ignored_versions": ["2.7", "3.7", "3.8", "3.9", "3.10", "3.11", "3.12"], + "enforce_type_hints": True, + "gcloud_project_env": "GOOGLE_CLOUD_PROJECT", + "pip_version_override": None, + "envs": {}, +} diff --git a/spanner/postgresql/pyproject.toml b/spanner/postgresql/pyproject.toml new file mode 100644 index 00000000000..754d6461912 --- /dev/null +++ b/spanner/postgresql/pyproject.toml @@ -0,0 +1,30 @@ +# 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. + +# Local samples only. This package isn't published: install it from this +# directory with `pip install -e .`, never by name from PyPI. +[build-system] +requires = ["setuptools>=64"] +build-backend = "setuptools.build_meta" + +[project] +name = "spanner-postgresql-samples" +version = "0.0.0" +requires-python = ">=3.13" +dependencies = [ + "google-api-core==2.44.0", + "google-cloud-spanner==3.72.0", +] +# PyPI rejects uploads with this classifier. +classifiers = ["Private :: Do Not Upload"] diff --git a/spanner/postgresql/requirements-test.txt b/spanner/postgresql/requirements-test.txt new file mode 100644 index 00000000000..ac63bdc5a92 --- /dev/null +++ b/spanner/postgresql/requirements-test.txt @@ -0,0 +1,2 @@ +-e . +pytest==9.2.0 diff --git a/spanner/postgresql/requirements.txt b/spanner/postgresql/requirements.txt new file mode 100644 index 00000000000..a56c81cc2eb --- /dev/null +++ b/spanner/postgresql/requirements.txt @@ -0,0 +1,2 @@ +google-api-core==2.44.0 +google-cloud-spanner==3.72.0 diff --git a/spanner/postgresql/src/spanner_postgresql/__init__.py b/spanner/postgresql/src/spanner_postgresql/__init__.py new file mode 100644 index 00000000000..58d482ea386 --- /dev/null +++ b/spanner/postgresql/src/spanner_postgresql/__init__.py @@ -0,0 +1,13 @@ +# 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. diff --git a/spanner/postgresql/src/spanner_postgresql/postgresql_dml_last_statement.py b/spanner/postgresql/src/spanner_postgresql/postgresql_dml_last_statement.py new file mode 100644 index 00000000000..36d34d47a93 --- /dev/null +++ b/spanner/postgresql/src/spanner_postgresql/postgresql_dml_last_statement.py @@ -0,0 +1,103 @@ +# 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_postgresql_dml_last_statement] +import sys + +from google.api_core import exceptions +from google.cloud import spanner +from google.cloud import spanner_v1 +from google.cloud.spanner_v1 import param_types + + +def update_postgresql_dml_last_statement( + project_id: str, instance_id: str, database_id: str +) -> None: + """Executes the final PostgreSQL DML statement with last_statement=True. + + Setting last_statement=True commits the transaction inline with the final + DML request, avoiding a separate Commit RPC round trip. + + Args: + project_id: The Google Cloud project ID. + instance_id: The Spanner instance ID. + database_id: The PostgreSQL-dialect Spanner database ID. + """ + client = spanner.Client(project=project_id) + database = client.instance(instance_id).database(database_id) + updated_counts: list[int] = [] + + def update_singers(transaction: spanner_v1.Transaction) -> None: + row_count = transaction.execute_update( + "UPDATE Singers SET LastName = $1 WHERE SingerId = $2", + params={"p1": "Doe", "p2": 54214}, + param_types={"p1": param_types.STRING, "p2": param_types.INT64}, + last_statement=True, + ) + updated_counts.append(int(row_count)) + + try: + database.run_in_transaction(update_singers) + except exceptions.NotFound as err: + print( + f"error: PostgreSQL database '{database_id}' on instance " + f"'{instance_id}' in project '{project_id}' was not found: " + f"{err.message}", + file=sys.stderr, + ) + except exceptions.GoogleAPICallError as err: + print( + f"error: PostgreSQL DML last_statement update 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("Last Statement Optimization: True") + print(f"Updated Rows: {updated_counts[-1]}") + + +# [END spanner_postgresql_dml_last_statement] + + +if __name__ == "__main__": + import argparse + import os + + parser = argparse.ArgumentParser( + description="Execute a PostgreSQL-dialect DML update with last_statement=True." + ) + 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-pg-db"), + help="PostgreSQL-dialect Spanner database ID (default: $SPANNER_DATABASE_ID)", + ) + args = parser.parse_args() + + update_postgresql_dml_last_statement( + project_id=args.project_id, + instance_id=args.instance_id, + database_id=args.database_id, + ) diff --git a/spanner/postgresql/tests/__init__.py b/spanner/postgresql/tests/__init__.py new file mode 100644 index 00000000000..58d482ea386 --- /dev/null +++ b/spanner/postgresql/tests/__init__.py @@ -0,0 +1,13 @@ +# 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. diff --git a/spanner/postgresql/tests/conftest.py b/spanner/postgresql/tests/conftest.py new file mode 100644 index 00000000000..cd0aa69802f --- /dev/null +++ b/spanner/postgresql/tests/conftest.py @@ -0,0 +1,38 @@ +# 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. + +"""Shared live-test configuration for Cloud Spanner PostgreSQL-Dialect Samples.""" + +import os + +import pytest + +LIVE_PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT", "") +LIVE_INSTANCE_ID = os.environ.get("SPANNER_INSTANCE_ID", "") +LIVE_DATABASE_ID = os.environ.get( + "SPANNER_PG_DATABASE_ID", os.environ.get("SPANNER_DATABASE_ID", "") +) + +if os.environ.get("RUN_INTEGRATION_TESTS") == "true" and ( + not LIVE_PROJECT_ID or not LIVE_INSTANCE_ID or not LIVE_DATABASE_ID +): + raise RuntimeError( + "Set GOOGLE_CLOUD_PROJECT, SPANNER_INSTANCE_ID, and " + "SPANNER_PG_DATABASE_ID when RUN_INTEGRATION_TESTS=true." + ) + +live_only = pytest.mark.skipif( + os.environ.get("RUN_INTEGRATION_TESTS") != "true", + reason="Set RUN_INTEGRATION_TESTS=true to run integration tests.", +) diff --git a/spanner/postgresql/tests/postgresql_dml_last_statement_test.py b/spanner/postgresql/tests/postgresql_dml_last_statement_test.py new file mode 100644 index 00000000000..1d051b7df01 --- /dev/null +++ b/spanner/postgresql/tests/postgresql_dml_last_statement_test.py @@ -0,0 +1,137 @@ +# 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. + +import runpy +from unittest import mock + +from google.api_core import exceptions +import pytest +from spanner_postgresql import postgresql_dml_last_statement + +from . import conftest + +PROJECT_ID = "example-project-id" +INSTANCE_ID = "example-instance" +DATABASE_ID = "example-pg-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_update_postgresql_dml_last_statement_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.return_value = 1 + database.run_in_transaction.side_effect = lambda fn: fn(transaction) + + postgresql_dml_last_statement.update_postgresql_dml_last_statement( + PROJECT_ID, INSTANCE_ID, DATABASE_ID + ) + + call = transaction.execute_update.call_args + assert "$1" in call.args[0] + assert call.kwargs["last_statement"] is True + out, err = capsys.readouterr() + assert f"Resource ID: {DATABASE_NAME}" in out + assert "Last Statement Optimization: True" in out + assert "Updated Rows: 1" in out + assert err == "" + + +@pytest.mark.parametrize( + "error, expected_prefix", + [ + ( + exceptions.NotFound("db missing"), + "error: PostgreSQL database 'example-pg-db' on instance", + ), + ( + exceptions.Aborted("aborted"), + "error: PostgreSQL DML last_statement update failed", + ), + ], +) +@mock.patch(SPANNER_CLIENT) +def test_update_postgresql_dml_last_statement_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 + + postgresql_dml_last_statement.update_postgresql_dml_last_statement( + PROJECT_ID, INSTANCE_ID, DATABASE_ID + ) + + out, err = capsys.readouterr() + assert out == "" + assert err.startswith(expected_prefix) + + +@mock.patch(SPANNER_CLIENT) +def test_update_postgresql_dml_last_statement_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.return_value = 1 + database.run_in_transaction.side_effect = lambda fn: fn(transaction) + monkeypatch.setattr( + "sys.argv", + [ + "postgresql_dml_last_statement.py", + "--project-id", + PROJECT_ID, + "--instance-id", + INSTANCE_ID, + "--database-id", + DATABASE_ID, + ], + ) + + runpy.run_module( + "spanner_postgresql.postgresql_dml_last_statement", run_name="__main__" + ) + + assert "Updated Rows: 1" in capsys.readouterr().out + + +@conftest.live_only +def test_update_postgresql_dml_last_statement_live( + capsys: pytest.CaptureFixture[str], +) -> None: + postgresql_dml_last_statement.update_postgresql_dml_last_statement( + conftest.LIVE_PROJECT_ID, + conftest.LIVE_INSTANCE_ID, + conftest.LIVE_DATABASE_ID, + ) + + out, err = capsys.readouterr() + assert err == "" + assert "Last Statement Optimization: True" in out + assert "Updated Rows: 1" in out From 36683b41a3c513d7fdb0a3e341bde15211ea10be Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Wed, 18 Nov 2026 00:38:18 +0000 Subject: [PATCH 2/6] fix(spanner): Use nonlocal row count and omit project_id in PG DML sample Replaces the outer list cell with a nonlocal integer, isolates live test row setup/teardown, and omits project_id from output. --- .../postgresql_dml_last_statement.py | 15 ++++--- .../postgresql_dml_last_statement_test.py | 42 ++++++++++++++----- 2 files changed, 39 insertions(+), 18 deletions(-) diff --git a/spanner/postgresql/src/spanner_postgresql/postgresql_dml_last_statement.py b/spanner/postgresql/src/spanner_postgresql/postgresql_dml_last_statement.py index 36d34d47a93..3f68c92f6c4 100644 --- a/spanner/postgresql/src/spanner_postgresql/postgresql_dml_last_statement.py +++ b/spanner/postgresql/src/spanner_postgresql/postgresql_dml_last_statement.py @@ -36,37 +36,36 @@ def update_postgresql_dml_last_statement( """ client = spanner.Client(project=project_id) database = client.instance(instance_id).database(database_id) - updated_counts: list[int] = [] + updated_count = 0 def update_singers(transaction: spanner_v1.Transaction) -> None: + nonlocal updated_count row_count = transaction.execute_update( "UPDATE Singers SET LastName = $1 WHERE SingerId = $2", params={"p1": "Doe", "p2": 54214}, param_types={"p1": param_types.STRING, "p2": param_types.INT64}, last_statement=True, ) - updated_counts.append(int(row_count)) + updated_count = int(row_count) try: database.run_in_transaction(update_singers) except exceptions.NotFound as err: print( f"error: PostgreSQL database '{database_id}' on instance " - f"'{instance_id}' in project '{project_id}' was not found: " - f"{err.message}", + f"'{instance_id}' was not found: {err.message}", file=sys.stderr, ) except exceptions.GoogleAPICallError as err: print( f"error: PostgreSQL DML last_statement update 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("Last Statement Optimization: True") - print(f"Updated Rows: {updated_counts[-1]}") + print(f"Updated Rows: {updated_count}") # [END spanner_postgresql_dml_last_statement] diff --git a/spanner/postgresql/tests/postgresql_dml_last_statement_test.py b/spanner/postgresql/tests/postgresql_dml_last_statement_test.py index 1d051b7df01..7482fb32d39 100644 --- a/spanner/postgresql/tests/postgresql_dml_last_statement_test.py +++ b/spanner/postgresql/tests/postgresql_dml_last_statement_test.py @@ -16,6 +16,7 @@ from unittest import mock from google.api_core import exceptions +from google.cloud import spanner import pytest from spanner_postgresql import postgresql_dml_last_statement @@ -48,7 +49,8 @@ def test_update_postgresql_dml_last_statement_success( assert "$1" in call.args[0] assert call.kwargs["last_statement"] is True 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 "Last Statement Optimization: True" in out assert "Updated Rows: 1" in out assert err == "" @@ -86,6 +88,9 @@ def test_update_postgresql_dml_last_statement_errors( out, err = capsys.readouterr() assert out == "" assert err.startswith(expected_prefix) + assert PROJECT_ID not in err + assert PROJECT_ID not in err + assert PROJECT_ID not in err @mock.patch(SPANNER_CLIENT) @@ -125,13 +130,30 @@ def test_update_postgresql_dml_last_statement_cli_entrypoint( def test_update_postgresql_dml_last_statement_live( capsys: pytest.CaptureFixture[str], ) -> None: - postgresql_dml_last_statement.update_postgresql_dml_last_statement( - conftest.LIVE_PROJECT_ID, - conftest.LIVE_INSTANCE_ID, - conftest.LIVE_DATABASE_ID, + client = spanner.Client(project=conftest.LIVE_PROJECT_ID) + database = client.instance(conftest.LIVE_INSTANCE_ID).database( + conftest.LIVE_DATABASE_ID ) - - out, err = capsys.readouterr() - assert err == "" - assert "Last Statement Optimization: True" in out - assert "Updated Rows: 1" in out + database.run_in_transaction( + lambda txn: txn.execute_update( + "INSERT INTO Singers (SingerId, FirstName, LastName) " + "VALUES (54214, 'John', 'Smith') " + "ON CONFLICT (SingerId) DO UPDATE SET LastName = 'Smith'" + ) + ) + try: + postgresql_dml_last_statement.update_postgresql_dml_last_statement( + conftest.LIVE_PROJECT_ID, + conftest.LIVE_INSTANCE_ID, + conftest.LIVE_DATABASE_ID, + ) + + out, err = capsys.readouterr() + assert err == "" + assert conftest.LIVE_PROJECT_ID not in out + assert "Last Statement Optimization: True" in out + assert "Updated Rows: 1" in out + finally: + database.run_in_transaction( + lambda txn: txn.execute_update("DELETE FROM Singers WHERE SingerId = 54214") + ) From dab463ccb9f7d041d16b2384d36bf24d00db2990 Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Wed, 18 Nov 2026 02:42:52 +0000 Subject: [PATCH 3/6] fix(spanner): Remove hardcoded static stdout lines from sample output Prints only runtime resource and query results instead of hardcoded string literals. --- .../src/spanner_postgresql/postgresql_dml_last_statement.py | 1 - spanner/postgresql/tests/postgresql_dml_last_statement_test.py | 2 -- 2 files changed, 3 deletions(-) diff --git a/spanner/postgresql/src/spanner_postgresql/postgresql_dml_last_statement.py b/spanner/postgresql/src/spanner_postgresql/postgresql_dml_last_statement.py index 3f68c92f6c4..811c0c142a9 100644 --- a/spanner/postgresql/src/spanner_postgresql/postgresql_dml_last_statement.py +++ b/spanner/postgresql/src/spanner_postgresql/postgresql_dml_last_statement.py @@ -64,7 +64,6 @@ def update_singers(transaction: spanner_v1.Transaction) -> None: ) else: print(f"Resource ID: {database_id}") - print("Last Statement Optimization: True") print(f"Updated Rows: {updated_count}") diff --git a/spanner/postgresql/tests/postgresql_dml_last_statement_test.py b/spanner/postgresql/tests/postgresql_dml_last_statement_test.py index 7482fb32d39..f5aa55aa22c 100644 --- a/spanner/postgresql/tests/postgresql_dml_last_statement_test.py +++ b/spanner/postgresql/tests/postgresql_dml_last_statement_test.py @@ -51,7 +51,6 @@ def test_update_postgresql_dml_last_statement_success( out, err = capsys.readouterr() assert f"Resource ID: {DATABASE_ID}" in out assert PROJECT_ID not in out - assert "Last Statement Optimization: True" in out assert "Updated Rows: 1" in out assert err == "" @@ -151,7 +150,6 @@ def test_update_postgresql_dml_last_statement_live( out, err = capsys.readouterr() assert err == "" assert conftest.LIVE_PROJECT_ID not in out - assert "Last Statement Optimization: True" in out assert "Updated Rows: 1" in out finally: database.run_in_transaction( From 637268f6ff8849373ca0693ff3ee90b1dfc28d1e Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Wed, 18 Nov 2026 11:00:57 -0800 Subject: [PATCH 4/6] feat(spanner): Add PostgreSQL DROP SEQUENCE DDL sample (#14941) Dropping a sequence referenced by a column DEFAULT requires detaching the column default before executing DROP SEQUENCE. Add a standalone spanner_postgresql_drop_sequence sample and test suite. --- .../postgresql_drop_sequence.py | 98 +++++++++++ .../tests/postgresql_drop_sequence_test.py | 164 ++++++++++++++++++ 2 files changed, 262 insertions(+) create mode 100644 spanner/postgresql/src/spanner_postgresql/postgresql_drop_sequence.py create mode 100644 spanner/postgresql/tests/postgresql_drop_sequence_test.py diff --git a/spanner/postgresql/src/spanner_postgresql/postgresql_drop_sequence.py b/spanner/postgresql/src/spanner_postgresql/postgresql_drop_sequence.py new file mode 100644 index 00000000000..e1d5523d5c6 --- /dev/null +++ b/spanner/postgresql/src/spanner_postgresql/postgresql_drop_sequence.py @@ -0,0 +1,98 @@ +# 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_postgresql_drop_sequence] +import sys + +from google.api_core import exceptions +from google.cloud import spanner_admin_database_v1 + + +def drop_postgresql_sequence( + project_id: str, instance_id: str, database_id: str +) -> None: + """Detaches a column DEFAULT and drops a PostgreSQL sequence via DDL. + + Args: + project_id: The Google Cloud project ID. + instance_id: The Spanner instance ID. + database_id: The PostgreSQL-dialect Spanner database ID with Seq. + """ + client = spanner_admin_database_v1.DatabaseAdminClient() + database_path = client.database_path(project_id, instance_id, database_id) + sequence_name = "Seq" + request = spanner_admin_database_v1.UpdateDatabaseDdlRequest( + database=database_path, + statements=[ + "ALTER TABLE Customers ALTER COLUMN CustomerId DROP DEFAULT", + f"DROP SEQUENCE {sequence_name}", + ], + ) + + try: + operation = client.update_database_ddl(request=request) + print( + f"Waiting for PostgreSQL sequence '{sequence_name}' drop on " + f"'{database_id}'..." + ) + operation.result(timeout=300) + except exceptions.FailedPrecondition as err: + print( + f"error: sequence '{sequence_name}' is still referenced or missing " + f"on database '{database_id}' in instance '{instance_id}': {err.message}", + file=sys.stderr, + ) + except exceptions.GoogleAPICallError as err: + print( + f"error: failed to drop PostgreSQL sequence '{sequence_name}' on " + f"database '{database_id}' in instance '{instance_id}': {err.message}", + file=sys.stderr, + ) + else: + print(f"Resource ID: {database_id}") + print(f"Dropped Sequence: {sequence_name}") + + +# [END spanner_postgresql_drop_sequence] + + +if __name__ == "__main__": + import argparse + import os + + parser = argparse.ArgumentParser( + description="Detach column default and drop a PostgreSQL sequence." + ) + 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_PG_DATABASE_ID", "example-db"), + help="Spanner database ID", + ) + args = parser.parse_args() + + drop_postgresql_sequence( + project_id=args.project_id, + instance_id=args.instance_id, + database_id=args.database_id, + ) diff --git a/spanner/postgresql/tests/postgresql_drop_sequence_test.py b/spanner/postgresql/tests/postgresql_drop_sequence_test.py new file mode 100644 index 00000000000..fe4a75a90ac --- /dev/null +++ b/spanner/postgresql/tests/postgresql_drop_sequence_test.py @@ -0,0 +1,164 @@ +# 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. + +import runpy +from unittest import mock + +from google.api_core import exceptions +from google.cloud import spanner_admin_database_v1 +import pytest +from spanner_postgresql import postgresql_create_sequence +from spanner_postgresql import postgresql_drop_sequence + +from . import conftest + +PROJECT_ID = "example-project-id" +INSTANCE_ID = "example-instance" +DATABASE_ID = "example-pg-db" +ADMIN_CLIENT = "google.cloud.spanner_admin_database_v1.DatabaseAdminClient" + + +@mock.patch(ADMIN_CLIENT) +def test_drop_postgresql_sequence_success( + mock_client_class: mock.MagicMock, capsys: pytest.CaptureFixture[str] +) -> None: + mock_client_class.return_value.instance_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}" + ) + mock_client_class.return_value.database_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/{DATABASE_ID}" + ) + postgresql_drop_sequence.drop_postgresql_sequence( + PROJECT_ID, INSTANCE_ID, DATABASE_ID + ) + + req = mock_client_class.return_value.update_database_ddl.call_args.kwargs["request"] + assert len(req.statements) == 2 + out, err = capsys.readouterr() + assert f"Resource ID: {DATABASE_ID}" in out + assert "Dropped Sequence: Seq" in out + assert PROJECT_ID not in out + assert err == "" + + +@pytest.mark.parametrize( + "error, expected_prefix", + [ + ( + exceptions.FailedPrecondition("in use"), + "error: sequence 'Seq' is still referenced or missing", + ), + ( + exceptions.PermissionDenied("denied"), + "error: failed to drop PostgreSQL sequence 'Seq'", + ), + ], +) +@mock.patch(ADMIN_CLIENT) +def test_drop_postgresql_sequence_errors( + mock_client_class: mock.MagicMock, + capsys: pytest.CaptureFixture[str], + error: Exception, + expected_prefix: str, +) -> None: + mock_client_class.return_value.instance_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}" + ) + mock_client_class.return_value.database_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/{DATABASE_ID}" + ) + mock_client_class.return_value.update_database_ddl.side_effect = error + + postgresql_drop_sequence.drop_postgresql_sequence( + PROJECT_ID, INSTANCE_ID, DATABASE_ID + ) + + _out, err = capsys.readouterr() + assert err.startswith(expected_prefix) + assert PROJECT_ID not in err + + +@mock.patch(ADMIN_CLIENT) +def test_drop_postgresql_sequence_cli_entrypoint( + mock_client_class: mock.MagicMock, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + mock_client_class.return_value.instance_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}" + ) + mock_client_class.return_value.database_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/{DATABASE_ID}" + ) + monkeypatch.setattr( + "sys.argv", + [ + "postgresql_drop_sequence.py", + "--project-id", + PROJECT_ID, + "--instance-id", + INSTANCE_ID, + "--database-id", + DATABASE_ID, + ], + ) + + runpy.run_module("spanner_postgresql.postgresql_drop_sequence", run_name="__main__") + + assert "Dropped Sequence: Seq" in capsys.readouterr().out + + +@conftest.live_only +def test_drop_postgresql_sequence_live(capsys: pytest.CaptureFixture[str]) -> None: + admin = spanner_admin_database_v1.DatabaseAdminClient() + db_path = admin.database_path( + conftest.LIVE_PROJECT_ID, + conftest.LIVE_INSTANCE_ID, + conftest.LIVE_DATABASE_ID, + ) + admin.update_database_ddl( + request={ + "database": db_path, + "statements": [ + "DROP TABLE IF EXISTS Customers", + "DROP SEQUENCE IF EXISTS Seq", + ], + } + ).result(timeout=240) + try: + postgresql_create_sequence.create_postgresql_sequence( + conftest.LIVE_PROJECT_ID, + conftest.LIVE_INSTANCE_ID, + conftest.LIVE_DATABASE_ID, + ) + capsys.readouterr() + postgresql_drop_sequence.drop_postgresql_sequence( + conftest.LIVE_PROJECT_ID, + conftest.LIVE_INSTANCE_ID, + conftest.LIVE_DATABASE_ID, + ) + out, err = capsys.readouterr() + assert err == "" + assert conftest.LIVE_PROJECT_ID not in out + assert "Dropped Sequence: Seq" in out + finally: + admin.update_database_ddl( + request={ + "database": db_path, + "statements": [ + "DROP TABLE IF EXISTS Customers", + "DROP SEQUENCE IF EXISTS Seq", + ], + } + ).result(timeout=240) From 43569d563b06e5e943aa3197369d716de90a9269 Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Wed, 18 Nov 2026 21:40:59 +0000 Subject: [PATCH 5/6] fix(spanner): address review feedback for postgresql_drop_sequence Problem: review of this sample identified correctness and robustness improvements in the sample and its tests. Solution: apply the accepted review suggestions and extend the tests to cover the updated behavior. Details are in the review thread replies. Files updated: - spanner/postgresql/src/spanner_postgresql/postgresql_drop_sequence.py - spanner/postgresql/tests/postgresql_drop_sequence_test.py --- .../src/spanner_postgresql/postgresql_drop_sequence.py | 7 +++++++ spanner/postgresql/tests/postgresql_drop_sequence_test.py | 4 ++++ 2 files changed, 11 insertions(+) diff --git a/spanner/postgresql/src/spanner_postgresql/postgresql_drop_sequence.py b/spanner/postgresql/src/spanner_postgresql/postgresql_drop_sequence.py index e1d5523d5c6..fc7f3a7d4ca 100644 --- a/spanner/postgresql/src/spanner_postgresql/postgresql_drop_sequence.py +++ b/spanner/postgresql/src/spanner_postgresql/postgresql_drop_sequence.py @@ -53,6 +53,13 @@ def drop_postgresql_sequence( f"on database '{database_id}' in instance '{instance_id}': {err.message}", file=sys.stderr, ) + except TimeoutError as err: + print( + f"error: timed out waiting to drop PostgreSQL sequence " + f"'{sequence_name}' on database '{database_id}' in instance " + f"'{instance_id}'; the operation may still be running: {err}", + file=sys.stderr, + ) except exceptions.GoogleAPICallError as err: print( f"error: failed to drop PostgreSQL sequence '{sequence_name}' on " diff --git a/spanner/postgresql/tests/postgresql_drop_sequence_test.py b/spanner/postgresql/tests/postgresql_drop_sequence_test.py index fe4a75a90ac..111685f09dc 100644 --- a/spanner/postgresql/tests/postgresql_drop_sequence_test.py +++ b/spanner/postgresql/tests/postgresql_drop_sequence_test.py @@ -59,6 +59,10 @@ def test_drop_postgresql_sequence_success( exceptions.FailedPrecondition("in use"), "error: sequence 'Seq' is still referenced or missing", ), + ( + TimeoutError("deadline"), + "error: timed out waiting to drop PostgreSQL sequence 'Seq'", + ), ( exceptions.PermissionDenied("denied"), "error: failed to drop PostgreSQL sequence 'Seq'", From fcc349efa6245c1fa40766cbd9f85908fa8bf3ae Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Thu, 19 Nov 2026 04:41:42 +0000 Subject: [PATCH 6/6] style(spanner): use triple-quoted SQL strings in postgresql_dml_last_statement 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/tests/postgresql_dml_last_statement_test.py --- .../tests/postgresql_dml_last_statement_test.py | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/spanner/postgresql/tests/postgresql_dml_last_statement_test.py b/spanner/postgresql/tests/postgresql_dml_last_statement_test.py index f5aa55aa22c..36c0bbacde5 100644 --- a/spanner/postgresql/tests/postgresql_dml_last_statement_test.py +++ b/spanner/postgresql/tests/postgresql_dml_last_statement_test.py @@ -133,13 +133,11 @@ def test_update_postgresql_dml_last_statement_live( database = client.instance(conftest.LIVE_INSTANCE_ID).database( conftest.LIVE_DATABASE_ID ) - database.run_in_transaction( - lambda txn: txn.execute_update( - "INSERT INTO Singers (SingerId, FirstName, LastName) " - "VALUES (54214, 'John', 'Smith') " - "ON CONFLICT (SingerId) DO UPDATE SET LastName = 'Smith'" - ) - ) + database.run_in_transaction(lambda txn: txn.execute_update(""" + INSERT INTO Singers (SingerId, FirstName, LastName) + VALUES (54214, 'John', 'Smith') + ON CONFLICT (SingerId) DO UPDATE SET LastName = 'Smith' + """)) try: postgresql_dml_last_statement.update_postgresql_dml_last_statement( conftest.LIVE_PROJECT_ID,