- 2.0.1-RC1 (latest)
- 2.0.0-RC1
- 1.106.0
- 1.105.1
- 1.104.1
- 1.103.0
- 1.102.0
- 1.101.0
- 1.100.0
- 1.98.0
- 1.97.0
- 1.96.0
- 1.95.0
- 1.94.0
- 1.93.1
- 1.92.1
- 1.91.0
- 1.90.0
- 1.89.0
- 1.88.0
- 1.87.0
- 1.86.0
- 1.85.0
- 1.84.0
- 1.83.0
- 1.82.0
- 1.81.0
- 1.80.0
- 1.79.0
- 1.78.0
- 1.77.0
- 1.76.1
- 1.68.0
- 1.67.0
- 1.66.0
- 1.65.0
- 1.64.0
- 1.63.2
- 1.62.1
- 1.61.0
- 1.60.0
- 1.59.0
- 1.58.4
- 1.57.0
- 1.56.0
- 1.55.0
- 1.54.2
Reference documentation and code samples for the Cloud Spanner Client class Database.
Represents a Cloud Spanner Database.
Example:
use Google\Cloud\Spanner\SpannerClient;
$spanner = new SpannerClient(['projectId' => 'my-project']);
$database = $spanner->connect('my-instance', 'my-database');
// Databases can also be connected to via an Instance.
use Google\Cloud\Spanner\SpannerClient;
$spanner = new SpannerClient(['projectId' => 'my-project']);
$instance = $spanner->instance('my-instance');
$database = $instance->database('my-database');
Namespace
Google \ Cloud \ SpannerMethods
__construct
Create an object representing a Database.
spannerClient
databaseAdminClient
Admin\Database\V1\Client\DatabaseAdminClient
The database admin client used to interact with the API.
serializer
Serializer
The serializer instance to encode/decode messages.
instance
projectId
string
The project ID.
name
string
The database name or ID.
session
Session\SessionCache
the current Session
options
array
[Optional] { Database options.
@type bool $routeToLeader Enable/disable Leader Aware Routing.
**Defaults to** `true` (enabled).
@type array $defaultQueryOptions
@type bool $returnInt64AsObject If true, 64 bit integers will
be returned as a <xref uid="\Google\Cloud\Core\Int64">Google\Cloud\Core\Int64</xref> object for 32 bit
platform compatibility. **Defaults to** false.
@type string $databaseRole The user created database role which
creates the session.
@type array $database The database info.
@type int $isolationLevel The level of Isolation for the transactions executed by this Client's instance.
**Defaults to** IsolationLevel::ISOLATION_LEVEL_UNSPECIFIED
}
state
Return the database state.
When databases are created or restored, they may take some time before they are ready for use. This method allows for checking whether a database is ready. Note that this value is cached within the class instance, so if you are polling it, first call Database::reload() to refresh the cached value.
Example:
if ($database->state() === Database::STATE_READY) {
echo 'Database is ready!';
}
options
array
[optional] Configuration options.
int|null
backups
List completed and pending backups belonging to this database.
Example:
$backups = $database->backups();
options
array
Configuration options.
↳ filter
string
The standard list filter. NOTE: This method always sets the database filter as a name of this database. User may provide additional filter expressions which would be appended in the form of "(database:
↳ 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.
createBackup
Create a backup for this database.
Example:
$operation = $database->createBackup('my-backup', new \DateTime('+7 hours'));
name
string
The backup name.
expireTime
DateTimeInterface
The expiration time of the backup, with microseconds granularity that must be at least 6 hours and at most 366 days. Once the expireTime has passed, the backup is eligible to be automatically deleted by Cloud Spanner.
options
array
[optional] Configuration options.
name
Return the fully-qualified database name.
Example:
$name = $database->name();
string
info
See also:
options
array
[optional] Configuration options.
array
reload
See also:
options
array
[optional] Configuration options.
array
exists
Check if the database exists.
This method sends a service request.
NOTE: Requires https://www.googleapis.com/auth/spanner.admin
scope.
Example:
if ($database->exists()) {
echo 'Database exists!';
}
options
array
[optional] Configuration options.
bool
create
See also:
options
array
Configuration Options
↳ statements
string[]
Additional DDL statements.
↳ protoDescriptors
Google\Protobuf\FileDescriptorSet
|string
The file descriptor set object to be used in the update, or alternatively, an absolute path to the generated file descriptor set. The descriptor set is only used during DDL statements, such as CREATE PROTO BUNDLE
.
restore
Restores to this database from a backup.
NOTE: A restore operation can only be made to a non-existing database.
Example:
$operation = $database->restore($backup);
backup
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.
updateDatabase
See also:
options
array
Configuration Options
↳ enableDropProtection
bool
If true
, delete operations for Database and Instance will be blocked. Defaults to false
.
updateDdl
See also:
statement
string
A DDL statements to run against a database.
options
array
[optional] Configuration options.
updateDdlBatch
See also:
statements
string[]
A list of DDL statements to run against a database.
options
array
Configuration options. Supports setting the fields of Admin\Database\V1\UpdateDatabaseDdlRequest and Google\ApiCore\Options\CallOptions .
drop
See also:
options
array
Configuration options. Supports setting the fields of Admin\Database\V1\DropDatabaseRequest and Google\ApiCore\Options\CallOptions .
void
ddl
See also:
options
array
Configuration options. Supports setting the fields of Admin\Database\V1\GetDatabaseDdlRequest and Google\ApiCore\Options\CallOptions .
array
iam
Manage the database IAM policy
Example:
$iam = $database->iam();
Google\Cloud\Core\Iam\IamManager
snapshot
See also:
options
array
Configuration Options
See [ReadOnly](https://cloud.google.com/spanner/reference/rpc/google.spanner.v1#google.spanner.v1.TransactionOptions.ReadOnly)
for detailed description of available options.
Please note that only one of `$strong`, `$readTimestamp` or
`$exactStaleness` may be set in a request.
↳ returnReadTimestamp
bool
If true, the Cloud Spanner-selected read timestamp is included in the Transaction message that describes the transaction.
↳ strong
bool
Read at a timestamp where all previously committed transactions are visible.
↳ readTimestamp
Timestamp
Executes all reads at the given timestamp.
↳ exactStaleness
Duration
Represents a number of seconds. Executes all reads at a timestamp that is $exactStaleness old.
↳ minReadTimestamp
Timestamp
Executes all reads at a timestamp >= min_read_timestamp. Only available when $options.singleUse
is true.
↳ maxStaleness
Duration
Read data at a timestamp >= NOW - max_staleness seconds. Guarantees that all writes that have committed more than the specified number of seconds ago are visible. Only available when $options.singleUse
is true.
↳ singleUse
bool
If true, a Transaction ID will not be allocated up front. Instead, the transaction will be considered "single-use", and may be used for only a single operation. Defaults to false
.
↳ sessionOptions
array
Session configuration and request options. Session labels may be applied using the labels
key.
TransactionalReadInterface
transaction
See also:
options
array
Configuration Options.
↳ singleUse
bool
If true, a Transaction ID will not be allocated up front. Instead, the transaction will be considered "single-use", and may be used for only a single operation. Defaults to false
.
↳ sessionOptions
array
Session configuration and request options. Session labels may be applied using the labels
key.
↳ tag
string
A transaction tag. Requests made using this transaction will use this as the transaction tag.
runTransaction
See also:
operation
callable
The operations to run in the transaction. Signature:
* function (Transaction $transaction)
.
options
array
Configuration Options
↳ retrySettings
RetrySettings|array
{ Retry configuration options. Currently, only the maxRetries
option is supported.
↳ maxRetries
int
The maximum number of retry attempts before the operation fails. Defaults to 10. }
↳ singleUse
bool
If true, a Transaction ID will not be allocated up front. Instead, the transaction will be considered "single-use", and may be used for only a single operation. Note that in a single-use transaction, only a single operation may be executed, and rollback is not available. Defaults to false
.
↳ sessionOptions
array
Session configuration and request options. Session labels may be applied using the labels
key.
↳ tag
string
A transaction tag. Requests made using this transaction will use this as the transaction tag.
↳ transactionOptions
mixed
insert
See also:
table
string
The table to mutate.
data
array
The row data to insert.
options
array
Configuration options.
↳ requestOptions
array
Request options. For more information on available options, please see RequestOptions
. Please note, if using the priority
setting you may utilize the constants available on V1\RequestOptions\Priority
to set a value. Please note, the transactionTag
setting will be ignored as it is not supported for single-use transactions.
insertBatch
See also:
table
string
The table to mutate.
dataSet
array
The row data to insert.
options
array
Configuration options.
↳ requestOptions
array
Request options. For more information on available options, please see RequestOptions
. Please note, if using the priority
setting you may utilize the constants available on V1\RequestOptions\Priority
to set a value. Please note, the transactionTag
setting will be ignored as it is not supported for single-use transactions.
update
See also:
table
string
The table to mutate.
data
array
The row data to update.
options
array
Configuration options.
↳ requestOptions
array
Request options. For more information on available options, please see RequestOptions
. Please note, if using the priority
setting you may utilize the constants available on V1\RequestOptions\Priority
to set a value. Please note, the transactionTag
setting will be ignored as it is not supported for single-use transactions.
updateBatch
See also:
table
string
The table to mutate.
dataSet
array
The row data to update.
options
array
Configuration options.
↳ requestOptions
array
Request options. For more information on available options, please see RequestOptions
. Please note, if using the priority
setting you may utilize the constants available on V1\RequestOptions\Priority
to set a value. Please note, the transactionTag
setting will be ignored as it is not supported for single-use transactions.
insertOrUpdate
See also:
table
string
The table to mutate.
data
array
The row data to insert or update.
options
array
Configuration options.
↳ requestOptions
array
Request options. For more information on available options, please see RequestOptions
. Please note, if using the priority
setting you may utilize the constants available on V1\RequestOptions\Priority
to set a value. Please note, the transactionTag
setting will be ignored as it is not supported for single-use transactions.
insertOrUpdateBatch
See also:
table
string
The table to mutate.
dataSet
array
The row data to insert or update.
options
array
Configuration options.
↳ requestOptions
array
Request options. For more information on available options, please see RequestOptions
. Please note, if using the priority
setting you may utilize the constants available on V1\RequestOptions\Priority
to set a value. Please note, the transactionTag
setting will be ignored as it is not supported for single-use transactions.
replace
See also:
table
string
The table to mutate.
data
array
The row data to replace.
options
array
Configuration options.
↳ requestOptions
array
Request options. For more information on available options, please see RequestOptions
. Please note, if using the priority
setting you may utilize the constants available on V1\RequestOptions\Priority
to set a value. Please note, the transactionTag
setting will be ignored as it is not supported for single-use transactions.
replaceBatch
See also:
table
string
The table to mutate.
dataSet
array
The row data to replace.
options
array
Configuration options.
↳ requestOptions
array
Request options. For more information on available options, please see RequestOptions
. Please note, if using the priority
setting you may utilize the constants available on V1\RequestOptions\Priority
to set a value. Please note, the transactionTag
setting will be ignored as it is not supported for single-use transactions.
delete
See also:
table
string
The table to mutate.
keySet
options
array
Configuration options.
↳ requestOptions
array
Request options. For more information on available options, please see RequestOptions
. Please note, if using the priority
setting you may utilize the constants available on V1\RequestOptions\Priority
to set a value. Please note, the transactionTag
setting will be ignored as it is not supported for single-use transactions.
execute
See also:
sql
string
The query string to execute.
options
array
Configuration Options.
See V1\TransactionOptions\PBReadOnly
for detailed description of
available transaction options. Please note that only one of $strong
, $minReadTimestamp
, $maxStaleness
, $readTimestamp
or $exactStaleness
may be set in a request.
↳ parameters
array
A key/value array of Query Parameters, where the key is represented in the query string prefixed by a @
symbol.
↳ types
array
A key/value array of Query Parameter types. Generally, Google Cloud PHP can infer types. Explicit type declarations are required in the case of struct parameters, or when a null value exists as a parameter. Accepted values for primitive types are defined as constants on Database
, and are as follows: Database::TYPE_BOOL
, Database::TYPE_INT64
, Database::TYPE_FLOAT64
, Database::TYPE_TIMESTAMP
, Database::TYPE_DATE
, Database::TYPE_STRING
, Database::TYPE_BYTES
. If the value is an array, use ArrayType
to declare the array parameter types. Likewise, for structs, use StructType
.
↳ returnReadTimestamp
bool
If true, the Cloud Spanner-selected read timestamp is included in the Transaction message that describes the transaction.
↳ strong
bool
Read at a timestamp where all previously committed transactions are visible.
↳ minReadTimestamp
Timestamp
Execute reads at a timestamp >= the given timestamp. Only available in single-use transactions.
↳ maxStaleness
Duration
Read data at a timestamp >= NOW - the given timestamp. Only available in single-use transactions.
↳ readTimestamp
Timestamp
Executes all reads at the given timestamp.
↳ exactStaleness
Duration
Represents a number of seconds. Executes all reads at a timestamp that is $exactStaleness old.
↳ begin
bool|array
If true, will begin a new transaction. If a read/write transaction is desired, set the value of $transactionType. If a transaction or snapshot is created, it will be returned as $result->transaction()
or $result->snapshot()
. If $begin is an array, see TransactionOptions
. Defaults to false
.
↳ transactionType
string
One of Database::CONTEXT_READ
or Database::CONTEXT_READWRITE
. If read/write is chosen, any snapshot options will be disregarded. If $begin
is false, transaction type MUST be Database::CONTEXT_READ
. Defaults to Database::CONTEXT_READ
.
↳ sessionOptions
array
Session configuration and request options. Session labels may be applied using the labels
key.
↳ queryOptions
array
Query optimizer configuration.
optimizerVersion
string
An option to control the selection of optimizer version. This parameter allows individual queries to pick different query optimizer versions. Specifying "latest" as a value instructs Cloud Spanner to use the latest supported query optimizer version. If not specified, Cloud Spanner uses optimizer version set at the client level options or set by the SPANNER_OPTIMIZER_VERSION
environment variable. Any other positive integer (from the list of supported optimizer versions) overrides the default optimizer version for query execution. Executing a SQL statement with an invalid optimizer version will fail with a syntax error ( INVALID_ARGUMENT
) status.
↳ requestOptions
array
Request options. For more information on available options, please see RequestOptions
. Please note, if using the priority
setting you may utilize the constants available on V1\RequestOptions\Priority
to set a value. Please note, the transactionTag
setting will be ignored as it is not supported for read-only transactions.
↳ directedReadOptions
array
Directed read options. V1\DirectedReadOptions
If using the replicaSelection::type
setting, utilize the constants available in V1\DirectedReadOptions\ReplicaSelection\Type
to set a value.
mutationGroup
Create a new MutationGroup object.
MutationGroup
batchWrite
Batches the supplied mutation groups in a collection of efficient transactions. All mutations in a group are committed atomically. However, mutations across groups can be committed non-atomically in an unspecified order and thus, they must be independent of each other. Partial failure is possible, i.e., some groups may have been committed successfully, while some may have failed. The results of individual batches are streamed into the response as the batches are applied.
BatchWrite requests are not replay protected, meaning that each mutation group may be applied more than once. Replays of non-idempotent mutations may have undesirable effects. For example, replays of an insert mutation may produce an already exists error or if you use generated or commit timestamp-based keys, it may result in additional rows being added to the mutation's table. We recommend structuring your mutation groups to be idempotent to avoid this issue.
Sample code:
mutationGroups
array< MutationGroup
>
Required. The groups of mutations to be applied.
options
array
Optional.
↳ requestOptions
array
Common options for this request.
↳ excludeTxnFromChangeStreams
bool
Optional. When exclude_txn_from_change_streams
is set to true
: * * Mutations from all transactions in this batch write operation will not be recorded in change streams with DDL option allow_txn_exclusion=true
that are tracking columns modified by these transactions. * * Mutations from all transactions in this batch write operation will be recorded in change streams with DDL option allow_txn_exclusion=false or not set
that are tracking columns modified by these transactions. When exclude_txn_from_change_streams
is set to false
or not set, mutations from all transactions in this batch write operation will be recorded in all change streams that are tracking columns modified by these transactions.
Generator
executePartitionedUpdate
See also:
statement
string
The DML statement to execute.
options
array
Configuration Options.
↳ parameters
array
A key/value array of Query Parameters, where the key is represented in the statement prefixed by a @
symbol.
↳ types
array
A key/value array of Query Parameter types. Generally, Google Cloud PHP can infer types. Explicit type declarations are required in the case of struct parameters, or when a null value exists as a parameter. Accepted values for primitive types are defined as constants on Database
, and are as follows: Database::TYPE_BOOL
, Database::TYPE_INT64
, Database::TYPE_FLOAT64
, Database::TYPE_TIMESTAMP
, Database::TYPE_DATE
, Database::TYPE_STRING
, Database::TYPE_BYTES
. If the value is an array, use ArrayType
to declare the array parameter types. Likewise, for structs, use StructType
.
↳ requestOptions
array
Request options. For more information on available options, please see RequestOptions
. Please note, if using the priority
setting you may utilize the constants available on V1\RequestOptions\Priority
to set a value. Please note, the transactionTag
setting will be ignored as it is not supported for partitioned DML.
↳ transactionOptions
array
Transaction options. V1\TransactionOptions} </xref
int
read
See also:
table
string
The table name.
keySet
columns
array
A list of column names to return.
options
array
Configuration Options.
See [TransactionOptions](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.TransactionOptions)
for detailed description of available transaction options.
Please note that only one of `$strong`, `$minReadTimestamp`,
`$maxStaleness`, `$readTimestamp` or `$exactStaleness` may be set in
a request.
↳ index
string
The name of an index on the table.
↳ limit
int
The number of results to return.
↳ returnReadTimestamp
bool
If true, the Cloud Spanner-selected read timestamp is included in the Transaction message that describes the transaction.
↳ strong
bool
Read at a timestamp where all previously committed transactions are visible.
↳ minReadTimestamp
Timestamp
Execute reads at a timestamp >= the given timestamp. Only available in single-use transactions.
↳ maxStaleness
Duration
Read data at a timestamp >= NOW - the given timestamp. Only available in single-use transactions.
↳ readTimestamp
Timestamp
Executes all reads at the given timestamp.
↳ exactStaleness
Duration
Represents a number of seconds. Executes all reads at a timestamp that is $exactStaleness old.
↳ begin
bool
If true, will begin a new transaction. If a read/write transaction is desired, set the value of $transactionType. If a transaction or snapshot is created, it will be returned as $result->transaction()
or $result->snapshot()
. Defaults to false
.
↳ transactionType
string
One of Database::CONTEXT_READ
or Database::CONTEXT_READWRITE
. If read/write is chosen, any snapshot options will be disregarded. If $begin
is false, transaction type MUST be Database::CONTEXT_READ
. Defaults to Database::CONTEXT_READ
.
↳ sessionOptions
array
Session configuration and request options. Session labels may be applied using the labels
key.
↳ requestOptions
array
Request options. For more information on available options, please see RequestOptions
. Please note, if using the priority
setting you may utilize the constants available on V1\RequestOptions\Priority
to set a value. Please note, the transactionTag
setting will be ignored as it is not supported for read-only transactions.
↳ directedReadOptions
array
Directed read options. V1\DirectedReadOptions
If using the replicaSelection::type
setting, utilize the constants available in V1\DirectedReadOptions\ReplicaSelection\Type
to set a value.
↳ orderBy
int
Set the OrderBy option for the ReadRequest. V1\ReadRequest and V1\ReadRequest\OrderBy for more information and available options.
↳ lockHint
int
Set the LockHint option for the ReadRequest. Only available when transactionType is read/write. V1\ReadRequest and V1\ReadRequest\LockHint for more information and available options.
identity
Retrieves the database's identity.
array
backupOperations
Lists backup operations.
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.
createDatabaseFromBackup
Create a database from a backup.
name
string
The database name.
backup
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.
databaseOperations
Lists database operations.
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.
resumeOperation
Resume a Long Running Operation
Example:
$operation = $database->resumeOperation($operationName);
operationName
string
The Long Running Operation name.
options
array
longRunningOperations
List long running operations.
Example:
$operations = $database->longRunningOperations();
options
array
Configuration Options.
↳ name
string
The name of the operation collection.
↳ filter
string
The standard list filter.
↳ 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.
session
Get the current multiplex session or create a new one.
Session\SessionCache
__debugInfo
Represent the class in a more readable and digestable fashion.
Constants
CONTEXT_READ
Value: 'r'
CONTEXT_READWRITE
Value: 'rw'
STATE_CREATING
Value: \Google\Cloud\Spanner\Admin\Database\V1\Database\State::CREATING
STATE_READY
Value: \Google\Cloud\Spanner\Admin\Database\V1\Database\State::READY
STATE_READY_OPTIMIZING
Value: \Google\Cloud\Spanner\Admin\Database\V1\Database\State::READY_OPTIMIZING
MAX_RETRIES
Value: 10
TYPE_BOOL
Value: \Google\Cloud\Spanner\V1\TypeCode::BOOL
TYPE_INT64
Value: \Google\Cloud\Spanner\V1\TypeCode::INT64
TYPE_FLOAT32
Value: \Google\Cloud\Spanner\V1\TypeCode::FLOAT32
TYPE_FLOAT64
Value: \Google\Cloud\Spanner\V1\TypeCode::FLOAT64
TYPE_TIMESTAMP
Value: \Google\Cloud\Spanner\V1\TypeCode::TIMESTAMP
TYPE_DATE
Value: \Google\Cloud\Spanner\V1\TypeCode::DATE
TYPE_STRING
Value: \Google\Cloud\Spanner\V1\TypeCode::STRING
TYPE_BYTES
Value: \Google\Cloud\Spanner\V1\TypeCode::BYTES
TYPE_ARRAY
Value: \Google\Cloud\Spanner\V1\TypeCode::PBARRAY
TYPE_STRUCT
Value: \Google\Cloud\Spanner\V1\TypeCode::STRUCT
TYPE_NUMERIC
Value: \Google\Cloud\Spanner\V1\TypeCode::NUMERIC
TYPE_PROTO
Value: \Google\Cloud\Spanner\V1\TypeCode::PROTO
TYPE_PG_NUMERIC
Value: 'pgNumeric'
TYPE_PG_JSONB
Value: 'pgJsonb'
TYPE_JSON
Value: \Google\Cloud\Spanner\V1\TypeCode::JSON
TYPE_PG_OID
Value: 'pgOid'
TYPE_INTERVAL
Value: \Google\Cloud\Spanner\V1\TypeCode::INTERVAL
