Skip to content

gohan documentation

gohan is a SQL query builder for Go in which values are always bound and identifiers are always quoted. It renders a SQL string and an argument list for PostgreSQL, SQLite, ClickHouse or a generic ANSI dialect. It does not run queries: pass the result to database/sql or your driver.

Every SQL string and argument list in these pages is copied from real gohan output.

Why "gohan"?

gohan is a spiritual successor to goqu, the expressive Go SQL builder. The name is a nod to that lineage: goqu reads like Goku, and in Dragon Ball, Gohan is Goku's son — the next generation, raised on what came before, carrying it forward in its own way. (Gohan is also the Japanese word for a meal of rice, which suits a library you use every day.)

What it inherits from goqu

  • A fluent builder: Select, From, Where, Join, OrderBy, Insert, Update, Delete, OnConflict, Returning, CTEs and UNION read the way goqu users expect.
  • Dialect awareness: one query definition renders for PostgreSQL, SQLite, ClickHouse or generic ANSI SQL.
  • Map conditions (Match(map), in the spirit of goqu.Ex) and struct-based inserts and updates.
  • goqu's struct-tag vocabulary: goqu:"skipinsert", goqu:"skipupdate", goqu:"omitnil" and goqu:"omitempty" are honoured, so existing record types keep working.

What it does differently

  • Values are always bound. There is no interpolated mode that writes values into the SQL text, so there is no mode in which a forgotten setting turns user input into SQL.
  • Identifiers are always quoted and escaped, with per-dialect rules (including ClickHouse's backslash escapes and SQLite's backtick quoting).
  • Refuses dangerous or ambiguous SQL at build time: an UPDATE or DELETE without a WHERE needs an explicit All(), and ClickHouse values the driver would format unsafely are rejected.
  • Builds, never runs. Build(dialect) returns SQL and arguments; execution belongs to database/sql or your driver.
  • Immutable builders: every method returns a copy, so a base query can be shared and extended safely.

gohan is an independent project, written from scratch; it is not a fork of goqu and is not affiliated with its authors.

Guides

Page Contents
Getting started Install, build a first query, run it with database/sql, pick a dialect, handle errors
SELECT Columns, WHERE, ORDER BY, LIMIT/OFFSET, joins, GROUP BY/HAVING, subqueries, CTEs, UNION
INSERT and upsert Values, Rows, SetMap, INSERT ... SELECT, ON CONFLICT, RETURNING
UPDATE and DELETE Set, SetMap, SetRecord, the WHERE requirement, All(), RETURNING
Expressions Col and Val, comparisons, IN, LIKE helpers, And/Or/Not, aggregates, Fn, Cast, Case, Int
Raw SQL and escape hatches Raw, Fn and Cast, and what is validated in each
Dialects What changes per dialect, driver-name lookup, PostgreSQL, SQLite, ClickHouse and Generic notes
Records and struct tags Mapping structs to columns, tag reference, RecordColumns/InsertColumns, the field package
Security model What gohan guarantees, what is trusted input, and what remains your job
Errors Every Err* value and when it is returned

Other resources