---
name: go-postgres-react
description: "Use when building, refactoring, or reviewing a Go + PostgreSQL (pgx & sqlc) + React project (Go, PostgreSQL, React, Docker, TypeScript). High-throughput systems architecture rules for Go (Golang), pgxpool connection management, sqlc type-safe query generation, and React web dashboards."
license: MIT
metadata:
  source: https://stackitfast.com/rules/go-postgres-react
  version: "2026-10-04"
---

# Go + PostgreSQL (pgx & sqlc) + React — Agent Skill

## When to use this skill
- Any task that scaffolds, modifies, refactors, or reviews code in a Go + PostgreSQL (pgx & sqlc) + React codebase.
- Whenever the project depends on Go, PostgreSQL, React, Docker, TypeScript.
- Apply these guidelines before proposing architecture, database, or deployment changes.

## Guidelines
# Project Architecture & Guidelines (Go + PostgreSQL + React)

## 1. System Architecture
- **Backend Language**: Go (Golang 1.22+).
- **Database Driver**: `pgx/v5` with `pgxpool` connection pooling.
- **SQL Query Compilation**: `sqlc` for compile-time type-safe Go struct and query generation.
- **HTTP Framework**: Standard library `net/http` with `chi` or `echo` router.
- **Frontend Client**: React + TypeScript Single Page Application (SPA).

## 2. PostgreSQL Connection Pool Management (pgxpool)
- Configure `pgxpool.Config` during application startup:
  ```go
  config, err := pgxpool.ParseConfig(databaseURL)
  if err != nil {
      log.Fatalf("Unable to parse DB URL: %v", err)
  }

  config.MaxConns = 25
  config.MinConns = 5
  config.MaxConnLifetime = 1 * time.Hour
  config.MaxConnIdleTime = 15 * time.Minute
  config.HealthCheckPeriod = 1 * time.Minute

  pool, err := pgxpool.NewWithConfig(context.Background(), config)
  if err != nil {
      log.Fatalf("Unable to create connection pool: %v", err)
  }
  defer pool.Close()
  ```
- Always propagate `context.Context` (with timeouts/deadlines) into all database query calls (`pool.Query(ctx, ...)`).

## 3. SQL & Schema Rules (sqlc)
- Write plain SQL files in `sql/queries/` and DDL migrations in `sql/schema/`.
- Run `sqlc generate` to compile SQL into type-safe Go code. NEVER write manual string concatenation queries.
- Migrations: Manage database versions using `golang-migrate` or `goose`.

## 4. Layer Organization
- `cmd/server/main.go`: Application entrypoint, configuration parsing, dependency wiring, graceful shutdown.
- `internal/db/`: Generated sqlc models and database queries.
- `internal/api/`: HTTP route handlers, middleware, request decoding, response serialization.
- `internal/service/`: Business domain logic and transactional boundaries.
- `frontend/`: React SPA source code.

## 5. Common Pitfalls to Avoid
- ❌ Forgetting `rows.Close()` when iterating over raw query results.
- ❌ Ignoring context cancellation: If an HTTP client disconnects, pass `r.Context()` to cancel active database queries immediately.
- ❌ Global Database Handles: Inject `*pgxpool.Pool` or `*db.Queries` into handler structs via constructor functions.

## 6. Testing Conventions
- Use Go's built-in `testing` package with `testify/assert` for readable assertions; avoid heavier frameworks unless the team already standardizes on one.
- Spin up an ephemeral Postgres instance per test run with `testcontainers-go` rather than mocking `pgx` — sqlc-generated queries should be verified against a real schema.
- Table-driven tests (`[]struct{ name string; input ...; want ... }`) are the idiomatic Go pattern; use them for handler and service logic.
- Run `go test -race ./...` in CI to catch data races in goroutines handling concurrent requests.

## 7. Git Workflow & PR Conventions
- Conventional Commits (`feat:`, `fix:`, `refactor:`) scoped by package, e.g. `fix(internal/api): handle nil pointer on empty query result`.
- Regenerate and commit `sqlc generate` output in the same PR as any `sql/queries/` change — never let generated code drift from source SQL.
- Require `go vet ./...`, `go test -race ./...`, and `golangci-lint run` green before merge.
- Squash-merge; keep `main` bisectable for `go test` regression hunting.

## Source
Maintained at https://stackitfast.com/rules/go-postgres-react — also available as AGENTS.md, CLAUDE.md, and Cursor .mdc.