As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

Instance API¶

User friendly container for Cloud Spanner Instance.

class google.cloud.spanner_v1.instance.Instance(instance_id, client, configuration_name=None, node_count=None, display_name=None, emulator_host=None, labels=None, processing_units=None)[source]¶

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

backup(backup_id, database='', expire_time=None, version_time=None, encryption_config=None)[source]¶

Factory to create a backup within this instance.

Parameters

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

Return type

Backup

Returns

a backup owned by this instance.

copy()[source]¶

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.

copy_backup(backup_id, source_backup, expire_time=None, encryption_config=None)[source]¶

Factory to create a copy backup within this instance.

Parameters

backup_id (str) – The ID of the backup copy.
source_backup_id – The full path of the source backup to be copied.
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

Return type

Backup

Returns

a copy backup owned by this instance.

create()[source]¶

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: Operation
Returns: an operation instance
Raises: Conflict – if the instance already exists

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, proto_descriptors=None)[source]¶

Factory to create a database within this instance.

Parameters

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.
proto_descriptors (bytes) – (Optional) Proto descriptors used by CREATE/ALTER PROTO BUNDLE statements in ‘ddl_statements’ above.

Return type

Database

Returns

a database owned by this instance.

delete()[source]¶

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()[source]¶

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)[source]¶

Creates an instance from a protobuf.

Parameters

instance_pb (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_backup_operations(filter_='', page_size=None)[source]¶

List backup operations for the instance.

Parameters

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.

Return type

Iterator

Returns

Iterator of Operation resources within the current instance.

list_backups(filter_='', page_size=None)[source]¶

List backups for the instance.

Parameters

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.

Return type

Iterator

Returns

Iterator of Backup resources within the current instance.

list_database_operations(filter_='', page_size=None)[source]¶

List database operations for the instance.

Parameters

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.

Return type

Iterator

Returns

Iterator of Operation resources within the current instance.

list_databases(page_size=None)[source]¶

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

property node_count¶

Node count used in requests.

Return type: int
Returns: The number of nodes in the instance’s cluster; used to set up the instance’s cluster.

property processing_units¶

Processing units used in requests.

Return type: int
Returns: The number of processing units allocated to this instance.

reload()[source]¶

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()[source]¶

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
instance.display_name = 'New display name'
instance.node_count = 5

before calling update().

Return type: google.api_core.operation.Operation
Returns: an operation instance
Raises: NotFound – if the instance does not exist

Instance API¶

google-cloud-spanner

Navigation

Related Topics