Class Instance (3.45.0)

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

Representation of a Cloud Spanner Instance.

We can use a Instance to:

  • reload itself
  • create itself
  • update itself
  • delete itself

Parameters

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

processing_units int

(Optional) The number of processing units allocated to this 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.

labels dict (str -> str) or None

(Optional) User-assigned labels for this instance.

Properties

name

Instance name used in requests.

"projects/{project}/instances/{instance_id}"

Returns
TypeDescription
strThe instance name.

node_count

Node count used in requests.

Returns
TypeDescription
intThe number of nodes in the instance's cluster; used to set up the instance's cluster.

processing_units

Processing units used in requests.

Returns
TypeDescription
intThe number of processing units allocated to this instance.

Methods

backup

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

Factory to create a backup within this instance.

Parameters
NameDescription
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.

version_time datetime.datetime

Optional. The version time that will be used to create the externally consistent copy of the database. If not present, it is the same as the create_time of the backup.

encryption_config CreateBackupEncryptionConfig or dict

(Optional) Encryption configuration for the backup. If a dict is provided, it must be of the same form as the protobuf message CreateBackupEncryptionConfig

Returns
TypeDescription
Backupa backup owned by this instance.

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
TypeDescription
InstanceA copy of the current instance.

copy_backup

copy_backup(backup_id, source_backup, expire_time=None, encryption_config=None)

Factory to create a copy backup within this instance.

Parameters
NameDescription
backup_id str

The ID of the backup copy.

expire_time datetime.datetime

Optional. The expire time that will be used when creating the copy backup. Required if the create method needs to be called.

encryption_config CopyBackupEncryptionConfig or dict

(Optional) Encryption configuration for the backup. If a dict is provided, it must be of the same form as the protobuf message CopyBackupEncryptionConfig

Returns
TypeDescription
Backupa copy backup owned by this 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

Exceptions
TypeDescription
Conflictif the instance already exists
Returns
TypeDescription
google.api_core.operation.Operationan operation instance

database

database(
    database_id,
    ddl_statements=(),
    pool=None,
    logger=None,
    encryption_config=None,
    database_dialect=DatabaseDialect.DATABASE_DIALECT_UNSPECIFIED,
    database_role=None,
    enable_drop_protection=False,
    enable_interceptors_in_tests=False,
)

Factory to create a database within this instance.

Parameters
NameDescription
database_id str

The ID of the database.

ddl_statements list of string

(Optional) DDL statements, excluding the 'CREATE DATABASE' statement.

pool concrete subclass of AbstractSessionPool.

(Optional) session pool to be used by database.

logger logging.Logger

(Optional) a custom logger that is used if log_commit_stats is True to log commit statistics. If not passed, a logger will be created when needed that will log the commit statistics to stdout.

encryption_config EncryptionConfig or RestoreDatabaseEncryptionConfig or dict

(Optional) Encryption configuration for the database. If a dict is provided, it must be of the same form as either of the protobuf messages EncryptionConfig or RestoreDatabaseEncryptionConfig

database_dialect DatabaseDialect

(Optional) database dialect for the database

enable_drop_protection boolean

(Optional) Represents whether the database has drop protection enabled or not.

enable_interceptors_in_tests boolean

(Optional) should only be set to True for tests if the tests want to use interceptors.

Returns
TypeDescription
Databasea 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 deleted. All data in the databases will be permanently deleted.

exists

exists()
Returns
TypeDescription
boolTrue if the instance exists, else false

from_pb

from_pb(instance_pb, client)

Creates an instance from a protobuf.

Parameters
NameDescription
instance_pb google.spanner.v2.spanner_instance_admin_pb2.Instance

A instance protobuf object.

client Client

The client that owns the instance.

Exceptions
TypeDescription
ValueErrorif 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
TypeDescription
InstanceThe instance parsed from the protobuf response.

list_backup_operations

list_backup_operations(filter_="", page_size=None)

List backup operations for the instance.

Parameters
NameDescription
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
TypeDescription
google.api_core.page_iterator.IteratorIterator 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
NameDescription
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
TypeDescription
google.api_core.page_iterator.IteratorIterator of Backup resources within the current instance.

list_database_operations

list_database_operations(filter_="", page_size=None)

List database operations for the instance.

Parameters
NameDescription
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
TypeDescription
google.api_core.page_iterator.IteratorIterator of google.api_core.operation.Operation resources within the current instance.

list_databases

list_databases(page_size=None)
Parameter
NameDescription
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
TypeDescription
google.api._ore.page_iterator.IteratorIterator of Database resources within the current instance.

reload

reload()
Exceptions
TypeDescription
NotFoundif 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

Exceptions
TypeDescription
NotFoundif the instance does not exist
Returns
TypeDescription
google.api_core.operation.Operationan operation instance