Skip to main content

PostgreSQL client for Trio based on asyncpg

Project description

Automated test status (Linux and MacOS) Automated test status (Windows) Test coverage

triopg

Welcome to triopg!

PostgreSQL client for Trio based on asyncpg.

License: Your choice of MIT or Apache License 2.0

Quick example:

import trio_asyncio
import triopg


async def main():
    async with triopg.connect() as conn:

        await conn.execute(
            """
            DROP TABLE IF EXISTS users;
            CREATE TABLE IF NOT EXISTS users (
                _id SERIAL PRIMARY KEY,
                user_id VARCHAR(32) UNIQUE
            )"""
        )

        async with conn.transaction():
            await conn.execute("INSERT INTO users (user_id) VALUES (1)")
            await conn.execute("INSERT INTO users (user_id) VALUES (2)")
            await conn.execute("INSERT INTO users (user_id) VALUES (3)")

        print(await conn.fetch("SELECT * FROM users"))


trio_asyncio.run(main)

API basics

triopg is a thin Trio-compatible wrapper around asyncpg. The API is the same, with one exception - triopg does not support manual resource management. In asyncpg you can manage pools, connections and transactions manually:

conn = await asyncpg.connect()
tr = conn.transaction()
# ..
tr.commit()
conn.close()

While in triopg you can only use async with blocks:

async with triopg.connect() as conn:
    async with conn.transaction():
        # ...

Otherwise you can follow asyncpg tutorial and reference. Everything should work the same way. Please file an issue if it doesn’t.

Helpers

In addition to asyncpg-compatible API, triopg provides Trio-style .listen() helper for the eponymous Postgres statement:

async with conn.listen('some.channel', max_buffer_size=1) as notifications:
    async for notification in notifications:
        if notification != triopg.NOTIFY_OVERFLOW:
            print('Notification received:', notification)

max_buffer_size is the amount of notifications you are willing to queue in memory.

If you don’t want to think about buffering, set the buffer size to math.inf and everything will just work in regular non-pathological situations.

Otherwise, you can set a finite buffer. In this case you should handle triopg.NOTIFY_OVERFLOW marker and react according to your use case. For example, you could re-scan the tables, like you would do at startup. Or could you simply ignore the marker if you are only interested in the newest notifications.

For detailed discussion on buffering, see Trio manual, “Buffering in channels” section.

Note: we can’t politely ask Postgres to slow down: LISTEN backpressure is not supported by asyncpg. There’s also an inherent challenge with Postgres. Postgres (like most broadcast systems) doesn’t really have a good way to communicate backpressure further upstream to the clients that are calling NOTIFY.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

triopg-0.6.0.tar.gz (19.7 kB view details)

Uploaded Source

Built Distribution

triopg-0.6.0-py3-none-any.whl (13.8 kB view details)

Uploaded Python 3

File details

Details for the file triopg-0.6.0.tar.gz.

File metadata

  • Download URL: triopg-0.6.0.tar.gz
  • Upload date:
  • Size: 19.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/39.0.1 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.6.9

File hashes

Hashes for triopg-0.6.0.tar.gz
Algorithm Hash digest
SHA256 ead3505aa702da02e4ec78710385cfa3c216747279d0ab4e6c37fff4236ff162
MD5 ff733f997678fff5ac7338694bb329e9
BLAKE2b-256 5aa90b2d1d66d922f4712c710de87c90adf073e252737a846e77b981eeb95688

See more details on using hashes here.

Provenance

File details

Details for the file triopg-0.6.0-py3-none-any.whl.

File metadata

  • Download URL: triopg-0.6.0-py3-none-any.whl
  • Upload date:
  • Size: 13.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/39.0.1 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.6.9

File hashes

Hashes for triopg-0.6.0-py3-none-any.whl
Algorithm Hash digest
SHA256 a65147183c0992d0902f6acdeb2b177bb23efbff1ca971ee4f480d02c9cd5442
MD5 0a85ff8cee0a7f5982a1be448cc2f3dc
BLAKE2b-256 9579adb39234737385586bb407ed854355556120db982074724b972be30d7b18

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page