rinha2-back-end-go

Getting Started

Prerequisites

  • Docker with Docker Compose and a reachable Docker daemon.
  • A shell with curl for quick smoke tests.

The full benchmark stack depends on Docker daemon access. In this Hermes environment the Docker CLI exists, but daemon access is not available, so local compose verification must run in CI or on a machine with Docker permissions.

Clone and run

git clone https://github.com/jonathanperis/rinha2-back-end-go.git
cd rinha2-back-end-go
docker compose up nginx -d --build

The API is exposed through NGINX at http://localhost:9999.

Smoke-test the API

Check the health endpoint used by CI:

curl -i http://localhost:9999/healthz

Create a credit transaction:

curl -sS -X POST http://localhost:9999/clientes/1/transacoes   -H "Content-Type: application/json"   -d '{"valor": 1000, "tipo": "c", "descricao": "deposito"}'

Read the statement:

curl -sS http://localhost:9999/clientes/1/extrato

Try an over-limit debit to confirm the current database behavior: the stored procedure refuses the balance mutation and returns the existing balance. This is documented as current behavior on the source-audit page rather than as a strict 422 validation response.

curl -i -X POST http://localhost:9999/clientes/1/transacoes   -H "Content-Type: application/json"   -d '{"valor": 999999999, "tipo": "d", "descricao": "limite"}'

Useful compose targets

Command Use
docker compose up nginx -d --build Build and start the challenge-counted stack behind NGINX.
docker compose logs -f nginx webapi1-go webapi2-go db Follow request path and database startup logs.
docker compose up k6 --build --force-recreate Run the configured k6 service after the API is healthy. Root compose runs MODE=dev; prod compose runs MODE=prod.
docker compose down -v Stop services and remove the database volume for a clean run.

Endpoint summary

Endpoint Method Payload / response
/healthz GET Returns Healthy; used by compose/CI health checks.
/clientes/{id}/transacoes POST JSON body with valor, tipo, and descricao. Returns id, limite, and updated saldo.
/clientes/{id}/extrato GET Returns saldo metadata and up to 10 recent ultimas_transacoes; the current Go DTO serializes transaction valor, tipo, and descricao.

Current response examples

Transaction response:

{
  "id": 1,
  "limite": 100000,
  "saldo": 1000
}

Statement response:

{
  "saldo": {
    "total": 1000,
    "limite": 100000,
    "data_extrato": "2026-05-29T22:00:00Z"
  },
  "ultimas_transacoes": [
    {
      "valor": 1000,
      "tipo": "c",
      "descricao": "deposito"
    }
  ]
}

For the full status-code matrix and source-backed edge cases, see Source Audit.

Local Go build

cd src/WebApi
go build -ldflags="-s -w" -o rinha2-back-end-go .

The binary requires DATABASE_URL; inside the Docker network it should point at the db service with credentials matching the compose/PostgreSQL environment.