gcloud spanner

The gcloud command-line tool enables you to interact with Cloud Spanner. You use the gcloud spanner command to interact with Cloud Spanner.

If you haven't already set up your environment to use Cloud Spanner, follow the Set up steps.

This page describes common gcloud spanner commands. You can also get command-line help by invoking a command with a --help argument. For example:

gcloud spanner instances create --help

SYNOPSIS
    gcloud spanner instances create INSTANCE --config=CONFIG
        --description=DESCRIPTION --nodes=NODES [--async] [GLOBAL-FLAG ...]

DESCRIPTION
    Cloud Spanner instances create command.

...

This page uses several variables which you should replace with values from your Cloud Spanner project.

• PROJECT_ID: project ID
• INSTANCE_ID: instance ID
• NODE_COUNT: number of nodes in an instance
• DATABASE_ID: database ID
• SQL_STATEMENT: SQL statement
• TABLE_NAME: table name
• COL_NAME: column name
• COL_VALUE: value for a column
• KEY_VALUE: value for a primary key column
• SESSION_ID: session ID
• POLICY_FILE: filename of a JSON or YAML policy file

For the complete gcloud spanner reference, see gcloud spanner.

Set a default project

If you haven't already done so, set the ID of a Google Cloud Platform project as the default project for the gcloud command-line tool:

gcloud config set project PROJECT_ID

If you don't set the default project, you must pass --project PROJECT_ID to each of the commands below as the first argument to gcloud spanner. For example:

gcloud spanner --project=PROJECT_ID instance-configs list

Instances and instance configurations

A Cloud Spanner instance is an allocation of resources that are used by Cloud Spanner databases. To create an instance, you must select an instance configuration, which is like a blueprint for your instance that defines the geographic placement and replication of your Cloud Spanner data.

List instance configurations

To see the set of instance configurations that are available for your project:

gcloud spanner instance-configs list

You should see a list of regional and multi-region configurations.

Regional configurations distribute data in a single region, while multi-region configurations distribute data geographically across multiple regions. Read more about these in Instances.

Create instances

After you've selected an instance configuration that meets your application's needs, the next step is to choose the number of nodes to use when creating your instance. The number of nodes corresponds to the amount of resources that are available to the databases in your instance. Note that regional instances are always resilient to single zone outages, regardless of the number of nodes they contain. For more information about regions and zones, refer to Geography and regions.

To create an instance named test-instance with the display name My Instance using the regional instance configuration regional-us-central1 with 5 nodes:

gcloud spanner instances create test-instance --config=regional-us-central1 \
    --description="My Instance" --nodes=5

In the command above, the instance name is set to test-instance and --description sets the display name of the instance. Both of these values must be unique within a Google Cloud Platform project.

Note: Use the instance ID, not the display name, when referring to an instance in gcloud spanner commands.

Set the default instance

You can set the default instance that Cloud Spanner uses when you have not specified an instance in your command. To set the default instance:

gcloud config set spanner/instance INSTANCE_ID

List instances

To list all the live instances and their configurations (e.g., node count, state) in a project:

gcloud spanner instances list

List a specific instance

To get the configuration of a specific instance:

gcloud spanner instances describe INSTANCE_ID

Update instances

You can update only the display name and the node count of an existing instance. To update the number of nodes in an instance:

gcloud spanner instances update INSTANCE_ID --nodes=NODE_COUNT

You can find the existing set of properties using gcloud spanner instances list or gcloud spanner instances describe INSTANCE_ID.

Delete instances

To delete an existing instance:

gcloud spanner instances delete INSTANCE_ID

Note that deleting an instance also drops all of the databases in that instance. Deleting an instance is not reversible.

Create and manage databases

Create databases

To use Cloud Spanner's read and write APIs, you must create a database. You can create multiple databases in an instance.

To create a database with the ID DATABASE_ID in the instance INSTANCE_ID:

gcloud spanner databases create DATABASE_ID --instance=INSTANCE_ID

List databases

To list the databases in an instance:

gcloud spanner databases list --instance=INSTANCE_ID

Delete databases

To delete the database DATABASE_ID in the instance INSTANCE_ID:

gcloud spanner databases delete DATABASE_ID --instance=INSTANCE_ID

Note: This operation is irreversible.

Update databases

You can modify the schema of an existing database. For example, to create a table named MyTable:

gcloud spanner databases ddl update example-db --instance=test-instance \
    --ddl='CREATE TABLE MyTable ( MyKey INT64, MyValue STRING(MAX) ) PRIMARY KEY (MyKey)'

Refer to Data Definition Language for the schema syntax.

Execute SQL statements

To execute a SQL SELECT statement on the command line, use the following syntax:

gcloud spanner databases execute-sql DATABASE_ID --instance=INSTANCE_ID \
    --sql=SQL_STATEMENT

For example, to execute a SQL SELECT statement:

gcloud spanner databases execute-sql example-db --instance=test-instance \
    --sql='SELECT * FROM MyTable WHERE MyKey = 1'

For the Cloud Spanner SQL reference, see Query syntax.

Manage IAM policies

You can use the gcloud tool to manage IAM policies for Cloud Spanner instances and databases.

An IAM policy is a collection of statements that define who has what access to a resource in Google Cloud Platform.

• See Cloud IAM policies to learn more about Cloud IAM policies.

• See Access Control for Spanner to learn more about managing permissions for Cloud Spanner resources.

Note: Use the instance ID or database ID when referring to an instance or database in gcloud spanner commands. Do not use the display name.

Get IAM policies

Instance

To get the IAM policy for an instance:

gcloud spanner instances get-iam-policy INSTANCE_ID

Database

To get the IAM policy for a database:

gcloud spanner databases get-iam-policy DATABASE_ID --instance=INSTANCE_ID

Set IAM policies

To set the IAM policy for a resource, define the policy in a JSON or YAML file and reference that file in your set-iam-policy command. If your resource already has an IAM policy, this command will replace the entire policy with the policy in your policy file. For help working with IAM policy files, see Cloud IAM policies.

Once you set your IAM policy, you can update it by adding or removing IAM policy bindings. You do not need to run set-iam-policy to update your policy.

Instance

To set an IAM policy for an instance:

gcloud spanner instances set-iam-policy INSTANCE_ID POLICY_FILE

For example, this command sets the IAM policy defined in myPolicy.json:

gcloud spanner instances set-iam-policy test-instance myPolicy.json

Database

To set an IAM policy for the database DATABASE_ID in the instance INSTANCE_ID:

gcloud spanner databases set-iam-policy DATABASE_ID --instance=INSTANCE_ID POLICY_FILE

For example, this command sets the IAM policy defined in myPolicy.json:

gcloud spanner databases set-iam-policy example-db --instance=test-instance myPolicy.json

Add IAM policy bindings

Adding an IAM policy binding updates your IAM policy by granting permissions to a specific user, group, or service. Each IAM policy binding identifies a member (such as a Google account) and grants that member a bundle of permissions called a role (such as databaseAdmin). See Access control for Cloud Spanner for a list of roles that control access to Cloud Spanner resources.

The sample commands below grant databaseAdmin permissions to [e-mail]. They add a policy binding that grants the databaseAdmin role to the Google account associated with [e-mail].

Instance

You can add a policy binding to an instance. For example, to grant permissions to an account:

gcloud spanner instances add-iam-policy-binding test-instance --member="user:[e-mail]" \
    --role="roles/spanner.databaseAdmin"

Database

You can add a policy binding to a database. For example, to grant permissions to an account:

gcloud spanner databases add-iam-policy-binding example-db --instance=test-instance \
    --member="user:[e-mail]" --role="roles/spanner.databaseAdmin"

Remove IAM policy bindings

Removing an IAM policy binding removes a set of permissions from the IAM policy used by a resource.

Each IAM policy binding identifies a member (such as a Google account) and grants that member a bundle of permissions called a role (such as databaseAdmin). Removing a binding revokes its bundle of permissions from the member identified in the binding. See Access control for Cloud Spanner for a list of roles that control access to Cloud Spanner resources.

The sample commands below revoke databaseAdmin permissions from [e-mail]. In other words, these commands update the IAM policy to remove the policy binding that grants the databaseAdmin role to the Google account associated with [e-mail]. Note that this only affects permissions for the resource that uses this particular IAM policy.

Instance

You can remove a policy binding from an instance. For example, to remove permissions from an account:

gcloud spanner instances remove-iam-policy-binding test-instance \
    --member="user:[e-mail]" --role="roles/spanner.databaseAdmin"

Database

You can remove a policy binding from a database. For example, to remove permissions from an account:

gcloud spanner databases remove-iam-policy-binding example-db --instance=test-instance \
    --member="user:[e-mail]" --role="roles/spanner.databaseAdmin"

Note: Removing an IAM policy binding for a specific resource does not necessarily remove all access for the affected member. The member might have an additional role that grants a different or overlapping set of permissions. This role might be in the policy used by another resource, or set at the project level.

Manage sessions

If you are creating a client library or using the REST API, it can be useful to know how many active sessions you have. See Sessions to learn more.

List all active sessions

To list all active sessions for a database:

gcloud spanner databases sessions list --database=DATABASE_ID --instance=INSTANCE_ID

Delete session

To delete a session:

gcloud spanner databases sessions delete SESSION_ID --database=DATABASE_ID --instance=INSTANCE_ID

What's next

Learn how to insert, update, and delete rows in a table using the gcloud command-line tool.