Skip to content
sqlc-model

Fluent Active Record models, generated over sqlc.

sqlc stays the source of truth for SQL, query signatures, parameter types, and driver integration. sqlc-model adds behavior, lifecycle, relations, validation, and persistence on top — statically generated, nothing dynamic, nothing improvised.

Read the docs View on GitHub 
The rich-model layer owns model behavior and lifecycle.

sqlc owns SQL contracts and database access.

What it looks like

Mutate a model

user, err := models.Users.Find(ctx, userID)
if err != nil {
    return err
}

err = user.
    Rename("Marcos Aurelio").
    ChangeEmail("marcos@example.com").
    Activate().
    Save(ctx)

Traverse a relation

posts, err := user.
    Posts().
    Published().
    Latest().
    Limit(10).
    Get(ctx)

Calling Posts() or a scope method does not execute SQL. Get(ctx) is the operation boundary that may perform lazy loading.

What it adds

  • Active Record–style models. Generated over sqlc queries — not a dynamic ORM, every terminal operation resolves to a statically declared query.
  • Sessions and collections. APIs for model construction, lookup, persistence, and transactions.
  • Dirty tracking and validation. Original snapshots, lifecycle state, and validation errors on every model.
  • Typed relations. Lazy loading, eager loading, scopes, cache inspection, and explicit terminal operations.
  • Value-object conversion hooks. Map database columns to real domain types at the field level.
  • Deterministic generation. Golden snapshot coverage keeps generated output stable across runs.

Install

Install the sqlc process plugin:

go install github.com/macoaure/sqlc-model/cmd/sqlc-model@latest

Add it to sqlc.yaml:

plugins:
  - name: richmodel
    process:
      cmd: sqlc-model

sql:
  - schema: schema.sql
    queries: query.sql
    engine: postgresql
    codegen:
      - plugin: richmodel
        out: internal/models
        options:
          version: 1
          sqlc:
            package: sqlcdb
            import: example.com/project/internal/database/sqlc
            driver: pgx/v5
          contexts:
            - name: content
              package: content
              directory: content
              models: {}

See the configuration reference for the complete options contract.

Documentation

  • Tutorials teach the system through complete, guided examples.
  • How-to guides solve specific implementation and application tasks.
  • Reference defines exact configuration, API, lifecycle, query, and compatibility contracts.
  • Explanation records the architectural reasoning and rejected alternatives.
  • Project implementation defines the delivery plan, release boundary, and definition of done.

Start with the documentation index.