Create and manage databases

Create and manage databases

This page describes how to create, update, and delete Firestore databases. You can create multiple Firestore databases per project. You can use multiple databases to set up production and testing environments, to isolate customer data, and for data regionalization.

The (default) database

If your app does not require multiple databases, use the (default) database.

If you do not specify a database, the Firestore client libraries and the Google Cloud CLI connect to the (default) database by default.

You can use the Free quota only with the (default) database.

Required roles

To create and manage databases, you need the Owner or Datastore Owner Identity and Access Management role. These roles grant the required permissions.

Required permissions

To manage databases, you require the following permissions:

• Create a database: datastore.databases.create
• Read database configuration: datastore.databases.getMetadata
• Configure a database: datastore.databases.update
• Delete a database: datastore.databases.delete

Create a database

To create a database, use one of the following methods:

Console

1. In the Google Cloud console, go to the Databases page.

   Go to Databases

2. Click Create Database.
3. Select a database mode. Click Continue
4. Configure your database. Enter a Database ID. Select a location. Select security rules for mobile and web clients. Click Create Database.

gcloud

Use the gcloud firestore databases create command.

gcloud firestore databases create \
--database=DATABASE_ID \
--location=LOCATION \
--type=DATABASE_TYPE \
[--delete-protection]

Replace the following:

• DATABASE_ID: a valid database ID.
• LOCATION: the name of a Firestore multi-region or region.
• DATABASE_TYPE: either firestore-native for Native mode or datastore-mode for Datastore mode.

--delete-protection is an optional flag to enable deletion protection. You cannot delete a database with deletion protection enabled until you disable this setting. This setting is disabled by default.

Firebase CLI

firebase firestore:databases:create DATABASE_ID \
--location=LOCATION \
[--delete-protection DELETE_PROTECTION_ENABLEMENT]

Replace the following:

• DATABASE_ID: a valid database ID.
• LOCATION: the name of a Firestore multi-region or region.
• DELETE_PROTECTION_ENABLEMENT: Either ENABLED or DISABLED.
The database created is always in Firestore Native mode.

--delete-protection is an optional argument to enable deletion protection. You cannot delete a database with deletion protection enabled until you disable this setting. This setting is disabled by default.

Terraform

resource "google_firestore_database" "database" {
  project     = "project-id"
  name        = DATABASE_ID
  location_id = LOCATION
  type        = DATABASE_TYPE

  // Optional
  delete_protection_state = DELETE_PROTECTION_STATE
}

Replace the following:

• DATABASE_ID: a valid database ID.
• LOCATION: the name of a Firestore multi-region or region.
• DATABASE_TYPE: either FIRESTORE_NATIVE for Native mode or DATASTORE_MODE for Datastore mode.
• DELETE_PROTECTION_ENABLEMENT: Either DELETE_PROTECTION_ENABLED or DELETE_PROTECTION_DISABLED.

delete_protection_state is an optional argument to enable deletion protection. You cannot delete a database with deletion protection enabled until you disable this setting. This setting is disabled by default.

Database ID

Valid database IDs include (default) and IDs that conform to the following:

• Includes only letters, numbers, and hyphen (-) characters.
• Letters must be lowercase.
• The first character must be a letter.
• The last character must be a letter or number.
• Minimum of 4 characters.
• Maximum of 63 characters.
• Must not be a UUID or resemble a UUID. For example, do not use an ID like f47ac10b-58cc-0372-8567-0e02b2c3d479.

If you delete a database, you cannot immediately re-use the database ID until after 5 minutes.

Delete protection

Use delete protection to prevent accidental deletion of a database. You cannot delete a database with delete protection enabled until you disable delete protection. Delete protection is disabled by default. You can enable delete protection when you create the database or you can update a database configuration to enable delete protection.

Set up Firestore Security Rules for your databases

Use the Firebase CLI to deploy Firestore Security Rules to each of your databases. Refer to the guide for managing and deploying Firestore Security Rules.

Access a named database with a client library

A named database includes any database not named (default). By default, the Firebase SDKs and Google API Client Libraries connect to the (default) Firestore database in a project. To create a client connected to a named database, set the database ID when you instantiate a client.

Note: To work with multiple databases, be sure to update to the latest Firebase Client SDKs and Google API Client Libraries.

List databases

Use one of the following methods to list your databases:

Console

In the Google Cloud console, go to the Databases page.

Go to Databases

Note:You can view and list your databases in the Google Cloud console. You can create the (default) database using the Google Cloud console, but you must use the Google Cloud CLI or another method to create a named database. To delete a database use the Google Cloud CLI.

gcloud

Use the gcloud firestore databases list command to list all the databases in your project.

gcloud firestore databases list

Firebase CLI

Use the firebase firestore:databases:list command to list all the databases in your project.

firebase firestore:databases:list

View database details

To view details about a single database, use one of the following methods:

gcloud

Use the gcloud firestore databases describe command:

gcloud firestore databases describe --database=DATABASE_ID

Firebase CLI

Use the firebase firestore:databases:get command:

firebase firestore:databases:get DATABASE_ID

Replace DATABASE_ID with a database ID.

Update database configuration

To update the configurations settings of a database, use the gcloud firestore databases update command. Use this command to change the database type or to toggle delete protection.

Change the database type

To update the type of a database, use the gcloud firestore databases update command with the --type= flag. You can change the type only if the database is empty.

gcloud

gcloud firestore databases update --database=DATABASE_ID \
--type=DATABASE_TYPE

Replace the following:

• DATABASE_ID: a database ID.
• DATABASE_TYPE: either firestore-native for Native mode or datastore-mode for Datastore mode.

Update the delete protection setting

To enable delete protection on a database, use the gcloud firestore databases update command with the --delete-protection flag. For example:

gcloud

gcloud firestore databases update --database=DATABASE_ID --delete-protection

Replace DATABASE_ID with a database ID.

To disable delete protection on a database, use the gcloud firestore databases update command with the --no-delete-protection flag. For example:

gcloud

gcloud firestore databases update --database=DATABASE_ID --no-delete-protection

Replace DATABASE_ID with a database ID.

Delete a database

To delete a database, use the console or command-line tool.

If the database has the delete protection setting enabled, you must first disable delete protection.

If the database contains App Engine search data or blob entities, you must delete that data first.

Deleting a database does not automatically delete any Eventarc triggers for that database. The trigger stops delivering events but continues to exist until you delete the trigger.

Console

1. In the Google Cloud console, go to the Databases page.

   Go to Databases

2. Click View more in the table row for the database you wish to delete. Click Delete. A dialog appears.

3. In the Delete database? dialog, confirm deletion by typing the database ID in the text field. Click Delete. The console informs you of operation success or failure.

   If the operation fails, view the database details and verify that delete protection is disabled. To disable delete protection, see Update the delete protection setting.

gcloud

Use the `gcloud firestore databases delete` command.

gcloud firestore databases delete --database=DATABASE_ID

Replace DATABASE_ID with the ID of the database to delete.

Configure per-database access permissions

You can use Identity and Access Management Conditions to configure access permissions on a per-database level. The following examples use the Google Cloud CLI to assign conditional access for one or more databases. You can also define IAM conditions in the Google Cloud console.

View existing IAM policies

gcloud projects get-iam-policy PROJECT_ID

Set PROJECT_ID to your project ID.

Grant access to a database

gcloud projects add-iam-policy-binding PROJECT_ID \
--member='user:EMAIL' \
--role='roles/datastore.user' \
--condition='expression=resource.name=="projects/PROJECT_ID/databases/DATABASE_ID",title=TITLE,description=DESCRIPTION'

Set the following:

• PROJECT_ID: your project ID
• EMAIL: an email address that represents a specific Google account. For example, [e-mail].
• DATABASE_ID: a database ID.
• TITLE: an optional title for the expression.
• DESCRIPTION: an optional description of the expression.

Grant access to all except one database

gcloud projects add-iam-policy-binding PROJECT_ID \
--member='user:EMAIL' \
--role='roles/datastore.user' \
--condition='expression=resource.name!="projects/PROJECT_ID/databases/DATABASE_ID",title=TITLE,description=DESCRIPTION'

Set the following:

• PROJECT_ID: your project ID
• EMAIL: an email address that represents a specific Google account. For example, [e-mail].
• DATABASE_ID: a database ID.
• TITLE: an optional title for the expression.
• DESCRIPTION: an optional description of the expression.

Remove policies for a given member and role

gcloud projects remove-iam-policy-binding PROJECT_ID \
--member='user:EMAIL' \
--role='roles/datastore.user' --all

Set the following:

• PROJECT_ID: your project ID
• EMAIL: an email address that represents a specific Google account. For example, [e-mail].

Cloud Monitoring

Firestore metrics are reported under two monitored resources.

• firestore.googleapis.com/Database
• firestore_instance(Legacy)

You can inspect aggregate metrics at the database level by looking at firestore.googleapis.com/Database. The metrics reported under firestore_instance are aggregated at the project level.

Limitations

• You can have a maximum of 100 databases per project. You can contact support to request an increase to this limit.
• You cannot delete your (default) database if it contains any GAE search data. Please use the index delete api to delete GAE search data. If you recently deleted GAE Search data, there may be a waiting period before you are able to delete the database.
• You cannot delete your (default) database if it contains any blob entities. Please use the Blobstore delete api to delete Blobstore data. You can check if your (default) database has Blobstore data by running the following GQL query in the Google Cloud console: SELECT * FROM __BlobInfo__.
• You cannot reuse a database ID until 5 minutes after the delete happens.
• Cloud Function v1 does not support Firestore Named databases. Please use Cloud Firestore Triggers (2nd Gen) to configure events for named databases.
• Firestore function triggers v1 and Firestore event triggers may stop working after the database is deleted, even if a new database is created with the same name.

What's next

• Add data
• Get data
• Delete data