Managing Long-Running Operations

This page describes how to manage the lifecycle of a Cloud Spanner long-running operation using operations APIs.

Long-running operations are method calls that may take a substantial amount of time to complete. Cloud Spanner creates long-running operations for several database and instance actions. An example is the method to create a database, projects.instances.databases.create. When projects.instances.databases.create is called, the Cloud Spanner service creates a long-running operation to track the database creation status. Cloud Spanner provides operations APIs that allow you to check the status of long-running operations. You can also list and cancel long-running operations, as well as delete long-running instance operations.

In addition to REST APIs, the following sources generate long-running operations when you create databases and instances, update schema, and update instances:

Manage your Cloud Spanner long-running operations using these methods:

Action Long-running database operations Long-running instance operations
Cancel a long-running operation cancel cancel
Delete a long-running operation Unsupported delete
Get the status of a long-running operation get get
List long-running operations list list

Database operations

The following are long-running database operations.

Get the status of a long-running database operation

Use projects.instances.databases.operations.get to get the status of a long-running database operation.

As an example, this is a response from projects.instances.databases.create:

{
  "name": "projects/[PROJECT_ID]/instances/test-instance/databases/example-db/operations/_auto_1492721321097206",
  "metadata": {
    "@type": "type.googleapis.com/google.spanner.admin.database.v1.CreateDatabaseMetadata",
    "database": "projects/[PROJECT_ID]/instances/test-instance/databases/example-db"
  }
}

The name value at the top of the response shows the Cloud Spanner service created a long-running database operation named projects/[PROJECT_ID]/instances/test-instance/databases/example-db/operations/_auto_1492721321097206.

To get the status of the long-running database operation:

  1. Click projects.instances.databases.operations.get.
  2. For name, enter the long-running database operation name as shown in the response to projects.instances.databases.create or projects.instances.databases.updateDdl. For example:

    projects/[PROJECT_ID]/instances/test-instance/databases/example-db/operations/_auto_1492721321097206
    

    (Use the operation name you received instead of this value.) You can also retrieve the database operation name by listing long-running database operations.

  3. Click Execute and view the response. When an operation is done, the done field will be set to true.

To poll a long-running database operation, repeatedly invoke the projects.instances.databases.operations.get method until the operation is done. Use a backoff between each poll request. For example, poll every 10 seconds.

List long-running database operations

Use projects.instances.databases.operations.list to list long-running database operations.

  1. Click projects.instances.databases.operations.list.
  2. For name, enter:

    projects/[PROJECT_ID]/instances/test-instance/databases/example-db/operations
    
  3. Click Execute. The response contains the long-running database operations.

Cancel a long-running database operation

Use projects.instances.databases.operations.cancel to cancel a long-running instance operation.

  1. Click projects.instances.databases.operations.cancel.
  2. For name, enter the long-running database operation name as shown in the long-running database operation response. For example:

    projects/[PROJECT_ID]/instances/test-instance/databases/example-db/operations/_auto_1492721321097206
    

    (Use the operation name you received instead of this value.) You can also retrieve the database operation name by listing long-running database operations.

  3. Click Execute.

Instance operations

The following are long-running instance operations.

Get the status of a long-running instance operation

Use projects.instances.operations.get to get the status of a long-running instance operation.

As an example, this is a response from projects.instances.create:

{
  "name": "projects/[PROJECT_ID]/instances/test-instance/operations/9af0cf8c1e123a2e",
  "metadata": {
    "@type": "type.googleapis.com/google.spanner.admin.instance.v1.CreateInstanceMetadata",
    "instance": {
      "name": "projects/[PROJECT_ID]/instances/test-instance",
      "config": "projects/[PROJECT_ID]/instanceConfigs/regional-us-central1",
      "displayName": "Test Instance",
      "nodeCount": 1,
      "state": "READY"
    },
    "startTime": "2017-04-24T22:45:41.130854Z"
  }
}

The name value at the top of the response shows the Cloud Spanner service created a long-running instance operation named projects/[PROJECT_ID]/instances/test-instance/operations/9af0cf8c1e123a2e.

To get the status of the long-running instance operation:

  1. Click projects.instances.operations.get.
  2. For name, enter the long-running instance operation name as shown in the response to projects.instances.create or projects.instances.patch. For example:

    projects/[PROJECT_ID]/instances/test-instance/operations/9af0cf8c1e123a2e
    

    (Use the operation name you received instead of this value.) You can also retrieve the instance operation name by listing long-running instance operations.

  3. Click Execute and view the response. When an operation is done, the done field will be set to true.

To poll a long-running instance operation, repeatedly invoke the projects.instances.operations.get method until the operation is done. Use a backoff between each poll request. For example, poll every 10 seconds.

List long-running instance operations

Use projects.instances.operations.list to list long-running instance operations.

  1. Click projects.instances.operations.list.
  2. For name, enter:

    projects/[PROJECT_ID]/instances/test-instance/operations
    
  3. Click Execute. The response contains the long-running instance operations.

Cancel a long-running instance operation

Use projects.instances.operations.cancel to cancel a long-running instance operation.

  1. Click projects.instances.operations.cancel.
  2. For name, enter the long-running instance operation name as shown in the long-running instance operation response. For example:

    projects/[PROJECT_ID]/instances/test-instance/operations/9af0cf8c1e123a2e
    

    (Use the operation name you received instead of this value.) You can also retrieve the instance operation name by listing long-running instance operations.

  3. Click Execute.

Delete a long-running instance operation

Use projects.instances.operations.delete to delete a long-running instance operation.

  1. Click projects.instances.operations.delete.
  2. For name, enter the long-running instance operation name as shown in the long-running instance operation response. For example:

    projects/[PROJECT_ID]/instances/test-instance/operations/9af0cf8c1e123a2e
    

    (Use the operation name you received instead of this value.) You can also retrieve the instance operation name by listing long-running instance operations.

  3. Click Execute.

Send feedback about...

Cloud Spanner Documentation