Reference documentation and code samples for the Cloud Spanner Client class CacheSessionPool.
This session pool implementation accepts a PSR-6 compatible cache implementation and utilizes it to store sessions between requests.
We provide Google\Auth\Cache\SysVCacheItemPool
, which is a fast PSR-6
implementation in google/auth
library. If your PHP has sysvshm
extension enabled (most binary distributions have it compiled in), consider
using it. Please note the SysVCacheItemPool implementation defaults to a
memory allotment that may not meet your requirements. We recommend setting
the memsize setting to 250000 (250kb) as it should safely contain the default
500 maximum sessions the pool can handle. Please modify this value
accordingly depending on the number of maximum sessions you would like
for the pool to handle.
Please note that when Google\Cloud\Spanner\Session\CacheSessionPool::acquire() is called at most only a single session is created. Due to this, it is possible to sit under the minimum session value declared when constructing this instance. In order to have the pool match the minimum session value please use the Google\Cloud\Spanner\Session\CacheSessionPool::warmup() method. This will create as many sessions as needed to match the minimum value, and is the recommended way to bootstrap the session pool.
Sessions are created on demand up to the maximum session value set during instantiation of the pool. To help ensure the minimum number of sessions required are managed by the pool, attempts will be made to automatically downsize after every 10 minute window. This feature is configurable and one may also downsize at their own choosing via Google\Cloud\Spanner\Session\CacheSessionPool::downsize(). Downsizing will help ensure you never run into issues where the Spanner backend is locked up after having met the maximum number of sessions assigned per node. For reference, the current maximum sessions per database per node is 10k. For more information on limits please see here.
When expecting a long period of inactivity (such as a maintenance window), please make sure to call Google\Cloud\Spanner\Session\CacheSessionPool::clear() in order to delete any active sessions.
If you're on Windows, or your PHP doesn't have sysvshm
extension,
unfortunately you can not use Google\Auth\Cache\SysVCacheItemPool
. In such
cases, it will be necessary to include a separate dependency to fulfill
this requirement. The below example makes use of
Symfony's Cache Component. For more
implementations please see the Packagist PHP Package
Repository.
Example:
use Google\Cloud\Spanner\SpannerClient;
use Google\Cloud\Spanner\Session\CacheSessionPool;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
$spanner = new SpannerClient();
$cache = new FilesystemAdapter();
$sessionPool = new CacheSessionPool($cache);
$database = $spanner->connect('my-instance', 'my-database', [
'sessionPool' => $sessionPool
]);
// Labels configured on the pool will be applied to each session created by the pool.
use Google\Cloud\Spanner\Session\CacheSessionPool;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
$cache = new FilesystemAdapter();
$sessionPool = new CacheSessionPool($cache, [
'labels' => [
'environment' => getenv('APPLICATION_ENV')
]
]);
Database role configured on the pool will be applied to each session created by the pool.
use Google\Cloud\Spanner\SpannerClient;
use Google\Cloud\Spanner\Session\CacheSessionPool;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
$spanner = new SpannerClient();
$cache = new FilesystemAdapter();
$sessionPool = new CacheSessionPool($cache, [
'databaseRole' => 'Reader'
]);
$database = $spanner->connect('my-instance', 'my-database', [
'sessionPool' => $sessionPool
]);
Namespace
Google \ Cloud \ Spanner \ SessionMethods
__construct
Parameters | |
---|---|
Name | Description |
cacheItemPool |
Psr\Cache\CacheItemPoolInterface
A PSR-6 compatible cache implementation used to store the session data. |
config |
array
Configuration Options. |
↳ maxSessions |
int
The maximum number of sessions to store in the pool. Defaults to |
↳ minSessions |
int
The minimum number of sessions to store in the pool. Defaults to |
↳ shouldWaitForSession |
bool
If the pool is full, whether to block until a new session is available. *Defaults to |
↳ maxCyclesToWaitForSession |
int
The maximum number cycles to wait for a session before throwing an exception. Defaults to |
↳ sleepIntervalSeconds |
float
The sleep interval between cycles. Defaults to |
↳ lock |
LockInterface
A lock implementation capable of blocking. Defaults to a semaphore based implementation if the required extensions are installed, otherwise an flock based implementation. |
↳ shouldAutoDownsize |
bool
Determines whether or not to automatically attempt to downsize the pool after every 10 minute window. Defaults to |
↳ labels |
array
Labels to be applied to each session created in the pool. Label keys must be between 1 and 63 characters long and must conform to the following regular expression: |
↳ databaseRole |
string
The user created database role which creates the session. |
acquire
Acquire a session from the pool.
Parameter | |
---|---|
Name | Description |
context |
string
The type of session to fetch. May be either |
Returns | |
---|---|
Type | Description |
Google\Cloud\Spanner\Session\Session |
release
Release a session back to the pool.
Parameter | |
---|---|
Name | Description |
session |
Google\Cloud\Spanner\Session\Session
The session. |
keepAlive
Keeps a checked out session alive.
In use sessions that have not had their lastActive
time updated
in the last 20 minutes will be considered eligible to be moved back into
the queue if the max sessions value has been met. In order to work around
this when performing a large streaming execute or read call please make
sure to call this method roughly every 15 minutes between reading rows
to keep your session active.
Parameter | |
---|---|
Name | Description |
session |
Google\Cloud\Spanner\Session\Session
The session to keep alive. |
downsize
Downsizes the queue of available sessions by the given percentage. This is relative to the minimum sessions value. For example: Assuming a full queue, with maximum sessions of 10 and a minimum of 2, downsizing by 50% would leave 6 sessions in the queue. The count of items to be deleted will be rounded up in the case of a fraction.
Please note this method will attempt to synchronously delete sessions and will block until complete.
Parameter | |
---|---|
Name | Description |
percent |
int
The percentage to downsize the pool by. Must be between 1 and 100. |
Returns | |
---|---|
Type | Description |
int |
The number of sessions removed from the pool. |
warmup
Create enough sessions to meet the minimum session constraint.
Returns | |
---|---|
Type | Description |
int |
The number of sessions created and added to the queue. |
clear
Clear the cache and attempt to delete all sessions in the pool.
A session may be removed from the cache, but still tracked as active by the Spanner backend if a delete operation failed. To ensure you do not exceed the maximum number of sessions available per node, please be sure to check the return value of this method to be certain all sessions have been deleted.
Returns | |
---|---|
Type | Description |
bool |
Returns false if some delete operations failed to delete. True if $waitForPromises flag is false or all delete are successful. |
setDatabase
Set the database used to make calls to manage sessions.
Parameter | |
---|---|
Name | Description |
database |
Google\Cloud\Spanner\Database
The database. |
cacheItemPool
Get the underlying cache implementation.
Returns | |
---|---|
Type | Description |
Psr\Cache\CacheItemPoolInterface |
maintain
Maintain queued sessions for selected database and keep them alive.
This method drops expired sessions and refreshes "old" ones (expiring in next 10 minutes).
It can also refresh some non-"old" sessions to distribute refresh calls more or less
evenly between maintenance calls.
Only up to minSessions
sessions are maintained, all excess ones are left to expire.
Constants
CACHE_KEY_TEMPLATE
Value: 'cache-session-pool.%s.%s.%s'
DURATION_SESSION_LIFETIME
Value: 28 * 24 * 3600
DURATION_TWENTY_MINUTES
Value: 1200
DURATION_ONE_MINUTE
Value: 60
WINDOW_SIZE
Value: 600