Home

quill is a fluent SQL query builder for Go with an API inspired by Laravel's query builder. It builds SQL plus bind arguments, and can optionally run them through database/sql.

It is not an ORM. There are no models, relations, lifecycle hooks or migrations. You keep control of the SQL.

sql, args, err := db.Use(db.Postgres).
    Select("id", "name").
    From("users").
    Where("votes", ">", 100).
    OrderByDesc("created_at").
    Limit(10).
    ToSQL()
// SELECT "id", "name" FROM "users" WHERE "votes" > $1 ORDER BY "created_at" DESC LIMIT 10
// args: [100]

Module	github.com/akfaiz/quill (import github.com/akfaiz/quill/db)
Go version	1.25+
Dialects	PostgreSQL, MySQL, MariaDB, SQLite
Runtime dependencies	None (standard library only)
License	MIT
Source	https://github.com/akfaiz/quill
API docs	https://pkg.go.dev/github.com/akfaiz/quill/db

Why quill

• You keep control of the SQL. Every query reads like the SQL it produces.
• One API, four dialects. Quoting, placeholders and syntax differences are handled for you. A feature a dialect cannot express returns ErrUnsupported instead of emitting SQL that behaves differently.
• Safe by default. Values are always bound, identifiers are always quoted, and an UPDATE or DELETE without a WHERE is refused unless you call AllRows().
• Errors, not panics. A bad argument is recorded and returned from the terminal call. Only the Must* variants panic.
• Fast to build. Query construction is about 2 to 7 times faster than squirrel and goqu in the project's benchmark scenarios (see the repository's test/benchmark/README.md).

Where to start

New here? Read these three in order:

1. Getting Started: install, connect, run your first query.
2. Core Concepts: how builders, errors and dialects work. Ten minutes that save hours.
3. Cookbook: copy-paste recipes for common tasks.

Pages

Basics

Page	What it covers
Getting Started	Install, db.Use vs db.New, options, first queries
Core Concepts	Builders, error handling, Clone, Must*, types

Building queries

Page	What it covers
Select Queries	Columns, FROM, grouping, ordering, limits, locks, conditional building
Where Clauses	Comparisons, IN, BETWEEN, LIKE, NULL, groups, dates, EXISTS
Joins	Inner, left, right, cross, subquery and lateral joins
Subqueries, Unions and CTEs	Nested queries, UNION, WITH, WITH RECURSIVE
JSON Support	column->path selectors, JSON predicates, JSON path updates
Raw SQL	db.Raw, *Raw methods and their safety rules

Writing and reading data

Page	What it covers
Writing Data	Insert, upsert, update, increment, delete, truncate, RETURNING, the WHERE guard
Reading Data	Get, First, Find, Sole, Pluck, aggregates, how rows are scanned
Pagination and Chunking	Offset, simple and cursor pagination, Chunk, ChunkByID, Each, Stream
Transactions	Commit, rollback, savepoints, isolation levels
Typed API	db.From[T], db.As[T], TableName(), scalar helpers
Struct Mapping	db tags, omitempty, NULL handling, embedded structs
Hooks and Options	WithPrefix, WithHook, WithLogArgs, logging and tracing

Reference and operations

Page	What it covers
Dialect Differences	What changes between PostgreSQL, MySQL, MariaDB and SQLite
Security	Injection, raw SQL, dynamic identifiers, logging, cursors
Error Reference	Every sentinel error and when it is returned
API Overview	Types, options, package functions
Cookbook	Task-based recipes
FAQ	Common questions and gotchas
Contributing	Repository layout, tests, adding a method or dialect

Conventions used in this wiki

• Examples assume conn := db.New(sqlDB, db.Postgres) for running queries, or db.Use(...) for building SQL only.
• Generated SQL is shown for PostgreSQL unless a page says otherwise.
• ctx is a context.Context.
• Name your variable conn, not db. A local variable called db hides the package.
• Version note: this wiki documents v0.2.0. quill is pre-1.0, so the API may still change between minor versions.