Cloud Spanner Client - Class Instance (1.60.0)

Reference documentation and code samples for the Cloud Spanner Client class Instance.

Represents a Cloud Spanner instance

Example:

use Google\Cloud\Spanner\SpannerClient;

$spanner = new SpannerClient();

$instance = $spanner->instance('my-instance');

Methods

__construct

Create an object representing a Cloud Spanner instance.

Parameters
Name	Description
`connection`	`Google\Cloud\Spanner\Connection\ConnectionInterface` The connection to the Cloud Spanner Admin API.
`lroConnection`	`Google\Cloud\Core\LongRunning\LongRunningConnectionInterface` An implementation mapping to methods which handle LRO resolution in the service.
`lroCallables`	`array`
`projectId`	`string` The project ID.
`name`	`string` The instance name or ID.
`returnInt64AsObject`	`bool` [optional] If true, 64 bit integers will be returned as a {@see \Google\Cloud\Spanner\Google\Cloud\Core\Int64} object for 32 bit platform compatibility. Defaults to false.
`info`	`array` [optional] A representation of the instance object.

name

Return the instance name.

Example:

$name = $instance->name();

Returns
Type	Description
`string`

info

Return the service representation of the instance.

This method may require a service call.

Example:

$info = $instance->info();
echo $info['nodeCount'];

Parameters
Name	Description
`options`	`array` Configuration options
`↳ fieldMask`	`string\|string[]` One or a list of `Instance` fields that should be returned. Eligible values are: `name`, `displayName`, `endpointUris`, `labels`, `config`, `nodeCount`, `state`. If absent, all fields are returned. Note: This parameter will only apply when service call is required (`info` values are not present).

Returns
Type	Description
`array`

exists

Check if the instance exists.

This method requires a service call.

Example:

if ($instance->exists()) {
   echo 'Instance exists!';
}

Parameter
Name	Description
`options`	`array` [optional] Configuration options.

Returns
Type	Description
`bool`

reload

Fetch a fresh representation of the instance from the service.

Example:

$info = $instance->reload();

Parameters
Name	Description
`options`	`array` Configuration options
`↳ fieldMask`	`string\|string[]` One or a list of `Instance` fields that should be returned. Eligible values are: `name`, `displayName`, `endpointUris`, `labels`, `config`, `nodeCount`, `state`. If absent, all fields are returned.

Returns
Type	Description
`array`

create

Create a new instance.

Example:

$operation = $instance->create($configuration);

Parameters
Name	Description
`config`	`Google\Cloud\Spanner\InstanceConfiguration` The configuration to use
`options`	`array` Configuration options
`↳ displayName`	`string` Defaults to the value of $name.
`↳ nodeCount`	`int` Defaults to `1`.
`↳ processingUnits`	`int` An alternative measurement to `nodeCount` that allows smaller increments.
`↳ labels`	`array` For more information, see Using labels to organize Google Cloud Platform resources.

Returns
Type	Description
`Google\Cloud\Core\LongRunning\LongRunningOperation<\google\cloud\spanner\instance>`

state

Return the instance state.

When instances are created or updated, they may take some time before they are ready for use. This method allows for checking whether an instance is ready. Note that this value is cached within the class instance, so if you are polling it, first call Google\Cloud\Spanner\Google\Cloud\Spanner\Instance::reload() to refresh the cached value

Example:

if ($instance->state() === Instance::STATE_READY) {
    echo 'Instance is ready!';
}

Parameter
Name	Description
`options`	`array` [optional] Configuration options.

Returns
Type	Description
`int\|null`

update

Update the instance

Example:

$instance->update([
    'displayName' => 'My Instance',
    'nodeCount' => 4
]);

Parameters
Name	Description
`options`	`array` Configuration options
`↳ displayName`	`string` The descriptive name for this instance as it appears in UIs. Defaults to the value of $name.
`↳ nodeCount`	`int` The number of nodes allocated to this instance. Defaults to `1`.
`↳ processingUnits`	`int` An alternative measurement to `nodeCount` that allows smaller increments.
`↳ labels`	`array` For more information, see Using labels to organize Google Cloud Platform resources.

Returns
Type	Description
`Google\Cloud\Core\LongRunning\LongRunningOperation`

delete

Delete the instance, any databases in the instance, and all data.

Example:

$instance->delete();

Parameter
Name	Description
`options`	`array` [optional] Configuration options.

Returns
Type	Description
`void`

createDatabase

Create a Database

Example:

$operation = $instance->createDatabase('my-database');

Parameters
Name	Description
`name`	`string` The database name.
`options`	`array` Configuration Options
`↳ statements`	`array` Additional DDL statements.
`↳ sessionPool`	`SessionPoolInterface` A pool used to manage sessions.

Returns
Type	Description
`Google\Cloud\Core\LongRunning\LongRunningOperation<\google\cloud\spanner\database>`

createDatabaseFromBackup

Create a database from a backup.

Example:

$operation = $instance->createDatabaseFromBackup('my-new-database', $backup);

Parameters
Name	Description
`name`	`string` The database name.
`backup`	`Google\Cloud\Spanner\Backup\|string` The backup to restore, given as a Backup instance or a string of the form `projects/<project>/instances/<instance>/backups/<backup>`.
`options`	`array` [optional] Configuration options.

Returns
Type	Description
`Google\Cloud\Core\LongRunning\LongRunningOperation<\google\cloud\spanner\database>`

database

Lazily instantiate a database object

Example:

$database = $instance->database('my-database');

Database role configured on the database object will be applied to the session created by this object.

$database = $instance->database('my-database', ['databaseRole' => 'Reader']);

Parameters
Name	Description
`name`	`string` The database name
`options`	`array` Configuration options.
`↳ sessionPool`	`SessionPoolInterface` A pool used to manage sessions.
`↳ databaseRole`	`string` The user created database role which creates the session.

Returns
Type	Description
`Google\Cloud\Spanner\Database`

databases

List databases in an instance

Example:

$databases = $instance->databases();

Parameters
Name	Description
`options`	`array` Configuration options.
`↳ pageSize`	`int` Maximum number of results to return per request.
`↳ resultLimit`	`int` Limit the number of results returned in total. Defaults to `0` (return all results).
`↳ pageToken`	`string` A previously-returned page token used to resume the loading of results from a specific point.

Returns
Type	Description
`Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\spanner\database>`

backup

Lazily instantiate a backup object

Example:

$backup = $instance->backup('my-backup');

Parameters
Name	Description
`name`	`string` The backup name.
`backup`	`array`

Returns
Type	Description
`Google\Cloud\Spanner\Backup`

backups

List completed and pending backups in an instance.

Example:

$backups = $instance->backups();

Parameters
Name	Description
`options`	`array` Configuration options.
`↳ filter`	`string` The standard list filter.
`↳ pageSize`	`int` The maximum number of resources contained in the underlying API response. The API may return fewer values in a page, even if there are additional values to be retrieved.
`↳ resultLimit`	`int` Limit the number of results returned in total. Defaults to `0` (return all results).
`↳ pageToken`	`string` A page token is used to specify a page of values to be returned. If no page token is specified (the default), the first page of values will be returned. Any page token used here must have been generated by a previous call to the API.

Returns
Type	Description
`Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\spanner\backup>`

backupOperations

Lists backup operations for the instance.

Example:

$backupOperations = $instance->backupOperations();

Parameters
Name	Description
`options`	`array` Configuration options.
`↳ pageSize`	`int` The maximum number of resources contained in the underlying API response. The API may return fewer values in a page, even if there are additional values to be retrieved.
`↳ resultLimit`	`int` Limit the number of results returned in total. Defaults to `0` (return all results).
`↳ pageToken`	`string` A page token is used to specify a page of values to be returned. If no page token is specified (the default), the first page of values will be returned. Any page token used here must have been generated by a previous call to the API.

Returns
Type	Description
`Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\core\longrunning\longrunningoperation>`

databaseOperations

Lists database operations for the instance.

Example:

$databaseOperations = $instance->databaseOperations();

Parameters
Name	Description
`options`	`array` Configuration options.
`↳ pageSize`	`int` The maximum number of resources contained in the underlying API response. The API may return fewer values in a page, even if there are additional values to be retrieved.
`↳ resultLimit`	`int` Limit the number of results returned in total. Defaults to `0` (return all results).
`↳ pageToken`	`string` A page token is used to specify a page of values to be returned. If no page token is specified (the default), the first page of values will be returned. Any page token used here must have been generated by a previous call to the API.

Returns
Type	Description
`Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\core\longrunning\longrunningoperation>`

iam

Manage the instance IAM policy

Example:

$iam = $instance->iam();

Returns
Type	Description
`Google\Cloud\Core\Iam\Iam`

__debugInfo

Represent the class in a more readable and digestable fashion.

resumeOperation

{ Resume a Long Running Operation

Example:
```php
$operation = $instance->resumeOperation($operationName);
```

@param string $operationName The Long Running Operation name.
@param array $info [optional] The operation data.
@return LongRunningOperation

}

Returns
Type	Description
`void`

longRunningOperations

{ List long running operations.

Example:
```php
$operations = $instance->longRunningOperations();
```

@param array $options [optional] {
    Configuration Options.

    @type string $name The name of the operation collection.
    @type string $filter The standard list filter.
    @type int $pageSize Maximum number of results to return per
          request.
    @type int $resultLimit Limit the number of results returned in total.
          **Defaults to** `0` (return all results).
    @type string $pageToken A previously-returned page token used to
          resume the loading of results from a specific point.
}
@return ItemIterator<InstanceConfiguration>

}

Returns
Type	Description
`void`

Constants

STATE_READY

Value: \Google\Cloud\Spanner\Admin\Instance\V1\Instance\State::READY

STATE_CREATING

Value: \Google\Cloud\Spanner\Admin\Instance\V1\Instance\State::CREATING

DEFAULT_NODE_COUNT

Value: 1