v1.0.0A generator for Go services · MIT

Conventions, laid on Go track.

A Go API service, from zero to production.

One command gives you a plain Go API on Gin and Postgres, with sqlc, goose migrations, tests, CI and Kamal deploys.

Bogie's mascot: a gopher and a red gem riding a mine cart along a track
Go up front. The generators ride along.

Try it

From install to a working resource.

Install · new · run
# Needs Go 1.26+ and Docker
$ go install github.com/bogie-go/bogie@latest
$ bogie new blog
$ cd blog && make up && bogie db:prepare && bogie server
Scaffold a resource
$ bogie g scaffold product name:string price_cents:integer
      create  db/migrate/20261031072511_create_products.sql
      create  db/queries/products.sql
      create  app/models/product.go
      create  app/models/product_test.go
      create  db/adapter/products.go
      create  db/adapter/products_test.go
      create  test/factories/products.go
      create  app/views/products.go
      create  app/controllers/products_controller.go
      create  app/controllers/products_controller_test.go
      insert  app/controllers/application.go: Products *ProductsController
      insert  app/application.go: server.Products = controllers.NewProductsController(store, log)
      insert  app/controllers/routes.go: s.Products.SetupRoutes(&r.RouterGroup)
         run  sqlc generate

$ curl -i -X POST localhost:8080/products \
    -H "Content-Type: application/json" -d '{"name":"Blue mug","price_cents":1250}'
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
X-Request-Id: 19772870-4255-42bd-aace-4787be857598
Date: Sat, 31 Oct 2026 07:25:46 GMT
Content-Length: 141

{"id":1,"name":"Blue mug","price_cents":1250,"created_at":"2026-10-31T14:25:46.054672+07:00","updated_at":"2026-10-31T14:25:46.054672+07:00"}

Under the car

Built from tools Go already ships.

No new runtime to learn. Bogie picks one tool per job, wires them the same way in every app, and leaves the code where you can read it.

  • Gin
  • sqlc + pgx
  • goose
  • River
  • Air
  • Kamal
  • Postgres
YOUR SERVICE app/ · db/ · config/ · bin/ River · jobs sqlc + pgx Gin · routing goose · migrate Postgres, the only database Kamal ships it
Fig. 1. A bogie is the wheeled frame under a rail car. The car is yours; Bogie carries it.

Convention without magic

Nothing exists until it is written down and registered.

What the generators give you

  • Generators: new, g scaffold, d to undo
  • A layout where every file has a place: app/controllers, db/migrate
  • Commands that read the same everywhere: db:migrate, credentials:edit
  • One way to do it, so reviews talk about the work

What Go keeps honest

  • Generated code is yours: read it, change it, own it
  • Registration lands above marker comments you can see
  • Interfaces sit next to the code that uses them
  • Generators are idempotent; bogie d removes exactly what g made

Out of scope, on purpose

  • Templates, sessions, CSRF: it serves JSON
  • Databases other than Postgres
  • An ORM, fixtures or a console
  • A framework to import: apps use only the credentials library

The line

Every app rides the same four stops.

Models, controllers and views stay separate, and each is spelled out in plain Go. Here is what bogie g scaffold post lays down, plus a job from bogie g job.

  1. 01 · app/models · db/queries · db/adapter

    Models keep the SQL honest

    A model type with no third-party imports. Named queries in plain SQL, compiled by sqlc onto pgx. A store in db/adapter maps one to the other, and runs the model's validations on save. When you want to know what hits the database, you open a .sql file.

    // app/models/post.go
    type Post struct {
    	ID          int64
    	Title       string
    	Body        string
    	Score       int32
    	PublishedAt time.Time
    	AuthorID    int64
    	CreatedAt   time.Time
    	UpdatedAt   time.Time
    }
    -- db/queries/posts.sql
    -- name: CreatePost :one
    INSERT INTO posts (title, body, score, published_at, author_id)
    VALUES ($1, $2, $3, $4, $5) RETURNING *;
  2. 02 · app/controllers

    Controllers convert and call

    A handler converts HTTP into model values, calls one method on a store interface declared next to it holding only what that controller needs, and converts the result back. *gin.Context never leaves this folder.

    // app/controllers/posts_controller.go
    type postsStore interface {
    	CreatePost(ctx context.Context, p models.Post) (models.Post, error)
    	GetPost(ctx context.Context, id string) (models.Post, error)
    	ListPosts(ctx context.Context, limit int32) ([]models.Post, error)
    	UpdatePost(ctx context.Context, p models.Post) (models.Post, error)
    	DeletePost(ctx context.Context, id string) error
    }
  3. 03 · app/views

    Views are the wire contract

    A model type never doubles as a wire type, so a field added to the database does not silently appear on the wire. Requests and responses are their own structs.

    // app/views/posts.go
    type PostResponse struct {
    	ID          int64     `json:"id"`
    	Title       string    `json:"title"`
    	Body        string    `json:"body"`
    	PublishedAt time.Time `json:"published_at"`
    }
  4. 04 · app/jobs · bogie g job

    Jobs can commit with the row

    River runs on the same Postgres as the app: no Redis, no second system to keep up. Enqueue with InsertTx inside a transaction and the job commits with the row or not at all. bogie g job registers the worker above the bogie:jobs marker.

    type SendWelcomeArgs struct{}
    
    func (SendWelcomeArgs) Kind() string { return "send_welcome" }
    
    type SendWelcomeWorker struct {
    	river.WorkerDefaults[SendWelcomeArgs]
    	Log *slog.Logger
    }
    
    func (w *SendWelcomeWorker) Work(ctx context.Context,
    	job *river.Job[SendWelcomeArgs]) error {
    	w.Log.InfoContext(ctx, "send_welcome: not implemented yet", "job", job.ID)
    	return nil
    }

The short version

Why Bogie

  1. 1

    How should I structure a Go API?

    You don't have to decide. bogie new shop picks Gin, Postgres, sqlc and goose and lays out the folders the same way in every app.

  2. 2

    Will I be stuck with the framework?

    No. Generated apps are plain Go and never import Bogie itself, so there's nothing to upgrade around. The only bogie-go library they use is credentials.

  3. 3

    Is it more than hello world?

    Yes. One bogie g scaffold Product name:string price_cents:integer gives you a migration, typed queries, a Validate hook, a controller and tests. bin/ci runs the checks from day one, and the Kamal deploy config comes with bogie new.

  4. 4

    Can an AI agent work on it safely?

    Every app ships an AGENTS.md with its conventions, so changes land where you'd expect and you review them as plain diffs.

  5. 5

    How do I learn it end to end?

    The book Bogie: How to Go from Zero to Production builds one real shop, Bogie Depot, from bogie new to production. Bogie is the guide, not the destination: what readers really learn is Go and its standard production tools, skills they can take to any Go service. It is out now on Amazon (Kindle and paperback). About the book.

Change at this station

Everything you type, in one table.

The same few commands, whatever the service is for: generate, migrate, test, deploy. Tasks use a colon, as in db:migrate; everything else is a plain word.

Read the command reference →
ToRun or open
Start a servicebogie new blog
Run it, reloading on savebogie s
Generate a whole resourcebogie g scaffold
Guard a route groupbogie g authentication
Add a background jobbogie g job
Migrate the databasebogie db:migrate
Edit encrypted settingsbogie credentials:edit
Run the testsbogie t
See the routing tableapp/controllers/routes.go
Find a postapp/models/post.go
db/adapter/posts.go
db/queries/posts.sql

Not the same train

Bogie vs nearby tools.

Three projects get mentioned together. They solve different problems.

Bogiego-on-rails (gem)Andurel
WhatStandalone Go CLI, generators for API servicesRails generator that emitted Go from a Rails appFull-stack Go with views
FitsOne Go API serviceLegacy generate-from-Rails workflowFull-stack Go wanting views

In the box

From first commit to production, on one track.

AGENTS.md · CLAUDE.md

Written for agents and humans

Every app ships the six rules, every command and a recipe per generator. Because nothing is implicit, an agent’s change is a diff you can actually review.

bin/ci

CI runs on your machine

bin/ci is the whole pipeline: tests with race detection, gofmt, vet and golangci-lint. No hosted runner to wait on.

bogie server · bogie worker

Reload on save

Development runs the server and the worker under Air: save a file and it rebuilds and restarts. Migrations are embedded in the binary and applied at boot, so a new one is picked up on the next reload too. Production runs the compiled binary, untouched.

Kamal

One deploy tool

A container, a server, Kamal. The service migrates at boot, so shipping is one command.

bogie d

Undo is a command

Destroy removes what a generator made, registration included. --pretend shows the change before it happens.

bogie app:update

Upgrades that respect your edits

A three-way merge brings a newer layout into an app you have already changed, instead of overwriting it.

credentials:edit

Secrets, encrypted in the repo

Per-environment encrypted settings: the ciphertext is committed, the key never is.

Go's freedom, with the decisions made.

We moved the parts of our system that needed heavy concurrency and high load to Go. Go handles that work well, but it gives you so many choices that building the service itself became the hard part. Bogie makes those choices once, so every service starts from a layout and a pipeline that already work.

Questions

Short answers, before the long guides.

What is Bogie?

A command-line tool that scaffolds an API-only, Postgres-only Go service with generators that also wire the code in: bogie new, g scaffold, g model, g controller, g job, g seed, g authentication. It writes plain Go on top of Gin, sqlc, goose, River and Kamal. Generated apps never import Bogie itself; the only bogie-go library they use is credentials.

How is Bogie different from go-on-rails / Go on Rails?

The go-on-rails gem generated Go code from an existing Rails app, and that project is separate and archived. Bogie is an unrelated standalone Go CLI: bogie new and g scaffold create a Go service from nothing. Generated apps never import Bogie itself; the only bogie-go library they use is credentials.

Is Bogie a Go web framework?

No. There is no framework runtime, no base class and no DSL. Bogie renders templates and shells out to tools the Go ecosystem already ships. Delete the tool and the app does not notice. For a Go framework with views, see Andurel.

Which databases does Bogie support?

Postgres only, by design. Background jobs run on River, which uses the same Postgres, so there is no Redis. SQLite was considered and declined until River's SQLite driver is stable.

How do I install Bogie?

go install github.com/bogie-go/bogie@latest. Generated apps need Go 1.26 or newer (the CLI itself builds with 1.25). Postgres runs in Docker, with Compose v2, from the generated app's own compose file. There is no Homebrew tap and nothing prebuilt.

How does a generated app get upgraded?

bogie app:update is a three-way merge: it renders what the recorded Bogie version generated, what the current version generates, and merges each template-owned file with your edits kept. Only a real overlap leaves conflict markers.

Can an AI agent work in a Bogie app?

Yes. Every generated app ships an AGENTS.md with the six rules, every command and a recipe per task, and the generators register code above visible marker comments, so an agent's change is a diff a person can review.

All aboard.

Four steps to a running JSON API on Postgres: bogie new, make up, bogie db:prepare, bogie server. Migrations, tests and a deploy path come already laid. You need Go 1.26 or newer, and Docker for the local Postgres.

Terminal
$ go install github.com/bogie-go/bogie@latest
$ bogie new blog
$ cd blog && make up && bogie db:prepare && bogie server
# then
$ bogie g scaffold post title:string body:text
$ bin/ci