STACK IT FAST
ALL RULES & SKILLS

Go + PostgreSQL (pgx & sqlc) + React

Raw .MD go-postgres-react
CURATED RULE AGENTS.MD + CLAUDE.MD + .MDC + SKILL.MD

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

AGENTS.md
Paste in your project root
SKILL.md
Installs to .claude/skills/go-postgres-react
INTERACTIVE RULE & SKILL VIEWER (AGENTS.MD, CLAUDE.MD, .MDC & SKILL.MD)
Optimized for:CursorClaude CodeWindsurfAGY
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.
ARCHITECTURE NOTES & IMPLEMENTATION GUIDE
Export as Markdown

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.

MORE AI AGENT CODING RULES & SKILLS
View All Rules & Skills