diff --git a/spanner/backups/src/spanner_backups/create_backup.py b/spanner/backups/src/spanner_backups/create_backup.py new file mode 100644 index 0000000000..edd104d732 --- /dev/null +++ b/spanner/backups/src/spanner_backups/create_backup.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_create_backup] +import datetime +import sys + +from google.api_core import exceptions +from google.cloud import spanner +from google.cloud import spanner_admin_database_v1 + + +def create_backup( + project_id: str, instance_id: str, database_id: str, backup_id: str +) -> None: + """Creates a point-in-time Cloud Spanner database backup. + + Args: + project_id: The Google Cloud project ID. + instance_id: The Spanner instance ID. + database_id: The source Spanner database ID. + backup_id: The new backup ID to create. + """ + admin_client = spanner_admin_database_v1.DatabaseAdminClient() + parent = admin_client.instance_path(project_id, instance_id) + database_path = admin_client.database_path(project_id, instance_id, database_id) + data_client = spanner.Client(project=project_id) + database = data_client.instance(instance_id).database(database_id) + expire_time = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta( + days=7 + ) + + try: + with database.snapshot() as snapshot: + version_row = next(iter(snapshot.execute_sql("SELECT CURRENT_TIMESTAMP()"))) + version_time = version_row[0] + + backup_pb = spanner_admin_database_v1.Backup( + database=database_path, + expire_time=expire_time, + version_time=version_time, + ) + request = spanner_admin_database_v1.CreateBackupRequest( + parent=parent, + backup_id=backup_id, + backup=backup_pb, + ) + operation = admin_client.create_backup(request=request) + print(f"Waiting for backup '{backup_id}' creation to complete...") + backup = operation.result(timeout=2100) + except exceptions.AlreadyExists as err: + print( + f"error: backup '{backup_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 backup '{backup_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 backup '{backup_id}' for database " + f"'{database_id}' on instance '{instance_id}': {err.message}", + file=sys.stderr, + ) + else: + print(f"Resource ID: {backup_id}") + print(f"Backup Size Bytes: {backup.size_bytes}") + print(f"Backup State: {backup.state.name}") + + +# [END spanner_create_backup] + + +if __name__ == "__main__": + import argparse + import os + + parser = argparse.ArgumentParser(description="Create a Spanner database backup.") + 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"), + ) + parser.add_argument( + "--database-id", + default=os.environ.get("SPANNER_DATABASE_ID", "example-db"), + ) + parser.add_argument( + "--backup-id", + default="example-backup", + ) + args = parser.parse_args() + + create_backup( + project_id=args.project_id, + instance_id=args.instance_id, + database_id=args.database_id, + backup_id=args.backup_id, + ) diff --git a/spanner/backups/tests/create_backup_test.py b/spanner/backups/tests/create_backup_test.py new file mode 100644 index 0000000000..327b2d981b --- /dev/null +++ b/spanner/backups/tests/create_backup_test.py @@ -0,0 +1,157 @@ +# 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 datetime +import runpy +from unittest import mock +import uuid + +from google.api_core import exceptions +from google.cloud import spanner_admin_database_v1 +import pytest +from spanner_backups import create_backup + +from . import conftest + +PROJECT_ID = "example-project-id" +INSTANCE_ID = "example-instance" +DATABASE_ID = "example-db" +BACKUP_ID = "example-backup" +ADMIN_CLIENT = "google.cloud.spanner_admin_database_v1.DatabaseAdminClient" +SPANNER_CLIENT = "google.cloud.spanner.Client" + + +def _setup_mocks( + mock_admin_class: mock.MagicMock, mock_client_class: mock.MagicMock +) -> None: + admin = mock_admin_class.return_value + admin.instance_path.return_value = f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}" + admin.database_path.return_value = ( + f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/{DATABASE_ID}" + ) + snap = ( + mock_client_class.return_value.instance.return_value.database.return_value.snapshot.return_value.__enter__.return_value + ) + snap.execute_sql.return_value = [ + (datetime.datetime(2026, 1, 15, tzinfo=datetime.timezone.utc),) + ] + bkp = mock.MagicMock(size_bytes=4096) + bkp.state.name = "READY" + admin.create_backup.return_value.result.return_value = bkp + + +@mock.patch(SPANNER_CLIENT) +@mock.patch(ADMIN_CLIENT) +def test_create_backup_success( + mock_admin_class: mock.MagicMock, + mock_client_class: mock.MagicMock, + capsys: pytest.CaptureFixture[str], +) -> None: + _setup_mocks(mock_admin_class, mock_client_class) + + create_backup.create_backup(PROJECT_ID, INSTANCE_ID, DATABASE_ID, BACKUP_ID) + + out, err = capsys.readouterr() + assert f"Resource ID: {BACKUP_ID}" in out + assert "Backup Size Bytes: 4096" in out + assert "Backup State: READY" 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.AlreadyExists("dup"), + "error: backup 'example-backup' already exists", + ), + ( + exceptions.PermissionDenied("denied"), + "error: failed to create backup 'example-backup'", + ), + ], +) +@mock.patch(SPANNER_CLIENT) +@mock.patch(ADMIN_CLIENT) +def test_create_backup_errors( + mock_admin_class: mock.MagicMock, + mock_client_class: mock.MagicMock, + capsys: pytest.CaptureFixture[str], + error: Exception, + expected_prefix: str, +) -> None: + _setup_mocks(mock_admin_class, mock_client_class) + mock_admin_class.return_value.create_backup.side_effect = error + + create_backup.create_backup(PROJECT_ID, INSTANCE_ID, DATABASE_ID, BACKUP_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_create_backup_cli_entrypoint( + mock_admin_class: mock.MagicMock, + mock_client_class: mock.MagicMock, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + _setup_mocks(mock_admin_class, mock_client_class) + monkeypatch.setattr( + "sys.argv", + [ + "create_backup.py", + "--project-id", + PROJECT_ID, + "--instance-id", + INSTANCE_ID, + "--database-id", + DATABASE_ID, + "--backup-id", + BACKUP_ID, + ], + ) + + runpy.run_module("spanner_backups.create_backup", run_name="__main__") + + assert "Backup State: READY" in capsys.readouterr().out + + +@conftest.live_only +def test_create_backup_live(capsys: pytest.CaptureFixture[str]) -> None: + admin = spanner_admin_database_v1.DatabaseAdminClient() + bkp_id = f"example-bkp-{uuid.uuid4().hex[:6]}" + bkp_path = admin.backup_path( + conftest.LIVE_PROJECT_ID, conftest.LIVE_INSTANCE_ID, bkp_id + ) + try: + create_backup.create_backup( + conftest.LIVE_PROJECT_ID, + conftest.LIVE_INSTANCE_ID, + conftest.LIVE_DATABASE_ID, + bkp_id, + ) + out, err = capsys.readouterr() + assert err == "" + assert conftest.LIVE_PROJECT_ID not in out + assert "Backup State: READY" in out + finally: + try: + admin.delete_backup(name=bkp_path) + except exceptions.NotFound: + pass