Skip to content


feat: add support for backups (#35)
Browse files Browse the repository at this point in the history
* feat: implement backup support

* Apply suggestions from code review

Co-Authored-By: skuruppu <>

* refactor restore to use source

Co-authored-by: larkee <>
Co-authored-by: skuruppu <>
  • Loading branch information
3 people committed Mar 13, 2020
1 parent a48c4b1 commit 39288e7
Show file tree
Hide file tree
Showing 6 changed files with 1,725 additions and 1 deletion.
275 changes: 275 additions & 0 deletions google/cloud/spanner_v1/
Original file line number Diff line number Diff line change
@@ -0,0 +1,275 @@
# Copyright 2020 Google LLC All rights reserved.
# 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
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# See the License for the specific language governing permissions and
# limitations under the License.

"""User friendly container for Cloud Spanner Backup."""

import re

from import _datetime_to_pb_timestamp, _pb_timestamp_to_datetime
from import NotFound

from import enums
from import _metadata_with_prefix

_BACKUP_NAME_RE = re.compile(

class Backup(object):
"""Representation of a Cloud Spanner Backup.
We can use a :class`Backup` to:
* :meth:`create` the backup
* :meth:`update` the backup
* :meth:`delete` the backup
:type backup_id: str
:param backup_id: The ID of the backup.
:type instance: :class:``
:param instance: The instance that owns the backup.
:type database: str
:param database: (Optional) The URI of the database that the backup is
for. Required if the create method needs to be called.
:type expire_time: :class:`datetime.datetime`
:param expire_time: (Optional) The expire time that will be used to
create the backup. Required if the create method
needs to be called.

def __init__(self, backup_id, instance, database="", expire_time=None):
self.backup_id = backup_id
self._instance = instance
self._database = database
self._expire_time = expire_time
self._create_time = None
self._size_bytes = None
self._state = None
self._referencing_databases = None

def name(self):
"""Backup name used in requests.
The backup name is of the form
:rtype: str
:returns: The backup name.
return + "/backups/" + self.backup_id

def database(self):
"""Database name used in requests.
The database name is of the form
:rtype: str
:returns: The database name.
return self._database

def expire_time(self):
"""Expire time used in creation requests.
:rtype: :class:`datetime.datetime`
:returns: a datetime object representing the expire time of
this backup
return self._expire_time

def create_time(self):
"""Create time of this backup.
:rtype: :class:`datetime.datetime`
:returns: a datetime object representing the create time of
this backup
return self._create_time

def size_bytes(self):
"""Size of this backup in bytes.
:rtype: int
:returns: the number size of this backup measured in bytes
return self._size_bytes

def state(self):
"""State of this backup.
:rtype: :class:``
:returns: an enum describing the state of the backup
return self._state

def referencing_databases(self):
"""List of databases referencing this backup.
:rtype: list of strings
:returns: a list of database path strings which specify the databases still
referencing this backup
return self._referencing_databases

def from_pb(cls, backup_pb, instance):
"""Create an instance of this class from a protobuf message.
:type backup_pb: :class:`~google.spanner.admin.database.v1.Backup`
:param backup_pb: A backup protobuf object.
:type instance: :class:``
:param instance: The instance that owns the backup.
:rtype: :class:`Backup`
:returns: The backup parsed from the protobuf response.
:raises ValueError:
if the backup name does not match the expected format or if
the parsed project ID does not match the project ID on the
instance's client, or if the parsed instance ID does not match
the instance's ID.
match = _BACKUP_NAME_RE.match(
if match is None:
raise ValueError(
"Backup protobuf name was not in the expected format.",
if"project") != instance._client.project:
raise ValueError(
"Project ID on backup does not match the project ID"
"on the instance's client"
instance_id ="instance_id")
if instance_id != instance.instance_id:
raise ValueError(
"Instance ID on database does not match the instance ID"
"on the instance"
backup_id ="backup_id")
return cls(backup_id, instance)

def create(self):
"""Create this backup within its instance.
:rtype: :class:`~google.api_core.operation.Operation`
:returns: a future used to poll the status of the create request
:raises Conflict: if the backup already exists
:raises NotFound: if the instance owning the backup does not exist
:raises BadRequest: if the database or expire_time values are invalid
or expire_time is not set
if not self._expire_time:
raise ValueError("expire_time not set")
if not self._database:
raise ValueError("database not set")
api = self._instance._client.database_admin_api
metadata = _metadata_with_prefix(
backup = {
"database": self._database,
"expire_time": _datetime_to_pb_timestamp(self.expire_time),

future = api.create_backup(, self.backup_id, backup, metadata=metadata
return future

def exists(self):
"""Test whether this backup exists.
:rtype: bool
:returns: True if the backup exists, else False.
api = self._instance._client.database_admin_api
metadata = _metadata_with_prefix(

api.get_backup(, metadata=metadata)
except NotFound:
return False
return True

def reload(self):
"""Reload this backup.
Refresh the stored backup properties.
:raises NotFound: if the backup does not exist
api = self._instance._client.database_admin_api
metadata = _metadata_with_prefix(
pb = api.get_backup(, metadata=metadata)
self._database = pb.database
self._expire_time = _pb_timestamp_to_datetime(pb.expire_time)
self._create_time = _pb_timestamp_to_datetime(pb.create_time)
self._size_bytes = pb.size_bytes
self._state = enums.Backup.State(pb.state)
self._referencing_databases = pb.referencing_databases

def update_expire_time(self, new_expire_time):
"""Update the expire time of this backup.
:type new_expire_time: :class:`datetime.datetime`
:param new_expire_time: the new expire time timestamp
api = self._instance._client.database_admin_api
metadata = _metadata_with_prefix(
backup_update = {
"expire_time": _datetime_to_pb_timestamp(new_expire_time),
update_mask = {"paths": ["expire_time"]}
api.update_backup(backup_update, update_mask, metadata=metadata)
self._expire_time = new_expire_time

def is_ready(self):
"""Test whether this backup is ready for use.
:rtype: bool
:returns: True if the backup state is READY, else False.
return self.state == enums.Backup.State.READY

def delete(self):
"""Delete this backup."""
api = self._instance._client.database_admin_api
metadata = _metadata_with_prefix(
api.delete_backup(, metadata=metadata)

class BackupInfo(object):
def __init__(self, backup, create_time, source_database):
self.backup = backup
self.create_time = _pb_timestamp_to_datetime(create_time)
self.source_database = source_database

def from_pb(cls, pb):
return cls(pb.backup, pb.create_time, pb.source_database)

0 comments on commit 39288e7

Please sign in to comment.