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.
Features¶
- Implements asyncio DBAPI like interface for PostgreSQL. It includes Connection, Cursor and Pool objects.
- Implements optional support for charming sqlalchemy functional sql layer.
Basics¶
The library uses psycopg2
connections in asynchronous mode
internally.
Literally it is an (almost) transparent wrapper for psycopg2 connection and cursor, but with only exception.
You should use yield from 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'
@asyncio.coroutine
def go():
pool = yield from aiopg.create_pool(dsn)
with (yield from pool.cursor()) as cur:
yield from cur.execute("SELECT 1")
ret = yield from cur.fetchone()
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 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)))
@asyncio.coroutine
def go():
engine = yield from create_engine(user='aiopg',
database='aiopg',
host='127.0.0.1',
password='passwd')
with (yield from engine) as conn:
yield from conn.execute(tbl.insert().values(val='abc'))
res = yield from conn.execute(tbl.select().where(tbl.c.val=='abc'))
for row in res:
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
convinient.
Installation¶
pip3 install aiopg
Note
aiopg
requires psycopg2 library.
You can use standard one from your distro like:
$ sudo apt-get install python3-psycopg2
but if you 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 sqlalchemy
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.
Dependencies¶
- Python 3.3 and
asyncio
or Python 3.4+ - psycopg2
- aiopg.sa requires sqlalchemy.
Authors and License¶
The aiopg
package is written by Andrew Svetlov. It’s BSD
licensed and freely available.
Feel free to improve this package and send a pull request to GitHub.
Contents: