Where the generated ORM lands (database.orm.package), and the per-project database opt-outs — `//forge:no-orm` in internal/db (or `features: {orm: false}` in forge.yaml) to skip the generated ORM, and `-- forge:allow-destructive` in a migration to allow one destructive change — plus how the database itself is derived, and the lint rules for a migration file that cannot run as one transaction (CONCURRENTLY, enum values).
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Orm And Safety?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/reliant-labs-orm-and-safety)
---
name: db/orm-and-safety
description: Where the generated ORM lands (database.orm.package), and the per-project database opt-outs — `//forge:no-orm` in internal/db (or `features: {orm: false}` in forge.yaml) to skip the generated ORM, and `-- forge:allow-destructive` in a migration to allow one destructive change — plus how the database itself is derived, and the lint rules for a migration file that cannot run as one transaction (CONCURRENTLY, enum values).
applies: any
---
# ORM opt-out and migration-safety directives
forge.yaml has no `database.driver`, `database.migrations_dir`, `database.seed`, or
`allowed_destructive` — each was derived, defaulted, or moved to the code it affects.
## The database is derived
A service project with `db/migrations/` has a postgres database and that directory is where
migrations live. Delete the directory and the project has no database: no ORM, no
migrations feature. `forge project features` shows the reason for each.
## Skipping the ORM: `//forge:no-orm`
Some projects hand-write their data layer and must not get generated entity structs over it.
Put the marker in the doc comment of `internal/db`, with the reason:
```go
// Package db is the hand-owned repository layer.
//
//forge:no-orm: the repository is hand-written; entities are not projected
package db
```
**Or in forge.yaml.** `features: {orm: false}` says the same thing beside every other feature
switch — the spelling a repository adopting forge reaches for first. The marker documents the
decision where a reader of `internal/db` sees it, with its reason; use either, or both. Pinning
`orm: true` while the marker is present is a load error: the two would contradict each other.
Either opts out of the ORM projection only — migrations, codegen and the database stay on.
With no ORM there is no generic CRUD to wire, so every rpc is custom on the server: a
CRUD-named one (`CreateTask` over a `tasks` table) gets a pb-through stub and a scaffold test
row like any other, for your data layer to implement. To keep the ORM and opt ONE rpc out,
mark it `// forge:custom` instead (`forge project annotations --kind method`).
forge reads it from non-test, non-generated `.go` files **directly in** `internal/db/`. A line
that merely mentions it in prose, a `_gen.go` file, a `_test.go` file, or another package does
not count. `forge project features` shows `orm` off with `(//forge:no-orm in internal/db)`, or
`(pinned in forge.yaml features:)`.
With `database.orm.package` set, the marker is read in THAT directory instead.
## Placing the ORM: `database.orm.package`
The one ORM setting forge.yaml does carry, because it is a property of the
PROJECT (where generated code goes), not of a package that already exists:
```yaml
database:
orm:
package: internal/store # default internal/db
```
Every projected file — `<entity>_orm_gen.go`, `<entity>_store_gen.go`, `store_gen.go`, the scaffold-once
`<entity>_repo_ext.go` seams — lands in that directory and declares its package
(`package store`). Everything compiled against the ORM follows it: the CRUD
wiring imports it (as `db`, the qualifier every generated CRUD file uses),
`compose.go` provides `store.Store` / `store.<Entity>Store` Deps fields, the
test factories, `forge project shapes --kind store`, and the drift guard. The
name-collision refusal and `//forge:no-orm` read that package, not internal/db.
The `_gen.go` files open with Go's `// Code generated by forge. DO NOT EDIT.`
banner, so golangci-lint and gopls treat them as generated with no exclusion
of yours; the `_repo_ext.go` seams are yours and carry no banner.
Use it when `internal/db` is already a data layer of yours whose names (a
`Chat` alias, a `Repo`, a `Store`) collide with the projection's, and you are
porting onto the generated store one table at a time: the two packages coexist,
and nothing about your `internal/db` has to change first. Moving the key
reclaims forge's previous projection from the old directory; your
`_repo_ext.go` seams there are yours and stay.
## Allowing one destructive migration: `-- forge:allow-destructive`
`forge lint --migration-safety` refuses `DROP COLUMN`, `DROP TABLE` and `TRUNCATE`. When the
change is intentional, mark that migration file with a SQL comment line:
```sql
-- forge:allow-destructive: the column was never read; removed after the 2026-09 release
ALTER TABLE daemons DROP COLUMN last_heartbeat;
```
- It is **per file** and **in the file**: the exemption sits next to the SQL it excuses. There
is no forge.yaml allowlist and no second spelling (`-- forge-safety: allow-destructive` is
gone and no longer silences anything).
- `forge project audit` lists every migration that carries it (`allow_destructive_files`).
- NOT NULL findings have their own separate directive, `-- forge:allow-unsafe-not-null`.
**Editing an applied migration.** forge does not checksum migrations, so adding the comment
to an already-merged file does not disturb forge. Whether your migration RUNNER records a hash
of the file is the runner's business — check it before touching a merged file, and never change
the statements themselves.
## A migration file runs as one transaction
The migrator (and AutoMigrate, and testkit) sends a migration file to postgres as ONE query.
A query holding several statements runs as one implicit transaction, so two kinds of file
pass review, fail at deploy, and leave the schema dirty. `forge lint --migration-safety`
refuses both, at the statement's line.
- **`non-transactional-statement`** — a statement postgres refuses inside a transaction block
(SQLSTATE 25001) shares its file with another statement. `CREATE`/`DROP INDEX CONCURRENTLY`,
`REINDEX … CONCURRENTLY` (and `REINDEX SCHEMA|DATABASE|SYSTEM`), `ALTER TABLE … DETACH
PARTITION … CONCURRENTLY`, `VACUUM`, a table-less `CLUSTER`, and the database, tablespace,
`ALTER SYSTEM` and subscription statements. Give each one a file of its own
(`forge db migration new <name>`): a lone statement runs outside any transaction block.
- **`enum-value-used-before-commit`** — a file uses an enum value it also adds
(`ALTER TYPE … ADD VALUE 'x'`, then `'x'` in an UPDATE, INSERT or DEFAULT). A value added in
a transaction cannot be used until it commits (SQLSTATE 55P04). Move the `ADD VALUE` to an
earlier migration of its own. A value added to a type the same file creates is fine.
Both read statements, not the database. When postgres does run the file as one transaction
(a subscription created with `slot_name = NONE`; a string that only shares an added enum
value's spelling), say so in the file with `-- forge:allow-in-transaction: <why>`.
`forge lint --show-suppressed` lists it.
`ALTER TYPE … ADD VALUE` on its own is not refused: postgres has allowed it inside a
transaction since 12, and every postgres forge provisions or tests against is 16 or newer.
## Entity field types
The entity struct's field names and types are Go's, and lossless against the
column:
- Names spell initialisms in capitals: `id` → `ID`, `org_id` → `OrgID`,
`api_key` → `APIKey` (a plural stays: `user_ids` → `UserIds`). The
`<E>Field*` and `<E>Constraint*` constants follow.
- An integer is as wide as its column: `INTEGER` → `int32`, `SMALLINT` →
`int16`, `BIGINT` → `int64`.
- `JSONB` / `JSON` is `json.RawMessage` — the document's bytes, nil for NULL
(`jsonb[]` stays `[]string`).
- `COMMENT ON COLUMN t.c IS 'forge:go-type=<type>'` declares another type for
one column: a named enum over an integer, `map[string]any` over json,
`time.Duration` over a bigint, or `<import path>[;<pkg>].<Type>`. The type
must scan and bind by Bun's rules. forge generates no wire conversion for
such a column: a CRUD rpc carrying it fails generate naming it.