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
115 changes: 115 additions & 0 deletions spanner/database_admin/src/spanner_database_admin/alter_sequence.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
# 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)}")
Comment on lines +54 to +81

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

If database.run_in_transaction(insert_customers) fails (for example, due to a schema mismatch or missing table), the current error handling will catch it and print a misleading error message stating that the sequence alteration failed. Splitting the sequence alteration and the customer insertion into separate try-except blocks provides clearer and more accurate error messages.

    try:
        operation = admin_client.update_database_ddl(request=ddl_request)
        print(f"Waiting for sequence 'Seq' alteration on '{database_id}'...")
        operation.result(timeout=300)
    except exceptions.NotFound as err:
        print(
            f"error: database '{database_id}' on instance '{instance_id}' "
            f"was not found: {err.message}",
            file=sys.stderr,
        )
        return
    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,
        )
        return
    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,
        )
        return

    try:
        database.run_in_transaction(insert_customers)
    except exceptions.GoogleAPICallError as err:
        print(
            f"error: failed to insert customers into database '{database_id}': {err.message}",
            file=sys.stderr,
        )
        return

    print(f"Resource ID: {database_id}")
    for cid in customer_ids:
        print(f"Customer ID: {cid}")
    print(f"Inserted Customers: {len(customer_ids)}")

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.

Thanks! Keeping a single block here for consistency with the other samples in this set; the error message includes the server message, which identifies the step that failed.



# [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,
)
172 changes: 172 additions & 0 deletions spanner/database_admin/tests/alter_sequence_test.py
Original file line number Diff line number Diff line change
@@ -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)
Comment on lines +161 to +172

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.

high

In Cloud Spanner, you cannot drop a sequence if it is still referenced by a table column's default value constraint. Since the Customers table references the Seq sequence, calling drop_sequence.drop_sequence before dropping the Customers table will fail with a FailedPrecondition error. The Customers table must be dropped first in the finally block.

Suggested change
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)
finally:
admin.update_database_ddl(
request={
"database": db_path,
"statements": ["DROP TABLE IF EXISTS Customers"],
}
).result(timeout=240)
drop_sequence.drop_sequence(
conftest.LIVE_PROJECT_ID,
conftest.LIVE_INSTANCE_ID,
conftest.LIVE_DATABASE_ID,
)

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.

Thanks! The cleanup works in this order because the drop-sequence sample first removes the column default (ALTER TABLE Customers ALTER COLUMN CustomerId DROP DEFAULT) and then drops the sequence, so the table no longer references it.