Instance Admin Usage

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 iterate over all instance configurations available to your project, use the list_instance_configs() method of the client:

for config in client.list_instance_configs():
    # `config` is an instance of `InstanceConfig`

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

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

Each of these methods provide InstanceConfig objects.

List Instances

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

for instance in client.list_instances():
    # `instance` is an instance of `Instance`

This iterator yields Instance objects.

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 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_v1.instance.Operation object. See Resolve 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_v1.instance.Operation object. See Resolve 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()

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

If you want to block on the completion of those operations, use the result method on the returned objects:

>>> operation = instance.create()
>>> result = operation.result()

This method will raise an exception if the operation fails.

Next Step

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

Next, learn about the Database Admin Usage.