# Class Instance (3.68.0)

3.68.0 (latest) 3.67.0 3.66.0 3.65.0 3.64.0 3.63.0 3.62.0 3.61.0 3.60.0 3.59.0 3.58.0 3.57.0 3.56.0 3.55.0 3.54.0 3.53.0 3.52.0 3.51.0 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,
        experimental_host=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` | `https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_v1.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. |
| `experimental_host` | `str` (Deprecated) The instance type and host are now managed by the Client. |

## Properties

### name

Instance name used in requests.

<br />

> [!NOTE]
> **Note:** This property will not change if `instance_id` does not, but the return value is not cached.

`"projects/{project}/instances/{instance_id}"`

<br />

| **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` | `https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_v1.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` | `` https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_admin_database_v1.types.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](https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_admin_database_v1.types.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** |
| `https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_v1.instance.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` | `` https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_admin_database_v1.types.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](https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_admin_database_v1.types.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]
> **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,
        database_role=None,
        enable_drop_protection=False,
        enable_interceptors_in_tests=False,
        proto_descriptors=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 https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_v1.pool.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` | `` https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_admin_database_v1.types.EncryptionConfig or https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_admin_database_v1.types.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](https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_admin_database_v1.types.EncryptionConfig) or [RestoreDatabaseEncryptionConfig](https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_admin_database_v1.types.RestoreDatabaseEncryptionConfig) |
| `database_dialect` | `https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_admin_database_v1.types.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. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_v1.database.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` | `https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_v1.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](https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_admin_database_v1.types.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](https://docs.cloud.google.com/python/docs/reference/spanner/latest/google.cloud.spanner_admin_database_v1.types.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]
> **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 |