@nakedev/go-scaffold 0.1.3 → 0.3.0

package/templates/create/base/go.mod.hbs

@@ -3,9 +3,9 @@ module {{goModule}}
 go 1.25
 
 require (
-	github.com/gin-gonic/gin v1.10.0
-	github.com/go-playground/validator/v10 v10.20.0
+	github.com/gin-gonic/gin v1.10.1
+	github.com/go-playground/validator/v10 v10.30.3
 	github.com/google/uuid v1.6.0
-	gorm.io/driver/postgres v1.5.9
-	gorm.io/gorm v1.25.12
+	gorm.io/driver/postgres v1.6.2
+	gorm.io/gorm v1.31.2
 )

package/templates/create/base/internal/platform/database/database.go.hbs

@@ -2,34 +2,45 @@ package database
 
 import (
 	"fmt"
+	"log"
+	"log/slog"
+	"os"
 	"regexp"
 	"strconv"
+	"time"
 
-{{#if observability}}
-	"{{goModule}}/internal/platform/telemetry"
-{{/if}}
 	"{{goModule}}/internal/shared/config"
 	"{{goModule}}/migrations"
+	// go-scaffold:imports
 
 	"gorm.io/driver/postgres"
 	"gorm.io/gorm"
+	gormlogger "gorm.io/gorm/logger"
 )
 
 // Open connects to Postgres and sets the connection pool — it talks to a
 // real external system, so it lives in platform/, not shared/.
 // Schema is managed via golang-migrate (migrations/) in prod, not AutoMigrate — see README.
 func Open(cfg config.Config) (*gorm.DB, error) {
-	db, err := gorm.Open(postgres.Open(cfg.DBDSN), &gorm.Config{TranslateError: true})
-	if err != nil {
-		return nil, err
-	}
+	// GORM's default logger reports ErrRecordNotFound at ERROR level, so an
+	// ordinary miss — every FindByID behind a 404, cmd/seed's "does this admin
+	// exist yet" check — printed a red line that reads like a failure and
+	// isn't. Everything else GORM's default does is kept.
+	gormLog := gormlogger.New(log.New(os.Stdout, "", log.LstdFlags), gormlogger.Config{
+		SlowThreshold:             200 * time.Millisecond,
+		LogLevel:                  gormlogger.Warn,
+		IgnoreRecordNotFoundError: true,
+	})
 
-{{#if observability}}
-	if err := db.Use(telemetry.NewGormPlugin()); err != nil {
+	db, err := gorm.Open(postgres.Open(cfg.DBDSN), &gorm.Config{
+		TranslateError: true,
+		Logger:         gormLog,
+	})
+	if err != nil {
 		return nil, err
 	}
+	// go-scaffold:platform-init
 
-{{/if}}
 	sqlDB, err := db.DB()
 	if err != nil {
 		return nil, err
@@ -74,8 +85,16 @@ func CheckMigrationVersion(db *gorm.DB) error {
 	if dirty {
 		return fmt.Errorf("schema_migrations is dirty at version %d — a previous migration failed partway; fix it before starting the app", version)
 	}
-	if version != latest {
+	if version < latest {
 		return fmt.Errorf("DB schema is at migration %d, this binary expects %d — run `make migrate-up`", version, latest)
 	}
+	if version > latest {
+		// Only "DB behind binary" is fatal. A rolling deploy migrates first and
+		// replaces pods after, so an old pod restarting mid-rollout legitimately
+		// sees a newer schema — refusing to boot there turns a normal rollout
+		// into a crashloop of the very replicas still serving traffic.
+		slog.Warn("DB schema is ahead of this binary — fine mid-rollout, investigate if it persists",
+			"db_version", version, "binary_version", latest)
+	}
 	return nil
 }

package/templates/create/base/internal/shared/config/config.go.hbs

@@ -20,9 +20,9 @@ type Config struct {
 	DBConnMaxLifetime time.Duration
 
 	CORSAllowedOrigins []string
-{{#if observability}}
-	OTELExporterEndpoint string
-{{/if}}
+	// TrustedProxies is which peers may set X-Forwarded-For — empty means
+	// "nobody", so ClientIP() is the address that actually connected.
+	TrustedProxies []string
 	// go-scaffold:config-fields
 }
 
@@ -37,15 +37,14 @@ func Load() Config {
 		Port:              env("PORT", "8080"),
 		DBDSN:             env("DB_DSN", "postgres://postgres:postgres@localhost:5432/{{dbName}}?sslmode=disable"),
 		LogLevel:          env("LOG_LEVEL", "info"),
-		AutoMigrate:       env("AUTO_MIGRATE", "true") == "true",
 		DBMaxOpenConns:    envInt("DB_MAX_OPEN_CONNS", 10),
 		DBMaxIdleConns:    envInt("DB_MAX_IDLE_CONNS", 10),
 		DBConnMaxLifetime: time.Duration(envInt("DB_CONN_MAX_LIFETIME_MIN", 5)) * time.Minute,
 
 		CORSAllowedOrigins: envList("CORS_ALLOWED_ORIGINS", "http://localhost:3000"),
-{{#if observability}}
-		OTELExporterEndpoint: env("OTEL_EXPORTER_OTLP_ENDPOINT", ""),
-{{/if}}
+		// empty on purpose: trust nothing until you know which hop in front of
+		// this app is yours. See main.go's SetTrustedProxies call.
+		TrustedProxies: envList("TRUSTED_PROXIES", ""),
 		// go-scaffold:config-load
 	}
 
@@ -57,6 +56,13 @@ func Load() Config {
 		panic(fmt.Sprintf("invalid APP_ENV %q — must be development or production", cfg.AppEnv))
 	}
 
+	// Defaults off in production, which is why it's set here rather than in
+	// the literal above — it needs a validated AppEnv first. AutoMigrate
+	// rewrites the schema at boot AND skips CheckMigrationVersion entirely
+	// (see main.go), so a deploy that merely forgets to set it used to get
+	// both. AUTO_MIGRATE=true still forces it on if you really mean it.
+	cfg.AutoMigrate = env("AUTO_MIGRATE", strconv.FormatBool(!cfg.IsProd())) == "true"
+
 	return cfg
 }
 

package/templates/create/base/internal/shared/pagination/pagination.go.hbs

@@ -37,3 +37,14 @@ func Parse(c *gin.Context) Params {
 func (p Params) Response(data any) gin.H {
 	return gin.H{"data": data, "limit": p.Limit, "offset": p.Offset}
 }
+
+// ResponseWithTotal is Response plus the row count the filter matched, which
+// is what a client needs to render "page 3 of 12". Separate rather than
+// folded into Response because the count costs a second query:
+//
+//	var total int64
+//	if err := db.Model(&model.Thing{}).Count(&total).Error; err != nil { ... }
+//	c.JSON(http.StatusOK, p.ResponseWithTotal(out, total))
+func (p Params) ResponseWithTotal(data any, total int64) gin.H {
+	return gin.H{"data": data, "limit": p.Limit, "offset": p.Offset, "total": total}
+}

package/templates/create/base/internal/shared/tx/tx.go.hbs

@@ -0,0 +1,47 @@
+// Package tx carries a database transaction on the request context, so that
+// several repositories can take part in one atomic write without every
+// method growing a *gorm.DB parameter (which would leak GORM into the
+// service layer and break every existing signature).
+//
+// Repositories call From; callers that need more than one write to succeed
+// or fail together call Do. Code that does neither behaves exactly as it did
+// before this package existed.
+package tx
+
+import (
+	"context"
+
+	"gorm.io/gorm"
+)
+
+// ctxKey is unexported so no other package can put a *gorm.DB in this slot.
+type ctxKey struct{}
+
+// Do runs fn inside one transaction: every repository called from fn picks
+// it up via From, so returning an error from anywhere rolls back everything.
+//
+// A nested Do reuses the outer transaction instead of opening a savepoint —
+// a partial rollback is almost never what the caller means, and one commit
+// boundary per request is far easier to reason about.
+//
+// Never hand the ctx passed to fn to a goroutine, a queue, or anything that
+// outlives Do: the transaction is closed on return, and later use of it
+// fails with "transaction has already been committed or rolled back".
+func Do(ctx context.Context, db *gorm.DB, fn func(context.Context) error) error {
+	if _, ok := ctx.Value(ctxKey{}).(*gorm.DB); ok {
+		return fn(ctx)
+	}
+	return db.WithContext(ctx).Transaction(func(t *gorm.DB) error {
+		return fn(context.WithValue(ctx, ctxKey{}, t))
+	})
+}
+
+// From returns the transaction running on ctx, or db when there is none, so
+// a repository method behaves identically whether or not its caller opened
+// a transaction.
+func From(ctx context.Context, db *gorm.DB) *gorm.DB {
+	if t, ok := ctx.Value(ctxKey{}).(*gorm.DB); ok {
+		return t
+	}
+	return db
+}

package/templates/create/base/redocly.yaml.hbs

@@ -0,0 +1,21 @@
+# Config for `npx @redocly/cli lint docs/openapi.yaml` (run in CI, see
+# .github/workflows/ci.yml) and `make openapi-bundle`.
+#
+# `recommended` (the CLI's default with no config at all) enforces
+# documentation-completeness style — every operation must declare security,
+# every operation needs a documented 4xx, no unused security scheme, no
+# localhost server URL — none of which are spec defects, and all of which are
+# true of a freshly generated project before auth exists or of a redirect/
+# no-content endpoint by design. `minimal` checks the things that are
+# actually bugs: unresolved $refs, malformed schemas, invalid enum/type
+# values. The specific rules below would otherwise fire on this project's own
+# generated output, which would make the CI step fail from the day the
+# project is created rather than when someone actually breaks the spec.
+extends:
+  - minimal
+rules:
+  security-defined: off
+  operation-4xx-response: off
+  operation-2xx-response: off
+  no-unused-components: off
+  no-server-example.com: off

package/templates/create/features/docs/architecture.md.hbs

@@ -1,5 +1,24 @@
 # Architecture Decision Record: {{projectName}}
 
+## Composition root
+
+`cmd/api/main.go` decides the exit code and nothing else. Everything it used to
+do lives in `cmd/api/wiring.go`, in a `run() error` — the one function that sees
+every module and hands them what they need.
+
+Modules never import one another. A domain that needs another's behaviour
+declares a narrow interface for exactly what it needs and receives the concrete
+service from `run()`; `.golangci.yml` has a depguard rule per domain that fails
+the build if anyone shortcuts that.
+
+Two things the split buys. `run()` returns an error instead of calling
+`os.Exit`, so the deferred cleanup below it actually runs — `os.Exit` skips
+defers, and telemetry shutdown and the signal handler used to be abandoned on a
+startup error. And the file `go-scaffold` patches is no longer the first file
+you open to understand the binary: `wiring.go` grows with the system, which is
+what a composition root is for, while `main.go` stays put.
+
+
 > Status: generated by `@nakedev/go-scaffold`
 > Scope: initial scaffold
 
@@ -20,7 +39,8 @@ internal/
 ├── platform/                # talks to real external systems (DB, later: cache, queue, mail, ...)
 │   └── database/
 ├── shared/                  # pure logic/framework glue, no I/O
-│   ├── config/  apperror/  dberr/  httpx/  middleware/  pagination/
+│   ├── config/  apperror/  dberr/  httpx/  id/
+│   └── middleware/  pagination/  tx/
 └── app/                     # domain packages (one per feature)
     └── <domain>/
 ```
@@ -102,20 +122,21 @@ is set — empty means no exporter is created and no network calls are made.
 scrapes the app, the app never dials out) so there's no reason to gate them
 further. Tracing needs a collector to be useful, so it stays off until one's
 actually configured, instead of trying to dial a collector that isn't there.
-This is a `create`-time choice (unlike `add auth`/`add rbac`), not something
-layered on afterward — flip it by hand (`internal/shared/middleware/{metrics,tracing}.go`,
-`internal/platform/telemetry/tracing.go`, wiring in `cmd/api/main.go` and
-`internal/platform/database`) if the project needs it later. Both the Gin and
-GORM tracing hooks are hand-rolled against the OTel SDK directly, not the
-official `otelgin`/`gorm.io/plugin/opentelemetry` contrib packages — those
-pull in a newer Gin (→ HTTP/3/quic-go) and every DB driver they support
-tracing for (MySQL, ClickHouse, MongoDB), respectively, for a Postgres-only
-project that only wants request/query spans.
+This is not a one-way `create`-time door: `go-scaffold add observability`
+layers the same files onto a project that started without it, the way `add
+auth`/`add rbac` do — `internal/shared/middleware/{metrics,tracing}.go`,
+`internal/platform/telemetry/tracing.go`, and the wiring in `cmd/api/wiring.go`
+and `internal/platform/database`. Both the Gin and GORM tracing hooks are
+hand-rolled against the OTel SDK directly, not the official
+`otelgin`/`gorm.io/plugin/opentelemetry` contrib packages — those pull in a
+newer Gin (→ HTTP/3/quic-go) and every DB driver they support tracing for
+(MySQL, ClickHouse, MongoDB), respectively, for a Postgres-only project that
+only wants request/query spans.
 
 {{/if}}
 ## Evolution Notes
 
 - `go-scaffold generate module <name>` adds a new domain package and
-  wires it into `cmd/api/main.go`
+  wires it into `cmd/api/wiring.go`
 - This document only reflects the initial scaffold — update it as the real
   architecture evolves

package/templates/create/features/docs/openapi.yaml.hbs

@@ -1,11 +1,10 @@
 # ponytail: hand-written, not generated from annotations — cheap while the
-# endpoint count is low. Ceiling: must be updated by hand whenever an
-# endpoint/DTO changes beyond what `generate module` scaffolds.
+# endpoint count is low. Generated module/method stubs keep the index wired,
+# but request/response schemas still need to be completed with the code.
 # Switch to swaggo (comment-generated) if drift becomes a recurring problem.
 # multi-file: split by domain module (health/<domain>) + common/ for shared
-# pieces — this file is just the index. `generate module <name>`
-# adds its paths/schemas here automatically; `generate method` does not
-# (endpoint-specific docs stay hand-written).
+# pieces — this file is just the index. `generate module` and `generate method`
+# add path entries automatically.
 openapi: 3.0.3
 info:
   title: {{projectName}} API
@@ -19,10 +18,6 @@ paths:
     $ref: './health/health-livez.yaml'
   /readyz:
     $ref: './health/health-readyz.yaml'
-{{#if observability}}
-  /metrics:
-    $ref: './observability/metrics.yaml'
-{{/if}}
   # go-scaffold:paths
 
 components:

package/templates/create/features/docs/patterns.md.hbs

@@ -17,8 +17,9 @@ internal/app/<domain>/
 ├── repository.go       # the only place that touches the DB for this domain, every method takes ctx
 ├── service.go          # business logic; declares the repository interface it needs (mockable in tests)
 ├── handler.go          # HTTP: routing, bind, delegate, respond
-├── service_test.go     # unit test, fake repo, no DB
-└── handler_test.go     # integration test, real Postgres, transaction rolled back per test
+├── service_test.go     # unit test, function-backed repository stub, no DB
+├── handler_test.go     # HTTP unit test, service stub, no DB
+└── repository_test.go  # Postgres integration test against migrated schema
 ```
 
 ### Model
@@ -28,9 +29,17 @@ internal/app/<domain>/
 - A folder, not a single file, so a domain with more than one table (e.g.
   `order` + `order_item`) adds one file per table instead of growing a single
   file — `generate module` only ever creates the first one
-- Every consumer inside `cmd/api/main.go` imports each domain's `model`
+- Every consumer inside `cmd/api/wiring.go` imports each domain's `model`
   package under an alias (`ordermodel`, `usermodel`, ...) since they all share
   the package name `model`
+- `TableName()` returns a schema-qualified name (`order_svc.orders`, not
+  `orders`) — every domain gets its own Postgres schema, created by its own
+  migration (`CREATE SCHEMA IF NOT EXISTS`) and by `cmd/api/wiring.go` before
+  `AutoMigrate` runs in dev (AutoMigrate creates tables, never the schema they
+  live in). A cross-domain FK is still fine — see the FK rules below — this
+  only stops one domain's table from silently colliding with another's, or a
+  raw SQL `JOIN` from reaching into a domain it doesn't own without at least
+  naming the schema it's crossing into.
 
 ## Layer Conventions
 
@@ -53,6 +62,15 @@ internal/app/<domain>/
 - The only file per domain that talks to GORM
 - Every method takes `ctx context.Context` first, so a cancelled request
   cancels the query
+- Every query starts from `tx.From(ctx, r.db).WithContext(ctx)`, never from
+  `r.db` directly — `shared/tx` is what lets a caller wrap two repositories
+  in one `tx.Do(ctx, db, func(ctx) error { ... })` and have both commit or
+  roll back together. `From` returns the transaction on the context, or the
+  plain `*gorm.DB` when there is none, so a method written this way behaves
+  identically either way. A hand-written method that uses `r.db` compiles,
+  passes its tests, and silently escapes any surrounding transaction — that
+  write commits on its own even when the rest of `tx.Do` rolls back. This is
+  the single easiest convention to miss when adding a method by hand.
 - Look up by ID with an explicit `"id = ?"` — the PK is a UUID, not an int,
   and GORM can misinterpret a bare struct arg
 
@@ -68,6 +86,31 @@ internal/app/<domain>/
 - Codes are domain-specific (`ORDER_NOT_FOUND`), never the generic
   `apperror.NewNotFound()` directly from a handler
 
+## Optimistic Locking
+
+Every generated table has a `version INTEGER NOT NULL DEFAULT 1` column, and
+every generated `Repository.Update` is guarded by it — the `UPDATE` carries
+`WHERE id = ? AND version = ?` and bumps the version in the same statement.
+Zero rows affected means someone else saved between the caller's read and its
+write, so the repository returns `ErrStaleVersion` instead of reporting a
+success that changed nothing.
+
+The version the check compares against is the one **the client** last read,
+not the one on the row the service just loaded — comparing a row against
+itself always matches and defeats the whole check. That's why a CRUD
+skeleton's `updateInput` carries `Version int` with `binding:"required"`
+and `response` echoes it back: the client round-trips the value, and an
+update that arrives without one is rejected rather than treated as a blind
+overwrite.
+
+In a CRUD skeleton the service translates `ErrStaleVersion` into `errStale()`
+from the domain's error catalog (`<DOMAIN>_STALE`, HTTP 409) — a lost update
+is a client problem to retry, not a 500. A minimal module has the same
+`Repository.Update` and the same `errStale()` waiting for it, just no update
+path yet. Keep the chain intact when you add one by hand:
+`errors.Is(err, ErrStaleVersion)` → `errStale()`, and never set `Version` on
+the model yourself — `Repository.Update` owns the bump.
+
 ## Domains With a Foreign Key (Relations) — 3 Rules
 
 The CLI does not scaffold relations between domains; when you add one by
@@ -91,23 +134,55 @@ if this project has one):
 For behavior, not just a data reference (e.g. `order` needs `user`'s email
 to put on a receipt) — the caller's `service.go` declares its own narrow
 interface for exactly what it needs, the same way it already declares a
-`repository` interface:
+`repository` interface.
+
+**The interface speaks in the caller's own terms.** No domain package ever
+imports another domain package — `golangci-lint`'s `depguard` rules enforce
+this, and it is the same rule that makes rule 1 above work. So the interface
+names primitives, or types the caller owns, never `user.Response`:
 
 ```go
 // order/service.go
 type userLookup interface {
-    GetByID(ctx context.Context, id uuid.UUID) (user.Response, error)
+    EmailOf(ctx context.Context, id uuid.UUID) (string, error)
 }
 ```
 
-`cmd/api/main.go` wires the concrete `user` service in — it already
-satisfies the interface, no adapter needed:
+`cmd/api/wiring.go` is the one place that knows both domains, so the adapter
+lives there — a func literal, not a type:
+
+```go
+userSvc := user.NewService(userRepo, ...)
+orderSvc := order.NewService(orderRepo, order.UserLookupFunc(
+    func(ctx context.Context, id uuid.UUID) (string, error) {
+        u, err := userSvc.Get(ctx, id)
+        if err != nil {
+            return "", err
+        }
+        return u.Email, nil
+    },
+))
+```
+
+where `order` provides the usual func-to-interface shim next to its
+interface:
 
 ```go
-userSvc := user.NewService(userRepo)
-orderSvc := order.NewService(orderRepo, userSvc)
+// order/service.go
+type UserLookupFunc func(ctx context.Context, id uuid.UUID) (string, error)
+
+func (f UserLookupFunc) EmailOf(ctx context.Context, id uuid.UUID) (string, error) {
+    return f(ctx, id)
+}
 ```
 
+It looks like more ceremony than passing `*user.Service` straight in, and it
+is — four lines of it. What you buy is that `order` compiles, tests, and
+moves without `user` existing at all, and that a change to `user.Response`
+can never silently ripple into `order`. The adapter is also the honest place
+to notice you are reaching for something that should have been the caller's
+own data.
+
 - **One direction only.** If `user` would need to call back into `order`,
   don't wire it both ways — either the two belong in one domain, or the
   callback needs an event/queue, not a direct call.
@@ -124,7 +199,7 @@ go-scaffold generate method <domain> <name> --type <get|post|put|patch|delete> [
 ```
 
 Patches `handler.go`/`service.go` (and `repository.go` + the `repository`
-interface + its `fakeRepo` test stub, for a `get --get-mode one --field`
+interface + its `repositoryStub` test stub, for a `get --get-mode one --field`
 lookup) in place, at the `// go-scaffold:*` marker comments near the end of
 each file. **Don't delete those markers** — they're where the next
 `generate method` call inserts. The method body is always left as a `TODO`
@@ -137,10 +212,12 @@ placeholder fields.
 - Unit and integration tests live in the same directory as the code under
   test (Go convention) — never a separate `test/` folder. `test/` is only
   for e2e black-box suites or fixtures.
-- `service_test.go` uses a fake repository — no DB required, always runs.
-- `handler_test.go` runs against a real Postgres instance inside a
-  transaction that's rolled back after each test — skips automatically if
-  the DB isn't reachable.
+- `service_test.go` uses a function-backed repository stub so each dependency
+  method has independent behavior and argument assertions.
+- `handler_test.go` uses a service stub — HTTP tests never need Postgres.
+- `repository_test.go` runs against a migrated Postgres database inside a
+  transaction that's rolled back after each test. Local runs may skip when
+  `TEST_DB_DSN` is unset; CI sets `REQUIRE_TEST_DB=true` so it must run.
 
 ## Docs Maintenance
 

package/templates/create/features/docs/techstack.md.hbs

@@ -7,10 +7,10 @@
 | Layer | Technology |
 |-------|-----------|
 | Language | Go 1.25 |
-| HTTP framework | Gin (`github.com/gin-gonic/gin` v1.10.0) |
+| HTTP framework | Gin (`github.com/gin-gonic/gin` v1.10.1) |
 | Database | PostgreSQL |
-| ORM | GORM (`gorm.io/gorm` v1.25.12 + `gorm.io/driver/postgres` v1.5.9) |
-| Validation | `go-playground/validator/v10` v10.20.0 |
+| ORM | GORM (`gorm.io/gorm` v1.31.2 + `gorm.io/driver/postgres` v1.6.2) |
+| Validation | `go-playground/validator/v10` v10.30.3 |
 | IDs | UUID v7 (`google/uuid` v1.6.0) |
 | Logging | `log/slog`, JSON handler |
 | Migrations | [golang-migrate](https://github.com/golang-migrate/migrate) |
@@ -39,3 +39,8 @@
   nowhere — set it to a real OTLP/HTTP collector address to see traces
 {{/if}}- Versions above are what `go-scaffold create` pinned in `go.mod` — bump them
   by hand (`go get -u` + `go mod tidy`) as the stack evolves
+- Each `go-scaffold add ...` command pins its own dependencies the same way
+  (River/Asynq, JWT, oauth2, Prometheus, OpenTelemetry, ...), so `go mod tidy`
+  resolves them to the versions that feature was built against instead of
+  whatever happened to be newest that day. The full list is `go.mod`; this
+  table only covers what `create` itself brings in

package/templates/generate/module/docs/item.yaml.hbs

@@ -29,9 +29,9 @@ put:
     "400": { $ref: '../common/responses.yaml#/ValidationError' }
     "404": { $ref: '../common/responses.yaml#/NotFoundError' }
 delete:
-  summary: Delete {{pkg}}
+  summary: Delete {{name}}
+  description: Idempotent — deleting an already-missing resource also returns 204.
   operationId: delete{{pascalName}}
   tags: [{{plural}}]
   responses:
-    "204": { description: deleted }
-    "404": { $ref: '../common/responses.yaml#/NotFoundError' }
+    "204": { description: deleted or already absent }

package/templates/generate/module/dto.go.hbs

@@ -9,21 +9,28 @@ import (
 )
 
 // TODO: add request fields, e.g. Name string `json:"name" binding:"required"`
+// When you do: update createBody in handler_test.go to match, or the
+// generated create test starts failing on its own empty `{}` body.
 type createInput struct {
 }
 
 // TODO: add request fields, e.g. Name string `json:"name" binding:"omitempty"`
 type updateInput struct {
+	// Version the client last read. Required: without it an update is a blind
+	// overwrite of whatever anyone else has since saved.
+	Version int `json:"version" binding:"required"`
 }
 
 // response = the DTO sent out (kept separate from the model so a later DB column doesn't leak automatically)
 type response struct {
 	ID        uuid.UUID `json:"id"`
 	CreatedAt time.Time `json:"created_at"`
+	// echoed back so the client can send it with its next update
+	Version int `json:"version"`
 }
 
 func toResponse(m *model.{{pascalName}}) response {
-	return response{ID: m.ID, CreatedAt: m.CreatedAt}
+	return response{ID: m.ID, CreatedAt: m.CreatedAt, Version: m.Version}
 }
 
 // go-scaffold:dto

package/templates/generate/module/errors.go.hbs

@@ -22,6 +22,11 @@ func errConflict() *apperror.AppError {
 	return apperror.New(http.StatusConflict, "{{errorPrefix}}_CONFLICT", "{{pkg}} already exists")
 }
 
+//nolint:unused
+func errStale() *apperror.AppError {
+	return apperror.New(http.StatusConflict, "{{errorPrefix}}_STALE", "{{pkg}} was modified by someone else — reload and try again")
+}
+
 //nolint:unused
 func errHasReferences() *apperror.AppError {
 	return apperror.New(http.StatusConflict, "{{errorPrefix}}_HAS_REFERENCES", "{{pkg}} still has related records")

package/templates/generate/module/field-column.down.sql.hbs

@@ -0,0 +1,2 @@
+DROP INDEX IF EXISTS {{schemaName}}.idx_{{tableName}}_{{fieldColumn}};
+ALTER TABLE {{schemaName}}.{{tableName}} DROP COLUMN IF EXISTS {{fieldColumn}};

package/templates/generate/module/field-column.up.sql.hbs

@@ -0,0 +1,15 @@
+-- `generate method {{pkg}} {{methodName}} --field {{fieldColumn}}` generates a
+-- lookup that queries this column. GORM builds that SQL at runtime, so without
+-- the column the code compiles, the tests pass, and the endpoint fails on its
+-- first real request — which is why the migration is generated with it.
+--
+-- TODO: the type is a guess. Change it to whatever the field actually is, and
+-- drop NULL handling in if the column can be empty.
+ALTER TABLE {{schemaName}}.{{tableName}}
+    ADD COLUMN IF NOT EXISTS {{fieldColumn}} VARCHAR(255);
+
+-- The lookup fetches one row by this column on every call. Without an index
+-- that is a sequential scan of the whole table, which is invisible until the
+-- table is big enough for it to hurt.
+CREATE INDEX IF NOT EXISTS idx_{{tableName}}_{{fieldColumn}}
+    ON {{schemaName}}.{{tableName}} ({{fieldColumn}});

package/templates/generate/module/handler.go.hbs

@@ -1,8 +1,10 @@
 package {{pkg}}
 
 import (
+	"context"
 	"net/http"
 
+	"{{goModule}}/internal/app/{{modulePath}}/model"
 	"{{goModule}}/internal/shared/httpx"
 {{#if auth}}
 	"{{goModule}}/internal/shared/middleware"
@@ -10,11 +12,23 @@ import (
 	"{{goModule}}/internal/shared/pagination"
 
 	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
 )
 
+// service is the narrow application API required by this HTTP adapter. Keeping
+// the dependency as an interface makes handler tests fast and database-free.
+type service interface {
+	Create(context.Context, createInput) (*model.{{pascalName}}, error)
+	List(context.Context, int, int) ([]model.{{pascalName}}, error)
+	Get(context.Context, uuid.UUID) (*model.{{pascalName}}, error)
+	Update(context.Context, uuid.UUID, updateInput) (*model.{{pascalName}}, error)
+	Delete(context.Context, uuid.UUID) error
+	// go-scaffold:service-interface
+}
+
 // Handler = delivery for {{pkg}} (parses HTTP, calls the service, attaches errors for the middleware to render)
 type Handler struct {
-	svc *Service
+	svc service
 {{#if auth}}
 	jwtSecret string
 {{/if}}
@@ -23,7 +37,7 @@ type Handler struct {
 {{/if}}
 }
 
-func NewHandler(svc *Service{{#if auth}}, jwtSecret string{{/if}}{{#if permission}}, authz *middleware.Authz{{/if}}) *Handler {
+func NewHandler(svc service{{#if auth}}, jwtSecret string{{/if}}{{#if permission}}, authz *middleware.Authz{{/if}}) *Handler {
 	return &Handler{
 		svc: svc,
 {{#if auth}}
@@ -52,7 +66,7 @@ func (h *Handler) create(c *gin.Context) {
 		c.Error(httpx.BindErr(err))
 		return
 	}
-	m, err := h.svc.Create(c.Request.Context())
+	m, err := h.svc.Create(c.Request.Context(), in)
 	if err != nil {
 		c.Error(err)
 		return
@@ -97,7 +111,7 @@ func (h *Handler) update(c *gin.Context) {
 		c.Error(httpx.BindErr(err))
 		return
 	}
-	m, err := h.svc.Update(c.Request.Context(), id)
+	m, err := h.svc.Update(c.Request.Context(), id, in)
 	if err != nil {
 		c.Error(err)
 		return