Skip to content

henriqueatila/golang-gin-best-practices / skills/golang-gin-architect

golang-gin-architect

Verified

Software architect for Go Gin APIs. Use when making architecture decisions, evaluating complexity, designing systems, choosing patterns, or coordinating across gin skills.

FileKindSize
SKILL.mdskill md10.7 KB
metadata.jsonconfig466 B
references/adr-format-and-templates.mdmarkdown4.1 KB
references/adr-service-extraction-and-example.mdmarkdown4.0 KB
references/api-design-error-contract-docs.mdmarkdown1.8 KB
references/api-design-filtering-bulk-evolution.mdmarkdown3.8 KB
references/api-design-versioning-pagination.mdmarkdown4.3 KB
references/clean-architecture-feature-module.mdmarkdown4.5 KB
references/clean-architecture-layers-di.mdmarkdown5.2 KB
references/complexity-assessment-budget.mdmarkdown5.6 KB
references/complexity-assessment-gates.mdmarkdown4.2 KB
references/complexity-assessment-patterns.mdmarkdown5.0 KB
references/cross-cutting-health-checks.mdmarkdown1.7 KB
references/cross-cutting-observability.mdmarkdown3.9 KB
references/cross-cutting-security-config.mdmarkdown4.4 KB
references/data-ownership-boundaries.mdmarkdown4.5 KB
references/data-ownership-sync-migration.mdmarkdown4.3 KB
references/data-patterns-cqrs.mdmarkdown3.8 KB
references/data-patterns-event-sourcing-aggregate.mdmarkdown2.2 KB
references/data-patterns-event-store.mdmarkdown3.7 KB
references/data-patterns-outbox.mdmarkdown3.7 KB
references/data-patterns-read-replicas.mdmarkdown2.6 KB
references/data-patterns-saga.mdmarkdown3.6 KB
references/error-flow-domain-layers.mdmarkdown5.3 KB
references/error-flow-handler-chain.mdmarkdown4.7 KB
references/golden-main-medium-project.mdmarkdown3.0 KB
references/golden-main-medium-startup.mdmarkdown2.8 KB
references/golden-main-small-project.mdmarkdown4.0 KB
references/grpc-interop-gateway-docker.mdmarkdown2.1 KB
references/grpc-interop-server-client.mdmarkdown2.7 KB
references/grpc-interop-setup.mdmarkdown3.6 KB
references/messaging-consumer-docker.mdmarkdown1.6 KB
references/messaging-consumer-workqueues.mdmarkdown3.6 KB
references/messaging-dlq-idempotency.mdmarkdown3.1 KB
references/messaging-dlq-setup.mdmarkdown2.4 KB
references/messaging-pubsub-exchanges.mdmarkdown3.6 KB
references/messaging-rabbitmq-connection.mdmarkdown3.2 KB
references/messaging-rabbitmq-producer.mdmarkdown2.4 KB
references/object-storage-download-presign.mdmarkdown3.5 KB
references/object-storage-multipart-minio.mdmarkdown2.2 KB
references/object-storage-setup-upload.mdmarkdown4.2 KB
references/redis-cache-warming-pubsub.mdmarkdown3.2 KB
references/redis-caching-patterns.mdmarkdown4.3 KB
references/redis-session-distributed-lock.mdmarkdown3.9 KB
references/resilience-circuit-breaker-bulkhead.mdmarkdown4.3 KB
references/resilience-retry-rate-limiting.mdmarkdown4.0 KB
references/skill-orchestration-overview.mdmarkdown3.2 KB
references/skill-orchestration-workflows.mdmarkdown5.4 KB
references/system-design-bounded-contexts.mdmarkdown4.1 KB
references/system-design-c4-model.mdmarkdown4.6 KB
references/system-design-dependency-graphs.mdmarkdown2.6 KB
references/system-design-domain-modeling.mdmarkdown3.5 KB
references/system-design-project-structure.mdmarkdown4.2 KB
references/tech-debt-identification-prioritization.mdmarkdown5.1 KB
references/tech-debt-refactoring-communication.mdmarkdown4.0 KB

references/data-patterns-read-replicas.md

View on GitHub
# Data Patterns — Read Replicas

Go implementation for PostgreSQL read replica pool with lag handling.

Companion to `data-patterns-cqrs.md` (CQRS pattern, materialized views).

**Default stance:** Add indexes and run EXPLAIN ANALYZE before splitting to replicas.

---

## Gate — all must be true

- [ ] Read/write ratio exceeds 5:1 AND you have measured that the primary is the bottleneck
- [ ] Replication lag is acceptable for your read use cases (typically <100ms for sync replica)
- [ ] You have a plan for handling replication lag in code (stale reads, retry on not-found)

**Simpler alternative:** Add indexes. Run `EXPLAIN ANALYZE` on your slowest queries. PostgreSQL with correct indexes routinely handles 10K+ reads/sec on modest hardware. Measure before splitting.

---

## Go Implementation

```go
// internal/repository/db.go
type DBPool struct {
    Primary *sqlx.DB // reads + writes
    Replica *sqlx.DB // reads only (can be nil — falls back to Primary)
}

func (p *DBPool) ReadDB() *sqlx.DB {
    if p.Replica != nil {
        return p.Replica
    }
    return p.Primary
}

func NewDBPool(primaryDSN, replicaDSN string) (*DBPool, error) {
    primary, err := sqlx.Connect("postgres", primaryDSN)
    if err != nil {
        return nil, fmt.Errorf("connect primary: %w", err)
    }
    pool := &DBPool{Primary: primary}
    if replicaDSN != "" {
        replica, err := sqlx.Connect("postgres", replicaDSN)
        if err != nil {
            slog.Warn("replica unavailable, using primary for reads", "err", err)
        } else {
            pool.Replica = replica
        }
    }
    return pool, nil
}
```

---

## Usage in Repository

```go
func (r *UserRepository) FindByID(ctx context.Context, id string) (*User, error) {
    var u User
    err := r.pool.ReadDB().GetContext(ctx, &u, `SELECT * FROM users WHERE id = $1`, id)
    if err != nil {
        return nil, fmt.Errorf("find user: %w", err)
    }
    return &u, nil
}

func (r *UserRepository) Create(ctx context.Context, u *User) error {
    _, err := r.pool.Primary.NamedExecContext(ctx,
        `INSERT INTO users (id, email, name) VALUES (:id, :email, :name)`, u)
    return err
}
```

---

## Handling Replication Lag (Read-Your-Writes)

```go
type contextKey string
const ReadYourWritesKey contextKey = "read_your_writes"

func (r *UserRepository) readDB(ctx context.Context) *sqlx.DB {
    if ryw, _ := ctx.Value(ReadYourWritesKey).(bool); ryw {
        return r.pool.Primary
    }
    return r.pool.ReadDB()
}
```

Set `ctx = context.WithValue(ctx, ReadYourWritesKey, true)` immediately after a write when the caller needs to read back their own write within the same request.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall