Skip to content
Back to skills

Tx Isolation

ASecurity

Upgrade v1.0.0 pkg/orm transactions to an explicit isolation level — run forge fix tx-isolation, clear what it lists, then review forgeconv-tx-lock-under-serializable.

  • 10 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 13, 2026
ai-agentsgobashsqldatabase

Works with

  • cli

Security analysis

A100/100

Scanned November 13, 2026

npx -y skills add reliant-labs/forge --skill tx-isolation --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Tx Isolation?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Tx Isolation
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-tx-isolation/badge)](https://www.skillsdirectory.com/skills/reliant-labs-tx-isolation)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: migration-v1.0.0-tx-isolation
description: Upgrade v1.0.0 pkg/orm transactions to an explicit isolation level — run forge fix tx-isolation, clear what it lists, then review forgeconv-tx-lock-under-serializable.
relevance: migration
---

# v1.0.0 — explicit transaction isolation: no default level

Use when Go code calls `RunTx(ctx, fn)`, `RunTxWithOptions`,
`RunTransaction(ctx, fn)`, `RunTransactionWithOptions`, or an `*orm.Client`'s
`BeginTx`.

### What changed

pkg/orm had two opposite defaults. `RunTx`, `RunTxWithOptions` and
`BeginDetached` with an unset level began **SERIALIZABLE** (RunTx retrying
`40001`/`40P01` up to seven times); `Client.BeginTx` and `RunTransaction`
with nil options began at the database's default, **READ COMMITTED**, once.
The two make opposite correctness arguments — SERIALIZABLE is correct
without locks because the database aborts the loser and the retry re-reads;
READ COMMITTED is correct only with a lock or a single statement — so a port
from one call to the other changed what the code relied on, with no diff
line saying so. Lock-based code moved onto `RunTx` dropped updates under
contention (the waiter wakes into a stale snapshot and fails `40001`), and
lock-free code moved onto `RunTransaction` would double-apply.

Now every opener takes an `orm.TxPolicy` — a level constant
(`orm.Serializable`, `orm.ReadCommitted`, `orm.RepeatableRead`) carrying its
attempt budget, or an `orm.TxOptions` refined from one — and an unset level is
rejected with `orm.ErrInvalidTxOptions` naming the call site:

| Before | After |
|---|---|
| `RunTx(ctx, fn)` | `RunTx(ctx, orm.Serializable, fn)` — serializable, 7 attempts |
| `RunTxWithOptions(ctx, opts, fn)` | `RunTx(ctx, opts, fn)` |
| `tx.RunTx(ctx, fn)` on an `*orm.Tx` | `tx.Join(ctx, fn)` — a join keeps the transaction's own level |
| `RunTransaction(ctx, fn)` | `RunTransaction(ctx, orm.ReadCommitted, fn)` — read committed, 1 attempt |
| `RunTransactionWithOptions(ctx, nil, fn)` | `RunTransaction(ctx, orm.ReadCommitted, fn)` |
| `client.BeginTx(ctx, nil)` | `client.BeginDetached(ctx, orm.ReadCommitted)` |
| `BeginDetached(ctx, orm.TxOptions{})` | `BeginDetached(ctx, orm.Serializable.WithMaxAttempts(1))` |
| `orm.TxOptions{Isolation: orm.IsolationReadCommitted}` (7 attempts) | `orm.ReadCommitted.WithMaxAttempts(orm.DefaultTxMaxAttempts)` |
| `orm.IsolationSerializable` / `IsolationReadCommitted` / `IsolationRepeatableRead` | `orm.Serializable` / `ReadCommitted` / `RepeatableRead` |
| `orm.IsolationDefault` | gone — `orm.Serializable` |

`RunTxReadOnly(ctx, fn)` is unchanged (SERIALIZABLE READ ONLY DEFERRABLE): a
transaction that cannot write has one right level. `BeginDetached` (and the
`Tx` it returns) cannot retry, so it requires `MaxAttempts == 1`.
`RunTransaction` now honours the attempt budget like `RunTx`, and reports an
exhausted `40001`/`40P01` as `svcerr.Aborted` (the driver error kept as its
cause). An `orm.Context` implementation — a test double — needs the new
method set: `RunTx(ctx, policy orm.TxPolicy, fn)`, `RunTransaction(ctx, policy, fn)`,
`BeginDetached(ctx, policy)`, no `RunTxWithOptions`.

### What to do

1. Run the codemod (`forge project upgrade` runs it for you):

   ```bash
   forge fix tx-isolation --dry-run   # list every site
   forge fix tx-isolation
   ```

   It rewrites every call on a pkg/orm handle to the explicit form that
   **keeps today's behaviour exactly** — same level on the wire, same number
   of attempts — and never chooses a different one. It is type-aware: a
   project's own `RunTx` (a repository wrapper) and database/sql's `BeginTx`
   are left alone. It prints each site with the level it kept.

2. Clear what it lists under **Next**: options computed at run time (a
   `*sql.TxOptions` built from a variable, an `orm.TxOptions` whose level is
   not a constant) and `orm.Context` test doubles. Each line names the edit.

3. Review the levels it kept — this is the decision the codemod will not
   make. `forge lint --conventions` reports every SERIALIZABLE transaction
   whose body takes a lock as `forgeconv-tx-lock-under-serializable`:

   - the lock is the correctness argument (lock-based code that was
     READ COMMITTED before it was ported onto `RunTx`) → `orm.ReadCommitted`;
   - SERIALIZABLE is the argument → delete the lock.

   And the reverse, which no lint sees: a `RunTransaction` (now
   `orm.ReadCommitted`) whose closure reads, checks, then writes with no lock
   was racy before and is still; move it to `RunTx(ctx, orm.Serializable, …)`
   (`service-layer/transactions`, "Porting a transaction").

4. `go build ./... && go vet ./...`, then the tests that cover your
   transactions — a test that asserts a transaction's level on the wire
   (`SHOW transaction_isolation` inside it) is the durable guard.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.