From 5bf3ff24c9247a4c370c6c4ca76d591b46f5edcd Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Wed, 18 Nov 2026 22:16:10 +0000 Subject: [PATCH] feat(spanner): Add ListDatabases instance inventory sample Enumerating databases and their leader options on an instance uses DatabaseAdminClient.list_databases. Add a standalone spanner_list_databases sample with unit and live tests. --- .../spanner_database_admin/list_databases.py | 75 ++++++++++++ .../tests/list_databases_test.py | 112 ++++++++++++++++++ 2 files changed, 187 insertions(+) create mode 100644 spanner/database_admin/src/spanner_database_admin/list_databases.py create mode 100644 spanner/database_admin/tests/list_databases_test.py diff --git a/spanner/database_admin/src/spanner_database_admin/list_databases.py b/spanner/database_admin/src/spanner_database_admin/list_databases.py new file mode 100644 index 0000000000..05158cffd9 --- /dev/null +++ b/spanner/database_admin/src/spanner_database_admin/list_databases.py @@ -0,0 +1,75 @@ +# 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_list_databases] +import sys + +from google.api_core import exceptions +from google.cloud import spanner_admin_database_v1 + + +def list_databases(project_id: str, instance_id: str) -> None: + """Lists all Spanner databases and their leader options on an instance. + + Args: + project_id: The Google Cloud project ID. + instance_id: The Spanner instance ID. + """ + client = spanner_admin_database_v1.DatabaseAdminClient() + parent = client.instance_path(project_id, instance_id) + request = spanner_admin_database_v1.ListDatabasesRequest(parent=parent) + + try: + databases = list(client.list_databases(request=request)) + except exceptions.NotFound as err: + print( + f"error: instance '{instance_id}' was not found: {err.message}", + file=sys.stderr, + ) + except exceptions.GoogleAPICallError as err: + print( + f"error: failed to list databases on instance '{instance_id}': " + f"{err.message}", + file=sys.stderr, + ) + else: + print(f"Resource ID: {instance_id}") + print(f"Database Count: {len(databases)}") + for db in databases: + db_id = db.name.split("/")[-1] + leader = db.default_leader or "regional-default" + print(f"Database ID: {db_id}, Default Leader: {leader}") + + +# [END spanner_list_databases] + + +if __name__ == "__main__": + import argparse + import os + + parser = argparse.ArgumentParser( + description="List Spanner databases on an instance." + ) + parser.add_argument( + "--project-id", + default=os.environ.get("GOOGLE_CLOUD_PROJECT", "example-project-id"), + ) + parser.add_argument( + "--instance-id", + default=os.environ.get("SPANNER_INSTANCE_ID", "example-instance"), + ) + args = parser.parse_args() + + list_databases(project_id=args.project_id, instance_id=args.instance_id) diff --git a/spanner/database_admin/tests/list_databases_test.py b/spanner/database_admin/tests/list_databases_test.py new file mode 100644 index 0000000000..12d9e785a3 --- /dev/null +++ b/spanner/database_admin/tests/list_databases_test.py @@ -0,0 +1,112 @@ +# 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 +import pytest +from spanner_database_admin import list_databases + +from . import conftest + +PROJECT_ID = "example-project-id" +INSTANCE_ID = "example-instance" +ADMIN_CLIENT = "google.cloud.spanner_admin_database_v1.DatabaseAdminClient" + + +@mock.patch(ADMIN_CLIENT) +def test_list_databases_success( + mock_client_class: mock.MagicMock, capsys: pytest.CaptureFixture[str] +) -> None: + mock_client_class.return_value.instance_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}" + ) + db_pb = mock.MagicMock() + db_pb.name = f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/example-db" + db_pb.default_leader = "us-east4" + mock_client_class.return_value.list_databases.return_value = [db_pb] + + list_databases.list_databases(PROJECT_ID, INSTANCE_ID) + + out, err = capsys.readouterr() + assert f"Resource ID: {INSTANCE_ID}" in out + assert "Database Count: 1" in out + assert "Database ID: example-db, Default Leader: us-east4" in out + assert PROJECT_ID not in out + assert err == "" + + +@pytest.mark.parametrize( + "error, expected_prefix", + [ + (exceptions.NotFound("missing"), "error: instance 'example-instance'"), + ( + exceptions.PermissionDenied("denied"), + "error: failed to list databases on instance 'example-instance'", + ), + ], +) +@mock.patch(ADMIN_CLIENT) +def test_list_databases_errors( + mock_client_class: mock.MagicMock, + capsys: pytest.CaptureFixture[str], + error: Exception, + expected_prefix: str, +) -> None: + mock_client_class.return_value.instance_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}" + ) + mock_client_class.return_value.list_databases.side_effect = error + + list_databases.list_databases(PROJECT_ID, INSTANCE_ID) + + _out, err = capsys.readouterr() + assert err.startswith(expected_prefix) + assert PROJECT_ID not in err + + +@mock.patch(ADMIN_CLIENT) +def test_list_databases_cli_entrypoint( + mock_client_class: mock.MagicMock, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + mock_client_class.return_value.instance_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}" + ) + mock_client_class.return_value.list_databases.return_value = [] + monkeypatch.setattr( + "sys.argv", + [ + "list_databases.py", + "--project-id", + PROJECT_ID, + "--instance-id", + INSTANCE_ID, + ], + ) + + runpy.run_module("spanner_database_admin.list_databases", run_name="__main__") + + assert "Database Count: 0" in capsys.readouterr().out + + +@conftest.live_only +def test_list_databases_live(capsys: pytest.CaptureFixture[str]) -> None: + list_databases.list_databases(conftest.LIVE_PROJECT_ID, conftest.LIVE_INSTANCE_ID) + out, err = capsys.readouterr() + assert err == "" + assert conftest.LIVE_PROJECT_ID not in out + assert f"Database ID: {conftest.LIVE_DATABASE_ID}" in out