diff --git a/spanner/change_streams/README.md b/spanner/change_streams/README.md new file mode 100644 index 00000000000..9681bb857ba --- /dev/null +++ b/spanner/change_streams/README.md @@ -0,0 +1,27 @@ +# Cloud Spanner Change Streams Samples + +Python samples demonstrating Cloud Spanner change stream DDL creation, transaction-level write exclusion, and `READ_` TVF queries. + +## 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/change_streams/noxfile_config.py b/spanner/change_streams/noxfile_config.py new file mode 100644 index 00000000000..fe371aaf480 --- /dev/null +++ b/spanner/change_streams/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/change_streams/pyproject.toml b/spanner/change_streams/pyproject.toml new file mode 100644 index 00000000000..fe963552748 --- /dev/null +++ b/spanner/change_streams/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-change-streams-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/change_streams/requirements-test.txt b/spanner/change_streams/requirements-test.txt new file mode 100644 index 00000000000..ac63bdc5a92 --- /dev/null +++ b/spanner/change_streams/requirements-test.txt @@ -0,0 +1,2 @@ +-e . +pytest==9.2.0 diff --git a/spanner/change_streams/requirements.txt b/spanner/change_streams/requirements.txt new file mode 100644 index 00000000000..a56c81cc2eb --- /dev/null +++ b/spanner/change_streams/requirements.txt @@ -0,0 +1,2 @@ +google-api-core==2.44.0 +google-cloud-spanner==3.72.0 diff --git a/spanner/change_streams/src/spanner_change_streams/__init__.py b/spanner/change_streams/src/spanner_change_streams/__init__.py new file mode 100644 index 00000000000..58d482ea386 --- /dev/null +++ b/spanner/change_streams/src/spanner_change_streams/__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/change_streams/src/spanner_change_streams/create_change_stream.py b/spanner/change_streams/src/spanner_change_streams/create_change_stream.py new file mode 100644 index 00000000000..555f31482db --- /dev/null +++ b/spanner/change_streams/src/spanner_change_streams/create_change_stream.py @@ -0,0 +1,106 @@ +# 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_change_stream] +import sys + +from google.api_core import exceptions +from google.cloud import spanner_admin_database_v1 + + +def create_change_stream(project_id: str, instance_id: str, database_id: str) -> None: + """Creates a Spanner change stream watching Singers and Albums. + + Enabling allow_txn_exclusion = true allows individual read-write + transactions to opt out of change-stream capture when needed. + + Args: + project_id: The Google Cloud project ID. + instance_id: The Spanner instance ID. + database_id: The Spanner database ID containing Singers and Albums. + """ + client = spanner_admin_database_v1.DatabaseAdminClient() + database_path = client.database_path(project_id, instance_id, database_id) + stream_name = "NamesAndAlbumsStream" + ddl_statement = f""" + CREATE CHANGE STREAM {stream_name} + FOR Singers(FirstName, LastName), Albums + OPTIONS (retention_period = '36h', allow_txn_exclusion = true) + """ + request = spanner_admin_database_v1.UpdateDatabaseDdlRequest( + database=database_path, + statements=[ddl_statement], + ) + + try: + operation = client.update_database_ddl(request=request) + print(f"Waiting for change stream '{stream_name}' creation...") + operation.result(timeout=300) + except (exceptions.AlreadyExists, exceptions.FailedPrecondition) as err: + print( + f"error: change stream '{stream_name}' already exists or failed " + f"preconditions on database '{database_id}' in 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 change stream '{stream_name}' on " + f"database '{database_id}' in instance '{instance_id}'" + f": {err.message}", + file=sys.stderr, + ) + else: + print(f"Resource ID: {database_id}") + print(f"Change Stream: {stream_name}") + + +# [END spanner_create_change_stream] + + +if __name__ == "__main__": + import argparse + import os + + parser = argparse.ArgumentParser( + description="Create a Cloud Spanner change stream via DDL." + ) + 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_change_stream( + project_id=args.project_id, + instance_id=args.instance_id, + database_id=args.database_id, + ) diff --git a/spanner/change_streams/tests/__init__.py b/spanner/change_streams/tests/__init__.py new file mode 100644 index 00000000000..58d482ea386 --- /dev/null +++ b/spanner/change_streams/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/change_streams/tests/conftest.py b/spanner/change_streams/tests/conftest.py new file mode 100644 index 00000000000..cbdf15b1a6a --- /dev/null +++ b/spanner/change_streams/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 Change Streams 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/change_streams/tests/create_change_stream_test.py b/spanner/change_streams/tests/create_change_stream_test.py new file mode 100644 index 00000000000..ce8d2231590 --- /dev/null +++ b/spanner/change_streams/tests/create_change_stream_test.py @@ -0,0 +1,145 @@ +# 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_change_streams import create_change_stream + +from . import conftest + +PROJECT_ID = "example-project-id" +INSTANCE_ID = "example-instance" +DATABASE_ID = "example-db" +DATABASE_PATH = f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/{DATABASE_ID}" +ADMIN_CLIENT = "google.cloud.spanner_admin_database_v1.DatabaseAdminClient" + + +@mock.patch(ADMIN_CLIENT) +def test_create_change_stream_success( + mock_client_class: mock.MagicMock, capsys: pytest.CaptureFixture[str] +) -> None: + client = mock_client_class.return_value + client.database_path.return_value = DATABASE_PATH + + create_change_stream.create_change_stream(PROJECT_ID, INSTANCE_ID, DATABASE_ID) + + req = client.update_database_ddl.call_args.kwargs["request"] + assert "CREATE CHANGE STREAM NamesAndAlbumsStream" in req.statements[0] + assert "allow_txn_exclusion = true" in req.statements[0] + out, err = capsys.readouterr() + assert f"Resource ID: {DATABASE_ID}" in out + assert PROJECT_ID not in out + assert "Change Stream: NamesAndAlbumsStream" in out + assert err == "" + + +@pytest.mark.parametrize( + "error, expected_prefix", + [ + (TimeoutError("deadline"), "error: timed out waiting for the operation"), + ( + exceptions.FailedPrecondition("duplicate"), + "error: change stream 'NamesAndAlbumsStream' already exists", + ), + ( + exceptions.PermissionDenied("denied"), + "error: failed to create change stream 'NamesAndAlbumsStream'", + ), + ], +) +@mock.patch(ADMIN_CLIENT) +def test_create_change_stream_errors( + mock_client_class: mock.MagicMock, + capsys: pytest.CaptureFixture[str], + error: Exception, + expected_prefix: str, +) -> None: + client = mock_client_class.return_value + client.database_path.return_value = DATABASE_PATH + client.update_database_ddl.side_effect = error + + create_change_stream.create_change_stream(PROJECT_ID, INSTANCE_ID, DATABASE_ID) + + _out, err = capsys.readouterr() + assert err.startswith(expected_prefix) + assert PROJECT_ID not in err + assert PROJECT_ID not in err + + +@mock.patch(ADMIN_CLIENT) +def test_create_change_stream_cli_entrypoint( + mock_client_class: mock.MagicMock, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + mock_client_class.return_value.database_path.return_value = DATABASE_PATH + monkeypatch.setattr( + "sys.argv", + [ + "create_change_stream.py", + "--project-id", + PROJECT_ID, + "--instance-id", + INSTANCE_ID, + "--database-id", + DATABASE_ID, + ], + ) + + runpy.run_module("spanner_change_streams.create_change_stream", run_name="__main__") + + assert "Change Stream: NamesAndAlbumsStream" in capsys.readouterr().out + + +@conftest.live_only +def test_create_change_stream_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, + ) + try: + admin.update_database_ddl( + request={ + "database": db_path, + "statements": ["DROP CHANGE STREAM NamesAndAlbumsStream"], + } + ).result(timeout=180) + except (exceptions.NotFound, exceptions.FailedPrecondition): + pass + + try: + create_change_stream.create_change_stream( + conftest.LIVE_PROJECT_ID, + conftest.LIVE_INSTANCE_ID, + conftest.LIVE_DATABASE_ID, + ) + out, err = capsys.readouterr() + assert err == "" + assert "Change Stream: NamesAndAlbumsStream" in out + finally: + try: + admin.update_database_ddl( + request={ + "database": db_path, + "statements": ["DROP CHANGE STREAM NamesAndAlbumsStream"], + } + ).result(timeout=180) + except (exceptions.NotFound, exceptions.FailedPrecondition): + pass