sqlc-gen-better-python

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

Note

This is currently being worked on. It is far from being ready for any kind of release, let alone a stable one.
Please wait for the v1 release; before that, this plugin is likely to not work.

Example Config

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

Configuration Options

Name	Type	Required	Description
package	string	yes	The name of the package where the generated files will be located
emit_init_file	bool	yes	If set to to false there will be no __init__.py file created in the package that you specified. Only set this to false if you know that you already have a __init__.py file otherwise the generated code wont work.
sql_driver	string	no	The name of the sql driver you want to use. Defaults to aiosqlite. Valid options are listed here
model_type	string	no	The model type you want to use. This can be one of dataclass, msgspec or attrs. Defaults to dataclass
initialisms	list[string]	no	An array of initialisms to upper-case. For example, app_id becomes AppID. Defaults to ["id"].
emit_exact_table_names	bool	no	If true, model names will mirror table names. Otherwise sqlc attempts to singularize plural table names.
emit_classes	bool	no	If true, every query function will be put into a class called Querier. Otherwise every function will be a standalone function.
inflection_exclude_table_names	list[string]	no	An array of table names that should not be turned singular. Only applies if emit_exact_table_names is false.
omit_unused_models	bool	no	If set to true and there are models/tables that are not used in any query, they wont be turned into models.
docstrings	string	no	If set, there will be docstrings generated in the selected format. This can be one of google, numpy, pep257 and none. none will not generate any docstrings.
docstrings_emit_sql	bool	no	If set to false the SQL code for each query wont be included in the docstrings. This defaults to true but is not used when docstrings is not set or set to none
query_parameter_limit	integer	no	Not yet implemented.
speedups	bool	no	If set to true the plugin will use other librarys for type conversion. Needs extra dependecys to be installed. This option currently only affects sqlite3 & aiosqlite and uses the library ciso8601
overrides	list[Override]	no	A list of type overrides.
debug	bool	no	If set to true, there will be debug logs generated into a log.txt file when executing sqlc generate. Defaults to false

Type Overrides

Similar to sqlc-gen-go this plugin supports overriding types with your own. You can either override the type of every column that has a specific sql type, or you can overwrite the type of specific columns.

# filename: sqlc.yaml
# ...
  options:
    # ...
    overrides:
      - db_type: text
        py_type:
          import: collections
          package: UserString
          type: UserString
      - column: table_name.text_column
        py_type:
          import: collections
          type: collections.UserString

Feature Support

Every sqlc macro is supported. The supported query commands depend on the SQL driver you are using, supported commands are listed below.

Every :batch* command is not supported by this plugin and probably will never be.

Prepared Queries are not planned for the near future, but will be implemented sooner or later

	:exec	:execresult	:execrows	:execlastid	:many	:one	:copyfrom
aiosqlite	yes	yes	yes	yes	yes	yes	no
sqlite3	yes	yes	yes	yes	yes	yes	no
asyncpg	yes	yes	yes	no	yes	yes	yes
psycopg2	no	no	no	no	no	no	no
mysql	no	no	no	no	no	no	no

Development

A roadmap of what is planned & worked on can be found here.

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.