Guide

This guide walks through sqlc-gen-better-python one feature at a time. Each page states what a feature does, the configuration it needs, and shows real schema, queries, and the exact Python the plugin generates for them.

How the pieces fit

You never call this plugin directly. You write a SQL schema and queries, and sqlc runs the plugin for you:

You write schema (CREATE TABLE, CREATE TYPE) and queries (annotated SELECT/INSERT/…).
sqlc parses them into a typed catalog and hands it to the plugin.
The plugin walks the catalog and emits Python: a models.py (one class per table), one query module per query .sql file (typed functions), and an enums.py when your schema has enums.

So everything in this guide is driven by two inputs - your SQL and your sqlc.yaml options - and observed through one output: the generated Python.

New here? Start with Getting Started for install and a first sqlc generate, then come back to this guide.

How to read this guide

Start with the essentials, then dip into feature pages as you need them:

Configuration

The sqlc.yaml plugin block and the core options.

Drivers

asyncpg, psycopg, aiosqlite, and sqlite3 - and which query commands each supports.

Model types

dataclass, attrs, msgspec, or pydantic models.

Writing queries

How query annotations become typed Python functions.

The remaining pages - enums, type overrides, converters, working with JSON, docstrings, SQLite type conversion, and naming - cover specific features and can be read in any order. The Reference section holds the canonical option, type-mapping, and driver-support tables.

Getting Started Configuration