RequestHandler Mixin¶

The RequestHandlerMixin is a Tornado tornado.web.RequestHandler mixin that provides easy to use functionality for interacting with PostgreSQL.

class sprockets_postgres.RequestHandlerMixin[source]¶

A RequestHandler mixin class exposing functions for querying the database, recording the duration to either sprockets-influxdb or sprockets.mixins.metrics, and handling exceptions.

async postgres_callproc(name, parameters=None, metric_name='', *, timeout=None)[source]¶

Execute a stored procedure / function

Parameters

name (str) – The stored procedure / function name to call
parameters (QueryParameters) – Query parameters to pass when calling
metric_name (str) – The metric name for duration recording and logging
timeout (Timeout) – Timeout value to override the default or the value specified when creating the PostgresConnector.

Raises

asyncio.TimeoutError – when there is a query or network timeout
psycopg2.Error – when there is an exception raised by Postgres

Return type: QueryResult

async postgres_execute(sql, parameters=None, metric_name='', *, timeout=None)[source]¶

Execute a query, specifying a name for the query, the SQL statement, and optional positional arguments to pass in with the query.

Parameters may be provided as sequence or mapping and will be bound to variables in the operation. Variables are specified either with positional %s or named %({name})s placeholders.

Parameters

sql (str) – The SQL statement to execute
parameters (QueryParameters) – Query parameters to pass as part of the execution
metric_name (str) – The metric name for duration recording and logging
timeout (Timeout) – Timeout value to override the default or the value specified when creating the PostgresConnector.

Raises

asyncio.TimeoutError – when there is a query or network timeout
psycopg2.Error – when there is an exception raised by Postgres

Return type: QueryResult

postgres_transaction(timeout=None)[source]¶

asynchronous context-manager function that implements full BEGIN, COMMIT, and ROLLBACK semantics. If there is a psycopg2.Error raised during the transaction, the entire transaction will be rolled back.

If no exception is raised, the transaction will be committed when exiting the context manager.

Usage Example

class RequestHandler(sprockets_postgres.RequestHandlerMixin,
                     web.RequestHandler):

async def post(self):
    async with self.postgres_transaction() as transaction:
        result1 = await transaction.execute(QUERY_ONE)
        result2 = await transaction.execute(QUERY_TWO)
        result3 = await transaction.execute(QUERY_THREE)

Parameters

timeout (Timeout) – Timeout value to override the default or the value specified when creating the PostgresConnector.

Raises

asyncio.TimeoutError – when there is a query or network timeout when starting the transaction
psycopg2.Error – when there is an exception raised by Postgres when starting the transaction

Return type: typing.AbstractAsyncContextManager[sprockets_postgres.PostgresConnector]

on_postgres_error(metric_name, exc)[source]¶

Invoked when an error occurs when executing a query

If tornado-problem-details is available, problemdetails.Problem will be raised instead of tornado.web.HTTPError.

Override for different error handling behaviors.

Return an exception if you would like for it to be raised, or swallow it here.

Parameters

metric_name (str) –
exc (Exception) –

Return type

typing.Optional[Exception]

on_postgres_timing(metric_name, duration)[source]¶

Override for custom metric recording. As a default behavior it will attempt to detect sprockets-influxdb and sprockets.mixins.metrics and record the metrics using them if they are available. If they are not available, it will record the query duration to the DEBUG log.

Parameters

metric_name (str) – The name of the metric to record
duration (float) – The duration to record for the metric

Return type

None

_postgres_connection_check()[source]¶

Ensures Postgres is connected, exiting the request in error if not

Raises: problemdetails.Problem
Raises: web.HTTPError

The StatusRequestHandler is a Tornado tornado.web.RequestHandler that can be used for application health monitoring. If the Postgres connection is unavailable, it will report the API as unavailable and return a 503 status code.

class sprockets_postgres.StatusRequestHandler(application, request, **kwargs)[source]¶

A RequestHandler that can be used to expose API health or status

Parameters

application (tornado.web.Application) –
request (tornado.httputil.HTTPServerRequest) –
kwargs (typing.Any) –

async get(*_args, **_kwarg)[source]¶