sqlc-gen-template

sqlc-gen-template

A sqlc WASM plugin that renders arbitrary code from user-supplied Go text/template files. Point it at a templates directory and it will render each *.tmpl file against sqlc's parsed catalog and queries.

A better equivalent of fdietze/sqlc-gen-from-template with the ergonomics of protoc-contrib/protoc-gen-template: sprig functions, naming helpers, language type mappers, filename templating, partials, and cross-file includes.

Features

• WASM plugin — no local binary, pinned by sha256 in sqlc.yaml
• Directory walk discovers every *.tmpl under templates_dir
• Filename templating — the output path is itself rendered as a template
• Partials — files whose base name starts with _ are parsed but not emitted
• Cross-file {{ template "name" . }} includes
• Sprig v3 function library
• Naming helpers: camelCase, pascalCase, snakeCase, kebabCase, screamingSnake, singular, plural, camelize, goNormalize, …
• Language type helpers: goType, pyType, tsType, rustType, kotlinType, cppType, goZeroValue
• Proto navigation: findTable, findEnum, queriesByCmd, hasColumn, columnComment, option, optionOr
• Per-render scratch store: setStore / getStore
• Language-agnostic — template data is the raw sqlc protobuf; no pre-computed enriched model

Installation

Pin the released .wasm artifact in sqlc.yaml. Grab the sha256 from the matching .wasm.sha256 asset on the release page.

version: "2"
plugins:
  - name: template
    wasm:
      url: https://github.com/sqlc-contrib/sqlc-gen-template/releases/download/v0.1.0/sqlc-gen-template.wasm
      sha256: <sha256 from the release assets>

Configuration

sql:
  - engine: postgresql
    schema: db/schema.sql
    queries: db/queries.sql
    codegen:
      - plugin: template
        out: ./gen
        options:
          templates_dir: ./templates # required
          extra: # free-form; surfaced as .Options
            package: db
            emit_json_tags: true

Unknown top-level options are rejected.

Template discovery & output

• Every file under templates_dir with a .tmpl suffix is parsed.
• All templates are loaded into a single template set, so {{ template "some-other-file.tmpl" . }} works across files.
• Files whose base name starts with _ are partials — parsed but never emitted as output files.
• For each non-partial template, the output path is computed as the template's path relative to templates_dir, with the .tmpl suffix stripped. That path is itself executed as a template, so it can depend on .Options, range contexts, etc.

Example layout:

templates/
  _header.tmpl                              # partial (not emitted)
  models.go.tmpl                            # → gen/models.go
  {{ .Options.package }}/schema.sql.tmpl    # → gen/db/schema.sql  (when .Options.package = "db")

Template context

The root value (.) is:

type Context struct {
    Request      *plugin.GenerateRequest // raw sqlc protobuf
    Options      map[string]any          // the `extra` map from sqlc.yaml
    TemplatesDir string                  // the resolved templates directory
    SqlcVersion  string                  // hoisted from Request.SqlcVersion
}

Useful proto field paths (see the plugin-sdk-go types for the full surface):

Template function reference

Naming

camelCase, pascalCase, goNormalize preserve common acronyms (ID, URL, URI, UUID, API, HTTP, JSON, XML, SQL, DB, IP, TCP, UDP, TLS, SSL).

Proto navigation

Example:

{{ $users := findTable .Request "public" "users" }}
{{ range $users.Columns }}{{ .Name }}: {{ goType . }}
{{ end }}

Language type helpers

Each helper takes a single *plugin.Column and returns the column's type in the target language, honouring NotNull, IsArray, and (where meaningful) Unsigned.

Covered SQL types include bool, int2/int4/int8 (and their smallint/ integer/bigint/serial aliases), tinyint/mediumint, float4/float8, numeric/decimal, text/varchar/char/citext, uuid, bytea/blob, date/time/timestamp/timestamptz, json/jsonb. Unknown types fall through to each language's catch-all (any, Any, unknown, serde_json::Value, Any, std::string).

Need a project-specific override? Use optionOr to let template authors pass type overrides through extra:

{{ $go := optionOr (printf "types.%s" .Type.Name) (goType .) .Options }}

Scratch store

setStore key value writes to a per-render map[string]any and returns an empty string (so it is safe to call from an action). getStore key reads back. Useful for collecting imports or accumulating state across templates in a single render.

{{ setStore "imports" (list "time" "database/sql") }}
...
{{ range getStore "imports" }}import "{{ . }}"
{{ end }}

Sprig

The full sprig v3 TxtFuncMap is available. Where sprig and this plugin define the same name (e.g. snakecase/snakeCase), the plugin's helpers take precedence — sprig functions are registered first and overwritten by the naming, navigation, language, and store helpers.

Writing templates

{{- /* templates/{{ .Options.package }}/models.go.tmpl */ -}}
package {{ .Options.package }}

{{ range .Request.Catalog.Schemas }}
{{- range .Tables }}
type {{ pascalCase .Rel.Name | singular }} struct {
{{- range .Columns }}
    {{ pascalCase .Name }} {{ goType . }} `db:"{{ .Name }}"`
{{- end }}
}
{{ end }}
{{- end }}

Caveats

• No formatter_cmd. WASI plugins cannot spawn processes. Format the generated output yourself (go fmt ./..., prettier --write, rustfmt, …).
• Filesystem access. sqlc mounts the configuration directory into the plugin's WASI sandbox. Relative templates_dir values resolve against that directory; absolute paths pointing outside the mount will fail.
• Raw proto surface. Template data is the sqlc SDK protobuf. The plugin pins a specific SDK version; field paths may shift across SDK bumps.

Development

nix develop
go tool ginkgo run -r -coverprofile=coverage.out -covermode=atomic ./...

Build the WASM artifact locally:

nix build .#wasm
sha256sum result/bin/sqlc-gen-template.wasm

License

MIT