Skip to content

Configuration reference

Root options

options:
  version: 1
  sqlc:
    package: sqlcdb
    import: example.com/project/internal/database/sqlc
    driver: pgx/v5
  contexts: []

version

Required configuration schema version. Unknown versions fail generation.

sqlc.package

Go package identifier used in generated imports.

sqlc.import

Go import path of the package generated by sqlc-gen-go.

sqlc.driver

Initial supported value: pgx/v5.

Bounded contexts

contexts:
  - name: content
    package: content
    directory: content
    models: {}

name is a diagnostic and identity label. package is the Go package name. directory is the output directory relative to the plugin output root.

Concrete models connected by bidirectional relations must be placed in the same context.

Model configuration

User:
  row: User
  operations:
    find: GetUser
    insert: CreateUser
    update: UpdateUser
    delete: DeleteUser
    refresh: GetUser
  fields: {}
  relations: {}

row

Canonical sqlc row type or result shape used to hydrate the model.

operations

Maps lifecycle operations to named sqlc queries.

fields

Maps model field policies and optional persistence mappings.

relations

Defines direct typed relations. Traversal paths are not configuration entities.

Field properties

Property Type Meaning
readable boolean Generate a getter
fillable boolean Include in new-model assignment API
mutable boolean Generate a chainable setter
generated enum insert or save hydration policy
immutable_after_insert boolean Allow assignment only while new
sensitive boolean Exclude from diagnostics/string output
version boolean Optimistic-concurrency field
column string Explicit database column mapping
row_field string Explicit sqlc result-field mapping
value_object object Model/persistence conversion contract

Relation properties

Property Meaning
kind belongs_to, has_one, has_many, many_to_many
model Target model in the same context
local_key Source-side key
foreign_key Target-side key
inverse Direct inverse relation name
lazy_query Single-parent sqlc loader
eager_query Multi-parent sqlc loader
nullable Whether dissociation is legal
parameters Mapping from relation state to query parameters
scopes Typed scope definitions

Scope forms

Constant parameter:

Published:
  parameter: published
  value: true

Argument parameter:

Limit:
  parameter: result_limit
  argument: int32

Query variant:

Archived:
  query: ListArchivedPostsByUser

The generator validates every scope against sqlc query metadata.