Class Instance (3.25.0)

Version 3.25.0

• 3.51.0 (latest)
• 3.50.1
• 3.46.0
• 3.45.0
• 3.44.0
• 3.43.0
• 3.42.0
• 3.41.0
• 3.40.1
• 3.39.0
• 3.38.0
• 3.37.0
• 3.36.0
• 3.35.1
• 3.34.0
• 3.33.0
• 3.32.0
• 3.31.0
• 3.30.0
• 3.29.0
• 3.28.0
• 3.27.1
• 3.26.0
• 3.25.0
• 3.24.0
• 3.23.0
• 3.22.2
• 3.21.0
• 3.20.0
• 3.19.0
• 3.18.0
• 3.17.0
• 3.16.0
• 3.15.1
• 3.14.1
• 3.13.0
• 3.12.1
• 3.11.1
• 3.10.0
• 3.9.0
• 3.8.0
• 3.7.0
• 3.6.0
• 3.5.0
• 3.4.0
• 3.3.0
• 3.2.0
• 3.1.0
• 3.0.0
• 2.1.1
• 2.0.0
• 1.19.3
• 1.18.0
• 1.17.1
• 1.16.0
• 1.15.1
• 1.14.0
• 1.13.0
• 1.12.0
• 1.11.0
• 1.10.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.

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

"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

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, logger=None, encryption_config=None, database_dialect=<DatabaseDialect.DATABASE_DIALECT_UNSPECIFIED: 0>, database_role=None)

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

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

Note: Updates the display_name, node_count, processing_units and labels. To change those values before updating, set them via .. code:: python instance.display_name = 'New display name' instance.node_count = 5

Exceptions
Type	Description
NotFound	if the instance does not exist

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