Welcome to AIOPG

aiopg is a library for accessing a PostgreSQL database from the asyncio (PEP-3156/tulip) framework. It wraps asynchronous features of the Psycopg database driver.

Current version is 1.2.1.

Travis CI status Code coverage status Latest PyPI package version

Warning

  1. Removing await the before Cursor.mogrify() function

  2. Only supports python >= 3.6

  3. Only support syntax async/await

  4. Only use get_running_loop

Features

Basics

The library uses psycopg2-binary connections in asynchronous mode internally.

Literally it is an (almost) transparent wrapper for psycopg2-binary connection and cursor, but with only exception.

You should use await conn.f() instead of just call conn.f() for every method.

Properties are unchanged, so conn.prop is correct as well as conn.prop = val.

See example:

import asyncio
import aiopg

dsn = 'dbname=aiopg user=aiopg password=passwd host=127.0.0.1'

async def go():
    async with aiopg.create_pool(dsn) as pool:
        async with pool.acquire() as conn:
            async with conn.cursor() as cur:
                await cur.execute("SELECT 1")
                ret = []
                async for row in cur:
                    ret.append(row)
                assert ret == [(1,)]

loop = asyncio.get_event_loop()
loop.run_until_complete(go())

For documentation about connection and cursor methods/properties please go to psycopg docs: http://initd.org/psycopg/docs/

Note

psycopg2-binary creates new connections with autocommit=True option in asynchronous mode. Autocommitting cannot be disabled.

See Transactions about transaction usage in autocommit mode.

SQLAlchemy and aiopg

Core API Reference provides core support for PostgreSQL connections.

We have found it to be very annoying to write raw SQL queries manually, so we introduce support for sqlalchemy query builders:

import asyncio
from aiopg.sa import create_engine
import sqlalchemy as sa


metadata = sa.MetaData()

tbl = sa.Table('tbl', metadata,
               sa.Column('id', sa.Integer, primary_key=True),
               sa.Column('val', sa.String(255)))

async def go():
    async with create_engine(user='aiopg',
                             database='aiopg',
                             host='127.0.0.1',
                             password='passwd') as engine:
        async with engine.acquire() as conn:
            await conn.execute(tbl.insert().values(val='abc'))

            async for row in conn.execute(tbl.select().where(tbl.c.val=='abc')):
                print(row.id, row.val)


loop = asyncio.get_event_loop()
loop.run_until_complete(go())

We believe constructions like tbl.insert().values(val='abc') and tbl.select().where(tbl.c.val=='abc') to be very handy and convenient.

Installation

pip3 install aiopg

Note

aiopg requires psycopg2-binary library.

You can use global environment or you use like to use virtual environments (virtualenvwrapper, virtualenv or venv) you probably have to install libpq development package

$ sudo apt-get install libpq-dev

Also you probably want to use aiopg.sa.

aiopg.sa module is optional and requires sqlalchemy. You can install sqlalchemy by running

$ pip3 install aiopg[sa]

Source code

The project is hosted on GitHub

Please feel free to file an issue on bug tracker if you have found a bug or have some suggestion for library improvement.

The library uses Travis for Continious Integration.

Discussion list

aio-libs google group: https://groups.google.com/forum/#!forum/aio-libs

Feel free to post your questions and ideas here.

Dependencies

  • Python 3.6+

  • psycopg2-binary

  • aiopg.sa requires sqlalchemy.