From a9ce279fbb7aa434fcf1fd031b7faba85843b813 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 fine-grained database role DDL lifecycle sample Fine-grained access control (FGAC) defines hierarchical SQL roles with CREATE ROLE, GRANT, REVOKE, and DROP ROLE DDL statements. Add a standalone spanner_add_and_drop_database_role sample. --- .../add_and_drop_database_role.py | 115 ++++++++++++++ .../tests/add_and_drop_database_role_test.py | 146 ++++++++++++++++++ 2 files changed, 261 insertions(+) create mode 100644 spanner/database_admin/src/spanner_database_admin/add_and_drop_database_role.py create mode 100644 spanner/database_admin/tests/add_and_drop_database_role_test.py diff --git a/spanner/database_admin/src/spanner_database_admin/add_and_drop_database_role.py b/spanner/database_admin/src/spanner_database_admin/add_and_drop_database_role.py new file mode 100644 index 0000000000..171d2b872f --- /dev/null +++ b/spanner/database_admin/src/spanner_database_admin/add_and_drop_database_role.py @@ -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_add_and_drop_database_role] +import sys + +from google.api_core import exceptions +from google.cloud import spanner_admin_database_v1 + + +def add_and_drop_database_role( + project_id: str, instance_id: str, database_id: str +) -> None: + """Creates fine-grained database roles, grants privileges, and drops child role. + + Args: + project_id: The Google Cloud project ID. + instance_id: The Spanner instance ID. + database_id: The Spanner database ID containing Singers. + """ + client = spanner_admin_database_v1.DatabaseAdminClient() + database_path = client.database_path(project_id, instance_id, database_id) + role_parent = "new_parent" + role_child = "new_child" + create_request = spanner_admin_database_v1.UpdateDatabaseDdlRequest( + database=database_path, + statements=[ + f"CREATE ROLE {role_parent}", + f"GRANT SELECT ON TABLE Singers TO ROLE {role_parent}", + f"CREATE ROLE {role_child}", + f"GRANT ROLE {role_parent} TO ROLE {role_child}", + ], + ) + drop_request = spanner_admin_database_v1.UpdateDatabaseDdlRequest( + database=database_path, + statements=[ + f"REVOKE ROLE {role_parent} FROM ROLE {role_child}", + f"DROP ROLE {role_child}", + ], + ) + + try: + create_op = client.update_database_ddl(request=create_request) + print(f"Waiting for database roles '{role_parent}' and '{role_child}'...") + create_op.result(timeout=300) + drop_op = client.update_database_ddl(request=drop_request) + print(f"Waiting for child role '{role_child}' revocation and drop...") + drop_op.result(timeout=300) + except (exceptions.AlreadyExists, exceptions.FailedPrecondition) as err: + print( + f"error: database role already exists or preconditions failed on " + f"database '{database_id}' in instance '{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 manage database roles on database " + f"'{database_id}' in instance '{instance_id}': {err.message}", + file=sys.stderr, + ) + else: + print(f"Resource ID: {database_id}") + print(f"Active Role: {role_parent}") + print(f"Dropped Role: {role_child}") + + +# [END spanner_add_and_drop_database_role] + + +if __name__ == "__main__": + import argparse + import os + + parser = argparse.ArgumentParser( + description="Create, grant, revoke, and drop Spanner fine-grained database roles." + ) + 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() + + add_and_drop_database_role( + project_id=args.project_id, + instance_id=args.instance_id, + database_id=args.database_id, + ) diff --git a/spanner/database_admin/tests/add_and_drop_database_role_test.py b/spanner/database_admin/tests/add_and_drop_database_role_test.py new file mode 100644 index 0000000000..615787cb8b --- /dev/null +++ b/spanner/database_admin/tests/add_and_drop_database_role_test.py @@ -0,0 +1,146 @@ +# 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 add_and_drop_database_role + +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" + + +@mock.patch(ADMIN_CLIENT) +def test_add_and_drop_database_role_success( + mock_client_class: mock.MagicMock, capsys: pytest.CaptureFixture[str] +) -> None: + mock_client_class.return_value.database_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/{DATABASE_ID}" + ) + + add_and_drop_database_role.add_and_drop_database_role( + PROJECT_ID, INSTANCE_ID, DATABASE_ID + ) + + assert mock_client_class.return_value.update_database_ddl.call_count == 2 + out, err = capsys.readouterr() + assert f"Resource ID: {DATABASE_ID}" in out + assert "Active Role: new_parent" in out + assert "Dropped Role: new_child" 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.FailedPrecondition("exists"), + "error: database role already exists", + ), + ( + exceptions.PermissionDenied("denied"), + "error: failed to manage database roles", + ), + ], +) +@mock.patch(ADMIN_CLIENT) +def test_add_and_drop_database_role_errors( + mock_client_class: mock.MagicMock, + capsys: pytest.CaptureFixture[str], + error: Exception, + expected_prefix: str, +) -> None: + mock_client_class.return_value.database_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/{DATABASE_ID}" + ) + mock_client_class.return_value.update_database_ddl.side_effect = error + + add_and_drop_database_role.add_and_drop_database_role( + PROJECT_ID, INSTANCE_ID, DATABASE_ID + ) + + _out, err = capsys.readouterr() + assert err.startswith(expected_prefix) + assert PROJECT_ID not in err + + +@mock.patch(ADMIN_CLIENT) +def test_add_and_drop_database_role_cli_entrypoint( + mock_client_class: mock.MagicMock, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + mock_client_class.return_value.database_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/{DATABASE_ID}" + ) + monkeypatch.setattr( + "sys.argv", + [ + "add_and_drop_database_role.py", + "--project-id", + PROJECT_ID, + "--instance-id", + INSTANCE_ID, + "--database-id", + DATABASE_ID, + ], + ) + + runpy.run_module( + "spanner_database_admin.add_and_drop_database_role", run_name="__main__" + ) + + assert "Active Role: new_parent" in capsys.readouterr().out + + +@conftest.live_only +def test_add_and_drop_database_role_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, + ) + for cleanup_stmt in [ + "REVOKE ROLE new_parent FROM ROLE new_child", + "DROP ROLE new_child", + "REVOKE SELECT ON TABLE Singers FROM ROLE new_parent", + "DROP ROLE new_parent", + ]: + try: + admin.update_database_ddl( + request={"database": db_path, "statements": [cleanup_stmt]} + ).result(timeout=120) + except exceptions.GoogleAPICallError: + pass + + add_and_drop_database_role.add_and_drop_database_role( + 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 "Active Role: new_parent" in out + assert "Dropped Role: new_child" in out From 5c3ce2875c981684eb0c14b4fb247ef4d69eceb1 Mon Sep 17 00:00:00 2001 From: Jennifer Davis Date: Thu, 19 Nov 2026 06:19:56 +0000 Subject: [PATCH 2/2] fix(spanner): address review feedback for add_and_drop_database_role Problem: review of this sample identified correctness and robustness improvements in the sample and its tests. Solution: apply the accepted review suggestions and extend the tests to cover the updated behavior. Details are in the review thread replies. Files updated: - spanner/database_admin/tests/add_and_drop_database_role_test.py --- .../tests/add_and_drop_database_role_test.py | 50 +++++++++++-------- 1 file changed, 28 insertions(+), 22 deletions(-) diff --git a/spanner/database_admin/tests/add_and_drop_database_role_test.py b/spanner/database_admin/tests/add_and_drop_database_role_test.py index 615787cb8b..6ff580dee7 100644 --- a/spanner/database_admin/tests/add_and_drop_database_role_test.py +++ b/spanner/database_admin/tests/add_and_drop_database_role_test.py @@ -121,26 +121,32 @@ def test_add_and_drop_database_role_live(capsys: pytest.CaptureFixture[str]) -> conftest.LIVE_INSTANCE_ID, conftest.LIVE_DATABASE_ID, ) - for cleanup_stmt in [ - "REVOKE ROLE new_parent FROM ROLE new_child", - "DROP ROLE new_child", - "REVOKE SELECT ON TABLE Singers FROM ROLE new_parent", - "DROP ROLE new_parent", - ]: - try: - admin.update_database_ddl( - request={"database": db_path, "statements": [cleanup_stmt]} - ).result(timeout=120) - except exceptions.GoogleAPICallError: - pass - add_and_drop_database_role.add_and_drop_database_role( - 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 "Active Role: new_parent" in out - assert "Dropped Role: new_child" in out + def cleanup_roles() -> None: + for cleanup_stmt in [ + "REVOKE ROLE new_parent FROM ROLE new_child", + "DROP ROLE new_child", + "REVOKE SELECT ON TABLE Singers FROM ROLE new_parent", + "DROP ROLE new_parent", + ]: + try: + admin.update_database_ddl( + request={"database": db_path, "statements": [cleanup_stmt]} + ).result(timeout=120) + except exceptions.GoogleAPICallError: + pass + + cleanup_roles() + try: + add_and_drop_database_role.add_and_drop_database_role( + 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 "Active Role: new_parent" in out + assert "Dropped Role: new_child" in out + finally: + cleanup_roles()