Skip to main content
skill CX Codex

go-database — Claude Code skill for Go databases

go-database is a Claude Code skill for database work in Go services. It activates for SQL queries, connection pools, transactions, and migrations.

MIT ★ 90 updated 2026-10-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add eduardo-sl/go-agent-skills --skill go-database -a claude-code
Open on GitHub

What go-database does

go-database guides database access in Go services, covering pool configuration, parameterized queries, and closing query results. Its transaction guidance includes rollback on errors; concurrency patterns cover row locks and version-based conflict checks.

The skill also addresses repository interfaces, SQL error handling, migrations, and ORM use with sqlc, GORM, and ent. It includes advice on batch writes and keyset pagination, with detailed examples in reference files. The Go toolchain is required. sqlc, golang-migrate, and Docker are optional tools.

What it helps with

  • configure a connection pool for a Go service
  • run parameterized SQL queries with context
  • handle database errors and roll back transactions
  • organize migrations and repository interfaces

Example prompts for the agent

  • Set up database access for this Go service.
  • Review transaction handling and database errors in this repository.
  • Add a migration for this database schema change.

How to install go-database

1Skills CLI (Vercel)

npx skills add eduardo-sl/go-agent-skills --skill go-database -a claude-code

2Manually: put the files in place

~/.claude/skills/go-database/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/go-database/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about go-database

How do I install go-database in Claude Code?

Run npx skills add eduardo-sl/go-agent-skills --skill go-database -a claude-code. The skill file is at ~/.claude/skills/go-database/SKILL.md.

What does go-database do?

It guides database access in Go services, including SQL queries, connection pools, transactions, migrations, and ORM use.

What does go-database require?

It requires the Go toolchain. sqlc, golang-migrate, and Docker are optional.

Source text

SKILL.md · MIT
---
name: go-database
description: >
  Database patterns for Go services: database/sql, connection management,
  transactions, migrations, query builders, and ORM usage (sqlc, GORM, ent).
  Use when: "database access", "SQL query", "connection pool",
  "transactions", "database migration", "sqlc", "GORM", "ent", "prepared
  statement", "repository pattern".
  Not for: in-memory structures (go-data-structures), SQL security
  (go-security-audit), query profiling (go-performance-review).
user-invocable: true
license: MIT
compatibility: Designed for Claude Code or similar AI coding agents working on Go projects. Requires the Go toolchain. sqlc, golang-migrate and Docker are optional.
allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(gofmt:*)
metadata:
  author: eduardo-sl
  version: "1.5.1"
---

# Go Database Patterns

Database access is where most Go services spend their complexity budget.
Get connection management, transactions, and query patterns right.

> Community default. A project skill or agent-config rule that explicitly
> supersedes `go-database` takes precedence over this one.

Detailed reference material, loaded on demand:

- `references/query-patterns.md` — full query/scan/rows patterns, null
  handling, N+1 avoidance, connection-leak examples.
- `references/tooling.md` — repository pattern implementation, sqlc
  annotated queries, migration tooling and rules.
- `references/locking-and-retries.md` — `FOR UPDATE`/`SKIP LOCKED`,
  optimistic versioning, retrying `40001`/`40P01`, constraint errors.
- `references/performance.md` — COPY and batched inserts, keyset
  pagination, pool statistics, `sql.Null[T]`.
- `references/testing.md` — choosing fakes vs a real database,
  testcontainers setup, isolation strategies.

Read a reference file only when the summary below is not enough.

## 1. Connection Management

Configure the pool explicitly — the default is unbounded connections:

```go
func OpenDB(dsn string) (*sql.DB, error) {
    db, err := sql.Open("postgres", dsn)
    if err != nil {
        return nil, fmt.Errorf("open db: %w", err)
    }

    db.SetMaxOpenConns(25)
    db.SetMaxIdleConns(10)
    db.SetConnMaxLifetime(5 * time.Minute)
    db.SetConnMaxIdleTime(1 * time.Minute)

    if err := db.PingContext(context.Background()); err != nil {
        return nil, fmt.Errorf("ping db: %w", err)
    }

    return db, nil
}
```

| Setting | Guideline |
|---|---|
| `MaxOpenConns` | Match your DB's max connections / number of app instances |
| `MaxIdleConns` | 40-50% of MaxOpenConns |
| `ConnMaxLifetime` | 5-10 minutes (prevents stale connections behind load balancers) |
| `ConnMaxIdleTime` | 1-2 minutes |

## 2. Query Rules

1. **Parameterized queries only** — string concatenation into SQL is an
   injection vulnerability, no exceptions.
2. **Always pass context** — use the `*Context` variants
   (`QueryContext`, `QueryRowContext`, `ExecContext`) so queries respect
   cancellation and timeouts.
3. **`defer rows.Close()`** immediately after the error check, and check
   `rows.Err()` after the iteration loop.
4. **Handle `sql.ErrNoRows` explicitly** with `errors.Is`, mapping it to
   a domain error like `ErrUserNotFound`.

```go
var user User
err := db.QueryRowContext(ctx,
    "SELECT id, name, email FROM users WHERE id = $1", id,
).Scan(&user.ID, &user.Name, &user.Email)

if errors.Is(err, sql.ErrNoRows) {
    return nil, ErrUserNotFound
}
if err != nil {
    return nil, fmt.Errorf("get user %s: %w", id, err)
}
```

Multi-row iteration patterns: `references/query-patterns.md`.

## 3. Transactions

Use a helper that guarantees rollback on error:

```go
func WithTx(ctx context.Context, db *sql.DB, fn func(tx *sql.Tx) error) (err error) {
    tx, err := db.BeginTx(ctx, nil)
    if err != nil {
        return fmt.Errorf("begin tx: %w", err)
    }
    defer func() {
        if p := recover(); p != nil {
            _ = tx.Rollback() // release the connection, then keep panicking
            panic(p)
        }
        if err != nil {
            if rbErr := tx.Rollback(); rbErr != nil && !errors.Is(rbErr, sql.ErrTxDone) {
                err = errors.Join(err, fmt.Errorf("rollback: %w", rbErr))
            }
        }
    }()

    if err := fn(tx); err != nil {
        return err
    }
    if err := tx.Commit(); err != nil {
        return fmt.Errorf("commit tx: %w", err)
    }
    return nil
}
```

The deferred rollback covers a panic inside `fn`, which would otherwise
leave the transaction open and its connection out of the pool until the
context ends. `errors.Join` keeps both errors inspectable.

Set isolation explicitly for critical operations:
`sql.TxOptions{Isolation: sql.LevelSerializable}`.

## 4. Concurrency Control and Errors

- Read-then-write in one transaction with `SELECT ... FOR UPDATE`; job
  queues claim rows with `FOR UPDATE SKIP LOCKED`; lock rows in a
  consistent order to avoid deadlocks.
- For user-facing edits, optimistic concurrency: a `version` column in the
  `WHERE`, and zero rows affected means conflict.
- `40001` (serialization failure) and `40P01` (deadlock) are retryable:
  retry the whole transaction function with jittered backoff and a cap.
  The function must have no side effects outside the transaction.
- Map constraint violations to domain errors (`23505` unique →
  `ErrEmailTaken` → 409). Let the database enforce uniqueness; check-then-
  insert races.

Code: `references/locking-and-retries.md`.

## 5. Structure and Tooling

- **Repository pattern:** define the interface at the consumer side,
  implement it with concrete database access, map driver errors to
  domain errors at this boundary.
- **sqlc:** prefer it for raw-SQL projects — generates type-safe Go from
  annotated SQL, catching query/schema mismatches at build time.
- **Migrations:** use a tool (`goose`, `golang-migrate`, `atlas`), one
  migration per change, forward-only in production, with `down` SQL, run
  as a separate step — not at server startup.

Implementations and examples: `references/tooling.md`.

## 6. Common Pitfalls

- **Null columns:** use `sql.NullString`/`sql.NullInt64` or pointer
  fields (`*string`, nil = SQL NULL). Scanning NULL into a plain string
  errors at runtime.
- **N+1 queries:** a query inside a loop over query results. Replace
  with a JOIN or a batch query (`WHERE id = ANY($1)`).
- **Connection leaks:** any early `return` between `Query` and
  `defer rows.Close()` leaks a connection from the pool — and so does
  `db.Query` for a statement that returns no rows; use `ExecContext`.

Worked examples of each pitfall: `references/query-patterns.md`.

## 7. Performance

- Bulk writes: pgx `CopyFrom`, or multi-row `INSERT` in batches of a few
  hundred rows — never one round trip per row.
- Paginate with a keyset cursor (`WHERE (created_at, id) < ($1, $2)`), not
  `OFFSET`, which scans skipped rows and shifts under inserts.
- Export `db.Stats()`: a rising `WaitCount` means the pool, or something
  holding connections, is the bottleneck.
- `sql.Null[T]` (Go 1.22+) replaces the per-type `NullString` family.

Examples: `references/performance.md`.

## 8. Testing

Fake the consumer-side repository interface for service logic; test SQL
against a real database in a container (testcontainers, behind
`//go:build integration`), running the production migrations. Isolate
tests with a transaction per test, a template database, or truncation.
Examples: `references/testing.md`.

## Verification Checklist

1. Connection pool configured with explicit limits (`MaxOpenConns`, `MaxIdleConns`, lifetimes)
2. All queries use parameterized placeholders, never string concatenation
3. All `QueryContext` results have `defer rows.Close()` immediately after error check
4. `rows.Err()` checked after row iteration loop
5. `sql.ErrNoRows` handled explicitly with `errors.Is`
6. Transactions use a helper that guarantees rollback on error
7. Context propagated to all database calls (`*Context` variants)
8. Nullable columns use `sql.NullString` / `sql.NullInt64` or pointer types
9. No N+1 query patterns — use JOINs or batch queries
10. Migrations are versioned, reversible, and run separately from app startup
11. No `OFFSET` pagination on large tables; bulk writes batched
12. SQL is tested against a real database, not mocked query strings

© eduardo-sl · MIT · eduardo-sl/go-agent-skills

Similar skills

All skills for Data and databases →

From the same set35

The whole set →
go-performance-review go-performance-review is a Claude Code skill that finds Go performance bottlenecks and checks optimizations with benchmarks and profiles. It supports hot-path reviews and allocation reduction. CX Codex +1 ★ 90repo stars go-observability go-observability — a skill that sets conventions for Go service telemetry: structured logs with log/slog, OpenTelemetry traces and metrics, SLO alerts. Useful once a service runs in production and you need to see what it does. CX Codex +1 ★ 90repo stars go-defensive-coding go-defensive-coding stops panics, slice aliasing, and subtle runtime bugs in Go: typed-nil interfaces, numeric truncation, and loop defer hazards. CX Codex +1 ★ 90repo stars go-concurrency-review go-concurrency-review is a Claude Code skill for reviewing and implementing concurrency patterns in Go. It kicks in for goroutine reviews, race investigations, and producer-consumer pipeline design. CX Codex +1 ★ 90repo stars go-naming Applies Go naming conventions from Effective Go to packages, methods, acronyms, and errors. Helps prevent stuttering names like order.OrderService. CX Codex +1 ★ 90repo stars go-modernize The go-modernize skill guides Go code updates using newer language and standard-library features. Use it for focused edits or a requested package or module sweep. CX Codex +1 ★ 90repo stars go-error-handling go-error-handling — a skill that tells your agent how to create, wrap and inspect Go errors: %w wrapping, sentinel errors, custom types, errors.Is and errors.As. CX Codex +1 ★ 90repo stars go-documentation The go-documentation skill directs coding agents on godoc conventions, testable examples, and project documentation for Go. It helps write docs that render cleanly on pkg.go.dev. CX Codex +1 ★ 90repo stars

Project sponsors

Companies that keep this analytics open