Go + PostgreSQL (pgx & sqlc) + React

Curated rule Developer Tool & API · Internal Admin Tool Updated Oct 2026 Which file does my tool read?

High-throughput systems architecture rules for Go (Golang), pgxpool connection management, sqlc type-safe query generation, and React web dashboards.

Go PostgreSQL React Docker TypeScript

Formats: 4 files
AGENTS.md: 59 lines
CLAUDE.md: 15 lines
Languages: Go, TypeScript
Updated: Oct 2026
Used by: 4 projects

Install

Writes .claude/skills/go-postgres-react/SKILL.md

$ curl -s --create-dirs -o .claude/skills/go-postgres-react/SKILL.md https://stackitfast.com/rules/go-postgres-react/SKILL.md

Rule files

AGENTS.md· 59 lines · 3.2 KB

1	# Project Architecture & Guidelines (Go + PostgreSQL + React)
2
3	## 1. System Architecture
4	- Backend Language: Go (Golang 1.22+).
5	- Database Driver: `pgx/v5` with `pgxpool` connection pooling.
6	- SQL Query Compilation: `sqlc` for compile-time type-safe Go struct and query generation.
7	- HTTP Framework: Standard library `net/http` with `chi` or `echo` router.
8	- Frontend Client: React + TypeScript Single Page Application (SPA).
9
10	## 2. PostgreSQL Connection Pool Management (pgxpool)
11	- Configure `pgxpool.Config` during application startup:
12	```go
13	config, err := pgxpool.ParseConfig(databaseURL)
14	if err != nil {
15	log.Fatalf("Unable to parse DB URL: %v", err)
16	}
17
18	config.MaxConns = 25
19	config.MinConns = 5
20	config.MaxConnLifetime = 1 * time.Hour
21	config.MaxConnIdleTime = 15 * time.Minute
22	config.HealthCheckPeriod = 1 * time.Minute
23
24	pool, err := pgxpool.NewWithConfig(context.Background(), config)
25	if err != nil {
26	log.Fatalf("Unable to create connection pool: %v", err)
27	}
28	defer pool.Close()
29	```
30	- Always propagate `context.Context` (with timeouts/deadlines) into all database query calls (`pool.Query(ctx, ...)`).
31
32	## 3. SQL & Schema Rules (sqlc)
33	- Write plain SQL files in `sql/queries/` and DDL migrations in `sql/schema/`.
34	- Run `sqlc generate` to compile SQL into type-safe Go code. NEVER write manual string concatenation queries.
35	- Migrations: Manage database versions using `golang-migrate` or `goose`.
36
37	## 4. Layer Organization
38	- `cmd/server/main.go`: Application entrypoint, configuration parsing, dependency wiring, graceful shutdown.
39	- `internal/db/`: Generated sqlc models and database queries.
40	- `internal/api/`: HTTP route handlers, middleware, request decoding, response serialization.
41	- `internal/service/`: Business domain logic and transactional boundaries.
42	- `frontend/`: React SPA source code.
43
44	## 5. Common Pitfalls to Avoid
45	- ❌ Forgetting `rows.Close()` when iterating over raw query results.
46	- ❌ Ignoring context cancellation: If an HTTP client disconnects, pass `r.Context()` to cancel active database queries immediately.
47	- ❌ Global Database Handles: Inject `pgxpool.Pool` or `db.Queries` into handler structs via constructor functions.
48
49	## 6. Testing Conventions
50	- Use Go's built-in `testing` package with `testify/assert` for readable assertions; avoid heavier frameworks unless the team already standardizes on one.
51	- 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.
52	- Table-driven tests (`[]struct{ name string; input ...; want ... }`) are the idiomatic Go pattern; use them for handler and service logic.
53	- Run `go test -race ./...` in CI to catch data races in goroutines handling concurrent requests.
54
55	## 7. Git Workflow & PR Conventions
56	- Conventional Commits (`feat:`, `fix:`, `refactor:`) scoped by package, e.g. `fix(internal/api): handle nil pointer on empty query result`.
57	- Regenerate and commit `sqlc generate` output in the same PR as any `sql/queries/` change — never let generated code drift from source SQL.
58	- Require `go vet ./...`, `go test -race ./...`, and `golangci-lint run` green before merge.
59	- Squash-merge; keep `main` bisectable for `go test` regression hunting.

Works with Cursor · Claude Code · Windsurf · AGY

Architecture notes

Architecture Overview

Production conventions for high-throughput, low-latency concurrent systems with Go (Golang), pgxpool, sqlc, and React.

Verified Real-World Adoption

This exact architecture powers massive monitoring and messaging systems including Grafana, Mattermost, Lago, and PocketBase.

Key Architectural Nuances

Compile-Time Type Safety: sqlc validates SQL queries against actual PostgreSQL schema at build time.
Context-Aware Query Execution: Automatically cancels long-running database queries if clients drop HTTP connections.

Frequently asked questions

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Yes — AGENTS.md is the open, cross-tool standard read by Cursor, Claude Code, Windsurf, and 30+ other agents. A dedicated .mdc file is also included for Cursor's native .cursor/rules format.

Why use sqlc instead of an ORM like GORM?

sqlc compiles hand-written SQL into type-safe Go structs and functions at build time, so a broken query fails the build instead of failing at runtime in production. ORMs like GORM generate SQL dynamically at runtime, which trades compile-time safety for convenience — sqlc keeps the performance and predictability of raw SQL with full type safety.

Why propagate context.Context into every database call?

If an HTTP client disconnects mid-request, Go's context carries that cancellation signal down into pgx, which immediately aborts the in-flight query instead of letting it run to completion on an abandoned connection. Skipping this wastes database connections and CPU on work nobody is waiting for anymore.

Used in production

Explore all stacks

Gotify

Self-Hosted Real-Time Push Server · 2-5 People

Gotify keeps the server one deployable Go binary by embedding its Vite/React web UI, using Gin and gorilla/websocket for the REST and streaming API, and swapping SQLite, MySQL or PostgreSQL through GORM, while a compiled Go plugin system handles extensibility instead of a scripting layer.

Grafana

Monitoring & Observability Dashboard · 20+ people

Grafana splits its backend into a growing set of independently versioned Go modules under apps/, tied together by a go.work workspace and modeled with Kubernetes-style APIs (pkg/apiserver, CUE-defined kinds), so individual product areas like alerting or dashboards can evolve without one monolithic backend module.

SeaweedFS

Distributed Blob & File Storage · 2-5 People

Decoupling directory metadata from physical volume storage eliminates central metadata bottlenecks, enabling massive horizontal scaling for small and large files alike.

Mattermost

Team Collaboration Suite · 20+ people

A single Go binary keeps the API, scheduler, and websocket hub in one deployable process backed by a required PostgreSQL database, while optional Redis, Elasticsearch, and OpenSearch clients let larger deployments add caching and full-text search without changing the core architecture.

Where this stack fits

Stack It First recommends it at:

Web · Scale · Tool Backend · Scale · Product API

Walk the web roadmap Walk the backend roadmap

Every stack ships as files

More AI agent coding rules and skills

View all

astro-static-content/AGENTS.mdAstro Static Site + Content Collections + TailwindAstro · Tailwind CSS · TypeScript bun-hono-sqlite/AGENTS.mdBun + Hono + SQLite (libSQL & Drizzle ORM)Bun · Hono · SQLite django-postgres-redis/AGENTS.mdDjango + PostgreSQL + Redis + CeleryDjango · Python · PostgreSQL fastapi-jev-decision-service/AGENTS.mdFastAPI + Jev Decision Service (Python)Python · FastAPI · Jev