Fast SQL query builder for Go



GoDoc Reference Build Status Go Report Card Go Coverage

A fast SQL query builder for Go.

sqlf statement builder provides a way to:

  • Combine SQL statements from fragments of raw SQL and arguments that match those fragments,
  • Map columns to variables to be referenced by Scan,
  • Convert ? placeholders into numbered ones for PostgreSQL ($1, $2, etc).

sqlf.Stmt has methods to execute a query using any database/sql compatible driver.

Is It Fast?

It is. See benchmarks:

In order to maximize performance and minimize memory footprint, sqlf reuses memory allocated for query building. The heavier load is, the faster sqlf works.


Build complex statements:

var (
    region       string
    product      string
    productUnits int
    productSales float64

err := sqlf.From("orders").
            Select("region, SUM(amount) AS total_sales").
            Where("total_sales > (SELECT SUM(total_sales)/10 FROM regional_sales)")).
    // Map query fields to variables
    Select("SUM(amount) AS product_sales").To(&productSales).
    Where("region IN (SELECT region FROM top_regions)").
    GroupBy("region, product").
    OrderBy("product_sales DESC").
    // Execute the query
    QueryAndClose(ctx, db, func(row *sql.Rows){
        // Callback function is called for every returned row.
        // Row values are scanned automatically to bound variables.
        fmt.Printf("%s\t%s\t%d\t$%.2f\n", region, product, productUnits, productSales)
if err != nil {

Bind structures to query results:

type Offer struct {
    id        int64
    productId int64
    price     float64
    isDeleted bool

var o Offer

err := sqlf.From("offers").
    Where("id = ?", 42).
    QueryRowAndClose(ctx, db)
if err != nil {

Some SQL fragments, like a list of fields to be selected or filtering condition may appear over and over. It can be annoying to repeat them or combine an SQL statement from chunks. Use sqlf.Stmt to construct a basic query and extend it for a case:

func (o *Offer) Select() *sqlf.Stmt {
    return sqlf.From("products").
        // Ignore deleted offers
        Where("is_deleted = false")

func (o Offer) Print() {
    fmt.Printf("%d\t%s\t$%.2f\n",,, o.price)

var o Offer

// Fetch offer data
err := o.Select().
    Where("id = ?", offerId).
    QueryRowAndClose(ctx, db)
if err != nil {
// ...

// Select and print 5 most recently placed
// offers for a given product
err = o.Select().
    Where("product_id = ?", productId).
    OrderBy("id DESC").
    QueryAndClose(ctx, db, func(row *sql.Rows){
if err != nil {
// ...

SQL Statement Construction and Execution


Value Binding

Bind columns to values using To method:

var (
    minAmountRequested = true
    maxAmount float64
    minAmount float64

q := sqlf.From("offers").
    Where("is_deleted = false")

if minAmountRequested {

err := q.QueryRowAndClose(ctx, db)
if err != nil {
if minAmountRequested {
    fmt.Printf("Cheapest offer: $%.2f\n", minAmount)
fmt.Printf("Most expensive offer: $%.2f\n", minAmount)


There are helper methods to construct a JOIN clause: Join, LeftJoin, RightJoin and FullJoin.

var (
    offerId     int64
    productName string
    price       float64

err := sqlf.From("offers o").
    Where("is_deleted = false").
    // Join
    LeftJoin("products p", " = o.product_id").
    // Bind a column from joined table to variable
    // Print top 10 offers
    OrderBy("price DEST").
    QueryAndClose(ctx, db, func(row *sql.Rows){
        fmt.Printf("%d\t%s\t$%.2f\n", offerId, productName, price)
if err != nil {

Use plain SQL for more fancy cases:

var (
    num   int64
    name  string
    value string
err := sqlf.From("t1 CROSS JOIN t2 ON t1.num = t2.num AND t2.value IN (?, ?)", "xxx", "yyy").
    QueryAndClose(ctx, db, func(row *sql.Rows){
        fmt.Printf("%d\t%s\ts\n", num, name, value)
if err != nil {


Use SubQuery method to add a sub query to a statement:

	q := sqlf.From("orders o").
		Select("date, region").
		SubQuery("(", ") AS prev_order_date",
			sqlf.From("orders po").
				Where("region = o.region").
				Where("id <").
				OrderBy("id DESC").
				Clause("LIMIT 1")).
		Where("date > CURRENT_DATE - interval '1 day'").
		OrderBy("id DESC")

Note that if a subquery uses no arguments, it's more effective to add it as SQL fragment:

	q := sqlf.From("orders o").
		Select("date, region").
		Where("date > CURRENT_DATE - interval '1 day'").
        Where("exists (SELECT 1 FROM orders po WHERE region = o.region AND id < ORDER BY id DESC LIMIT 1)").
        OrderBy("id DESC")
    // ...

To select from sub-query pass an empty string to From and immediately call a SubQuery method.

The query constructed by the following example returns top 5 news in each section:

	q := sqlf.Select("").
			"(", ") counted_news",
				Select("id, section, header, score").
				Select("row_number() OVER (PARTITION BY section ORDER BY score DESC) AS rating_in_section").
				OrderBy("section, rating_in_section")).
		Where("rating_in_section <= 5")
    // ...


Use Union method to combine results of two queries:

	q := sqlf.From("tasks").
		Select("id, status").
		Where("status = ?", "new").
		Union(true, sqlf.PostgreSQL.From("tasks").
			Select("id, status").
            Where("status = ?", "wip"))
    // ...


sqlf provides a Set method to be used both for UPDATE and INSERT statements:

var userId int64

err := sqlf.InsertInto("users").
    Set("email", "[email protected]").
    Set("address", "320 Some Avenue, Somewhereville, GA, US").
    Clause("ON CONFLICT (email) DO UPDATE SET address = users.address").
    ExecAndClose(ctx, db)

The same statement execution using the database/sql standard library looks like this:

var userId int64

// database/sql
err := db.ExecContext(ctx, "INSERT INTO users (email, address) VALUES ($1, $2) RETURNING id ON CONFLICT (email) DO UPDATE SET address = users.address", "[email protected]", "320 Some Avenue, Somewhereville, GA, US").Scan(&userId)

There are just 2 fields of a new database record to be populated, and yet it takes some time to figure out what columns are being updated and what values are to be assigned to them.

In real-world cases there are tens of fields. On any update both the list of field names and the list of values, passed to ExecContext method, have to to be reviewed and updated. It's a common thing to have values misplaced.

The use of Set method to maintain a field-value map is a way to solve this issue.


err := sqlf.Update("users").
    Set("email", "[email protected]").
    ExecAndClose(ctx, db)


err := sqlf.DeleteFrom("products").
    Where("id = ?", 42)
    ExecAndClose(ctx, db)
You might also like...
An easy-use SQL builder.

EQL An easy-use SQL builder. Design We are not English native speaker, so we use Chinese to write the design documents. We plan to translate them to E

A Go (golang) package that enhances the standard database/sql package by providing powerful data retrieval methods as well as DB-agnostic query building capabilities.

ozzo-dbx Summary Description Requirements Installation Supported Databases Getting Started Connecting to Database Executing Queries Binding Parameters

Query git repositories with SQL. Generate reports, perform status checks, analyze codebases. 🔍 📊

askgit askgit is a command-line tool for running SQL queries on git repositories. It's meant for ad-hoc querying of git repositories on disk through a

SQL query helper

SQL query helper

Command line tool to generate idiomatic Go code for SQL databases supporting PostgreSQL, MySQL, SQLite, Oracle, and Microsoft SQL Server

About xo xo is a command-line tool to generate Go code based on a database schema or a custom query. xo works by using database metadata and SQL intro

Go fearless SQL. Sqlvet performs static analysis on raw SQL queries in your Go code base.

Sqlvet Sqlvet performs static analysis on raw SQL queries in your Go code base to surface potential runtime errors at build time. Feature highlights:

PirateBuilder - Pirate Builder For Golang
PirateBuilder - Pirate Builder For Golang

PirateBuilder Builder You need to extract the file "PirateBuilder.rar". Start "P

Nerdlight-firmwarebuilder - Nerdlight NodeMCU Firmware Builder CLI

nerdlight-firmwarebuilder ⚒ ⚡️ Nerdlight NodeMCU Firmware Builder CLI ⚒ Descript

Additions to Go's database/sql for super fast performance and convenience. (fork of gocraft/dbr)

dbr (fork of gocraft/dbr) provides additions to Go's database/sql for super fast performance and convenience. Getting Started // create a connection (

  • Set with righthand expressions introduced

    Set with righthand expressions introduced


    Good library, and although we've had good times with it, we also ran into this issue of not being able to set righthand expressions in Set all around the place. I'm talking about InsertInto and Update too. This commit adds a reverse-compatible capability to use the following construct:

    // this is something very common in postgis, basically
    stmt := sqlf.InsertInto("geodata").
    	Set("geom = ST_GeomFromGeoJSON(?)", geoJSON)

    Producing the following SQL:

    INSERT INTO geodata ( geom ) VALUES ( ST_GeomFromGeoJSON($1) )

    Hopefully, this helps to bring the library to parity with SQL expressibility.

    Best regards, @tucnak

    P.S. What's your position on JOIN LATERAL and similar JOIN subqueries?

    SELECT a.*, bar
    FROM table
    	SELECT json_agg(foo) as bar
    	FROM other_table
    	GROUP BY id
    ) b ON true

    How would I write said query in sqlf, and if I couldn't, would you welcome a change that would enable me to?

    opened by tucnak 0
  • How to use subquery with IN() ?

    How to use subquery with IN() ?

    Hello, I'm trying to generate something similar to the following query with sqlf, but I can't find a correct sqlf syntax:

     SELECT product_name, code FROM en WHERE code IN(SELECT code from en_fts where en_fts MATCH "XXX");

    Is there currently a way to achieve such statement, or do I need to split my query in two statements ?

    opened by 4rnoP 1
Vlad Glushchuk
Vlad Glushchuk
SQL query builder for Go

GoSQL Query builder with some handy utility functions. Documentation For full documentation see the or GitBook. Examples // Open database a

Travis Harmon 26 Sep 26, 2022
Type safe SQL builder with code generation and automatic query result data mapping

Jet Jet is a complete solution for efficient and high performance database access, consisting of type-safe SQL builder with code generation and automa

null 886 Nov 21, 2022
Type safe SQL query builder and struct mapper for Go

sq (Structured Query) ?? ?? sq is a code-generated, type safe query builder and struct mapper for Go. ?? ?? Documentation • Reference • Examples This

null 180 Nov 26, 2022
gosq is a parsing engine for a simplicity-focused, template-based SQL query builder for Go.

gosq is a parsing engine for a simplicity-focused, template-based SQL query builder for Go.

Sang-gon Lee 51 Oct 24, 2022
Data-builder - Data builder with golang

databuilder import "" Index Variables func Is

Coldbrew 0 Feb 5, 2022
Go database query builder library for PostgreSQL

buildsqlx Go Database query builder library Installation Selects, Ordering, Limit & Offset GroupBy / Having Where, AndWhere, OrWhere clauses WhereIn /

Arthur Kushman 84 Nov 23, 2022
Simple query builder for MongoDB

?? greenleaf - simple, type safe and easy to use query builder for MongoDB Installation To install use: go get Quick

Slava 75 Nov 27, 2022
a golang library for sql builder

Gendry gendry is a Go library that helps you operate database. Based on go-sql-driver/mysql, it provides a series of simple but useful tools to prepar

DiDi 1.4k Nov 21, 2022
Database Abstraction Layer (dbal) for Go. Support SQL builder and get result easily (now only support mysql)

godbal Database Abstraction Layer (dbal) for go (now only support mysql) Motivation I wanted a DBAL that No ORM、No Reflect、Concurrency Save, support S

徐佳军 56 Nov 17, 2022
golang orm and sql builder

gosql gosql is a easy ORM library for Golang. Style: var userList []UserModel err := db.FetchAll(&userList, gosql.Columns("id","name"), gosql.

RushTeam 167 Nov 19, 2022