How to Add a Go Health Check Endpoint

Why a health check needs to ping the DB

A handler that always returns 200 OK is worse than no health check at all - it tells the load balancer the service is ready even when the database is down and every real request will fail. The check must exercise whatever the service depends on. For most Go APIs that means db.Ping().

Adding the handler

Register /health alongside your existing routes and call db.Ping():

func handleHealth(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    if err := db.Ping(); err != nil {
        w.WriteHeader(http.StatusServiceUnavailable) // 503
        json.NewEncoder(w).Encode(map[string]string{"status": "unhealthy"})
        return
    }
    w.WriteHeader(http.StatusOK) // 200
    json.NewEncoder(w).Encode(map[string]string{"status": "healthy"})
}

Wire it up where you register your other routes:

http.HandleFunc("/items", handleItems)
http.HandleFunc("/health", handleHealth)

Rebuild and restart after editing main.go:

go build -o my-api .
pkill -f my-api; ./my-api &
curl -s http://localhost:4000/health
# {"status":"healthy"}

What db.Ping() actually does

db.Ping() borrows a connection from the pool, sends a lightweight round-trip to the database, and returns it. It is not free - it opens a real connection if the pool is empty - but it is cheap enough to run on every health probe (which typically fires every few seconds). If the DB is unreachable, Ping() returns an error and you surface that as 503.

Splitting liveness from readiness

In production Kubernetes deployments, one health endpoint is not always enough:

• /livez - is the process alive? Return 200 immediately, no DB check. Kubernetes uses this as a liveness probe: failure here triggers a pod restart.
• /readyz - can the pod serve traffic? Run db.Ping() here. Kubernetes uses this as a readiness probe: failure here removes the pod from the Service endpoints without restarting it.

Keeping them separate means a temporary DB blip pulls the pod from rotation without killing it, and a deadlocked goroutine can still be caught by the cheap liveness check.

Setting the Content-Type header

Always set Content-Type: application/json before writing the status code. In Go's net/http, headers must be set before the first call to w.WriteHeader() or they are silently discarded. Put w.Header().Set(...) first.