From 54e9d559396662099c88363709f3f3eb4f01c8c0 Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Wed, 18 Nov 2026 22:16:09 +0000 Subject: [PATCH 1/2] feat(spanner): Add GoogleSQL database creation sample Core Spanner getting-started guides create a GoogleSQL database with Singers and interleaved Albums DDL via DatabaseAdminClient.create_database. Scaffold spanner/database_admin and add spanner_create_database. --- spanner/database_admin/README.md | 29 ++++ spanner/database_admin/noxfile_config.py | 21 +++ spanner/database_admin/pyproject.toml | 30 ++++ spanner/database_admin/requirements-test.txt | 2 + spanner/database_admin/requirements.txt | 2 + .../src/spanner_database_admin/__init__.py | 13 ++ .../spanner_database_admin/create_database.py | 112 ++++++++++++++ spanner/database_admin/tests/__init__.py | 13 ++ spanner/database_admin/tests/conftest.py | 36 +++++ .../tests/create_database_test.py | 139 ++++++++++++++++++ 10 files changed, 397 insertions(+) create mode 100644 spanner/database_admin/README.md create mode 100644 spanner/database_admin/noxfile_config.py create mode 100644 spanner/database_admin/pyproject.toml create mode 100644 spanner/database_admin/requirements-test.txt create mode 100644 spanner/database_admin/requirements.txt create mode 100644 spanner/database_admin/src/spanner_database_admin/__init__.py create mode 100644 spanner/database_admin/src/spanner_database_admin/create_database.py create mode 100644 spanner/database_admin/tests/__init__.py create mode 100644 spanner/database_admin/tests/conftest.py create mode 100644 spanner/database_admin/tests/create_database_test.py diff --git a/spanner/database_admin/README.md b/spanner/database_admin/README.md new file mode 100644 index 00000000000..8882a0f733c --- /dev/null +++ b/spanner/database_admin/README.md @@ -0,0 +1,29 @@ +# Cloud Spanner Database Admin Samples + +Python samples demonstrating Cloud Spanner database administration, online DDL +evolution, Customer-Managed Encryption Keys (CMEK), secondary indexes, +bit-reversed sequences, pre-splitting, and fine-grained access control (FGAC). + +## 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/database_admin/noxfile_config.py b/spanner/database_admin/noxfile_config.py new file mode 100644 index 00000000000..fe371aaf480 --- /dev/null +++ b/spanner/database_admin/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/database_admin/pyproject.toml b/spanner/database_admin/pyproject.toml new file mode 100644 index 00000000000..3ae5b3dc049 --- /dev/null +++ b/spanner/database_admin/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-database-admin-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/database_admin/requirements-test.txt b/spanner/database_admin/requirements-test.txt new file mode 100644 index 00000000000..ac63bdc5a92 --- /dev/null +++ b/spanner/database_admin/requirements-test.txt @@ -0,0 +1,2 @@ +-e . +pytest==9.2.0 diff --git a/spanner/database_admin/requirements.txt b/spanner/database_admin/requirements.txt new file mode 100644 index 00000000000..a56c81cc2eb --- /dev/null +++ b/spanner/database_admin/requirements.txt @@ -0,0 +1,2 @@ +google-api-core==2.44.0 +google-cloud-spanner==3.72.0 diff --git a/spanner/database_admin/src/spanner_database_admin/__init__.py b/spanner/database_admin/src/spanner_database_admin/__init__.py new file mode 100644 index 00000000000..58d482ea386 --- /dev/null +++ b/spanner/database_admin/src/spanner_database_admin/__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/database_admin/src/spanner_database_admin/create_database.py b/spanner/database_admin/src/spanner_database_admin/create_database.py new file mode 100644 index 00000000000..ad33dda9b4d --- /dev/null +++ b/spanner/database_admin/src/spanner_database_admin/create_database.py @@ -0,0 +1,112 @@ +# 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_create_database] +import sys + +from google.api_core import exceptions +from google.cloud import spanner_admin_database_v1 + + +def create_database(project_id: str, instance_id: str, database_id: str) -> None: + """Creates a GoogleSQL Spanner database with Singers and Albums tables. + + Args: + project_id: The Google Cloud project ID. + instance_id: The Spanner instance ID. + database_id: The new Spanner database ID to create. + """ + client = spanner_admin_database_v1.DatabaseAdminClient() + parent = client.instance_path(project_id, instance_id) + request = spanner_admin_database_v1.CreateDatabaseRequest( + parent=parent, + create_statement=f"CREATE DATABASE `{database_id}`", + extra_statements=[ + "CREATE TABLE Singers (" + " SingerId INT64 NOT NULL," + " FirstName STRING(1024)," + " LastName STRING(1024)," + " SingerInfo BYTES(MAX)," + " FullName STRING(2048) AS (" + " ARRAY_TO_STRING([FirstName, LastName], ' ')" + " ) STORED" + ") PRIMARY KEY (SingerId)", + "CREATE TABLE Albums (" + " SingerId INT64 NOT NULL," + " AlbumId INT64 NOT NULL," + " AlbumTitle STRING(MAX)" + ") PRIMARY KEY (SingerId, AlbumId)," + " INTERLEAVE IN PARENT Singers ON DELETE CASCADE", + ], + ) + + try: + operation = client.create_database(request=request) + print(f"Waiting for database '{database_id}' creation to complete...") + database = operation.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 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 database '{database_id}' on instance " + f"'{instance_id}': {err.message}", + file=sys.stderr, + ) + else: + print(f"Resource ID: {database_id}") + print(f"Database State: {database.state.name}") + + +# [END spanner_create_database] + + +if __name__ == "__main__": + import argparse + import os + + parser = argparse.ArgumentParser( + description="Create a GoogleSQL Spanner database and 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_DATABASE_ID", "example-db"), + help="Spanner database ID (default: $SPANNER_DATABASE_ID)", + ) + args = parser.parse_args() + + create_database( + project_id=args.project_id, + instance_id=args.instance_id, + database_id=args.database_id, + ) diff --git a/spanner/database_admin/tests/__init__.py b/spanner/database_admin/tests/__init__.py new file mode 100644 index 00000000000..58d482ea386 --- /dev/null +++ b/spanner/database_admin/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/database_admin/tests/conftest.py b/spanner/database_admin/tests/conftest.py new file mode 100644 index 00000000000..fd08d151783 --- /dev/null +++ b/spanner/database_admin/tests/conftest.py @@ -0,0 +1,36 @@ +# 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 Database Admin 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_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_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/database_admin/tests/create_database_test.py b/spanner/database_admin/tests/create_database_test.py new file mode 100644 index 00000000000..fac7faebed1 --- /dev/null +++ b/spanner/database_admin/tests/create_database_test.py @@ -0,0 +1,139 @@ +# 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_database_admin import create_database + +from . import conftest + +PROJECT_ID = "example-project-id" +INSTANCE_ID = "example-instance" +DATABASE_ID = "example-db" +ADMIN_CLIENT = "google.cloud.spanner_admin_database_v1.DatabaseAdminClient" + + +@mock.patch(ADMIN_CLIENT) +def test_create_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}" + ) + db_pb = mock.MagicMock() + db_pb.state.name = "READY" + mock_client_class.return_value.create_database.return_value.result.return_value = ( + db_pb + ) + + create_database.create_database(PROJECT_ID, INSTANCE_ID, DATABASE_ID) + + out, err = capsys.readouterr() + assert f"Resource ID: {DATABASE_ID}" in out + assert "Database State: READY" in out + assert PROJECT_ID not in out + assert err == "" + + +@pytest.mark.parametrize( + "error, expected_prefix", + [ + (TimeoutError("deadline"), "error: timed out waiting for the operation"), + ( + exceptions.AlreadyExists("dup"), + "error: database 'example-db' already exists", + ), + ( + exceptions.PermissionDenied("denied"), + "error: failed to create database 'example-db'", + ), + ], +) +@mock.patch(ADMIN_CLIENT) +def test_create_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.create_database.side_effect = error + + create_database.create_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_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}" + ) + db_pb = mock.MagicMock() + db_pb.state.name = "READY" + mock_client_class.return_value.create_database.return_value.result.return_value = ( + db_pb + ) + monkeypatch.setattr( + "sys.argv", + [ + "create_database.py", + "--project-id", + PROJECT_ID, + "--instance-id", + INSTANCE_ID, + "--database-id", + DATABASE_ID, + ], + ) + + runpy.run_module("spanner_database_admin.create_database", run_name="__main__") + + assert "Database State: READY" in capsys.readouterr().out + + +@conftest.live_only +def test_create_database_live(capsys: pytest.CaptureFixture[str]) -> None: + admin = spanner_admin_database_v1.DatabaseAdminClient() + temp_db_id = f"example-cdb-{uuid.uuid4().hex[:6]}" + db_path = admin.database_path( + conftest.LIVE_PROJECT_ID, conftest.LIVE_INSTANCE_ID, temp_db_id + ) + try: + create_database.create_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 State: READY" in out + finally: + try: + admin.drop_database(database=db_path) + except exceptions.NotFound: + pass From 26c014dbb4e04d4798a275fa3c61e16fd20cd12d Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Thu, 19 Nov 2026 04:44:11 +0000 Subject: [PATCH 2/2] style(spanner): use triple-quoted SQL strings in 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/database_admin/src/spanner_database_admin/create_database.py --- .../spanner_database_admin/create_database.py | 34 +++++++++++-------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/spanner/database_admin/src/spanner_database_admin/create_database.py b/spanner/database_admin/src/spanner_database_admin/create_database.py index ad33dda9b4d..0ad0d8c3dcc 100644 --- a/spanner/database_admin/src/spanner_database_admin/create_database.py +++ b/spanner/database_admin/src/spanner_database_admin/create_database.py @@ -33,21 +33,25 @@ def create_database(project_id: str, instance_id: str, database_id: str) -> None parent=parent, create_statement=f"CREATE DATABASE `{database_id}`", extra_statements=[ - "CREATE TABLE Singers (" - " SingerId INT64 NOT NULL," - " FirstName STRING(1024)," - " LastName STRING(1024)," - " SingerInfo BYTES(MAX)," - " FullName STRING(2048) AS (" - " ARRAY_TO_STRING([FirstName, LastName], ' ')" - " ) STORED" - ") PRIMARY KEY (SingerId)", - "CREATE TABLE Albums (" - " SingerId INT64 NOT NULL," - " AlbumId INT64 NOT NULL," - " AlbumTitle STRING(MAX)" - ") PRIMARY KEY (SingerId, AlbumId)," - " INTERLEAVE IN PARENT Singers ON DELETE CASCADE", + """ + CREATE TABLE Singers ( + SingerId INT64 NOT NULL, + FirstName STRING(1024), + LastName STRING(1024), + SingerInfo BYTES(MAX), + FullName STRING(2048) AS ( + ARRAY_TO_STRING([FirstName, LastName], ' ') + ) STORED + ) PRIMARY KEY (SingerId) + """, + """ + CREATE TABLE Albums ( + SingerId INT64 NOT NULL, + AlbumId INT64 NOT NULL, + AlbumTitle STRING(MAX) + ) PRIMARY KEY (SingerId, AlbumId), + INTERLEAVE IN PARENT Singers ON DELETE CASCADE + """, ], )