sqlc-gen-better-python

sqlc-gen-better-python

sqlc-gen-better-python is a sqlc plugin that turns your SQL schema and queries into modern, fully typed Python database code: models, typed query functions, and enums. You keep writing SQL; the Python stays in sync with it.

You write:

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

and get back:

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. Generated code targets Python 3.12 or newer and passes pyright (strict) and ruff.

Documentation

https://sqlc-gen-better-python.rayakame.dev/

• Getting Started - install the plugin and generate your first models.
• Guide - every feature, each with real generated output.
• Reference - all options, type mappings, and per-driver feature support.

Questions or feedback? Join the Discord.

Features

• Four model types - dataclass, attrs, msgspec, or pydantic (docs).
• Seven drivers - asyncpg, psycopg_async, and psycopg_sync for PostgreSQL, aiosqlite and sqlite3 for SQLite, plus experimental turso_async and turso_sync for Turso (docs).
• Typed query functions - one module per query file, one function per query (docs).
• PostgreSQL enums as enum.StrEnum classes (docs).
• Type overrides and converters - swap a column's Python type, or plug in your own encode/decode functions (overrides, converters).
• Typed JSON columns via msgspec structs (docs).
• Optional docstrings in google, numpy, or pep257 convention (docs).

Every sqlc macro is supported. Which query commands are available depends on the driver - see the feature support matrix.

Example config

# filename: sqlc.yaml
version: "2"
plugins:
  - name: python
    wasm:
      url: https://github.com/rayakame/sqlc-gen-better-python/releases/download/v0.7.0/sqlc-gen-better-python.wasm
      sha256: 64ac923cf5f14ebc05bdeb2d1827f14d89a6f3b7180ac08964ef44ff065af5f9
sql:
  - engine: "postgresql"
    queries: "query.sql"
    schema: "schema.sql"
    codegen:
      - out: "app/db"
        plugin: python
        options:
          package: "db"
          emit_init_file: true
          sql_driver: "asyncpg"
          model_type: "msgspec"

[!TIP] No sqlc yet? Besides the official installation methods, uv add --dev sqlc-bin (or pip install sqlc-bin) installs sqlc-bin, the unmodified official binaries as a pinnable Python package - no Go toolchain required.

More options at the sqlc config reference, and the full plugin option list in the configuration reference.

Used by

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.

Development

Contributions are very welcome, for more information and help please read the contribution guidelines.

Changelog

Can be found here

Credits

Because of missing documentation about creating these plugins, this work is heavily inspired by:

• sqlc-gen-go
• sqlc-gen-java

Special thanks to tandemdude for answering my questions on discord.