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
NameDescription
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
TypeDescription
string

info

Return the service representation of the instance.

This method may require a service call.

Example:

$info = $instance->info();
echo $info['nodeCount'];
Parameters
NameDescription
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
TypeDescription
array

exists

Check if the instance exists.

This method requires a service call.

Example:

if ($instance->exists()) {
   echo 'Instance exists!';
}
Parameter
NameDescription
options array

[optional] Configuration options.

Returns
TypeDescription
bool

reload

Fetch a fresh representation of the instance from the service.

Example:

$info = $instance->reload();
Parameters
NameDescription
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
TypeDescription
array

create

Create a new instance.

Example:

$operation = $instance->create($configuration);
Parameters
NameDescription
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
TypeDescription
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
NameDescription
options array

[optional] Configuration options.

Returns
TypeDescription
int|null

update

Update the instance

Example:

$instance->update([
    'displayName' => 'My Instance',
    'nodeCount' => 4
]);
Parameters
NameDescription
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
TypeDescription
Google\Cloud\Core\LongRunning\LongRunningOperation

delete

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

Example:

$instance->delete();
Parameter
NameDescription
options array

[optional] Configuration options.

Returns
TypeDescription
void

createDatabase

Create a Database

Example:

$operation = $instance->createDatabase('my-database');
Parameters
NameDescription
name string

The database name.

options array

Configuration Options

↳ statements array

Additional DDL statements.

↳ sessionPool SessionPoolInterface

A pool used to manage sessions.

Returns
TypeDescription
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
NameDescription
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
TypeDescription
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
NameDescription
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
TypeDescription
Google\Cloud\Spanner\Database

databases

List databases in an instance

Example:

$databases = $instance->databases();
Parameters
NameDescription
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
TypeDescription
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\spanner\database>

backup

Lazily instantiate a backup object

Example:

$backup = $instance->backup('my-backup');
Parameters
NameDescription
name string

The backup name.

backup array
Returns
TypeDescription
Google\Cloud\Spanner\Backup

backups

List completed and pending backups in an instance.

Example:

$backups = $instance->backups();
Parameters
NameDescription
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
TypeDescription
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\spanner\backup>

backupOperations

Lists backup operations for the instance.

Example:

$backupOperations = $instance->backupOperations();
Parameters
NameDescription
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
TypeDescription
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\core\longrunning\longrunningoperation>

databaseOperations

Lists database operations for the instance.

Example:

$databaseOperations = $instance->databaseOperations();
Parameters
NameDescription
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
TypeDescription
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\core\longrunning\longrunningoperation>

iam

Manage the instance IAM policy

Example:

$iam = $instance->iam();
Returns
TypeDescription
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
TypeDescription
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
TypeDescription
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