Go API Template

A minimal Go template for building HTTP APIs with Connect RPC, PostgreSQL, and Docker. Use this repo as a starting point for new services.

Stack

• Go 1.24+ – Application runtime
• Connect RPC – gRPC-compatible HTTP APIs (proto + generated Go)
• PostgreSQL – Database (pgx)
• Buf – Protobuf schema and code generation
• Docker & Compose – Local development and deployment

Prerequisites

• Go 1.24.3 or later
• Buf
• Docker and Docker Compose (for containerized runs)
• PostgreSQL (for local runs without Docker)

Quick Start

Generate protobuf code

buf generate

Run locally

Set the database URL and start the server:

export DATABASE_URL="postgres://user:password@localhost:5432/app"
make run

The API listens on http://localhost:8080.

Run with Docker Compose

Starts the app and PostgreSQL with hot reload (Air):

docker compose up

Ensure the app service has DATABASE_URL set, e.g. in compose.yml:

environment:
  DATABASE_URL: postgres://postgres:postgres@db:5432/app

Makefile

Target	Description
make all	Build the binary
make build	Build the binary
make run	Run the app
make test	Run tests (no coverage)
make test:ci	Run tests with coverage
make clean	Remove build artifacts

Tests use .env.test for DB connection (PGHOST, PGUSER, PGDATABASE, PGPASSWORD).

Project layout

.
├── main.go           # Entrypoint, DB init, server wiring
├── compose.yml       # App + Postgres for local dev
├── Containerfile     # Multi-stage: builder, development (Air), production
├── buf.yaml          # Buf config
├── buf.gen.yaml      # Buf codegen (Connect + Go)
├── db/
│   └── schema.sql    # Postgres schema (run on init)
├── proto/            # Protobuf definitions
│   └── app/api/v1/
├── pkg/
│   ├── db/           # Postgres pool and helpers
│   ├── gen/          # Generated Connect/Go code (from proto)
│   └── srv/          # HTTP server, Connect handlers, middleware
└── .github/
    └── go.yml        # CI: build, test, Codecov

Adding API methods

1. Define your RPCs in proto/app/api/v1/api.proto.
2. Run buf generate.
3. Implement the generated interface in pkg/srv/api.go.
4. Handlers are already registered in pkg/srv/srv.go.

Environment

Variable	Description
DATABASE_URL	Postgres connection URL (required)

For tests, use .env.test (or equivalent) with PGHOST, PGUSER, PGDATABASE, PGPASSWORD so that make test can connect to the test database.

CI/CD

• Build: make all
• Tests: make test:ci with a Postgres service and coverage upload to Codecov (set CODECOV_TOKEN in repo secrets)

License

Use and modify as needed for your project.