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
29 changes: 29 additions & 0 deletions spanner/database_admin/README.md
Original file line number Diff line number Diff line change
@@ -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
```
21 changes: 21 additions & 0 deletions spanner/database_admin/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/database_admin/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-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"]
2 changes: 2 additions & 0 deletions spanner/database_admin/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/database_admin/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/database_admin/src/spanner_database_admin/__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.
116 changes: 116 additions & 0 deletions spanner/database_admin/src/spanner_database_admin/create_database.py
Original file line number Diff line number Diff line change
@@ -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_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
""",
],
Comment on lines +35 to +55

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Using implicit string concatenation across multiple lines with single/double quotes can be error-prone and harder to read. Using triple-quoted multi-line strings for each DDL statement is much cleaner and more maintainable.

Suggested change
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",
],
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""",
],

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good suggestion, done: the DDL statements are now triple-quoted strings (26c014d). The same change was applied to the other samples in this set that built multi-line SQL from adjacent string fragments, so they are consistent.

)

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,
)
13 changes: 13 additions & 0 deletions spanner/database_admin/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/database_admin/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 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.",
)
Loading