Cloud Spanner Client - Class CacheSessionPool (1.78.0)

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
]);

Acquire a session from the pool.

Release a session back to the pool.

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.

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.

Create enough sessions to meet the minimum session constraint.

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.

Set the database used to make calls to manage sessions.

Get the underlying cache implementation.

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.