Automating database creation

Automating database creation

You can automate Firestore database creation with the following process:

1. Create a new Google Cloud project. Each project is limited to one Firestore database.
2. Create an App Engine application. Firestore depends on App Engine. You must activate App Engine to use Firestore.
3. Create a Firestore database.

This page describes how to complete this process using REST APIs, the gcloud command-line tool, and Terraform.

Create a database with REST APIs

You can provision a Firestore database using the Resource Manager API and the App Engine Admin API.

Authentication and authorization

To access the Resource Manager and App Engine Admin APIs, you must authenticate your request with an access token. Your access token requires an OAuth 2.0 scope of:

https://www.googleapis.com/auth/cloud-platform

To set up authentication for an application, see setting up authentication for server to server production applications.

While developing and testing your application, you can obtain an access token using:

gcloud auth application-default print-access-token.

Authorization

The authenticated user account or service account requires the resourcemanager.projects.create permission to create a new project. The Project Creator IAM role, for example, grants this permission.

To grant this role, see granting, changing, and revoking access to resources.

Create a new project and database

1. Use the projects.create method to start a project creation operation. In the request body, define a Project resource, for example:

   HTTP

   POST https://cloudresourcemanager.googleapis.com/v1/projects HTTP/1.1
   
   Authorization: Bearer access-token
   Accept: application/json
   Content-Type: application/json
   
   {
     "projectId": "project-id"
   }
         

   Replace the following:

   • access-token is an authenticated access token.
   • project-id is a unique project ID.

   On success, the request returns an operation name:

   200:
   
   {
     "name": "operations/cp.6311184959990822268"
   }
       

2. Use the operation name from the previous step and the Resource Manager operations.get method to confirm project creation:

   HTTP

   GET https://cloudresourcemanager.googleapis.com/v1/operations/operation-name HTTP/1.1
   
   Authorization: Bearer access-token
   Accept: application/json
   

   When project creation succeeds, the response includes the following field:

   "done": true,
         

3. Use the App Engine Admin API apps.create method to create an App Engine application and Firestore database. In the request body, define an Application resource and include the databaseType field, for example:

   HTTP

   POST https://appengine.googleapis.com/v1/apps HTTP/1.1
   
   Authorization: Bearer access_token
   Accept: application/json
   Content-Type: application/json
   
   {
     "databaseType": "CLOUD_FIRESTORE",
     "id": "project-id",
     "locationId": "location"
   }
         

   Note: To create a Firestore in Datastore mode database , set databaseType to CLOUD_DATASTORE_COMPATIBILITY.

   Replace the following:

   • project-id is the ID of the project you created.
   • location sets the location of both your App Engine application and your Firestore database. Once set, you cannot change the location. For a full list of supported locations, see App Engine locations.

     App Engine and Firestore support the same locations, but the following App Engine regions map to Firestore multi-regions:

     • us-central (Iowa) creates a Firestore database in the nam5 (United States) multi-region.
     • europe-west (Belgium) creates a Firestore database in the eur3 (Europe) multi-region.

   The request returns an operation name:

   200:
   
   {
     "name": "apps/project-id/operations/8612e502-4aeb-4f12-9e41-bbac0a0b819c",
     "metadata": {
       "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
       "method": "google.appengine.v1.Applications.CreateApplication",
       "insertTime": "2020-06-05T23:34:32.587Z",
       "user": "username",
       "target": "apps/project-id"
     }
   }
           

4. Use the operation name from the previous step and the apps.operations.get to confirm database creation:

   HTTP

   GET https://appengine.googleapis.com/v1/operation-name HTTP/1.1
   
   Authorization: Bearer access-token
   Accept: application/json
       

   When the operation succeeds, the response includes the following field:

   "done": true,
         

Add a billing account and Firebase services

To programmatically associate a billing account with your project, use the projects.updateBillingInfo method.

To programmatically enable Firebase services for your project, see set up and manage a Firebase project using the Management REST API.

Create a database with gcloud

You can use the gcloud command-line tool to automate database creation in a Bash or PowerShell script. In your script, complete the following steps:

1. Create a new project with gcloud projects create:

   gcloud projects create project-id

2. Activate App Engine with gcloud app create:

   gcloud app create --region=region --project=project-id

   where region is the location of both your App Engine application and your Firestore database. Once set, you cannot change the location. For a full list of supported locations, see App Engine locations.

   App Engine and Firestore support the same locations, but the following App Engine regions map to Firestore multi-regions:

   • us-central (Iowa) creates a Firestore database in the nam5 (United States) multi-region.
   • europe-west (Belgium) creates a Firestore database in the eur3 (Europe) multi-region.

3. Enable the App Engine Admin API with gcloud services enable:

   gcloud services enable appengine.googleapis.com --project=project-id

4. Create a Firestore database with gcloud alpha firestore databases create or gcloud alpha datastore databases create:

   gcloud alpha firestore databases create --project=project-id --region=region

   To create a Firestore in Datastore mode database, use:

   gcloud alpha datastore databases create --project=project-id --region=region

   For region, you must use the same value you used to activate App Engine.

Create a database with Terraform

To provision a Firestore database with Terraform, use the google_firestore_database resource.

For example, the following Terraform configuration file creates a new project and provisions a Firestore database:

firestore.tf

provider "google" {
  credentials = file("credentials-file")
}

resource "google_project" "my_project" {
  name       = "My Project"
  project_id = "project-id"
}

resource "google_project_service" "firestore" {
  project = google_project.my_project.project_id
  service = "firestore.googleapis.com"
}

resource "google_firestore_database" "database" {
  project     = google_project.my_project.project_id
  name        = "(default)"
  location_id = "location"
  type        = "FIRESTORE_NATIVE"

  depends_on = [google_project_service.firestore]
}

Note: To create a Firestore in Datastore mode database, set type to DATASTORE_MODE.

Replace the following:

• credentials-file is the path to your service account key file.
• project-id is your project ID. Project IDs must be unique.
• location is the location of both your Firestore database. Once set, you cannot change the location. For a full list of supported locations, see Firestore locations.

If you wish to use App Engine, use the google_app_engine_application resource instead. Set the database_type to CLOUD_FIRESTORE or CLOUD_DATASTORE_COMPATIBILITY.

provider "google" {
  credentials = file("credentials-file")
}

resource "google_project" "my_project" {
  name = "My Project"
  project_id = "project-id"
}

resource "google_app_engine_application" "app" {
  project     = google_project.my_project.project_id
  location_id = "location"
  database_type = "CLOUD_FIRESTORE"
}

Note: Many App Engine and Firestore location names are the same, but the following App Engine regions map to Firestore multi-regions:

• us-central (Iowa) creates a Firestore database in the nam5 (United States) multi-region.
• europe-west (Belgium) creates a Firestore database in the eur3 (Europe) multi-region.

Furthermore, Firestore is available in some regions that App Engine is not.

Note: To create a Firestore in Datastore mode database, set database_type to CLOUD_DATASTORE_COMPATIBILITY.

Creating indexes in the database

Firestore database can include a single-field index or composite index. You can edit the Terraform configuration file to create an index for your database.

Single-field index

The following example Terraform configuration file creates a single-field index on the name field in the chatrooms collection:

firestore.tf

resource "random_id" "variable"{
  byte_length = 8
}

resource "google_firestore_field" "single-index" {
  project = "project-id"
  database = "(default)"
  collection = "chatrooms_${random_id.variable.hex}"
  field = "name"

  index_config {
    indexes {
        order = "ASCENDING"
        query_scope = "COLLECTION_GROUP"
    }
    indexes {
        array_config = "CONTAINS"
    }
  }

  ttl_config {}
}

• Replace project-id with your project ID. Project IDs must be unique.

Composite index

The following example Terraform configuration file creates a composite index for a combination of the name field and the description field in the chatrooms collection:

firestore.tf

resource "google_firestore_index" "composite-index" {
  project = "project-id"

  collection = "chatrooms"

  fields {
    field_path = "name"
    order      = "ASCENDING"
  }

  fields {
    field_path = "description"
    order      = "DESCENDING"
  }

}

• Replace project-id with your project ID. Project IDs must be unique.