Instance API#

User friendly container for Cloud Spanner Instance.

class google.cloud.spanner.instance.Instance(instance_id, client, configuration_name=None, node_count=1, display_name=None)[source]#

Bases: object

Representation of a Cloud Spanner Instance.

We can use a Instance to:

Parameters:
  • instance_id (str) – The ID of the instance.
  • client (Client) – The client that owns the instance. Provides authorization and a project ID.
  • configuration_name (str) – Name of the instance configuration defining how the instance will be created. Required for instances which do not yet exist.
  • node_count (int) – (Optional) Number of nodes allocated to the instance.
  • display_name (str) – (Optional) The display name for the instance in the Cloud Console UI. (Must be between 4 and 30 characters.) If this value is not set in the constructor, will fall back to the instance ID.
copy()[source]#

Make a copy of this instance.

Copies the local data stored as simple types and copies the client attached to this instance.

Return type:Instance
Returns:A copy of the current instance.
create()[source]#

Create this instance.

See: https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.instance.v1#google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance

Note

Uses the project and instance_id on the current Instance in addition to the display_name. To change them before creating, reset the values via

instance.display_name = 'New display name'
instance.instance_id = 'i-changed-my-mind'

before calling create().

Return type:google.cloud.operation.Operation
Returns:an operation instance
database(database_id, ddl_statements=(), pool=None)[source]#

Factory to create a database within this instance.

Parameters:
  • database_id (str) – The ID of the instance.
  • ddl_statements (list of string) – (Optional) DDL statements, excluding the ‘CREATE DATABSE’ statement.
  • pool (concrete subclass of AbstractSessionPool.) – (Optional) session pool to be used by database.
Return type:

Database

Returns:

a database owned by this instance.

delete()[source]#

Mark an instance and all of its databases for permanent deletion.

See: https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.instance.v1#google.spanner.admin.instance.v1.InstanceAdmin.DeleteInstance

Immediately upon completion of the request:

  • Billing will cease for all of the instance’s reserved resources.

Soon afterward:

  • The instance and all databases within the instance will be deleteed. All data in the databases will be permanently deleted.
exists()[source]#

Test whether this instance exists.

See: https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.instance.v1#google.spanner.admin.instance.v1.InstanceAdmin.GetInstanceConfig

classmethod from_pb(instance_pb, client)[source]#

Creates an instance from a protobuf.

Parameters:
  • instance_pb (google.spanner.v2.spanner_instance_admin_pb2.Instance) – A instance protobuf object.
  • client (Client) – The client that owns the instance.
Return type:

Instance

Returns:

The instance parsed from the protobuf response.

Raises:

ValueError if the instance name does not match projects/{project}/instances/{instance_id} or if the parsed project ID does not match the project ID on the client.

list_databases(page_size=None, page_token=None)[source]#

List databases for the instance.

See: https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases

Parameters:
  • page_size (int) – (Optional) Maximum number of results to return.
  • page_token (str) – (Optional) Token for fetching next page of results.
Return type:

Iterator

Returns:

Iterator of Database resources within the current instance.

name#

Instance name used in requests.

Note

This property will not change if instance_id does not, but the return value is not cached.

The instance name is of the form

"projects/{project}/instances/{instance_id}"
Return type:str
Returns:The instance name.
reload()[source]#

Reload the metadata for this instance.

See: https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.instance.v1#google.spanner.admin.instance.v1.InstanceAdmin.GetInstanceConfig

update()[source]#

Update this instance.

See: https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.instance.v1#google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance

Note

Updates the display_name and node_count. To change those values before updating, set them via

  instance.display_name = 'New display name'
  instance.node_count = 5

before calling :meth:`update`.
Return type:google.cloud.operation.Operation
Returns:an operation instance