From 19a7a9839ef2aac6d4def6452bd33db9b7bd40da Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Wed, 18 Nov 2026 04:51:08 +0000 Subject: [PATCH 1/3] feat(spanner): Add PostgreSQL-dialect database creation sample Creating a PostgreSQL-dialect Spanner database sets DatabaseDialect.POSTGRESQL on CreateDatabaseRequest before applying PostgreSQL DDL via UpdateDatabaseDdlRequest. Add spanner_postgresql_create_database. --- .../postgresql_create_database.py | 116 +++++++++++++ .../tests/postgresql_create_database_test.py | 154 ++++++++++++++++++ 2 files changed, 270 insertions(+) create mode 100644 spanner/postgresql/src/spanner_postgresql/postgresql_create_database.py create mode 100644 spanner/postgresql/tests/postgresql_create_database_test.py diff --git a/spanner/postgresql/src/spanner_postgresql/postgresql_create_database.py b/spanner/postgresql/src/spanner_postgresql/postgresql_create_database.py new file mode 100644 index 0000000000..ed8d4f4d57 --- /dev/null +++ b/spanner/postgresql/src/spanner_postgresql/postgresql_create_database.py @@ -0,0 +1,116 @@ +# 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_create_database] +import sys + +from google.api_core import exceptions +from google.cloud import spanner_admin_database_v1 + + +def create_postgresql_database( + project_id: str, instance_id: str, database_id: str +) -> None: + """Creates a PostgreSQL-dialect Spanner database and initial Singers/Albums DDL. + + Args: + project_id: The Google Cloud project ID. + instance_id: The Spanner instance ID. + database_id: The new PostgreSQL-dialect database ID to create. + """ + client = spanner_admin_database_v1.DatabaseAdminClient() + parent = client.instance_path(project_id, instance_id) + database_path = client.database_path(project_id, instance_id, database_id) + create_request = spanner_admin_database_v1.CreateDatabaseRequest( + parent=parent, + create_statement=f'CREATE DATABASE "{database_id}"', + database_dialect=spanner_admin_database_v1.DatabaseDialect.POSTGRESQL, + ) + ddl_request = spanner_admin_database_v1.UpdateDatabaseDdlRequest( + database=database_path, + statements=[ + "CREATE TABLE Singers (" + " SingerId bigint NOT NULL," + " FirstName character varying(1024)," + " LastName character varying(1024)," + " SingerInfo bytea," + " FullName character varying(2048) " + " GENERATED ALWAYS AS (FirstName || ' ' || LastName) STORED," + " PRIMARY KEY (SingerId)" + ")", + "CREATE TABLE Albums (" + " SingerId bigint NOT NULL," + " AlbumId bigint NOT NULL," + " AlbumTitle character varying(1024)," + " PRIMARY KEY (SingerId, AlbumId)" + ") INTERLEAVE IN PARENT Singers ON DELETE CASCADE", + ], + ) + + try: + create_op = client.create_database(request=create_request) + print(f"Waiting for PostgreSQL database '{database_id}' creation...") + database = create_op.result(timeout=300) + ddl_op = client.update_database_ddl(request=ddl_request) + print(f"Waiting for Singers and Albums DDL on '{database_id}'...") + ddl_op.result(timeout=300) + except exceptions.AlreadyExists as err: + print( + f"error: database '{database_id}' already exists on instance " + f"'{instance_id}': {err.message}", + file=sys.stderr, + ) + except exceptions.GoogleAPICallError as err: + print( + f"error: failed to create PostgreSQL database '{database_id}' " + f"on instance '{instance_id}': {err.message}", + file=sys.stderr, + ) + else: + print(f"Resource ID: {database_id}") + print(f"Database Dialect: {database.database_dialect.name}") + + +# [END spanner_postgresql_create_database] + + +if __name__ == "__main__": + import argparse + import os + + parser = argparse.ArgumentParser( + description="Create a PostgreSQL-dialect Spanner database and initial tables." + ) + 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() + + create_postgresql_database( + project_id=args.project_id, + instance_id=args.instance_id, + database_id=args.database_id, + ) diff --git a/spanner/postgresql/tests/postgresql_create_database_test.py b/spanner/postgresql/tests/postgresql_create_database_test.py new file mode 100644 index 0000000000..a22feb64bf --- /dev/null +++ b/spanner/postgresql/tests/postgresql_create_database_test.py @@ -0,0 +1,154 @@ +# 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 +import uuid + +from google.api_core import exceptions +from google.cloud import spanner_admin_database_v1 +import pytest +from spanner_postgresql import postgresql_create_database + +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_create_postgresql_database_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}" + ) + db_pb = mock.MagicMock() + db_pb.database_dialect.name = "POSTGRESQL" + mock_client_class.return_value.create_database.return_value.result.return_value = ( + db_pb + ) + + postgresql_create_database.create_postgresql_database( + PROJECT_ID, INSTANCE_ID, DATABASE_ID + ) + + mock_client_class.return_value.update_database_ddl.assert_called_once() + out, err = capsys.readouterr() + assert f"Resource ID: {DATABASE_ID}" in out + assert "Database Dialect: POSTGRESQL" in out + assert PROJECT_ID not in out + assert err == "" + + +@pytest.mark.parametrize( + "error, expected_prefix", + [ + ( + exceptions.AlreadyExists("dup"), + "error: database 'example-pg-db' already exists", + ), + ( + exceptions.PermissionDenied("denied"), + "error: failed to create PostgreSQL database", + ), + ], +) +@mock.patch(ADMIN_CLIENT) +def test_create_postgresql_database_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.create_database.side_effect = error + + postgresql_create_database.create_postgresql_database( + 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_create_postgresql_database_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}" + ) + db_pb = mock.MagicMock() + db_pb.database_dialect.name = "POSTGRESQL" + mock_client_class.return_value.create_database.return_value.result.return_value = ( + db_pb + ) + monkeypatch.setattr( + "sys.argv", + [ + "postgresql_create_database.py", + "--project-id", + PROJECT_ID, + "--instance-id", + INSTANCE_ID, + "--database-id", + DATABASE_ID, + ], + ) + + runpy.run_module( + "spanner_postgresql.postgresql_create_database", run_name="__main__" + ) + + assert "Database Dialect: POSTGRESQL" in capsys.readouterr().out + + +@conftest.live_only +def test_create_postgresql_database_live(capsys: pytest.CaptureFixture[str]) -> None: + admin = spanner_admin_database_v1.DatabaseAdminClient() + temp_db_id = f"example-pgc-{uuid.uuid4().hex[:6]}" + db_path = admin.database_path( + conftest.LIVE_PROJECT_ID, conftest.LIVE_INSTANCE_ID, temp_db_id + ) + try: + postgresql_create_database.create_postgresql_database( + conftest.LIVE_PROJECT_ID, conftest.LIVE_INSTANCE_ID, temp_db_id + ) + out, err = capsys.readouterr() + assert err == "" + assert conftest.LIVE_PROJECT_ID not in out + assert f"Resource ID: {temp_db_id}" in out + assert "Database Dialect: POSTGRESQL" in out + finally: + try: + admin.drop_database(database=db_path) + except exceptions.NotFound: + pass From 2dd4365bcba704669dc8aa7bc4133d6a152409c8 Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Wed, 18 Nov 2026 21:42:43 +0000 Subject: [PATCH 2/3] fix(spanner): report operation wait timeouts in postgresql_create_database Problem: the sample waits on a long-running operation with a client-side timeout. When that wait expires the client raises TimeoutError, which is not an API call error, so the sample ended with an unhandled traceback. Solution: catch TimeoutError and print a clear message to stderr noting that only the wait timed out and the operation may still be running (the timeout does not cancel it). Add a unit test covering the new handler. --- .../src/spanner_postgresql/postgresql_create_database.py | 6 ++++++ spanner/postgresql/tests/postgresql_create_database_test.py | 1 + 2 files changed, 7 insertions(+) diff --git a/spanner/postgresql/src/spanner_postgresql/postgresql_create_database.py b/spanner/postgresql/src/spanner_postgresql/postgresql_create_database.py index ed8d4f4d57..a6c149d5c4 100644 --- a/spanner/postgresql/src/spanner_postgresql/postgresql_create_database.py +++ b/spanner/postgresql/src/spanner_postgresql/postgresql_create_database.py @@ -71,6 +71,12 @@ def create_postgresql_database( f"'{instance_id}': {err.message}", file=sys.stderr, ) + except TimeoutError as err: + print( + f"error: timed out waiting for the operation on database '{database_id}' " + f"to complete; the operation may still be running: {err}", + file=sys.stderr, + ) except exceptions.GoogleAPICallError as err: print( f"error: failed to create PostgreSQL database '{database_id}' " diff --git a/spanner/postgresql/tests/postgresql_create_database_test.py b/spanner/postgresql/tests/postgresql_create_database_test.py index a22feb64bf..d1a87ac955 100644 --- a/spanner/postgresql/tests/postgresql_create_database_test.py +++ b/spanner/postgresql/tests/postgresql_create_database_test.py @@ -60,6 +60,7 @@ def test_create_postgresql_database_success( @pytest.mark.parametrize( "error, expected_prefix", [ + (TimeoutError("deadline"), "error: timed out waiting for the operation"), ( exceptions.AlreadyExists("dup"), "error: database 'example-pg-db' already exists", From 96a2565283c7e99d13939d46d751d8445078a839 Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Thu, 19 Nov 2026 04:43:54 +0000 Subject: [PATCH 3/3] style(spanner): use triple-quoted SQL strings in postgresql_create_database 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_create_database.py --- .../postgresql_create_database.py | 34 +++++++++++-------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/spanner/postgresql/src/spanner_postgresql/postgresql_create_database.py b/spanner/postgresql/src/spanner_postgresql/postgresql_create_database.py index a6c149d5c4..5a0832ab6e 100644 --- a/spanner/postgresql/src/spanner_postgresql/postgresql_create_database.py +++ b/spanner/postgresql/src/spanner_postgresql/postgresql_create_database.py @@ -40,21 +40,25 @@ def create_postgresql_database( ddl_request = spanner_admin_database_v1.UpdateDatabaseDdlRequest( database=database_path, statements=[ - "CREATE TABLE Singers (" - " SingerId bigint NOT NULL," - " FirstName character varying(1024)," - " LastName character varying(1024)," - " SingerInfo bytea," - " FullName character varying(2048) " - " GENERATED ALWAYS AS (FirstName || ' ' || LastName) STORED," - " PRIMARY KEY (SingerId)" - ")", - "CREATE TABLE Albums (" - " SingerId bigint NOT NULL," - " AlbumId bigint NOT NULL," - " AlbumTitle character varying(1024)," - " PRIMARY KEY (SingerId, AlbumId)" - ") INTERLEAVE IN PARENT Singers ON DELETE CASCADE", + """ + CREATE TABLE Singers ( + SingerId bigint NOT NULL, + FirstName character varying(1024), + LastName character varying(1024), + SingerInfo bytea, + FullName character varying(2048) + GENERATED ALWAYS AS (FirstName || ' ' || LastName) STORED, + PRIMARY KEY (SingerId) + ) + """, + """ + CREATE TABLE Albums ( + SingerId bigint NOT NULL, + AlbumId bigint NOT NULL, + AlbumTitle character varying(1024), + PRIMARY KEY (SingerId, AlbumId) + ) INTERLEAVE IN PARENT Singers ON DELETE CASCADE + """, ], )