sqlc-gen-better-python

A WASM plugin for SQLC allowing the generation of Python code.

The generated code requires Python 3.12 or newer (it uses PEP 695 type aliases and generics, and enum.StrEnum).

Documentation

https://rayakame.github.io/sqlc-gen-better-python/

• Getting Started - install the plugin and generate your first models.
• Guide - configuration, drivers, model types, writing queries, and every feature, each with real generated output.
• Reference - all configuration options, SQL-to-Python type mappings, and per-driver feature support.

Questions or feedback? Join the Discord.

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.

Note

Every Release before v1.0.0, including this one is an beta release. These versions are primarly released for interested people who want to test this plugin and help make it better.

Everything that is implemented works and is being used in production environments already. Since v0.5.0 this includes full support for PostgreSQL enums and a fourth model type, pydantic. Feel free to lmk any wanted features and I'm going to do my best on implementing them with the time I have rn.

Example Config

# filename: sqlc.yaml
version: "2"
plugins:
  - name: python
    wasm:
      url: https://github.com/rayakame/sqlc-gen-better-python/releases/download/v0.6.0/sqlc-gen-better-python.wasm
      sha256: 16f5affb502f2ec65ca61f6fc5ddd993449c4a4fc281996c3c9a9bc2e35b1474
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"

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

Features

• Four model types - dataclass, attrs, msgspec, or pydantic (docs).
• Four drivers - asyncpg and psycopg_async for PostgreSQL, aiosqlite and sqlite3 for SQLite (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).
• Generated code passes pyright strict and ruff.

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

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.