Instance API

User friendly container for Cloud Spanner Instance.

class google.cloud.spanner_v1.instance.Instance(instance_id, client, configuration_name=None, node_count=1, display_name=None)

Bases: object

Representation of a Cloud Spanner Instance.

We can use a Instance to:

  • reload() itself

  • create() itself

  • update() itself

  • delete() itself

  • 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()

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()

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.api_core.operation.Operation

  • Returns

    an operation instance

  • Raises

    Conflict – if the instance already exists

database(database_id, ddl_statements=(), pool=None)

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()

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()

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

  • Return type

    bool

  • Returns

    True if the instance exists, else false

classmethod from_pb(instance_pb, client)

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)

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. The maximum number of databases in each page of results from this request. Non-positive values are ignored. Defaults to a sensible value set by the API.

    • page_token (str) – Optional. If present, return the next batch of databases, using the value, which must correspond to the nextPageToken value returned in the previous response. Deprecated: use the pages property of the returned iterator instead of manually passing the token.

  • Return type

    Iterator

  • Returns

    Iterator of Database resources within the current instance.

property 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()

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

  • Raises

    NotFound – if the instance does not exist

update()

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.api_core.operation.Operation

  • Returns

    an operation instance

  • Raises

    NotFound – if the instance does not exist