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)

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*]( https://python.readthedocs.io/en/latest/library/constants.html#None )) – (Optional) User-assigned labels for this instance.

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

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()

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.

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

 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)

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

• Return type

  Database

• Returns

  a database owned by this instance.

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()

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)

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)

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)

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)

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)

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()

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()

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