Cloud Spanner for global distribution in GCP - Commands & Configuration

Introduction

Cloud Spanner is a database service that stores data across the world. It helps keep your data safe and available everywhere, so your app works fast no matter where users are.

When you want your app's data to be available quickly to users in different countries.

When you need a database that can handle lots of users at the same time without slowing down.

When you want to avoid losing data even if one data center has a problem.

When you want to manage your database easily without worrying about servers.

When you need strong consistency so all users see the same data instantly.

Config File - instance-config.yaml

instance-config.yaml

apiVersion: spanner.cnrm.cloud.google.com/v1beta1
kind: SpannerInstance
metadata:
  name: global-spanner-instance
spec:
  config: regional-us-central1
  displayName: "Global Spanner Instance"
  nodes: 3
  labels:
    environment: production
---
apiVersion: spanner.cnrm.cloud.google.com/v1beta1
kind: SpannerDatabase
metadata:
  name: global-database
spec:
  instanceRef:
    name: global-spanner-instance
  ddlStatements:
    - "CREATE TABLE Users (UserId STRING(36) NOT NULL, UserName STRING(1024)) PRIMARY KEY (UserId)"
    - "CREATE TABLE Orders (OrderId STRING(36) NOT NULL, UserId STRING(36), OrderDate TIMESTAMP) PRIMARY KEY (OrderId)"

This file creates a Cloud Spanner instance named global-spanner-instance in the us-central1 region with 3 nodes for capacity. It also creates a database called global-database inside that instance. The database has two tables: Users and Orders. The tables have primary keys defined to organize data efficiently.

The config field sets the instance location. The nodes field controls how much power the instance has. Labels help identify the environment.

Commands

This command creates a Cloud Spanner instance named 'global-spanner-instance' in the us-central1 region with 3 nodes. Nodes determine the capacity and performance of the instance.

Terminal

gcloud spanner instances create global-spanner-instance --config=regional-us-central1 --description="Global Spanner Instance" --nodes=3

Expected Output

Created instance [global-spanner-instance].

→

--config - Sets the geographic location of the instance.

→

--nodes - Specifies the number of nodes for capacity.

This command creates a database named 'global-database' inside the 'global-spanner-instance' instance. It also creates two tables: Users and Orders with their columns and primary keys.

Terminal

gcloud spanner databases create global-database --instance=global-spanner-instance --ddl='CREATE TABLE Users (UserId STRING(36) NOT NULL, UserName STRING(1024)) PRIMARY KEY (UserId)' --ddl='CREATE TABLE Orders (OrderId STRING(36) NOT NULL, UserId STRING(36), OrderDate TIMESTAMP) PRIMARY KEY (OrderId)'

Expected Output

Created database [global-database] on instance [global-spanner-instance].

→

--instance - Specifies the instance where the database will be created.

→

--ddl - Defines the schema for tables in the database.

This command shows details about the 'global-spanner-instance' instance, including its configuration, nodes, and state. It helps verify the instance is created correctly.

Terminal

gcloud spanner instances describe global-spanner-instance

Expected Output

name: projects/my-project/instances/global-spanner-instance

config: projects/my-project/instanceConfigs/regional-us-central1

description: Global Spanner Instance

nodeCount: 3

state: READY

This command lists all databases inside the 'global-spanner-instance' instance. It confirms that 'global-database' exists and is ready to use.

Terminal

gcloud spanner databases list --instance=global-spanner-instance

Expected Output

NAME

-----

global-database

→

--instance - Specifies the instance to list databases from.

Key Concept

If you remember nothing else from this pattern, remember: Cloud Spanner lets you store and access your data quickly and safely across the world by creating instances and databases with the right location and capacity.

Common Mistakes

Creating an instance without specifying the correct config region.

The instance may be created in a default or undesired location, causing higher latency for users.

Always use the --config flag with the region closest to your users or your app servers.

Not defining primary keys in table creation DDL statements.

Cloud Spanner requires primary keys for tables; missing them causes errors.

Include PRIMARY KEY clauses in every CREATE TABLE statement.

Trying to create a database before the instance is ready.

The database creation will fail because the instance does not exist or is not ready.

Wait for the instance creation to complete and verify with describe command before creating databases.

Summary

Create a Cloud Spanner instance with a specific region and number of nodes to set capacity.

Create a database inside the instance with tables and primary keys using DDL statements.

Verify the instance and database exist and are ready using describe and list commands.