Advanced Session Pool Topics

Custom Session Pool Implementations

You can supply your own pool implementation, which must satisfy the

contract laid out in

:class:`~google.cloud.spanner.pool.AbstractSessionPool`:

.. code-block:: python

Lowering latency for read / query operations

Some applications may need to minimize latency for read operations, including

particularly the overhead of making an API request to create or refresh a

session. :class:`~google.cloud.spanner.pool.PingingPool` is designed for such

applications, which need to configure a background thread to do the work of

keeping the sessions fresh.

Create an instance of :class:`~google.cloud.spanner.pool.PingingPool`:

.. code-block:: python

Set up a background thread to ping the pool's session, keeping them

from becoming stale:

.. code-block:: python

Lowering latency for mixed read-write operations

Some applications may need to minimize latency for read write operations,

including particularly the overhead of making an API request to create or

refresh a session or to begin a session's transaction.

:class:`~google.cloud.spanner.pool.TransactionPingingPool` is designed for

such applications, which need to configure a background thread to do the work

of keeping the sessions fresh and starting their transactions after use.

Create an instance of

:class:`~google.cloud.spanner.pool.TransactionPingingPool`:

.. code-block:: python

Set up a background thread to ping the pool's session, keeping them

from becoming stale, and ensuring that each session has a new transaction

started before it is used:

.. code-block:: python

Non-Admin Database Usage

A snapshot represents a read-only point-in-time view of the database.

Calling :meth:`~google.cloud.spanner.database.Database.snapshot` with

no arguments creates a snapshot with strong concurrency:

.. code:: python

See :class:`~google.cloud.spanner.snapshot.Snapshot` for the other options

which can be passed.

.. note::

:meth:`~google.cloud.spanner.database.Database.snapshot` returns an

object intended to be used as a Python context manager (i.e., as the

target of a ``with`` statement). Use the instance, and any result

sets returned by its ``read`` or ``execute_sql`` methods, only inside

the block created by the ``with`` statement.

See :doc:`snapshot-usage` for more complete examples of snapshot usage.

Use a Batch to Modify Rows in the Database

A batch represents a bundled set of insert/upsert/update/delete operations

on the rows of tables in the database.

.. code:: python

.. note::

:meth:`~google.cloud.spanner.database.Database.batch` returns an

object intended to be used as a Python context manager (i.e., as the

target of a ``with`` statement). It applies any changes made inside

the block of its ``with`` statement when exiting the block, unless an

exception is raised within the block. Use the batch only inside

the block created by the ``with`` statement.

See :doc:`batch-usage` for more complete examples of batch usage.

Use a Transaction to Query / Modify Rows in the Database

A transaction represents the union of a "strong" snapshot and a batch:

it allows ``read`` and ``execute_sql`` operations, and accumulates

insert/upsert/update/delete operations.

Because other applications may be performing concurrent updates which

would invalidate the reads / queries, the work done by a transaction needs

to be bundled as a retryable "unit of work" function, which takes the

transaction as a required argument:

.. code:: python

.. note::

:meth:`~google.cloud.spanner.database.Database.run_in_transaction`

commits the transaction automatically if the "unit of work" function

returns without raising an exception.

.. note::

:meth:`~google.cloud.spanner.database.Database.run_in_transaction`

retries the "unit of work" function if the read / query operatoins

or the commit are aborted due to concurrent updates

See :doc:`transaction-usage` for more complete examples of transaction usage.

Configuring a session pool for a database

Under the covers, the ``snapshot``, ``batch``, and ``run_in_transaction``

methods use a pool of :class:`~google.cloud.spanner.session.Session` objects

to manage their communication with the back-end. You can configure

one of the pools manually to control the number of sessions, timeouts, etc.,

and then passing it to the :class:`~google.cloud.spanner.database.Database`

constructor:

.. code-block:: python

Note that creating a database with a pool may presume that its database

already exists, as it may need to pre-create sessions (rather than creating

them on demand, as the default implementation does).

You can supply your own pool implementation, which must satisfy the

contract laid out in :class:`~google.cloud.spanner.pool.AbstractSessionPool`:

.. code-block:: python

See :doc:`advanced-session-pool-topics` for more advanced coverage of

session pools.