Class Instance (2.1.0)

Instance(
    instance_id,
    client,
    configuration_name=None,
    node_count=1,
    display_name=None,
    emulator_host=None,
)

Representation of a Cloud Spanner Instance.

We can use a Instance to:

reload itself
create itself
update itself
delete itself

Parameters

Name	Description
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.

Inheritance

builtins.object > Instance

Properties

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}"``

Returns

Type	Description
str	The instance name.

Methods

backup

backup(backup_id, database="", expire_time=None)

Factory to create a backup within this instance.

Parameters

Name	Description
backup_id	`str` The ID of the backup.
database	`Database` Optional. The database that will be used when creating the backup. Required if the create method needs to be called.
expire_time	`datetime.datetime` Optional. The expire time that will be used when creating the backup. Required if the create method needs to be called.

copy

copy()

Make a copy of this instance.

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

Returns

Type	Description
Instance	A copy of the current instance.

create

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

.. code:: python

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

before calling create.

Exceptions

Type	Description
Conflict	if the instance already exists

Returns

Type	Description
`google.api_core.operation.Operation`	an operation instance

database

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

Factory to create a database within this instance.

Parameters

Name	Description
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.

Returns

Type	Description
Database	a database owned by this instance.

delete

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

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

Returns

Type	Description
bool	True if the instance exists, else false

from_pb

from_pb(instance_pb, client)

Creates an instance from a protobuf.

Parameters

Name	Description
instance_pb	`google.spanner.v2.spanner_instance_admin_pb2.Instance` A instance protobuf object.
client	`Client` The client that owns the instance.

Exceptions

Type	Description
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.

Returns

Type	Description
`Instance`	The instance parsed from the protobuf response.

list_backup_operations

list_backup_operations(filter_="", page_size=None)

List backup operations for the instance.

Parameters

Name	Description
filter_	`str` Optional. A string specifying a filter for which backup operations to list.
page_size	`int` Optional. The maximum number of operations in each page of results from this request. Non-positive values are ignored. Defaults to a sensible value set by the API.

Returns

Type	Description
`google.api_core.page_iterator.Iterator`	Iterator of `google.api_core.operation.Operation` resources within the current instance.

list_backups

list_backups(filter_="", page_size=None)

List backups for the instance.

Parameters

Name	Description
filter_	`str` Optional. A string specifying a filter for which backups to list.
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.

Returns

Type	Description
`google.api_core.page_iterator.Iterator`	Iterator of Backup resources within the current instance.

list_database_operations

list_database_operations(filter_="", page_size=None)

List database operations for the instance.

Parameters

Name	Description
filter_	`str` Optional. A string specifying a filter for which database operations to list.
page_size	`int` Optional. The maximum number of operations in each page of results from this request. Non-positive values are ignored. Defaults to a sensible value set by the API.

Returns

Type	Description
`google.api_core.page_iterator.Iterator`	Iterator of `google.api_core.operation.Operation` resources within the current instance.

list_databases

list_databases(page_size=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

Parameter

Name	Description
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.

Returns

Type	Description
`google.api._ore.page_iterator.Iterator`	Iterator of Database resources within the current instance.

reload

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

Exceptions

Type	Description
NotFound	if the instance does not exist

update

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

.. code:: python

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

before calling update.

Exceptions

Type	Description
NotFound	if the instance does not exist

Returns

Type	Description
`google.api_core.operation.Operation`	an operation instance