# Gin CRUD API

A Gin 1.12 CRUD API starter for Go 1.25 that stores one resource, items, in PostgreSQL through pgx v5 and its pgxpool connection pool. It is for Go developers who want list, get, create, replace and delete endpoints with validation, JSON errors, a database health check, slog request logs, graceful shutdown and tests that need no database.

- Framework: Gin (Go)
- Category: Starters / CRUD APIs
- Creates: a server app and a PostgreSQL database on the Shared tier (1 GB)
- Plan: Lite or above
- Price: Free
- Author: Light Cloud
- Page: https://templates.light-cloud.com/starters/crud-apis/gin-postgresql-crud-api
- Updated: 2026-11-21

## Features

- GET /items?limit=20&offset=0 lists items oldest first; a limit outside 1 to 100 or a negative offset answers 400
- POST /items answers 201 and DELETE answers 204; an id that is not a positive 32-bit whole number is a 404
- name is trimmed and must be 1 to 200 characters; a description that is not a string is a 400
- Every error is { "error": "..." }, including unknown routes and a recovery middleware that turns a panic into a JSON 500
- GET /health pings the pool with a 3 second timeout and answers 503 when the database does not reply
- The items table is created on start with CREATE TABLE IF NOT EXISTS, so there is no migration tool to run
- Handlers depend on a small Store interface, so the table-driven route tests use an in-memory fake
- pgxpool capped at 5 connections, with TLS to the database by default (DB_SSLMODE=require)

## What you need

- A paid plan: deploying creates a PostgreSQL database, which the Free plan does not include
- To run it locally: Go 1.25 or newer, make, and Docker for a local PostgreSQL
- No API keys: it starts with nothing to configure
- Optional: GIN_MODE=debug for Gin's route list and warnings at start; it defaults to release
- Outside Light Cloud: a PostgreSQL database set through DB_HOST, DB_NAME, DB_USER and DB_PASSWORD, with DB_SSLMODE=disable if it has no TLS

## About

main.go reads PORT, GIN_MODE and the DB_* variables, builds a postgres:// URL, opens the pool and creates the table before the http.Server starts, so an unreachable database shows up at deploy time rather than on the first request. The SQL is a handful of hand-written queries in internal/store/store.go, request parsing lives in internal/server/request.go, and each handler is a few lines that call the store and answer with c.JSON. Adding a column means changing the CREATE TABLE, the Item struct, the queries and parseItem, plus one ALTER TABLE on a database that already has the table. On Light Cloud the Go module is built and run as a container on the platform's PORT with the DB_* variables set, and every push to your copy redeploys.

## Questions

### How do I connect a Gin API to PostgreSQL with pgx?

This starter does it in internal/config and internal/store: the DB_* variables become a postgres:// URL with sslmode and pool_max_conns=5, and pgxpool.New opens the pool. Locally, copy .env.example to .env and make run loads it.

### How do I add a new resource to a Gin API?

Add its queries to a store in internal/store modelled on store.go, add the methods to the Store interface in internal/server/server.go, write handlers and validation next to the item ones and register the routes in server.New.

### Do I need a database to run the Gin tests?

No. make test runs go vet and go test; the route tests in internal/server use an in-memory store and the tests in internal/config only check the database URL.

### Why pgx and not GORM for a Go CRUD API?

Each query is a few lines of SQL, which keeps the starter small and shows exactly what runs against the database. You can add GORM or sqlc later, since the handlers only see the Store interface.

### Can I host this Gin API without Light Cloud?

Yes. make build writes a static binary to bin/server; run it with PORT and the DB_* variables set on any server or container platform that can reach PostgreSQL. The repo has no Dockerfile, so add one if your host needs an image.
