diff --git a/spanner/postgresql/src/spanner_postgresql/postgresql_delete_dml_returning.py b/spanner/postgresql/src/spanner_postgresql/postgresql_delete_dml_returning.py new file mode 100644 index 0000000000..f5b3f94f6a --- /dev/null +++ b/spanner/postgresql/src/spanner_postgresql/postgresql_delete_dml_returning.py @@ -0,0 +1,102 @@ +# 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_delete_dml_returning] +import sys + +from google.api_core import exceptions +from google.cloud import spanner +from google.cloud import spanner_v1 + + +def postgresql_delete_dml_returning( + project_id: str, instance_id: str, database_id: str +) -> None: + """Deletes matching Singers rows in PostgreSQL Spanner with RETURNING. + + 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) + deleted_singers: list[tuple[int, str]] = [] + row_count = 0 + + def delete_singers(transaction: spanner_v1.Transaction) -> None: + nonlocal row_count + deleted_singers.clear() + results = transaction.execute_sql(""" + DELETE FROM Singers WHERE FirstName = 'David' + RETURNING SingerId, FullName + """) + for singer_id, full_name in results: + deleted_singers.append((int(singer_id), str(full_name))) + row_count = int(results.stats.row_count_exact) if results.stats else 0 + + try: + database.run_in_transaction(delete_singers) + except exceptions.NotFound as err: + print( + f"error: PostgreSQL database '{database_id}' on instance " + f"'{instance_id}' was not found: {err.message}", + file=sys.stderr, + ) + except exceptions.GoogleAPICallError as err: + print( + f"error: PostgreSQL DELETE RETURNING failed on database " + f"'{database_id}' in instance '{instance_id}': {err.message}", + file=sys.stderr, + ) + else: + print(f"Resource ID: {database_id}") + print(f"Deleted Rows: {row_count}") + for singer_id, full_name in deleted_singers: + print(f"Full Name: {full_name}") + print(f"Singer ID: {singer_id}") + + +# [END spanner_postgresql_delete_dml_returning] + + +if __name__ == "__main__": + import argparse + import os + + parser = argparse.ArgumentParser( + description="Delete Singers rows using PostgreSQL-dialect DML RETURNING." + ) + 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() + + postgresql_delete_dml_returning( + project_id=args.project_id, + instance_id=args.instance_id, + database_id=args.database_id, + ) diff --git a/spanner/postgresql/tests/postgresql_delete_dml_returning_test.py b/spanner/postgresql/tests/postgresql_delete_dml_returning_test.py new file mode 100644 index 0000000000..a291565edb --- /dev/null +++ b/spanner/postgresql/tests/postgresql_delete_dml_returning_test.py @@ -0,0 +1,160 @@ +# 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 +import pytest +from spanner_postgresql import postgresql_delete_dml_returning + +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" + + +def _mock_result_set(rows: list[tuple[object, ...]], count: int) -> mock.MagicMock: + rs = mock.MagicMock() + rs.__iter__.return_value = iter(rows) + rs.stats.row_count_exact = count + return rs + + +@mock.patch(SPANNER_CLIENT) +def test_postgresql_delete_dml_returning_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_sql.return_value = _mock_result_set([(25, "David Lee")], 1) + database.run_in_transaction.side_effect = lambda fn: fn(transaction) + + postgresql_delete_dml_returning.postgresql_delete_dml_returning( + PROJECT_ID, INSTANCE_ID, DATABASE_ID + ) + + sql = transaction.execute_sql.call_args.args[0] + assert "RETURNING SingerId, FullName" in sql + out, err = capsys.readouterr() + assert f"Resource ID: {DATABASE_ID}" in out + assert PROJECT_ID not in out + assert "Deleted Rows: 1" in out + assert "Full Name: David Lee" in out + assert "Singer ID: 25" 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 DELETE RETURNING failed", + ), + ], +) +@mock.patch(SPANNER_CLIENT) +def test_postgresql_delete_dml_returning_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_delete_dml_returning.postgresql_delete_dml_returning( + PROJECT_ID, INSTANCE_ID, DATABASE_ID + ) + + 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) +def test_postgresql_delete_dml_returning_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_sql.return_value = _mock_result_set([(25, "David Lee")], 1) + database.run_in_transaction.side_effect = lambda fn: fn(transaction) + monkeypatch.setattr( + "sys.argv", + [ + "postgresql_delete_dml_returning.py", + "--project-id", + PROJECT_ID, + "--instance-id", + INSTANCE_ID, + "--database-id", + DATABASE_ID, + ], + ) + + runpy.run_module( + "spanner_postgresql.postgresql_delete_dml_returning", run_name="__main__" + ) + + assert "Deleted Rows: 1" in capsys.readouterr().out + + +@conftest.live_only +def test_postgresql_delete_dml_returning_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 + ) + with database.batch() as batch: + batch.insert_or_update( + table="singers", + columns=("singerid", "firstname", "lastname"), + values=[(25, "David", "Lee")], + ) + + postgresql_delete_dml_returning.postgresql_delete_dml_returning( + conftest.LIVE_PROJECT_ID, + conftest.LIVE_INSTANCE_ID, + conftest.LIVE_DATABASE_ID, + ) + + out, err = capsys.readouterr() + assert err == "" + assert "Deleted Rows: 1" in out + assert "Full Name: David Lee" in out + assert "Singer ID: 25" in out