pronto-pg

Async PostgreSQL connection pool helper for FastAPI (and any async Python) projects. Wraps psycopg3 with a module-level pool and a ready-made FastAPI lifespan hook.

Installation

pip install pronto-pg

Quick start — FastAPI

from fastapi import FastAPI
from pronto_pg.v1 import make_lifespan, get_connection

app = FastAPI(lifespan=make_lifespan("DATABASE_URL"))

@app.get("/users")
async def list_users():
    async with get_connection() as conn:
        rows = await conn.execute("SELECT id, email FROM users")
        return await rows.fetchall()

Set your DSN in the environment (e.g. via .env + python-dotenv):

DATABASE_URL=postgresql://user:pass@host:5432/mydb

Pass any env var name to make_lifespan — PG_DATABASE_URL, MY_DATABASE_URL, whatever fits your project.

API

make_lifespan(env_var="DATABASE_URL", min_size=2, max_size=10)

Returns a FastAPI-compatible lifespan context manager. Opens the pool on startup, closes it on shutdown.

app = FastAPI(lifespan=make_lifespan("PG_DATABASE_URL"))

init_pool(dsn, min_size=2, max_size=10)

Open the pool with an explicit DSN string.

init_pool_from_env(env_var="DATABASE_URL", min_size=2, max_size=10)

Open the pool by reading the DSN from an environment variable. Raises RuntimeError if the variable is missing or empty.

close_pool()

Drain and close the pool. Called automatically by make_lifespan.

get_connection()

Async context manager that yields a psycopg.AsyncConnection in autocommit mode. Use async with conn.transaction(): for explicit transactions.

async with get_connection() as conn:
    await conn.execute("INSERT INTO events (type) VALUES (%s)", ["login"])

Manual lifespan (without make_lifespan)

from contextlib import asynccontextmanager
from fastapi import FastAPI
from pronto_pg.v1 import init_pool_from_env, close_pool

@asynccontextmanager
async def lifespan(app):
    await init_pool_from_env("DATABASE_URL")
    yield
    await close_pool()

app = FastAPI(lifespan=lifespan)

Development

pip install -e ".[dev]"
pytest

Versioning

Versions are derived from git tags via hatch-vcs.

git tag v0.1.0
hatch build