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 instance, database, and backup actions. An example is the method to restore a database, projects.instances.databases.restore. When you restore a database, the Cloud Spanner service creates a long-running operation to track restore progress. 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.

This page describe how to manage long-running operations with the REST API. But, you can also manage long-running operations with:

• Cloud Spanner client libraries
• The gcloud command-line tool
• The Spanner page in the Google Cloud Console

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

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

Database operations

The following are long-running database operations.

• projects.instances.databases.create
• projects.instances.databases.restore
• projects.instances.databases.updateDdl
• projects.instances.databaseOperations.list

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 database 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.

Backup operations

The following are long-running backup operations.

• projects.instances.backups.create

Get the status of a long-running backup operation

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

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

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

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

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

1. Click projects.instances.backups.operations.get.

2. For name, enter the long-running backup operation name as shown in the response to projects.instances.backups.create. For example:

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

   (Use the operation name you received instead of this value.) You can also retrieve the backup operation name by listing long-running backup 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 backup operation, repeatedly invoke the projects.instances.backups.operations.get method until the operation is done. Use a backoff between each poll request. For example, poll every 10 seconds.

List long-running backup operations

Use projects.instances.backups.operations.list to list the operations on a single backup or projects.instances.backupOperations.list to list all backup operations in the instance.

1. Click projects.instances.backups.operations.list.

2. For name, enter:

   projects/[PROJECT_ID]/instances/test-instance/backups/example-db-backup-4/operations
   

3. Click Execute. The response contains the long-running operations.

Cancel a long-running backup operation

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

1. Click projects.instances.backups.operations.cancel.

2. For name, enter the long-running backup operation name as shown in the long-running backup operation response. For example:

   projects/[PROJECT_ID]/instances/test-instance/backups/example-db-backup-4/operations/_auto_1492721321097206
   

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

3. Click Execute.

Instance operations

The following are long-running instance operations.

• projects.instances.create
• projects.instances.patch

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.