aiopg

library1.4.0pypypi✓ verified 22d ago

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. The current version is 1.4.0, and it is actively maintained by the aio-libs organization, though the last release was in October 2022.

database http-networking

pip install aiopg

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AIOPG

aiopg

databasepythonv1.4.0

Install

2.8s avg

Import

249ms

Disk

44MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.267s · 46.6MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.8s · import 0.231s · 45MB

44MB installed

● package 44MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

aiopg

✓ import aiopg

create_pool

✓ import aiopg await aiopg.create_pool(...)

create_engine

✓ from aiopg.sa import create_engine

✗ import aiopg.sa

For SQLAlchemy integration, create_engine is typically imported directly from aiopg.sa.

This quickstart demonstrates how to establish an asynchronous connection pool, acquire a connection, execute a simple query, and fetch results using aiopg. It includes error handling for already running event loops common in interactive environments. Ensure your PostgreSQL instance is running and accessible with the provided DSN, or set the AIOPG_DSN environment variable.

import asyncio import aiopg import os dsn = os.environ.get('AIOPG_DSN', 'dbname=aiopg user=aiopg password=passwd host=127.0.0.1') async def main(): # Establish a connection pool async with aiopg.create_pool(dsn) as pool: # Acquire a connection from the pool async with pool.acquire() as conn: # Open a cursor to perform database operations async with conn.cursor() as cur: # Execute a simple query await cur.execute("SELECT 1") ret = [] # Iterate over the results async for row in cur: ret.append(row) assert ret == [(1,)] print(f"Query result: {ret}") if __name__ == '__main__': # For Python 3.10+ try: asyncio.run(main()) except RuntimeError as e: if "cannot run an event loop while another loop is running" in str(e): # Handle cases where an event loop might already be running (e.g., in notebooks) loop = asyncio.get_event_loop() if loop.is_running(): loop.create_task(main()) else: loop.run_until_complete(main()) else: raise

Debug

Known issues

breakingaiopg internally uses `psycopg2-binary` connections in `autocommit=True` mode for asynchronous operations. This means `conn.commit()` and `conn.rollback()` methods are disabled and will raise `psycopg2.ProgrammingError`. Transactions must be explicitly managed by executing `BEGIN` and `COMMIT`/`ROLLBACK` SQL statements manually.

fix

Do not call `conn.commit()` or `conn.rollback()`. Instead, explicitly execute SQL: `await cur.execute('BEGIN')`, then `await cur.execute('COMMIT')` or `await cur.execute('ROLLBACK')`.

affects: <1.0.0 (behavior established early)

gotchaAlmost all connection and cursor methods in aiopg are coroutines and *must* be `await`ed. However, `Cursor.mogrify()` specifically had its `await` requirement removed in a later version and should now be called synchronously.

fix

Ensure all `aiopg` connection and cursor methods are `await`ed, e.g., `await conn.execute(...)`, `await cur.fetchone()`. For `cur.mogrify()`, do not use `await`.

affects: All versions

deprecatedIteration protocol support in `cursor` and `ResultProxy` was deprecated in version 0.7.0. While still functional for older codebases, relying on direct iteration for results might lead to unexpected behavior or future breakage.

fix

Prefer explicit iteration using `async for row in cur:` for cursors, and `await result.fetchall()` or `async for row in result:` for `ResultProxy` objects, rather than synchronous iteration.

affects: >=0.7.0

gotchaaiopg requires Python 3.7+ and only supports the `async/await` syntax. Older `asyncio` patterns (e.g., `@asyncio.coroutine` decorators) are not supported.

fix

Ensure your project uses Python 3.7 or newer and exclusively uses `async def` and `await` for asynchronous code.

affects: <1.0.0 (modern asyncio syntax enforced)

gotchaWhen creating a cursor via `conn.cursor()`, some parameters like `name`, `scrollable`, and `withhold` are not supported by `psycopg2-binary` in asynchronous mode and will be ignored or raise errors if specified. Only `cursor_factory` and `timeout` are reliably supported.

fix

Avoid passing `name`, `scrollable`, or `withhold` to `conn.cursor()`. If custom cursor behavior is needed, use `cursor_factory`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'fcntl'

The 'fcntl' module is not available on Windows systems, causing import errors when using aiopg.

fix

Upgrade to aiopg version 0.12 or later, which includes support for Windows by handling the absence of the 'fcntl' module.

NotImplementedError

The default ProactorEventLoop on Windows does not support certain operations required by aiopg.

fix

Set the event loop policy to WindowsSelectorEventLoopPolicy by adding 'asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())' before running your asyncio code.

psycopg2.ProgrammingError: copy_from cannot be used in asynchronous mode

The 'copy_from' method is not supported in asynchronous mode with aiopg.

fix

Use the synchronous psycopg2 library for operations requiring 'copy_from', or find an alternative method compatible with asynchronous execution.

ModuleNotFoundError: No module named 'aiopg'

The 'aiopg' library has not been installed in the current Python environment.

fix

Install the library using pip: `pip install aiopg`.

TypeError: __init__() takes 5 positional arguments

The `aiopg.Pool` constructor was called with an incorrect number of positional arguments. The `aiopg.Pool` typically expects `dsn`, `minsize`, `maxsize`, and `timeout`.

fix

Ensure `aiopg.Pool` is initialized with the correct parameters, usually `dsn`, `minsize`, `maxsize`, and `timeout`. For example: `await aiopg.create_pool(dsn='dbname=test', minsize=1, maxsize=10, timeout=30)`.

Upgrade

Version history

1.4.0latest on PyPI · released Oct 26, 2022

Audit

Dependencies

psycopg2-binaryrequiredRequired for PostgreSQL database connectivity.

SQLAlchemyoptionalOptional, for using the aiopg.sa module for SQLAlchemy functional SQL layer support.

Agent activity

44 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/aio-libs/aiopg ↗

packagehttps://pypi.org/project/aiopg/ ↗

homepagehttps://aiopg.readthedocs.io ↗