Type-safe Python from your SQL

A sqlc plugin that generates modern, fully typed Python database code from plain SQL - models plus async query functions.

Documentation Join the Discord

Four model types

Generate dataclass, attrs, msgspec, or pydantic models - pick per codegen block.

Seven drivers

asyncpg and psycopg for PostgreSQL, aiosqlite and sqlite3 for SQLite, and experimental turso support.

Strictly typed output

Generated code passes pyright strict and ruff, targeting Python 3.12+.

Enums

PostgreSQL enums become enum.StrEnum classes, wired through models and queries.

Type overrides & converters

Swap a column’s Python type, or plug in your own encode/decode functions.

Docstrings

Optional google, numpy, or pep257 docstrings on every generated function.

Used by

Projects running their database layer on generated code:

nMarkov - a Discord chatbot that learns from your server's messages and generates its own.

Using sqlc-gen-better-python in your project? Open an issue to get listed here.

From SQL to Python

You write a query, annotated with the name and shape you want:

-- name: GetUser :one
SELECT * FROM users WHERE id = $1;

and get a typed function back, with a model built from your schema:

async def get_user(conn: ConnectionLike, *, id_: int) -> models.User | None:
    row = await conn.fetchrow(GET_USER, id_)
    if row is None:
        return None
    return models.User(id_=row[0], name=row[1])

No ORM, no hand-written row unpacking, and pyright checks every field access.

One schema, four model types

Set model_type and the same table generates whichever flavour your project already uses - the fields and annotations are identical:

@dataclasses.dataclass()
class User:
  id_: int
  name: str

Built to be trusted

Generated code is held to the same standard as hand-written code:

Type-checked. Every generated file passes pyright in strict mode and ruff.
Tested against real databases. The suite runs the generated code against live PostgreSQL and SQLite, across every driver and model type.
Deterministic. Output is byte-identical between runs, and CI fails if a change would silently alter what you get.

Set up in three steps

Install the sqlc CLI (uv add --dev sqlc-bin) and your database driver.
Configure a sqlc.yaml pointing at the plugin’s release wasm, your schema, and your queries.
Generate - sqlc generate writes typed models and one query module per query file.

Read the Getting Started guide