- 1.104.0 (latest)
- 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 SpannerClient.
Cloud Spanner is a highly scalable, transactional, managed, NewSQL database service. Find more information at Cloud Spanner docs .
In production environments, it is highly recommended that you make use of the Protobuf PHP extension for improved performance. Protobuf can be installed via PECL .
$ pecl install protobuf
Example:
use Google\Cloud\Spanner\SpannerClient;
$spanner = new SpannerClient();
// Using a Spanner Emulator
use Google\Cloud\Spanner\SpannerClient;
// Be sure to use the port specified when starting the emulator.
// `9010` is used as an example only.
putenv('SPANNER_EMULATOR_HOST=localhost:9010');
$spanner = new SpannerClient();
Methods
__construct
Create a Spanner client. Please note that this client requires the gRPC extension .
config
array
Configuration Options.
↳ apiEndpoint
string
A hostname with optional port to use in place of the service's default endpoint.
↳ projectId
string
The project ID from the Google Developer's Console.
↳ authCache
CacheItemPoolInterface
A cache for storing access tokens. Defaults toa simple in memory implementation.
↳ authCacheOptions
array
Cache configuration options.
↳ authHttpHandler
callable
A handler used to deliver Psr7 requests specifically for authentication.
↳ credentialsFetcher
FetchAuthTokenInterface
A credentials fetcher instance.
↳ httpHandler
callable
A handler used to deliver Psr7 requests. Only valid for requests sent over REST.
↳ keyFile
array
The contents of the service account credentials .json file retrieved from the Google Developer's Console. Ex: json_decode(file_get_contents($path), true)
.
↳ keyFilePath
string
The full path to your service account credentials .json file retrieved from the Google Developers Console.
↳ requestTimeout
float
Seconds to wait before timing out the request. Defaults to 0
with REST and 60
with gRPC.
↳ retries
int
Number of retries for a failed request. Used only with default backoff strategy. Defaults to 3
.
↳ scopes
array
Scopes to be used for the request.
↳ quotaProject
string
Specifies a user project to bill for access charges associated with the request.
↳ returnInt64AsObject
bool
If true, 64 bit integers will be returned as a Google\Cloud\Spanner\Google\Cloud\Core\Int64 object for 32 bit platform compatibility. Defaults tofalse.
↳ queryOptions
array
Query optimizer configuration.
↳ queryOptions
string
.optimizerVersion An option to control the selection of optimizer version. This parameter allows all execute queries to use a specific query optimizer version. Specifying "latest" as a value instructs Cloud Spanner to use the latest supported query optimizer version. query-level values will take precedence over any global settings. If the SPANNER_OPTIMIZER_VERSION environment variable is set, it will take second priority. This value is used when neither a query-level value nor the environment variable is set. 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.
↳ useDiscreteBackoffs
bool
false
: use default backoff strategy (retry every failed request up to retries
times). true
: use discrete backoff settings based on called method name. Defaults to false
.
batch
Get a Batch Client.
Batch Clients allow you to execute reads of very large data sets, spread across multiple partitions.
Example:
$batch = $spanner->batch('instance-id', 'database-id');
Database role configured in the optional $options array will be applied to the session created by this object.
$batch = $spanner->batch('instance-id', 'database-id', ['databaseRole' => 'Reader']);
instanceId
string
The instance to connect to.
databaseId
string
The database to connect to.
options
array
Configuration options.
↳ databaseRole
string
The user created database role which creates the session.
createInstanceConfiguration
Create a new instance configuration.
Example:
use Google\Cloud\Spanner\Admin\Instance\V1\ReplicaInfo;
$operation = $spanner->createInstanceConfiguration(
$baseInstanceConfig,
'custom-instance-config',
// The replicas for the custom instance configuration must include all the replicas of the base
// configuration, in addition to at least one from the list of optional replicas of the base
// configuration.
array_merge(
$baseInstanceConfig->info()['replicas'],
[
new ReplicaInfo([
'location' => 'us-east1',
'type' => ReplicaInfo\ReplicaType::READ_ONLY,
'defaultLeaderLocation' => false
])
]
),
[
'displayName' => 'This is a display name',
'labels' => ['cloud_spanner_samples' => true]
]
);
baseConfig
Google\Cloud\Spanner\InstanceConfiguration
The base configuration to extend for this custom instance configuration.
name
string
The configuration name. Should be prefixed with "custom-".
replicas
array< Google\Cloud\Spanner\Admin\Instance\V1\ReplicaInfo
>|array
The replica information for the new instance configuration. This array must contain all the replicas from the base configuration, plus at least one from list of optional replicas of the base configuration. One of the replicas must be set as the default leader location.
options
array
Configuration options.
↳ displayName
string
Defaults tothe value of $name.
↳ leaderOptions
array
Allowed values of the "default_leader" schema option for databases in instances that use this instance configuration. Defaults tothe leader options of the base configuration. Please note it may be possible for the default value to be an empty array when lazy loading the base configuration. To ensure the default value matches the upstream values please make sure to trigger a network request on the base configuration with either Google\Cloud\Spanner\InstanceConfiguration::reload() or Google\Cloud\Spanner\InstanceConfiguration::info() .
↳ labels
↳ validateOnly
bool
An option to validate, but not actually execute, the request, and provide the same response. Defaults to false
.
Google\Cloud\Core\LongRunning\LongRunningOperation<\google\cloud\spanner\instanceconfiguration>
instanceConfigurations
List all available instance configurations.
Example:
$configurations = $spanner->instanceConfigurations();
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.
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\spanner\instanceconfiguration>
instanceConfiguration
Get an instance configuration by its name.
NOTE: This method does not execute a service request and does not verify the existence of the given configuration. Unless you know with certainty that the configuration exists, it is advised that you use Google\Cloud\Spanner\Google\Cloud\Spanner\InstanceConfiguration::exists() to verify existence before attempting to use the configuration.
Example:
$configuration = $spanner->instanceConfiguration($configurationName);
name
string
The Configuration name.
options
array
instanceConfigOperations
Lists instance configuration operations for the project.
Example:
$instanceConfigOperations = $spanner->instanceConfigOperations();
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.
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\core\longrunning\longrunningoperation>
createInstance
Create a new instance.
Example:
$operation = $spanner->createInstance($configuration, 'my-instance');
config
name
string
The instance name
options
array
Configuration options
↳ displayName
string
Defaults tothe value of $name.
↳ nodeCount
int
Defaults to 1
.
↳ labels
Google\Cloud\Core\LongRunning\LongRunningOperation<\google\cloud\spanner\instance>
instance
Lazily instantiate an instance.
Example:
$instance = $spanner->instance('my-instance');
name
string
The instance name
instance
array
instances
List instances in the project
Example:
$instances = $spanner->instances();
options
array
Configuration options
↳ filter
string
An expression for filtering the results of the request.
↳ 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.
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\spanner\instance>
connect
Connect to a database to run queries or mutations.
Example:
$database = $spanner->connect('instance-id', 'database-id');
Database role configured on the $options parameter will be applied to the session created by this object. Note: When the databseRole and sessionPool both are present in the options, we prioritize the sessionPool.
$database = $spanner->connect('instance-id', 'database-id', ['databaseRole' => 'Reader']);
instance
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.
keySet
Create a new KeySet object
Example:
$keySet = $spanner->keySet();
// Create a keyset to return all rows in a table.
$keySet = $spanner->keySet(['all' => true]);
options
array
Configuration Options
↳ keys
array
A list of keys
↳ ranges
KeyRange[]
A list of key ranges
↳ all
bool
Whether to include all keys in a table
keyRange
Create a new KeyRange object
Example:
$range = $spanner->keyRange();
// Ranges can be created with all data supplied.
$range = $spanner->keyRange([
'startType' => KeyRange::TYPE_OPEN,
'start' => ['Bob'],
'endType' => KeyRange::TYPE_OPEN,
'end' => ['Jill']
]);
options
array
Configuration Options.
↳ startType
string
Either "open" or "closed". Use constants KeyRange::TYPE_OPEN
and KeyRange::TYPE_CLOSED
for guaranteed correctness.
↳ start
array
The key with which to start the range.
↳ endType
string
Either "open" or "closed". Use constants KeyRange::TYPE_OPEN
and KeyRange::TYPE_CLOSED
for guaranteed correctness.
↳ end
array
The key with which to end the range.
bytes
Create a Bytes object.
Example:
$bytes = $spanner->bytes('hello world');
bytes
Psr\Http\StreamInterface
|string|resource
The bytes value.
date
Create a Date object.
Example:
$date = $spanner->date(new \DateTime('1995-02-04'));
date
DateTimeInterface
The date value.
timestamp
Create a Timestamp object.
Example:
$timestamp = $spanner->timestamp(new \DateTime('2003-02-05 11:15:02.421827Z'));
timestamp
DateTimeInterface
The timestamp value.
nanoSeconds
int
[optional] The number of nanoseconds in the timestamp.
numeric
Create a Numeric object.
Numeric represents a value with a data type of Numeric .
It supports a fixed 38 decimal digits of precision and 9 decimal digits of scale, and values are in the range of -99999999999999999999999999999.999999999 to 99999999999999999999999999999.999999999.
Example:
$numeric = $spanner->numeric('99999999999999999999999999999999999999.999999999');
value
string|int|float
The Numeric value.
numeric
pgNumeric
Represents a value with a data type of PG Numeric for the Postgres Dialect database.
It supports a value precision of up to 131072 digits before the decimal point and up to 16383 digits after the decimal point.
Example:
$pgNumeric = $spanner->pgNumeric('99999999999999999999999999999999999999.000000999999999');
value
string|int|float|null
The PgNumeric value.
pgJsonb
Represents a value with a data type of PG JSONB for the Postgres Dialect database.
Example:
$pgJsonb = $spanner->pgJsonb('}');
value
mixed
int64
Create an Int64 object. This can be used to work with 64 bit integers as a string value while on a 32 bit platform.
Example:
$int64 = $spanner->int64('9223372036854775807');
value
string
Google\Cloud\Core\Int64
duration
Create a Duration object.
Example:
$duration = $spanner->duration(100, 00001);
seconds
int
The number of seconds in the duration.
nanos
int
[optional] The number of nanoseconds in the duration. Defaults to 0
.
commitTimestamp
Create a CommitTimestamp object.
Commit Timestamps may be used to implement server-side commit timestamp tracking in tables. Refer to Google\Cloud\Spanner\Google\Cloud\Spanner\CommitTimestamp for usage details.
Example:
$commitTimestamp = $spanner->commitTimestamp();
Constants
VERSION
Value: '1.55.0'
FULL_CONTROL_SCOPE
Value: 'https://www.googleapis.com/auth/spanner.data'
ADMIN_SCOPE
Value: 'https://www.googleapis.com/auth/spanner.admin'
