From 8346b1d593c5b7cf19671c589629be01509d1f1e Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Wed, 18 Nov 2026 22:16:11 +0000 Subject: [PATCH 1/2] feat(spanner): Add GoogleSQL ALTER SEQUENCE skip_range sample Migrating existing primary keys into a sequence-backed table skips reserved ID ranges via skip_range_min and skip_range_max. Add a standalone spanner_alter_sequence sample and test suite. --- .../spanner_database_admin/alter_sequence.py | 117 ++++++++++++ .../tests/alter_sequence_test.py | 172 ++++++++++++++++++ 2 files changed, 289 insertions(+) create mode 100644 spanner/database_admin/src/spanner_database_admin/alter_sequence.py create mode 100644 spanner/database_admin/tests/alter_sequence_test.py diff --git a/spanner/database_admin/src/spanner_database_admin/alter_sequence.py b/spanner/database_admin/src/spanner_database_admin/alter_sequence.py new file mode 100644 index 0000000000..bb8029f187 --- /dev/null +++ b/spanner/database_admin/src/spanner_database_admin/alter_sequence.py @@ -0,0 +1,117 @@ +# 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_alter_sequence] +import sys + +from google.api_core import exceptions +from google.cloud import spanner +from google.cloud import spanner_admin_database_v1 +from google.cloud import spanner_v1 + + +def alter_sequence(project_id: str, instance_id: str, database_id: str) -> None: + """Alters skip_range_min and skip_range_max on a GoogleSQL sequence. + + Args: + project_id: The Google Cloud project ID. + instance_id: The Spanner instance ID. + database_id: The GoogleSQL Spanner database ID with Seq. + """ + admin_client = spanner_admin_database_v1.DatabaseAdminClient() + database_path = admin_client.database_path(project_id, instance_id, database_id) + ddl_request = spanner_admin_database_v1.UpdateDatabaseDdlRequest( + database=database_path, + statements=[ + "ALTER SEQUENCE Seq SET OPTIONS " + "(skip_range_min = 1000, skip_range_max = 5000000)" + ], + ) + client = spanner.Client(project=project_id) + database = client.instance(instance_id).database(database_id) + customer_ids: list[int] = [] + + def insert_customers(transaction: spanner_v1.transaction.Transaction) -> None: + nonlocal customer_ids + rows = list( + transaction.execute_sql( + "INSERT INTO Customers (CustomerName) VALUES " + "('Lea'), ('Cataline'), ('Smith') " + "THEN RETURN CustomerId" + ) + ) + customer_ids = [int(row[0]) for row in rows] + + try: + operation = admin_client.update_database_ddl(request=ddl_request) + print(f"Waiting for sequence 'Seq' alteration on '{database_id}'...") + operation.result(timeout=300) + database.run_in_transaction(insert_customers) + except exceptions.NotFound as err: + print( + f"error: database '{database_id}' on instance '{instance_id}' " + f"was not found: {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 alter sequence on database '{database_id}' " + f"in instance '{instance_id}': {err.message}", + file=sys.stderr, + ) + else: + print(f"Resource ID: {database_id}") + for cid in customer_ids: + print(f"Customer ID: {cid}") + print(f"Inserted Customers: {len(customer_ids)}") + + +# [END spanner_alter_sequence] + + +if __name__ == "__main__": + import argparse + import os + + parser = argparse.ArgumentParser( + description="Alter skip_range options on a GoogleSQL sequence." + ) + 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() + + alter_sequence( + project_id=args.project_id, + instance_id=args.instance_id, + database_id=args.database_id, + ) diff --git a/spanner/database_admin/tests/alter_sequence_test.py b/spanner/database_admin/tests/alter_sequence_test.py new file mode 100644 index 0000000000..4d86207742 --- /dev/null +++ b/spanner/database_admin/tests/alter_sequence_test.py @@ -0,0 +1,172 @@ +# 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_database_admin import alter_sequence +from spanner_database_admin import create_sequence +from spanner_database_admin import drop_sequence + +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" +SPANNER_CLIENT = "google.cloud.spanner.Client" + + +def _setup_txn(mock_client_class: mock.MagicMock) -> mock.MagicMock: + database = ( + mock_client_class.return_value.instance.return_value.database.return_value + ) + txn = mock.MagicMock() + database.run_in_transaction.side_effect = lambda fn, *a, **kw: fn(txn) + return txn + + +@mock.patch(SPANNER_CLIENT) +@mock.patch(ADMIN_CLIENT) +def test_alter_sequence_success( + mock_admin_class: mock.MagicMock, + mock_client_class: mock.MagicMock, + capsys: pytest.CaptureFixture[str], +) -> None: + mock_admin_class.return_value.database_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/{DATABASE_ID}" + ) + txn = _setup_txn(mock_client_class) + txn.execute_sql.return_value = [(6000001,), (6000002,), (6000003,)] + + alter_sequence.alter_sequence(PROJECT_ID, INSTANCE_ID, DATABASE_ID) + + out, err = capsys.readouterr() + assert f"Resource ID: {DATABASE_ID}" in out + assert "Inserted Customers: 3" 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.NotFound("missing"), "error: database 'example-db'"), + ( + exceptions.FailedPrecondition("missing seq"), + "error: failed to alter sequence", + ), + ], +) +@mock.patch(SPANNER_CLIENT) +@mock.patch(ADMIN_CLIENT) +def test_alter_sequence_errors( + mock_admin_class: mock.MagicMock, + mock_client_class: mock.MagicMock, + capsys: pytest.CaptureFixture[str], + error: Exception, + expected_prefix: str, +) -> None: + mock_admin_class.return_value.database_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/{DATABASE_ID}" + ) + mock_admin_class.return_value.update_database_ddl.side_effect = error + + alter_sequence.alter_sequence(PROJECT_ID, INSTANCE_ID, DATABASE_ID) + + _out, err = capsys.readouterr() + assert err.startswith(expected_prefix) + assert PROJECT_ID not in err + + +@mock.patch(SPANNER_CLIENT) +@mock.patch(ADMIN_CLIENT) +def test_alter_sequence_cli_entrypoint( + mock_admin_class: mock.MagicMock, + mock_client_class: mock.MagicMock, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + mock_admin_class.return_value.database_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/{DATABASE_ID}" + ) + txn = _setup_txn(mock_client_class) + txn.execute_sql.return_value = [(6000001,), (6000002,), (6000003,)] + monkeypatch.setattr( + "sys.argv", + [ + "alter_sequence.py", + "--project-id", + PROJECT_ID, + "--instance-id", + INSTANCE_ID, + "--database-id", + DATABASE_ID, + ], + ) + + runpy.run_module("spanner_database_admin.alter_sequence", run_name="__main__") + + assert "Inserted Customers: 3" in capsys.readouterr().out + + +@conftest.live_only +def test_alter_sequence_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, + ) + admin.update_database_ddl( + request={ + "database": db_path, + "statements": [ + "DROP TABLE IF EXISTS Customers", + "DROP SEQUENCE IF EXISTS Seq", + ], + } + ).result(timeout=240) + try: + create_sequence.create_sequence( + conftest.LIVE_PROJECT_ID, + conftest.LIVE_INSTANCE_ID, + conftest.LIVE_DATABASE_ID, + ) + capsys.readouterr() + alter_sequence.alter_sequence( + conftest.LIVE_PROJECT_ID, + conftest.LIVE_INSTANCE_ID, + conftest.LIVE_DATABASE_ID, + ) + out, err = capsys.readouterr() + assert err == "" + assert conftest.LIVE_PROJECT_ID not in out + assert "Inserted Customers: 3" in out + finally: + drop_sequence.drop_sequence( + conftest.LIVE_PROJECT_ID, + conftest.LIVE_INSTANCE_ID, + conftest.LIVE_DATABASE_ID, + ) + admin.update_database_ddl( + request={ + "database": db_path, + "statements": ["DROP TABLE IF EXISTS Customers"], + } + ).result(timeout=240) From ed4d3861c4a10b433b1946449f0417e15b3d8e17 Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Thu, 19 Nov 2026 04:44:34 +0000 Subject: [PATCH 2/2] style(spanner): use triple-quoted SQL strings in alter_sequence 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/alter_sequence.py --- .../spanner_database_admin/alter_sequence.py | 20 +++++++++---------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/spanner/database_admin/src/spanner_database_admin/alter_sequence.py b/spanner/database_admin/src/spanner_database_admin/alter_sequence.py index bb8029f187..9242264dbc 100644 --- a/spanner/database_admin/src/spanner_database_admin/alter_sequence.py +++ b/spanner/database_admin/src/spanner_database_admin/alter_sequence.py @@ -33,10 +33,10 @@ def alter_sequence(project_id: str, instance_id: str, database_id: str) -> None: database_path = admin_client.database_path(project_id, instance_id, database_id) ddl_request = spanner_admin_database_v1.UpdateDatabaseDdlRequest( database=database_path, - statements=[ - "ALTER SEQUENCE Seq SET OPTIONS " - "(skip_range_min = 1000, skip_range_max = 5000000)" - ], + statements=[""" + ALTER SEQUENCE Seq SET OPTIONS + (skip_range_min = 1000, skip_range_max = 5000000) + """], ) client = spanner.Client(project=project_id) database = client.instance(instance_id).database(database_id) @@ -44,13 +44,11 @@ def alter_sequence(project_id: str, instance_id: str, database_id: str) -> None: def insert_customers(transaction: spanner_v1.transaction.Transaction) -> None: nonlocal customer_ids - rows = list( - transaction.execute_sql( - "INSERT INTO Customers (CustomerName) VALUES " - "('Lea'), ('Cataline'), ('Smith') " - "THEN RETURN CustomerId" - ) - ) + rows = list(transaction.execute_sql(""" + INSERT INTO Customers (CustomerName) VALUES + ('Lea'), ('Cataline'), ('Smith') + THEN RETURN CustomerId + """)) customer_ids = [int(row[0]) for row in rows] try: