An asynchronous Postgres client mixin for Tornado applications
Find a file
Gavin M. Roy 664bedbb24 Don't blindly swallow ProgrammingError
ProgrammingError is raised when you try and fetch data from a cursor and there is no data to fetch. When this happens ProgrammingError.pgcode is None.

It is also raised when your query has errors in it. Now if that's the case, they will be caught on L249 and not inside the function at L259.

This new branch in the code will ensure that should we unexpectedly encounter a "real" programming error from Postgres, it is not blindly swallowed and a warning is issued. This should NEVER happen based upon my understanding of the psycopg2 internals.

Unfortunately I couldn't come up with a good test case using mocks to make it happen, as ProgrammingError() takes no keyword arguments and pgcode is a read-only attribute on a ProgrammingError instance. I also couldn't figure out a way to raise ProgrammingError from psycopg2.errors.lookup/1.

Thus, the # pragma: nocover
2020-08-11 19:25:34 -04:00
.github/workflows Include libffi-dev for testing 2020-06-02 11:34:11 -04:00
docs Add reconfiguration for SRV based connections 2020-07-07 16:17:56 -04:00
fixtures Don't blindly swallow ProgrammingError 2020-08-11 19:25:34 -04:00
.editorconfig Initial WIP commit 2020-04-06 17:39:52 -04:00
.gitignore Initial commit 2020-04-06 12:27:33 -04:00
bootstrap Testing update and fixes found in testing 2020-04-07 16:59:06 -04:00
CONTRIBUTING.md Add CONTRIBUTING info 2020-04-08 18:23:42 -04:00
docker-compose.yml Testing update and fixes found in testing 2020-04-07 16:59:06 -04:00
LICENSE Initial WIP commit 2020-04-06 17:39:52 -04:00
MANIFEST.in Include the VERSION file when packaging 2020-04-06 17:49:03 -04:00
README.rst Include aiodns in the requirements list 2020-06-02 11:32:44 -04:00
setup.cfg Include aiodns in the requirements list 2020-06-02 11:32:44 -04:00
setup.py Initial WIP commit 2020-04-06 17:39:52 -04:00
sprockets_postgres.py Don't blindly swallow ProgrammingError 2020-08-11 19:25:34 -04:00
tests.py Don't blindly swallow ProgrammingError 2020-08-11 19:25:34 -04:00
VERSION Delay the initialization of asyncio objects to on_start 2020-07-08 14:33:04 -04:00

Sprockets Postgres
==================
An set of mixins and classes for interacting with PostgreSQL using asyncio in
Tornado / sprockets.http applications using aiopg.

|Version| |Status| |Coverage| |License|

Installation
------------
``sprockets-postgres`` is available on the Python package index and is installable via pip:

.. code:: bash

    pip install sprockets-postgres

Documentation
-------------
Documentation is available at `sprockets-postgres.readthedocs.io <https://sprockets-postgres.readthedocs.io>`_.

Configuration
-------------
The following table details the environment variable configuration options:

+---------------------------------+--------------------------------------------------+-----------+
| Variable                        | Definition                                       | Default   |
+=================================+==================================================+===========+
| ``POSTGRES_URL``                | The PostgreSQL URL to connect to                 |           |
+---------------------------------+--------------------------------------------------+-----------+
| ``POSTGRES_MAX_POOL_SIZE``      | Maximum connection count to Postgres per backend | ``10``    |
+---------------------------------+--------------------------------------------------+-----------+
| ``POSTGRES_MIN_POOL_SIZE``      | Minimum or starting pool size.                   | ``1``     |
+---------------------------------+--------------------------------------------------+-----------+
| ``POSTGRES_CONNECTION_TIMEOUT`` | The maximum time in seconds to spend attempting  | ``10``    |
|                                 | to create a new connection.                      |           |
+---------------------------------+--------------------------------------------------+-----------+
| ``POSTGRES_CONNECTION_TTL``     | Time-to-life in seconds for a pooled connection. | ``300``   |
+---------------------------------+--------------------------------------------------+-----------+
| ``POSTGRES_QUERY_TIMEOUT``      | Maximum execution time for a query in seconds.   | ``60``    |
+---------------------------------+--------------------------------------------------+-----------+
| ``POSTGRES_HSTORE``             | Enable HSTORE support in the client.             | ``FALSE`` |
+---------------------------------+--------------------------------------------------+-----------+
| ``POSTGRES_JSON``               | Enable JSON support in the client.               | ``FALSE`` |
+---------------------------------+--------------------------------------------------+-----------+
| ``POSTGRES_UUID``               | Enable UUID support in the client.               | ``TRUE``  |
+---------------------------------+--------------------------------------------------+-----------+

If ``POSTGRES_URL`` uses a scheme of ``postgresql+srv``, a SRV DNS lookup will be
performed and the lowest priority record with the highest weight will be selected
for connecting to Postgres.

AWS's ECS service discovery does not follow the SRV standard, but creates SRV
records. If ``POSTGRES_URL`` uses a scheme of ``aws+srv``, a SRV DNS lookup will be
performed using the correct format for ECS service discovery. The lowest priority
record with the highest weight will be selected for connecting to Postgres.

Requirements
------------
- `aiodns <https://github.com/saghul/aiodns>`_
- `aiopg <https://aioboto3.readthedocs.io/en/latest/>`_
- `sprockets.http <https://sprocketshttp.readthedocs.io/en/master/>`_
- `Tornado <https://tornadoweb.org>`_

Version History
---------------
Available at https://sprockets-postgres.readthedocs.org/en/latest/history.html

.. |Version| image:: https://img.shields.io/pypi/v/sprockets-postgres.svg?
   :target: https://pypi.python.org/pypi/sprockets-postgres

.. |Status| image:: https://github.com/sprockets/sprockets-postgres/workflows/Testing/badge.svg?
   :target: https://github.com/sprockets/sprockets-postgres/actions?workflow=Testing
   :alt: Build Status

.. |Coverage| image:: https://img.shields.io/codecov/c/github/sprockets/sprockets-postgres.svg?
   :target: https://codecov.io/github/sprockets/sprockets-postgres?branch=master

.. |License| image:: https://img.shields.io/pypi/l/sprockets-postgres.svg?
   :target: https://sprockets-postgres.readthedocs.org