@nakedev/go-scaffold 0.9.0 → 0.10.0

package/dist/commands/worker.js

@@ -130,8 +130,11 @@ function patchMakefile(makefilePath, opts) {
     // Without it, .env.example's own `APP_ENV=development  # prod: production`
     // reaches `export` as a bare `#` and prints an error on every run.
     const loadEnv = "@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a;";
-    const targets = "\n# run both API + worker in one terminal — Ctrl+C kills both\n" +
-        "dev:\n" +
+    const targets = "\n# run both API + worker in one terminal — Ctrl+C kills both.\n" +
+        "#\n" +
+        "# migrate-up first, for the same reason `run` does it: cmd/api refuses to\n" +
+        "# boot against a database behind the migrations it embeds.\n" +
+        "dev: migrate-up\n" +
         `\t${loadEnv} \\\n` +
         "\t(trap 'kill 0' SIGINT SIGTERM; \\\n" +
         "\t go run ./cmd/api & \\\n" +

package/dist/utils/auth-patcher.js

@@ -113,7 +113,11 @@ function patchMainGoForAuth(mainGoPath, w) {
     const importLine = `"${goModule}/internal/app/user"`;
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, importLine, importLine);
     const modelImportLine = `usermodel "${goModule}/internal/app/user/adapters/outbound/postgres"`;
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
+    // Only the development AutoMigrate list ever used this alias, so it is only
+    // an import where that list still exists — see the guard further down.
+    if ((0, marker_patch_1.hasMarker)(content, MODEL_MARKER)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
+    }
     if (w.worker) {
         const queueImportLine = `"${goModule}/internal/platform/queue"`;
         content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, queueImportLine, queueImportLine);
@@ -166,7 +170,13 @@ function patchMainGoForAuth(mainGoPath, w) {
         '\treturn fmt.Errorf("create schema user_svc: %w", err)',
         "}",
     ].join("\n");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaBlock, "CREATE SCHEMA IF NOT EXISTS user_svc");
+    // The development AutoMigrate bootstrap is gone from the template, and with
+    // it the schema/model markers. A project scaffolded before that still has
+    // them, and still wants its tables registered there — so these stay, guarded
+    // by the marker's presence rather than deleted. New projects skip them.
+    if ((0, marker_patch_1.hasMarker)(content, SCHEMA_MARKER)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaBlock, "CREATE SCHEMA IF NOT EXISTS user_svc");
+    }
     const migrateLines = [
         "&usermodel.User{},",
         "&usermodel.UserEmail{},",
@@ -178,8 +188,10 @@ function patchMainGoForAuth(mainGoPath, w) {
     // live in Redis, so reset/verification can share the user transaction.
     migrateLines.push("&usermodel.AuthToken{},");
     migrateLines.push("&usermodel.MFAEnrollment{},", "&usermodel.MFAChallenge{},", "&usermodel.MFARecoveryCode{},");
-    for (const line of migrateLines) {
-        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, line, line);
+    if ((0, marker_patch_1.hasMarker)(content, MODEL_MARKER)) {
+        for (const line of migrateLines) {
+            content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, line, line);
+        }
     }
     // Keep auth construction inside the feature package. The root only chooses
     // shared infrastructure and registers the resulting handler.

package/dist/utils/main-patcher.js

@@ -39,10 +39,11 @@ function mainGoLines(patch) {
     return {
         importLine: `"${patch.goModule}/internal/app/${patch.modulePath}"`,
         modelImportLine: `${modelAlias} "${patch.goModule}/internal/app/${patch.modulePath}/adapters/outbound/postgres"`,
-        // Development schema bootstrap creates tables but not the schema they live in — see
-        // the comment on go-scaffold:schemas in main.go.hbs. One Exec per schema,
+        // Legacy only: projects generated before the development AutoMigrate
+        // bootstrap was removed still have the schema marker, and their tables are
+        // created by GORM rather than by the migration. One Exec per schema,
         // guarded by its own sentinel so two modules sharing a schema name only
-        // ever produce one line (not expected today, but cheap to keep safe).
+        // ever produce one line.
         schemaLines: [
             `if err := db.Exec("CREATE SCHEMA IF NOT EXISTS ${patch.schemaName}").Error; err != nil {`,
             `\treturn fmt.Errorf("create schema ${patch.schemaName}: %w", err)`,
@@ -73,7 +74,9 @@ function assertMainGoPatchable(mainGoPath) {
         throw new Error(`${mainGoPath} not found — this doesn't look like a go-scaffold project`);
     }
     const content = fs_extra_1.default.readFileSync(mainGoPath, "utf8");
-    const missing = [IMPORT_MARKER, SCHEMA_MARKER, MODEL_MARKER, ROUTE_MARKER].filter((m) => !(0, marker_patch_1.hasMarker)(content, m));
+    // Not SCHEMA_MARKER/MODEL_MARKER: those belong to the development
+    // AutoMigrate bootstrap, which newer projects do not have.
+    const missing = [IMPORT_MARKER, ROUTE_MARKER].filter((m) => !(0, marker_patch_1.hasMarker)(content, m));
     if (missing.length) {
         throw new Error(`cmd/api/wiring.go is missing the marker comment${missing.length > 1 ? "s" : ""} this command patches at:\n` +
             missing.map((m) => `  ${m}`).join("\n") +
@@ -94,9 +97,17 @@ function patchMainGo(mainGoPath, patch) {
     // folder was deleted (main.go still wired) is a no-op, not a dup that
     // panics gin at startup.
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, importLine, importLine);
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaLines, schemaSentinel);
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, migrateLine, migrateLine);
+    // The development AutoMigrate bootstrap is gone from the template, and with
+    // it the schema/model markers. A project scaffolded before that still has
+    // them, and still wants its tables registered there — so these stay, guarded
+    // by the marker's presence rather than deleted. New projects skip them.
+    if ((0, marker_patch_1.hasMarker)(content, MODEL_MARKER)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, migrateLine, migrateLine);
+    }
+    if ((0, marker_patch_1.hasMarker)(content, SCHEMA_MARKER)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaLines, schemaSentinel);
+    }
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, ROUTE_MARKER, routeLine, routeLine);
     content = (0, marker_patch_1.removeLines)(content, [UNUSED_API_LINE]);
     fs_extra_1.default.writeFileSync(mainGoPath, content);

package/dist/utils/rbac-patcher.js

@@ -167,16 +167,27 @@ function patchMainGoForRbac(mainGoPath, goModule, store, worker) {
     const importLine = `"${goModule}/internal/app/role"`;
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, importLine, importLine);
     const modelImportLine = `rolepostgres "${goModule}/internal/app/role/adapters/outbound/postgres"`;
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
+    // Only the development AutoMigrate list ever used this alias.
+    if ((0, marker_patch_1.hasMarker)(content, MODEL_MARKER)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
+    }
     const schemaBlock = [
         'if err := db.Exec("CREATE SCHEMA IF NOT EXISTS role_svc").Error; err != nil {',
         '\treturn fmt.Errorf("create schema role_svc: %w", err)',
         "}",
     ].join("\n");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaBlock, "CREATE SCHEMA IF NOT EXISTS role_svc");
+    // The development AutoMigrate bootstrap is gone from the template, and with
+    // it the schema/model markers. A project scaffolded before that still has
+    // them, and still wants its tables registered there — so these stay, guarded
+    // by the marker's presence rather than deleted. New projects skip them.
+    if ((0, marker_patch_1.hasMarker)(content, SCHEMA_MARKER)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaBlock, "CREATE SCHEMA IF NOT EXISTS role_svc");
+    }
     const migrateLines = ["&rolepostgres.Role{},", "&rolepostgres.Permission{},", "&rolepostgres.RolePermission{},"];
-    for (const line of migrateLines) {
-        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, line, line);
+    if ((0, marker_patch_1.hasMarker)(content, MODEL_MARKER)) {
+        for (const line of migrateLines) {
+            content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, line, line);
+        }
     }
     const wiring = { goModule, queueBackend: "river", store, worker };
     const authRouteLine = (0, auth_patcher_1.authHandlerLineFor)(wiring);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nakedev/go-scaffold",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Scaffold Gin + GORM + Postgres Go backend projects with a consistent domain-module standard",
   "repository": {
     "type": "git",

package/templates/add/auth/migrations/create_auth_tokens.up.sql.hbs

@@ -17,8 +17,8 @@ CREATE TABLE user_svc.auth_tokens (
     last_used_at TIMESTAMPTZ NOT NULL DEFAULT now()
 );
 
--- Named to match model.AuthToken's own `index:` tags exactly, so the
--- development bootstrap and production migration describe the same indexes.
+-- Named to match model.AuthToken's own `index:` tags exactly, so the Go model
+-- and the schema that actually exists describe the same indexes.
 CREATE INDEX idx_auth_tokens_user_kind ON user_svc.auth_tokens (user_id, kind);
 CREATE INDEX idx_auth_tokens_expires_at ON user_svc.auth_tokens (expires_at);
 CREATE INDEX idx_auth_tokens_absolute_expires_at ON user_svc.auth_tokens (absolute_expires_at);

package/templates/create/base/.claude/skills/go-scaffold/SKILL.md.hbs

@@ -329,10 +329,13 @@ go-scaffold add auth --store postgres --browser-topology same-site --defaults --
 
 - APP_ENV is the only environment gate and accepts development or production.
   Do not reintroduce an AUTO_MIGRATE setting.
-- Development may use the convenience db.AutoMigrate(...) bootstrap.
-  Production must never bootstrap or mutate schema at API startup. Apply
-  versioned SQL with make migrate-up; the startup version check must fail
-  fast for a behind or dirty database.
+- The schema comes from migrations/ in every environment, development
+  included. Apply it with make migrate-up; the startup version check fails
+  fast for a behind or dirty database. Never bootstrap or mutate schema at API
+  startup, and do not add a db.AutoMigrate(...) convenience for development:
+  GORM builds tables from the Go structs, so it produces none of the CHECK
+  constraints, foreign keys or seeded rows the SQL carries, and it silently
+  adds columns to an already-migrated database.
 - Use generate migration for schema changes outside a new module, write and
   review both migration directions, and test them against a disposable DB.
 - Keep SQL, Redis, queue, mail, and other external resources under the

package/templates/create/base/.github/workflows/ci.yml.hbs

@@ -64,6 +64,15 @@ jobs:
             migrate -path migrations -database "$DB_DSN" up
           fi
 
+      # up -> down -all -> up. The only check that catches a down.sql that has
+      # stopped reversing its up.sql, which is otherwise discovered during a
+      # rollback — the worst moment to find out. Runs against the test database
+      # and leaves it migrated up for the steps below.
+      - name: Verify migrations reverse cleanly
+        env:
+          TEST_DB_DSN: postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable
+        run: make migrate-verify
+
       - name: Test (required PostgreSQL integration tests cannot skip)
         env:
           TEST_DB_DSN: postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable

package/templates/create/base/AGENTS.md.hbs

@@ -160,14 +160,46 @@ endpoint is production-ready.
 
 - `APP_ENV` is the single environment gate and accepts only `development` or
   `production`. Do not add a parallel flag such as `AUTO_MIGRATE`.
-- Development may use the convenience `db.AutoMigrate(...)` path for the
-  models registered by the generator. Production must never bootstrap or
-  mutate schema at API startup: apply versioned SQL with
-  `make migrate-up`, then let the startup migration-version check fail fast if
-  the database is behind or dirty.
+- **The schema comes from `migrations/` in every environment, development
+  included.** `cmd/api/wiring.go` runs the migration-version check and nothing
+  else: apply versioned SQL with `make migrate-up`, and let the check fail
+  fast when the database is behind or dirty. Never bootstrap or mutate schema
+  at API startup, and do not reintroduce a `db.AutoMigrate(...)` convenience
+  for development — GORM builds tables from the Go structs, so it writes none
+  of the CHECK constraints, none of the foreign keys and none of the seeded
+  rows a migration carries, and it is additive over an already-migrated
+  database, so a column a model has and a migration does not shows up on one
+  developer's machine and nowhere else.
 - Any schema change is a reviewed pair of versioned files in `migrations/`.
   Use `go-scaffold generate migration <name>` for changes outside a new
   module, write both directions, and test them against a disposable database.
+  Write the SQL first and the Go struct second: the SQL is what exists, the
+  struct is Go's view of it, and doing it the other way round feels finished
+  while the database still has nothing.
+- **A destructive change takes two deploys, never one.** During a rolling
+  deploy the old binary and the new one serve traffic at the same time, so a
+  migration has to be readable by the version of the code still running.
+  `CheckMigrationVersion` is built for that order — a database ahead of the
+  binary is a warning, behind it is fatal — which only works if migrations go
+  out first and stay backward compatible.
+
+  | change | deploys |
+  |---|---|
+  | add a nullable column, add a table, add an index | 1 |
+  | add `NOT NULL` with a `DEFAULT` | 1 — but it rewrites the table, so check its size first |
+  | rename a column | **2** |
+  | drop a column or a table | **2** |
+  | change a column's type | **2** |
+
+  The two are *expand* then *contract*: add the new shape and have the code
+  write both and prefer the new one; deploy that everywhere; only then drop the
+  old shape. `DROP COLUMN` in one round pulls the floor out from under the pods
+  still serving requests.
+- `make migrate-verify` (up → down -all → up) runs in CI and is the only thing
+  that catches a `down.sql` which has quietly stopped reversing its `up.sql`.
+  Without it that is found during a rollback, which is the worst moment to find
+  out. Never run it against a database whose data matters — `down -all` means
+  it.
 - Keep `*sql.DB`, Redis, queue, mail, and other external resources owned by
   their composition root. Close them on every exit path and preserve the
   signal-driven graceful shutdown; do not call `os.Exit` from a goroutine or

package/templates/create/base/Makefile.hbs

@@ -39,7 +39,12 @@ ENV_FILE ?= .env
 
 .PHONY: tools run build test fmt vet lint tidy db-create db-drop migrate-up migrate-up-test migrate-down migrate-verify{{#if openapiDocs}} openapi-bundle{{/if}}{{#if docker}} docker-up docker-down{{/if}}
 
-run:
+# migrate-up first, because cmd/api refuses to boot against a database that is
+# behind the migrations it embeds. The schema is the migrations' in every
+# environment — this is the step that would otherwise be a db.AutoMigrate
+# bootstrap, except it applies the same SQL production gets, constraints and
+# seeded rows and all.
+run: migrate-up
 	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; go run ./cmd/api
 
 build:
@@ -115,26 +120,41 @@ db-drop:
 		exit 1; \
 	fi
 
+# A project has no migrations until its first `generate module` or `add auth`,
+# and `migrate up` treats an empty directory as an error rather than as nothing
+# to do. `run` depends on this target, so without the guard the very first
+# `make run` of a fresh scaffold fails on a database that is already correct.
 migrate-up:
-	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; migrate -path migrations -database "$$DB_DSN" up
+	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; \
+	if ! ls migrations/*.up.sql >/dev/null 2>&1; then echo "no migrations yet — nothing to apply"; exit 0; fi; \
+	migrate -path migrations -database "$$DB_DSN" up
 
 # same migration files, applied to TEST_DB_DSN instead of DB_DSN — run this
 # once after `make db-create DB_NAME=..._test` so repository_test.go files
 # see real tables instead of skipping (or failing, if REQUIRE_TEST_DB=true).
 migrate-up-test:
-	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; migrate -path migrations -database "$$TEST_DB_DSN" up
+	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; \
+	if ! ls migrations/*.up.sql >/dev/null 2>&1; then echo "no migrations yet — nothing to apply"; exit 0; fi; \
+	migrate -path migrations -database "$$TEST_DB_DSN" up
 
 migrate-down:
 	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; migrate -path migrations -database "$$DB_DSN" down 1
 
-# runs up -> down-to-zero -> up against $DB_DSN to catch a bit-rotted down.sql
-# (one that no longer reverses cleanly) before you actually need a rollback.
-# point DB_DSN at a throwaway/test database first — this drops every table.
+# runs up -> down-to-zero -> up to catch a bit-rotted down.sql (one that no
+# longer reverses cleanly) before you actually need a rollback.
+#
+# TEST_DB_DSN, not DB_DSN: this drops every table, and it used to say "point
+# DB_DSN at a throwaway database first" — advice its own recipe made impossible
+# to follow, because the .env sourced on the line below overwrites whatever
+# DB_DSN the caller set on the way in. The test database is the one that is
+# meant to be destroyed, so it is the one named here.
 migrate-verify:
 	@set -a; [ -f $(ENV_FILE) ] && . ./$(ENV_FILE); set +a; \
-	migrate -path migrations -database "$$DB_DSN" up && \
-	migrate -path migrations -database "$$DB_DSN" down -all && \
-	migrate -path migrations -database "$$DB_DSN" up
+	if ! ls migrations/*.up.sql >/dev/null 2>&1; then echo "no migrations yet — nothing to apply"; exit 0; fi; \
+	: "$${TEST_DB_DSN:?TEST_DB_DSN is required — migrate-verify drops every table and will not guess a database}"; \
+	migrate -path migrations -database "$$TEST_DB_DSN" up && \
+	migrate -path migrations -database "$$TEST_DB_DSN" down -all && \
+	migrate -path migrations -database "$$TEST_DB_DSN" up
 {{#if openapiDocs}}
 
 # docs/openapi.yaml is hand-written and split across sibling files via relative

package/templates/create/base/README.md.hbs

@@ -83,7 +83,7 @@ go mod tidy
 {{#if worker}}{{#if (eq queue "river")}}make river-migrate                 # create River's job tables before queued mail
 {{else}}# start Redis and set REDIS_URL before running the worker
 {{/if}}{{/if}}
-make run                           # APP_ENV=development enables the convenience schema bootstrap
+make run                           # needs `make migrate-up` first — the schema is the migrations'
 ```
 
 `make run`/`make test`/`make migrate-up`/`make migrate-down` load `.env` if
@@ -154,9 +154,9 @@ migrate -path migrations -database "$DB_DSN" down 1
 migrate create -ext sql -dir migrations -seq=false add_something   # same as `go-scaffold generate migration`, if you'd rather not use the CLI
 ```
 
-**dev:** `APP_ENV=development` enables the convenience table bootstrap.
-**prod:** `APP_ENV=production` never bootstraps or mutates the schema; run
-`migrate up` as a separate deploy step — versioned and rollback-capable.
+**Every environment:** the schema comes from `migrations/`. Nothing
+bootstraps or mutates it at startup; run `migrate up` as its own step —
+versioned and rollback-capable — and the app refuses to boot until you have.
 
 In production, the app checks the DB's applied migration version
 against the migration files baked into the binary (embedded at build time)
@@ -306,7 +306,7 @@ Before the first deploy of a release:
 
 | | |
 |---|---|
-| `APP_ENV` | `production` | production disables schema bootstrap and requires the applied migration version |
+| `APP_ENV` | `production` | production hides internal error details; the applied migration version is required in every environment |
 | migrations | `migrate -path migrations -database "$DB_DSN" up` as its own step, before the new binaries roll |
 | `TRUSTED_PROXIES` | the CIDRs of your ingress, or the auth rate limiter keys on a header anyone can send |
 | `COOKIE_SECURE` | `true` · `COOKIE_SAMESITE=none` as well if your frontend is on a different site |

package/templates/create/base/cmd/api/wiring.go.hbs

@@ -54,19 +54,21 @@ func run() error {
 	}()
 	// go-scaffold:platform-init
 
-	if !cfg.IsProd() {
-		// Development boot creates tables but never the schema they live in — each
-		// domain gets its own (see the outbound postgres model's TableName), so it has to exist
-		// before the bootstrap runs. Production runs the versioned SQL migrations
-		// instead, so this entire branch is skipped there.
-		// go-scaffold:schemas
-
-		if err := db.AutoMigrate(
-			// go-scaffold:models
-		); err != nil {
-			return fmt.Errorf("migrate: %w", err)
-		}
-	} else if err := database.CheckMigrationVersion(db); err != nil {
+	// The schema comes from migrations/ in every environment, development
+	// included: `make migrate-up` applies it, and this refuses to boot when the
+	// database is behind or dirty.
+	//
+	// There is deliberately no db.AutoMigrate bootstrap for development. GORM
+	// builds tables from the Go structs, so it writes none of the CHECK
+	// constraints, none of the foreign keys and none of the seeded rows a
+	// migration carries — a schema that only looks like production's, on which
+	// a seeded catalogue is simply empty. It is also additive over an
+	// already-migrated database, so a column a model has and a migration does
+	// not appears on the developer's machine and nowhere else.
+	//
+	// Every migration creates the schema its tables live in, so nothing here
+	// needs to.
+	if err := database.CheckMigrationVersion(db); err != nil {
 		return fmt.Errorf("migration version check: %w", err)
 	}
 

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

@@ -76,6 +76,14 @@ func CheckMigrationVersion(db *gorm.DB) error {
 		}
 	}
 
+	// A scaffold that has not generated a module or added auth yet embeds no
+	// migrations, so there is no schema_migrations table to read and nothing
+	// to compare against. That is a project with no schema, not a project
+	// whose schema is behind.
+	if latest == 0 {
+		return nil
+	}
+
 	var version int
 	var dirty bool
 	row := db.Raw("SELECT version, dirty FROM schema_migrations").Row()

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

@@ -143,9 +143,12 @@ wrong. See `patterns.md`, "Filtered Lists".
 
 **Decision:** PostgreSQL + GORM, schema managed by
 [golang-migrate](https://github.com/golang-migrate/migrate).
-**Rationale:** `APP_ENV=development` allows a convenience table bootstrap;
-`APP_ENV=production` runs only after `migrate up` has applied the separate,
-versioned, rollback-capable SQL migrations.
+**Rationale:** one source of schema in every environment — the separate,
+versioned, rollback-capable SQL migrations, applied by `migrate up` before the
+binary starts. A development-only `db.AutoMigrate` convenience would build
+tables from the Go structs instead, dropping the CHECK constraints, foreign
+keys and seeded rows the SQL carries, and adding columns to an
+already-migrated database where no test would see the difference.
 
 {{#if docker}}- `docker-compose.yml` provides the local Postgres instance
 {{/if}}

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

@@ -50,8 +50,8 @@ must import the specific boundary package it belongs to.
   kept in `domain/`.
 - `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
-  the development table bootstrap runs. A cross-domain FK is still fine — see
+  migration (`CREATE SCHEMA IF NOT EXISTS`), which is the only thing that
+  creates it. 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.
 
@@ -159,8 +159,8 @@ if this project has one):
    associations / belongs-to — that's what keeps one domain package from
    importing another.
 2. **Declare the FK constraint in migration SQL**
-   (`REFERENCES ... ON DELETE ...`), not a GORM tag — the development bootstrap
-   doesn't create the constraint, which would make dev and prod schemas diverge.
+   (`REFERENCES ... ON DELETE ...`), not a GORM tag — a GORM tag describes the
+   constraint to Go and to nothing that runs, so the database would not have it.
 3. **Map the FK error to the right status** in the outbound adapter with
    `dberr.IsForeignKey`, then let the inbound adapter render it — inserting a
    reference to a missing parent, or deleting a parent that still has children,

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

@@ -40,8 +40,9 @@
 {{/if}}{{#if worker}}{{#if (eq queue "river")}}- Run `make river-migrate` before relying on queued jobs in a fresh database;
   run `make river-migrate-test` as well when `REQUIRE_TEST_DB=true` runs the
   River worker round-trip test.{{/if}}{{/if}}
-- `APP_ENV=development` enables the convenience table bootstrap;
-  `APP_ENV=production` requires `migrate up` as a deploy step instead
+- The schema is the migrations', in every environment: `migrate up` applies
+  it and the startup version check refuses to boot without it. There is no
+  development table bootstrap
 {{#if worker}}{{#if (eq queue "river")}}- River uses the database/sql driver and polls for jobs instead of receiving
   PostgreSQL LISTEN/NOTIFY wakeups; this is deliberate for a shared GORM pool.
 {{/if}}{{/if}}