Go + Echo + SQLite (Embedded, Self-Hosted Tools)

Curated rule Developer Tool & API · Internal Admin Tool · DevOps & Infrastructure Updated Oct 2026 Which file does my tool read?

go-echo-sqlite.md

Architecture guidelines for single-binary Go services using the Echo framework, embedded SQLite, and minimal-JS server-rendered UI.

Go Echo SQLite Docker

Formats: 4 files
AGENTS.md: 38 lines
CLAUDE.md: 15 lines
Languages: Go
Updated: Oct 2026
Used by: 4 projects

Install

Writes .claude/skills/go-echo-sqlite/SKILL.md

$ curl -s --create-dirs -o .claude/skills/go-echo-sqlite/SKILL.md https://stackitfast.com/rules/go-echo-sqlite/SKILL.md

Rule files

AGENTS.md· 38 lines · 3.4 KB

1	# Project Architecture & Guidelines (Go + Echo + SQLite)
2
3	## 1. System Architecture
4	- Language: Go 1.27+, compiled to a single static binary with no runtime dependencies.
5	- Web Framework: Echo (lightweight HTTP router and middleware, `github.com/labstack/echo/v4`).
6	- Database: Embedded SQLite (`modernc.org/sqlite` or `mattn/go-sqlite3`), file-based, no separate database server to deploy or back up.
7	- Frontend: Server-rendered HTML via Go's `html/template` or a light templating library, with HTMX or minimal vanilla JS for interactivity — no separate SPA build.
8
9	## 2. Single-Binary Deployment Model
10	- Embed static assets (templates, CSS, migrations) into the binary with Go's `embed.FS` so deployment is copying one file, not a directory tree.
11	- Store the SQLite database file in a configurable data directory (`--data-dir` flag or `DATA_DIR` env var), never hardcoded, so it's easy to volume-mount in Docker.
12	- Enable SQLite's WAL (write-ahead log) mode at startup (`PRAGMA journal_mode=WAL;`) for concurrent read/write access without locking the whole database on every write.
13
14	## 3. Echo Handler & Middleware Conventions
15	- Group routes by resource with `e.Group("/api/projects")`; apply auth middleware at the group level, not per-handler.
16	- Handlers return typed errors that a central `HTTPErrorHandler` maps to status codes — never `c.String(500, err.Error())` scattered across handlers, which leaks internal error detail to clients.
17	- Use Echo's built-in request validation (`c.Bind()` + a `Validate()` method backed by `go-playground/validator`) before touching the database.
18
19	## 4. Database Access & Migrations
20	- Use a lightweight migration tool (`golang-migrate` or a hand-rolled versioned-SQL-files runner) that ships embedded in the binary and runs automatically on startup — self-hosted single-binary tools can't assume an operator will run a separate migration command.
21	- Wrap multi-statement writes in an explicit `sql.Tx`; SQLite's single-writer model makes uncommitted long-lived transactions a common source of "database is locked" errors.
22	- Keep the database package (`internal/db`) free of HTTP concerns — handlers call typed repository methods, not raw SQL.
23
24	## 5. Common Pitfalls / Coding Standards
25	- ❌ Leaving SQLite in the default `journal_mode=DELETE`, which serializes all writes and causes "database is locked" under any concurrent load.
26	- ❌ Hardcoding file paths instead of reading from a configurable data directory, breaking Docker volume mounts.
27	- ✅ Set `busy_timeout` on the SQLite connection so concurrent writers retry briefly instead of failing immediately.
28
29	## 6. Testing Conventions
30	- Standard `testing` package with table-driven tests; use an in-memory SQLite database (`:memory:`) per test for isolation and speed.
31	- `httptest` for handler-level tests against the Echo instance without a real network listener.
32	- Run `go vet` and `staticcheck` in CI; Go's compiler catches most type errors, so linting focuses on correctness patterns instead.
33
34	## 7. Git Workflow & PR Conventions
35	- Conventional Commits scoped to the package, e.g. `fix(db): use WAL mode to avoid write locking under load`.
36	- New migrations ship in the same PR as the schema change; migration files are numbered and never edited after merge.
37	- Require `go build ./...`, `go vet ./...`, and `go test ./...` green before merge.
38	- Squash-merge; tag releases so the single-binary artifact is reproducible from a known commit.

Works with Cursor · Claude Code · Windsurf · AGY

Architecture notes

Architecture Overview

Standardized production guidelines for Go, the Echo web framework, and embedded SQLite — the pattern behind small, single-binary, self-hosted tools that a user can run with one command and no external database server.

Verified Real-World Adoption

PocketBase is the canonical example of this exact stack (Go + Echo + embedded SQLite, single binary). Gitea and Gatus follow the same single-binary, embeddable-SQLite philosophy, offering PostgreSQL as an opt-in upgrade path for larger deployments rather than a requirement.

Key Architectural Nuances

Zero External Dependencies by Default: The database ships inside the same process as the application, so “installing” the tool is copying one binary and pointing it at a data directory.
WAL Mode as a Non-Negotiable Default: Without it, SQLite’s exclusive write lock turns any concurrent access pattern into a source of “database is locked” errors under real usage.

Frequently asked questions

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Yes — AGENTS.md is the open, cross-tool standard read by Cursor, Claude Code, Windsurf, and 30+ other agents. A dedicated .mdc file is also included for Cursor's native .cursor/rules format.

How is this different from the Go + PostgreSQL + React rule?

That rule targets a full-throughput web dashboard with a separate React frontend and a managed PostgreSQL server. This rule targets single-binary, self-hostable tools -- status pages, git servers, embedded backends -- where the entire application, including its database, ships as one file an operator runs with zero external dependencies.

Why WAL mode instead of the SQLite default?

SQLite's default rollback-journal mode takes an exclusive lock on the whole database file for the duration of a write, so any concurrent read blocks until it finishes. WAL (write-ahead log) mode lets readers continue against the last-committed state while a write is in progress, which is the difference between a tool that handles a handful of concurrent requests and one that locks up under them.

Used in production

Explore all stacks

Gotify

Self-Hosted Real-Time Push Server · 2-5 People

Gotify keeps the server one deployable Go binary by embedding its Vite/React web UI, using Gin and gorilla/websocket for the REST and streaming API, and swapping SQLite, MySQL or PostgreSQL through GORM, while a compiled Go plugin system handles extensibility instead of a scripting layer.

Grafana

Monitoring & Observability Dashboard · 20+ people

Grafana splits its backend into a growing set of independently versioned Go modules under apps/, tied together by a go.work workspace and modeled with Kubernetes-style APIs (pkg/apiserver, CUE-defined kinds), so individual product areas like alerting or dashboards can evolve without one monolithic backend module.

MindsHub (formerly MindsDB)

Desktop & Web AI Agent Workspace · 20+ People

Splitting the client, API and agent into separately versioned git submodules lets each ship on its own cadence (a signed desktop app, a PyPI server package, an agent package), while one Makefile and one docker-compose.yml still bring the whole stack up together.

SeaweedFS

Distributed Blob & File Storage · 2-5 People

Decoupling directory metadata from physical volume storage eliminates central metadata bottlenecks, enabling massive horizontal scaling for small and large files alike.

Every stack ships as files

More AI agent coding rules and skills

View all

astro-static-content/AGENTS.mdAstro Static Site + Content Collections + TailwindAstro · Tailwind CSS · TypeScript bun-hono-sqlite/AGENTS.mdBun + Hono + SQLite (libSQL & Drizzle ORM)Bun · Hono · SQLite django-postgres-redis/AGENTS.mdDjango + PostgreSQL + Redis + CeleryDjango · Python · PostgreSQL fastapi-jev-decision-service/AGENTS.mdFastAPI + Jev Decision Service (Python)Python · FastAPI · Jev