Class Instance (3.46.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
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.
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
Type Description
str The instance name.

node_count

Node count used in requests.

Returns
Type Description
int The number of nodes in the instance's cluster; used to set up the instance's cluster.

processing_units

Processing units used in requests.

Returns
Type Description
int The 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
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.
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
Type Description
Backup a 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
Type Description
Instance A 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
Name Description
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
Type Description
Backup a 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
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,
    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
Name Description
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
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 deleted. 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

Exceptions
Type Description
NotFound if the instance does not exist
Returns
Type Description
google.api_core.operation.Operation an operation instance