This page describes how to use the Cloud Firestore scheduled backups
feature. Use backups to protect your data from application-level data
corruption or from accidental data deletion.
Backups let you configure backup schedules to take daily or weekly
backups of the specified database. You can then use these backups to restore
data to a new database.
About backups
A backup is a consistent copy of the database at a point in time.
The backup contains all data and index configurations at that point
in time. A backup does not contain database
time to live policies
.
A backup resides in the same location as the source database.
Backups have a configurable retention period and are stored until the retention
period expires or until you delete the backup. Deleting the source database does
not automatically delete related backups.
Cloud Firestore stores metadata related to backups and backup
schedules related to a database. Cloud Firestore retains this metadata
until
all
backups for the database expire or are deleted.
Creating or retaining backups does not affect the performance of reads or
writes in your live database.
Costs
When you use backups, you're charged for the following:
- The amount of storage used by each backup.
- For a restore operation, you're charged based on the size of the backup.
For more details and exact rates, see the
Pricing
page.
Before you begin
This feature requires the
Blaze pricing plan
.
Required roles
To get the permissions that you need to manage backups and backup schedules,
ask your administrator to grant you one or more of the following Identity and Access Management
roles:
Create and manage backup schedules
The examples below demonstrate how to set up a backup schedule. For each
database, you can configure up to one daily backup schedule and up to one weekly
backup schedule. You cannot configure multiple weekly backups schedules for
different days of the week.
You cannot configure the exact time of day of the backup. Backups are taken at
different times each day. For weekly backup
schedules, you can configure the day of the week to take a backup.
Create a backup schedule
To create a backup schedule for a database, use the
gcloud alpha firestore backups schedules create
command.
Create a daily backup schedule
To create a daily backup schedule, set the
--recurrence
flag to
daily
:
gcloud alpha firestore backups schedules create \
--database='
DATABASE_ID
' \
--recurrence=daily \
--retention=
RETENTION_PERIOD
Replace the following:
DATABASE_ID
: The ID of the database to back up. Set to
(default)
for the default database.
RETENTION_PERIOD
: Set this to a value up to 14 weeks (
14w
).
Create a weekly backup schedule
To create a weekly backup schedule, set the
--recurrence
flag to
weekly
:
gcloud alpha firestore backups schedules create \
--database='
DATABASE_ID
' \
--recurrence=weekly \
--retention=
RETENTION_PERIOD
\
--day-of-week=
DAY
Replace the following:
DATABASE_ID
: The ID of the database to back up. Set to
(default)
for the default database.
RETENTION_PERIOD
: Set this to a value up to 14 weeks (
14w
).
DAY
: The day of the week to take the backup. Set to
one of the following:
SUN
for Sunday
MON
for Monday
TUE
for Tuesday
WED
for Wednesday
THU
for Thursday
FRI
for Friday
SAT
for Saturday
List backup schedules
To list all backup schedules for a database, use the
gcloud alpha firestore backups schedules list
command.
This command returns information about all backup schedules.
gcloud alpha firestore backups schedules list \
--database='
DATABASE_ID
'
Replace
DATABASE_ID
with the ID of the database. Use
(default)
for the default database.
Describe backup schedule
To retrieve information about a backup schedule, use the
gcloud alpha firestore backups schedules describe
command:
gcloud alpha firestore backups schedules describe \
--database='
DATABASE_ID
' \
--backup-schedule=
BACKUP_SCHEDULE_ID
Replace the following:
DATABASE_ID
: The ID of the database to back up. Set to
(default)
for the default database.
BACKUP_SCHEDULE_ID
: The ID of a backup schedule. You
can view the ID of each backup schedule when you
list all backup schedules
.
Update a backup schedule
To update the retention period of a backup schedule, use the
gcloud alpha firestore backups schedules update
command:
gcloud alpha firestore backups schedules update \
--database='
DATABASE_ID
' \
--backup-schedule=
BACKUP_SCHEDULE_ID
--retention=
RETENTION_PERIOD
Replace the following:
DATABASE_ID
: The ID of the database to back up. Set to
(default)
for the default database.
BACKUP_SCHEDULE_ID
: The ID of a backup schedule. You
can view the ID each backup schedule when you
list all backup schedules
.
RETENTION_PERIOD
: Set this to a value up to 14 weeks (
14w
).
Delete a backup schedule
To delete a backup schedule, use the
gcloud alpha firestore backups schedules delete
command:
gcloud alpha firestore backups schedules delete \
--database='
DATABASE_ID
' \
--backup-schedule=
BACKUP_SCHEDULE_ID
Replace the following:
DATABASE_ID
: The ID of the database to back up. Set to
(default)
for the default database.
BACKUP_SCHEDULE_ID
: The ID of a backup schedule. You
can view the ID of each backup schedule when you
list all backup schedules
.
Note that deleting a backup schedule will not delete backups already created by
this schedule. You can wait for them to expire after their retention period, or
to manually delete a backup, see
delete backup
.
Manage backups
List backups
To list available backups, use the
gcloud alpha firestore backups list
command:
gcloud alpha firestore backups list \
--format="table(name, database, state)"
The
--format="table(name, database, state)"
flag formats the output into a
more readable format.
To list only the backups from a specific location, use the
--location
flag:
gcloud alpha firestore backups list \
--location=
LOCATION
\
--format="table(name, database, state)"
Replace
LOCATION
with the name of a Cloud Firestore
location.
Describe a backup
To view details about a backup, use the
gcloud alpha firestore backups describe
command:
gcloud alpha firestore backups describe \
--location=
LOCATION
\
--backup=
BACKUP_ID
LOCATION
: The location of the database.
BACKUP_ID
: The ID of a backup. You
can view the ID each backup when you
list all backups
.
Delete backup
To delete a backup, use the
gcloud alpha firestore backups delete
command:
gcloud alpha firestore backups delete \
--location=
LOCATION
\
--backup=
BACKUP_ID
LOCATION
: The location of the database.
BACKUP_ID
: The ID of a backup. You
can view the ID each backup when you
list all backups
.
Restore data from a database backup
A restore operation writes the data from a backup to a new Cloud Firestore
database. To begin a restore operation, use the
gcloud alpha firestore databases restore
command:
gcloud alpha firestore databases restore \
--source-backup=projects/
PROJECT_ID
/locations/
LOCATION
/backups/
BACKUP_ID
\
--destination-database='
DATABASE_ID
'
PROJECT_ID
: Your project ID.
LOCATION
: The location of the database backup and the
location of the new database created for the restored data.
BACKUP_ID
: The ID of a backup.
You can view the ID each backup when you
list all backups
.
DATABASE_ID
: A database ID for the new
database. You cannot use a database ID that is already in use.
The output will include
metadata
,
name
, and
response
components:
metadata:
'@type': type.googleapis.com/google.firestore.admin.v1.RestoreDatabaseMetadata
backup: projects/
PROJECT_ID
/locations/
LOCATION
/backups/
BACKUP_ID
database: projects/
PROJECT_ID
/databases/
DATABASE_ID
operationState: PROCESSING
progressPercentage:
completedWork: '20'
estimatedWork: '100'
startTime: '2023-12-06T14:20:17.398325Z'
name: projects/
PROJECT_ID
/databases/
DATABASE_ID
/operations/operation_uuid
response:
'@type': type.googleapis.com/google.firestore.admin.v1.Database
createTime: '2023-12-06T14:20:17.398325Z'
name: projects/
PROJECT_ID
/databases/
DATABASE_ID
...
The
metadata
field includes a
progressPercentage
component, detailing the estimated progress of the restore thus far, and an
operationState
specifying
the overall state of the restore.
To retrieve this information again, use
gcloud firestore operations list
:
gcloud firestore operations list --database=
DATABASE_ID
or, using the
name
field from the output described above, with
gcloud firestore operations describe
:
gcloud firestore operations describe
OPERATION_NAME