Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions spanner/change_streams/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Cloud Spanner Change Streams Samples

Python samples demonstrating Cloud Spanner change stream DDL creation, transaction-level write exclusion, and `READ_<ChangeStream>` 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
```
21 changes: 21 additions & 0 deletions spanner/change_streams/noxfile_config.py
Original file line number Diff line number Diff line change
@@ -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": {},
}
30 changes: 30 additions & 0 deletions spanner/change_streams/pyproject.toml
Original file line number Diff line number Diff line change
@@ -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"]
2 changes: 2 additions & 0 deletions spanner/change_streams/requirements-test.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
-e .
pytest==9.2.0
2 changes: 2 additions & 0 deletions spanner/change_streams/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
google-api-core==2.44.0
google-cloud-spanner==3.72.0
13 changes: 13 additions & 0 deletions spanner/change_streams/src/spanner_change_streams/__init__.py
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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,
)
13 changes: 13 additions & 0 deletions spanner/change_streams/tests/__init__.py
Original file line number Diff line number Diff line change
@@ -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.
36 changes: 36 additions & 0 deletions spanner/change_streams/tests/conftest.py
Original file line number Diff line number Diff line change
@@ -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.",
)
Loading