To help you get started, we've collected the most common ways that aiopg is being used within popular public projects.

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.

Example

import asyncio
import aiopg

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

async def go():
    pool = await aiopg.create_pool(dsn)
    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())

Example of SQLAlchemy optional integration

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 create_table(engine):
    async with engine.acquire() as conn:
        await conn.execute('DROP TABLE IF EXISTS tbl')
        await conn.execute('''CREATE TABLE tbl (
                                  id serial PRIMARY KEY,
                                  val varchar(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()):
                print(row.id, row.val)

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

Please use:

$ make test

for executing the project's unittests. See for details on how to set up your environment to run the tests.

Changelog

1.4.0 (2022-10-26)

• Add python 3.11 and drop python 3.6 support#892

1.3.5 (2022-09-25)

• Fix pool size limit check for unlimited pools #888

1.3.4 (2022-06-30)

1.3.4b3 (2022-06-29)

1.3.4b2 (2022-06-29)

1.3.4b1 (2022-06-29)

• Fix compatibility with SA 1.4.38 #891
• Add py.typed marker #878

1.3.3 (2021-11-01)

• Support async-timeout 4.0+

1.3.2 (2021-10-07)

1.3.2b2 (2021-10-07)

• Respect use_labels for select statement #882

1.3.2b1 (2021-07-11)

• Fix compatibility with SQLAlchemy >= 1.4 #870

1.3.1 (2021-07-08)

1.3.1b2 (2021-07-06)

• Suppress "Future exception was never retrieved" #862

1.3.1b1 (2021-07-05)

• Fix ClosableQueue.get on cancellation, close it on Connection.close #859

1.3.0 (2021-06-30)

1.3.0b4 (2021-06-28)

• Fix "Unable to detect disconnect when using NOTIFY/LISTEN" #559

1.3.0b3 (2021-04-03)

• Reformat using black #814

1.3.0b2 (2021-04-02)

• Type annotations #813

1.3.0b1 (2021-03-30)

• Raise ResourceClosedError if we try to open a cursor on a closed SAConnection #811

1.3.0b0 (2021-03-25)

• Fix compatibility with SA 1.4 for IN statement #806

1.2.1 (2021-03-23)

• Pop loop in connection init due to backward compatibility #808

1.2.0b4 (2021-03-23)

• Set max supported sqlalchemy version #805

1.2.0b3 (2021-03-22)

• Don't run ROLLBACK when the connection is closed #778
• Multiple cursors support #801

1.2.0b2 (2020-12-21)

• Fix IsolationLevel.read_committed and introduce IsolationLevel.default #770
• Fix python 3.8 warnings in tests #771

1.2.0b1 (2020-12-16)

• Deprecate blocking connection.cancel() method #570

1.2.0b0 (2020-12-15)

• Implement timeout on acquiring connection from pool #766

1.1.0 (2020-12-10)

1.1.0b2 (2020-12-09)

• Added missing slots to context managers #763

1.1.0b1 (2020-12-07)

• Fix on_connect multiple call on acquire #552
• Fix python 3.8 warnings #622
• Bump minimum psycopg version to 2.8.4 #754
• Fix Engine.release method to release connection in any way #756

1.0.0 (2019-09-20)

• Removal of an asynchronous call in favor of issues # 550
• Big editing of documentation and minor bugs #534

0.16.0 (2019-01-25)

• Fix select priority name #525
• Rename psycopg2 to psycopg2-binary to fix deprecation warning #507
• Fix #189 hstore when using ReadDictCursor #512
• close cannot be used while an asynchronous query is underway #452
• sqlalchemy adapter trx begin allow transaction_mode #498

0.15.0 (2018-08-14)

• Support Python 3.7 #437

0.14.0 (2018-05-10)

• Add get_dialect func to have ability to pass json_serializer #451

0.13.2 (2018-01-03)

• Fixed compatibility with SQLAlchemy 1.2.0 #412
• Added support for transaction isolation levels #219

0.13.1 (2017-09-10)

• Added connection poll recycling logic #373

0.13.0 (2016-12-02)

• Add async with support to .begin_nested() #208
• Fix connection.cancel() #212 #223
• Raise informative error on unexpected connection closing #191
• Added support for python types columns issues #217
• Added support for default values in SA table issues #206

0.12.0 (2016-10-09)

• Add an on_connect callback parameter to pool #141
• Fixed connection to work under both windows and posix based systems #142

0.11.0 (2016-09-12)

• Immediately remove callbacks from a closed file descriptor #139
• Drop Python 3.3 support

0.10.0 (2016-07-16)

• Refactor tests to use dockerized Postgres server #107
• Reduce default pool minsize to 1 #106
• Explicitly enumerate packages in setup.py #85
• Remove expired connections from pool on acquire #116
• Don't crash when Connection is GC'ed #124
• Use loop.create_future() if available

0.9.2 (2016-01-31)

• Make pool.release return asyncio.Future, so we can wait on it in __aexit__ #102
• Add support for uuid type #103

0.9.1 (2016-01-17)

• Documentation update #101

0.9.0 (2016-01-14)

• Add async context managers for transactions #91
• Support async iterator in ResultProxy #92
• Add async with for engine #90

0.8.0 (2015-12-31)

• Add PostgreSQL notification support #58
• Support pools with unlimited size #59
• Cancel current DB operation on asyncio timeout #66
• Add async with support for Pool, Connection, Cursor #88

0.7.0 (2015-04-22)

• Get rid of resource leak on connection failure.
• Report ResourceWarning on non-closed connections.
• Deprecate iteration protocol support in cursor and ResultProxy.
• Release sa connection to pool on connection.close().

0.6.0 (2015-02-03)

• Accept dict, list, tuple, named and positional parameters in SAConnection.execute()

0.5.2 (2014-12-08)

• Minor release, fixes a bug that leaves connection in broken state after cursor.execute() failure.

0.5.1 (2014-10-31)

• Fix a bug for processing transactions in line.

0.5.0 (2014-10-31)

• Add .terminate() to Pool and Engine
• Reimplement connection pool (now pool size cannot be greater than pool.maxsize)
• Add .close() and .wait_closed() to Pool and Engine
• Add minsize, maxsize, size and freesize properties to sa.Engine
• Support echo parameter for logging executed SQL commands
• Connection.close() is not a coroutine (but we keep backward compatibility).

0.4.1 (2014-10-02)

• make cursor iterable
• update docs

0.4.0 (2014-10-02)

• add timeouts for database operations.
• Autoregister psycopg2 support for json data type.
• Support JSON in aiopg.sa
• Support ARRAY in aiopg.sa
• Autoregister hstore support if present in connected DB
• Support HSTORE in aiopg.sa

0.3.2 (2014-07-07)

• change signature to cursor.execute(operation, parameters=None) to follow psycopg2 convention.

0.3.1 (2014-07-04)

• Forward arguments to cursor constructor for pooled connections.

0.3.0 (2014-06-22)

• Allow executing SQLAlchemy DDL statements.
• Fix bug with race conditions on acquiring/releasing connections from pool.

0.2.3 (2014-06-12)

• Fix bug in connection pool.

0.2.2 (2014-06-07)

• Fix bug with passing parameters into SAConnection.execute when executing raw SQL expression.

0.2.1 (2014-05-08)

• Close connection with invalid transaction status on returning to pool.

0.2.0 (2014-05-04)

• Implemented optional support for sqlalchemy functional sql layer.

0.1.0 (2014-04-06)

• Implemented plain connections: connect, Connection, Cursor.
• Implemented database pools: create_pool and Pool.