Instance API

User friendly container for Cloud Spanner Instance.

class google.cloud.spanner_v1.instance.Instance(instance_id, client, configuration_name=None, node_count=1, display_name=None, emulator_host=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.

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

backup(backup_id, database='', expire_time=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.

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)

Factory to create a database within this instance.

  • Parameters

    • database_id (str) – The ID of the instance.

    • ddl_statements (list of string) – (Optional) DDL statements, excluding the ‘CREATE DATABSE’ statement.

    • pool (concrete subclass of AbstractSessionPool.) – (Optional) session pool to be used by database.

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

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 and node_count. To change those

values before updating, set them via

instance.display_name = 'New display name'
instance.node_count = 5

before calling update().

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025年12月16日 UTC.