Last Updated: 2020-07-23

What is Cloud Spanner?

Google Cloud Spanner is a globally distributed, ACID-compliant database that automatically handles replicas, sharding, and transaction processing, so you can quickly scale to meet any usage pattern and ensure success of your products.

Key Features

View all features

What you'll learn

Self-paced environment setup

If you don't already have a Google Account (Gmail or Google Apps), you must create one. Sign-in to Google Cloud Platform console (console.cloud.google.com) and create a new project:

Remember the project ID, a unique name across all Google Cloud projects (the name above has already been taken and will not work for you, sorry!). It will be referred to later in this codelab as PROJECT_ID.

Next, you'll need to enable billing in the Cloud Console in order to use Google Cloud resources.

Running through this codelab shouldn't cost you more than a few dollars, but it could be more if you decide to use more resources or if you leave them running (see "cleanup" section at the end of this document).

New users of Google Cloud Platform are eligible for a $300 free trial.

Authentication

If you haven't previously, please install the gcloud command line tool. Once gcloud is installed, active the Application Default Credentials by running the following command in your terminal:

$ gcloud auth application-default login

Terraform

If you haven't installed Terraform earlier, install Terraform.

Google Cloud Terraform Provider provides four Cloud Spanner resources:

In this codelab, we will create and manage Cloud Spanner instances and databases.

Environment

In your development environment, create a new directory for your Terraform configuration files.

$ mkdir ~/terraform-spanner
$ cd ~/terraform-spanner

Then, create a file named "main.tf" with the following content and replace PROJECT_ID wit h your own Google Cloud project ID:

$ cat >> main.tf <<'EOF'
provider "google" {
  project = "PROJECT_ID"
}
EOF

In this rest of this codelab, we are going to modify this file and apply changes.

Modify the main.tf with the following content to add a new Cloud Spanner instance:

provider "google" {
  project = "PROJECT_ID"
}

resource "google_spanner_instance" "main" {
  config       = "regional-us-central1"
  display_name = "first-terraform-instance"
  num_nodes    = 3
}

Run the following command to apply the changes:

$ terraform apply
# ...
Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes
# ...
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

After the changes are applied, you will be able to see the instance at Google Cloud Console. Please note that regional configuration is not possible to modify after an instance is created.

After creating the instance, we will create a database in the next steps. Modify main.tf with the following contents:

provider "google" {
  project = "PROJECT_ID"
}

resource "google_spanner_instance" "main" {
  config       = "regional-us-central1"
  display_name = "first-terraform-instance"
  num_nodes    = 3
}

resource "google_spanner_database" "database" {
  instance = google_spanner_instance.main.name
  name     = "my-first-database"
}

Again, use the following command to apply the changes:

$ terraform apply
# ...
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

Upon success, my-first-database will be available under the instance:

As noted in the earlier section, not all properties of the instances are modifiable. But you can increase/decrease the number of nodes to adjust the resources used by the instance. The instance created had 3 nodes. By modifying the main.tf file, we are going to increase the number of nodes to 5:

provider "google" {
  project = "PROJECT_ID"
}

resource "google_spanner_instance" "main" {
  config       = "regional-us-central1"
  display_name = "first-terraform-instance"
  num_nodes    = 5
}

resource "google_spanner_database" "database" {
  instance = google_spanner_instance.main.name
  name     = "my-first-database"
}

The next step is to apply the changes:

$ terraform apply
# ...
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

Once successful, the instance will be using 5 nodes.

You can delete a database permanently once you don't need it anymore. Simply, remove the database from main.tf and apply the changes.

provider "google" {
  project = "PROJECT_ID"
}

resource "google_spanner_instance" "main" {
  config       = "regional-us-central1"
  display_name = "first-terraform-instance"
  num_nodes    = 5
}
$ terraform apply
# ...
Apply complete! Resources: 0 added, 0 changed, 1 destroyed.

Once successful, the database will be permanently deleted.

You can delete an instance permanently once you don't need it anymore. Simply, remove the instance from main.tf and apply the changes.

provider "google" {
  project = "PROJECT_ID"
}
$ terraform apply
# ...
Apply complete! Resources: 0 added, 0 changed, 1 destroyed.

Once successful, the instance will be permanently deleted.

You have created, modified and deleted Cloud Spanner resources by using Terraform.

What we've covered

Learn More