Skip to content

Getting Started

From database schema to running API in under 5 minutes.

Prerequisites

  • Go 1.26 or later
  • Docker (for running a local database)
  • A Postgres, MySQL/MariaDB, or SQLite database

Install

# Homebrew (macOS/Linux)
brew install fisayoafolayan/kiln/kiln

# Or download a binary (no Go required)
curl -sSfL "https://github.com/fisayoafolayan/kiln/releases/latest/download/kiln_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/').tar.gz" | tar xz
sudo mv kiln /usr/local/bin/

# Or with Go
go install github.com/fisayoafolayan/kiln/cmd/kiln@latest

Your First API

1. Set up your database

Start a Postgres database (or use an existing one):

docker run --rm -d \
  --name kiln-db \
  -e POSTGRES_USER=app \
  -e POSTGRES_PASSWORD=app \
  -e POSTGRES_DB=app \
  -p 5432:5432 \
  postgres:16

Apply your schema:

docker exec -i kiln-db psql -U app -d app < schema.sql

2. Initialize kiln

mkdir my-api && cd my-api
go mod init my-api

export DATABASE_URL="postgres://app:app@localhost:5432/app?sslmode=disable"
kiln init

kiln asks a few questions:

Database driver (postgres/mysql/sqlite): postgres
Database DSN (or leave blank to use an env var):
Environment variable name for DSN: DATABASE_URL
Output directory: ./generated
API base path: /api/v1

✓ Created kiln.yaml

3. Generate

kiln generate

kiln reads your database schema and generates:

✓ generated/models/users.go
✓ generated/store/users.go
✓ generated/store/mappers/users.go
✓ generated/handlers/users.go
✓ generated/handlers/helpers.go
✓ generated/router.go
✓ docs/openapi.yaml
✓ cmd/server/main.go

4. Run

go mod tidy
go run cmd/server/main.go

Your API is running at http://localhost:8080.

5. Try it

# List users
curl http://localhost:8080/api/v1/users | jq

# Create a user
curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "name": "Alice"}' | jq

# Filter by role
curl "http://localhost:8080/api/v1/users?role=admin" | jq

# Sort descending
curl "http://localhost:8080/api/v1/users?sort=-created_at" | jq

What's Next