Instance Admin API#

After creating a Client, you can interact with individual instances for a project.

Instance Configurations#

Each instance within a project maps to a named “instance configuration”, specifying the location and other parameters for a set of instances. These configurations are defined by the server, and cannot be changed.

To list of all instance configurations available to your project, use the list_instance_configs() method of the client:

configs, token = client.list_instance_configs()

To fetch a single instance configuration, use the get_instance_configuration() method of the client:

config = client.get_instance_configuration('config-name')

List Instances#

If you want a comprehensive list of all existing instances, use the list_instances() method of the client:

instances, token = client.list_instances()

Instance Factory#

To create a Instance object:

config = configs[0]
instance = client.instance(instance_id,
                           configuration_name=config.name,
                           node_count=10,
                           display_name='My Instance')
  • configuration_name is the name of the instance configuration to which the instance will be bound. It must be one of the names configured for your project, discoverable via google.cloud.spanner.client.Client.list_instance_configs().
  • node_count is a postitive integral count of the number of nodes used by the instance. More nodes allows for higher performance, but at a higher billing cost.
  • display_name is optional. When not provided, display_name defaults to the instance_id value.

You can also use Client.instance() to create a local wrapper for an instance that has already been created:

instance = client.instance(existing_instance_id)
instance.reload()

Create a new Instance#

After creating the instance object, use its create() method to trigger its creation on the server:

instance.display_name = 'My very own instance'
operation = instance.create()

Note

Creating an instance triggers a “long-running operation” and returns an google.cloud.spanner.instance.Operation object. See Check on Current Instance Operation for polling to find out if the operation is completed.

Refresh metadata for an existing Instance#

After creating the instance object, reload its server-side configuration using its reload() method:

instance.reload()

This will load display_name, config_name, and node_count for the existing instance object from the back-end.

Update an existing Instance#

After creating the instance object, you can update its metadata via its update() method:

client.display_name = 'New display_name'
operation = instance.update()

Note

Update an instance triggers a “long-running operation” and returns a google.cloud.spanner.instance.Operation object. See Check on Current Instance Operation for polling to find out if the operation is completed.

Delete an existing Instance#

Delete an instance using its delete() method:

instance.delete()

Check on Current Instance Operation#

The create() and update() methods of instance object trigger long-running operations on the server, and return instances of the Operation class.

You can check if a long-running operation has finished by using its finished() method:

>>> operation = instance.create()
>>> operation.finished()
True

Note

Once an Operation object has returned True from its finished() method, the object should not be re-used. Subsequent calls to finished() will result in an :exc`ValueError` being raised.

Next Step#

Now we go down the hierarchy from Instance to a Database.

Next, learn about the Database Admin API.