← Voltar para o blog

sqlx em Go: Struct Scan, Named Queries e database/sql

Aprenda sqlx em Go sobre database/sql: StructScan, Get, Select, NamedExec, in clauses, transações, tags db e quando preferir sqlx a GORM ou sqlc.

Resposta rápida: sqlx é a camada prática para quem quer continuar no database/sql, escrever SQL explícito e parar de repetir Scan campo a campo. Com Get, Select, StructScan, NamedExec e sqlx.In, você mapeia linhas para structs via tags db, mantém controle total das queries e evita a magia de um ORM. Em 2026, sqlx continua a ponte natural entre database/sql puro, GORM e sqlc — especialmente em APIs, workers e serviços onde o SQL já é o contrato.

Este guia mostra como adotar github.com/jmoiron/sqlx em produção: conexão, tags, leitura tipada, named queries, IN, transações, nullables, organização de repositório e a comparação honesta com as outras camadas de banco do ecossistema Go. Se você ainda está no driver nativo, comece por Go com PostgreSQL e pelo pool de conexões do database/sql. Para PostgreSQL com pool nativo do pgx, veja também pgxpool em produção.

Decisão rápida: sqlx cabe no seu projeto?

SituaçãoEscolha inicial
SQL explícito, pouco boilerplate de Scansqlx
CRUD administrativo com muitos relacionamentosGORM
SQL versionado + tipos gerados no CIsqlc
Script curto ou uma query isoladadatabase/sql puro
Queries críticas e estáveis de leiturasqlc ou sqlx
Time odeia codegen, mas também odeia ORMsqlx
Precisa de Preload, hooks e AutoMigrateGORM
Precisa só de pool e timeoutsConfigure database/sql / pgxpool primeiro

A pergunta certa não é “sqlx é melhor que GORM?”. É quem controla o SQL no seu domínio. Se a resposta é o time de backend, sqlx e sqlc tendem a envelhecer melhor. Se a resposta é produtividade de modelagem com relacionamentos, GORM ainda brilha.

O que sqlx adiciona ao database/sql

sqlx não substitui database/sql. Ele embute um *sql.DB (ou *sql.Tx, *sql.Conn) e acrescenta helpers:

  • Get / Select para ler uma ou várias linhas direto em structs ou slices
  • StructScan para mapear a linha atual do cursor
  • NamedExec / NamedQuery para parâmetros :nome a partir de structs ou maps
  • sqlx.In para expandir IN (?) com slices com segurança
  • MustBegin, Bind, Rebind e utilitários de dialeto

O SQL continua visível no código. Isso é deliberado: sqlx reduz atrito operacional sem criar uma DSL que esconde joins, índices e planos de execução.

package main

import (
	"log"
	"time"

	"github.com/jmoiron/sqlx"
	_ "github.com/jackc/pgx/v5/stdlib"
)

type User struct {
	ID        string    `db:"id"`
	Email     string    `db:"email"`
	Name      string    `db:"name"`
	Active    bool      `db:"active"`
	CreatedAt time.Time `db:"created_at"`
}

func main() {
	db, err := sqlx.Connect("pgx", "postgres://app:senha@localhost:5432/app?sslmode=disable")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	db.SetMaxOpenConns(25)
	db.SetMaxIdleConns(25)
	db.SetConnMaxLifetime(5 * time.Minute)

	var user User
	err = db.Get(&user, `SELECT id, email, name, active, created_at FROM users WHERE email = $1`, "[email protected]")
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("user=%s active=%v", user.Name, user.Active)
}

sqlx.Connect faz Open + Ping. Em serviços longos, prefira falhar no bootstrap — o mesmo princípio do graceful shutdown em Go e do pool bem dimensionado.

Tags db e o mapeamento de structs

O mapeamento padrão usa a tag db:"coluna". Sem tag, sqlx tenta o nome do campo em formas comuns, mas em produção declare a tag. Isso evita surpresa quando o schema usa snake_case e o Go usa CamelCase.

type Order struct {
	ID          int64     `db:"id"`
	CustomerID  int64     `db:"customer_id"`
	Status      string    `db:"status"`
	TotalCents  int64     `db:"total_cents"`
	CreatedAt   time.Time `db:"created_at"`
	UpdatedAt   time.Time `db:"updated_at"`
}

Boas práticas:

  1. Mantenha a struct de persistência perto do SQL, não misturada com DTO de HTTP.
  2. Não force a mesma struct a servir JSON da API e linha do banco se os contratos divergirem.
  3. Prefira tipos explícitos (int64, string, time.Time) e trate null com sql.Null* ou tipos do driver.
  4. Evite embed excessivo só para “herdar” tags; o custo de legibilidade sobe rápido.

Get, Select e StructScan

Três helpers cobrem a maior parte das leituras:

func (r *UserRepo) ByID(ctx context.Context, id string) (User, error) {
	var u User
	err := r.db.GetContext(ctx, &u, `
		SELECT id, email, name, active, created_at
		  FROM users
		 WHERE id = $1
	`, id)
	return u, err
}

func (r *UserRepo) ListActive(ctx context.Context, limit int) ([]User, error) {
	var users []User
	err := r.db.SelectContext(ctx, &users, `
		SELECT id, email, name, active, created_at
		  FROM users
		 WHERE active = true
		 ORDER BY created_at DESC
		 LIMIT $1
	`, limit)
	return users, err
}

Diferenças importantes:

  • Get espera exatamente uma linha. Zero linhas vira sql.ErrNoRows; mais de uma também é erro.
  • Select preenche um slice. Zero linhas devolve slice vazio e nil error.
  • StructScan entra quando você itera um *sqlx.Rows manualmente, útil em streams e relatórios grandes.

Sempre passe context.Context (GetContext, SelectContext, ExecContext). Timeouts e cancelamento de request HTTP precisam chegar ao banco; o guia de context, timeout e cancelamento detalha o padrão completo.

Named queries: menos posição, mais clareza

Placeholders posicionais ($1, $2, ?) escalam mal em INSERT/UPDATE com muitos campos. NamedExec liga nomes a campos da struct:

func (r *UserRepo) Create(ctx context.Context, u User) error {
	_, err := r.db.NamedExecContext(ctx, `
		INSERT INTO users (id, email, name, active, created_at)
		VALUES (:id, :email, :name, :active, :created_at)
	`, u)
	return err
}

func (r *UserRepo) UpdateName(ctx context.Context, id, name string) error {
	_, err := r.db.NamedExecContext(ctx, `
		UPDATE users
		   SET name = :name
		 WHERE id = :id
	`, map[string]any{
		"id":   id,
		"name": name,
	})
	return err
}

No PostgreSQL os placeholders nomeados são convertidos para $n. No MySQL/SQLite, para ?. Use db.Rebind ou deixe o sqlx fazer isso via named helpers — não misture dialetos na mão sem necessidade.

sqlx.In: listas sem SQL injection

O erro clássico é montar IN ('a','b') com strings.Join. A forma correta:

func (r *UserRepo) ByEmails(ctx context.Context, emails []string) ([]User, error) {
	if len(emails) == 0 {
		return nil, nil
	}

	query, args, err := sqlx.In(`
		SELECT id, email, name, active, created_at
		  FROM users
		 WHERE email IN (?)
		 ORDER BY email
	`, emails)
	if err != nil {
		return nil, err
	}
	query = r.db.Rebind(query)

	var users []User
	err = r.db.SelectContext(ctx, &users, query, args...)
	return users, err
}

sqlx.In expande o ? em (?, ?, ?) e devolve os args na ordem. Depois Rebind ajusta para $1,$2,$3 no PostgreSQL. Esse padrão também funciona dentro de named queries quando você prepara a string antes.

Transações com sqlx

Transações seguem o mesmo espírito do database/sql, com *sqlx.Tx:

func (r *OrderRepo) Place(ctx context.Context, order Order, items []OrderItem) error {
	tx, err := r.db.BeginTxx(ctx, nil)
	if err != nil {
		return err
	}
	defer tx.Rollback()

	if _, err := tx.NamedExecContext(ctx, `
		INSERT INTO orders (id, customer_id, status, total_cents, created_at, updated_at)
		VALUES (:id, :customer_id, :status, :total_cents, :created_at, :updated_at)
	`, order); err != nil {
		return err
	}

	for _, item := range items {
		if _, err := tx.NamedExecContext(ctx, `
			INSERT INTO order_items (id, order_id, sku, qty, unit_cents)
			VALUES (:id, :order_id, :sku, :qty, :unit_cents)
		`, item); err != nil {
			return err
		}
	}

	return tx.Commit()
}

Para locks, retries e isolation levels, use o guia de transações PostgreSQL em Go. sqlx não inventa semântica nova de transação: ele só tipa melhor o handle.

Nullables, joins e leituras parciais

Três casos recorrentes:

1. Colunas nullable

type User struct {
	ID        string         `db:"id"`
	Email     string         `db:"email"`
	Name      string         `db:"name"`
	Phone     sql.NullString `db:"phone"`
	DeletedAt sql.NullTime   `db:"deleted_at"`
}

Alternativa moderna: ponteiros (*string, *time.Time) quando a semântica de ausência é clara. Escolha um padrão por projeto e documente.

2. Joins com structs aninhadas

type OrderRow struct {
	OrderID      int64  `db:"order_id"`
	Status       string `db:"status"`
	CustomerID   int64  `db:"customer_id"`
	CustomerName string `db:"customer_name"`
}

Para joins simples, uma struct “achatada” costuma ser mais clara que embeds profundos. Reserve embeds para casos estáveis e revisados.

3. SELECT parcial

Se a query não traz todas as colunas da struct, os campos omitidos ficam zero-value. Isso é fonte clássica de bug (“achei que Active veio do banco”). Ou alinhe a query à struct, ou crie structs específicas de leitura (UserListItem, UserEmailRow).

Organização de repositório sem overengineering

Um layout comum e saudável:

internal/
  db/
    db.go          # abre sqlx.DB, configura pool
  user/
    model.go       # structs de persistência
    repository.go  # queries sqlx
  http/
    handlers.go

No bootstrap:

db, err := sqlx.Connect("pgx", os.Getenv("DATABASE_URL"))
if err != nil {
	return err
}
db.SetMaxOpenConns(25)
db.SetMaxIdleConns(25)
db.SetConnMaxLifetime(5 * time.Minute)
db.MapperFunc(strings.ToLower) // opcional; tags explícitas ainda são melhores

Mantenha SQL perto do repositório. Se o volume de queries crescer e o time quiser contrato gerado, migre leituras críticas para sqlc sem reescrever o domínio inteiro. Para a fronteira de casos de uso, o guia de clean architecture sem overengineering mostra como não espalhar *sqlx.DB pelos handlers.

sqlx vs GORM vs sqlc vs database/sql

Critériodatabase/sqlsqlxsqlcGORM
Controle do SQLTotalTotalTotalBaixo/médio
Boilerplate de ScanAltoBaixoGeradoBaixo
Type safetyManualManualGeradaParcial
RelacionamentosManualManualManualFácil
CodegenNãoNãoSimNão
Curva para quem vem de ORMMédiaMédiaMédiaBaixa
Risco de N+1BaixoBaixoBaixoAlto se descuidar
Ideal paraScripts, bases simplesAPIs com SQL explícitoDomínios SQL-firstCRUD rico

Leitura prática da pesquisa e do mercado: sqlx aparece com frequência como escolha “leve” em backends Go brasileiros, ao lado de sqlc e GORM. Se o seu time já padronizou GORM, não troque por moda. Se o time reclama de reflection, queries opacas e N+1, sqlx ou sqlc são o caminho de volta ao SQL visível.

Armadilhas comuns em produção

  1. Esquecer Rebind depois de sqlx.In no PostgreSQL — a query fica com ? e quebra em runtime.
  2. Usar Get quando zero linhas é caso normal — trate sql.ErrNoRows ou mude para uma query que devolva ausência de forma explícita.
  3. Struct compartilhada entre JSON e banco — tags json e db misturadas escondem campos sensíveis ou nomes divergentes.
  4. Abrir sqlx.DB por request — o pool é recurso de processo; crie uma vez no bootstrap.
  5. Ignorar pool — sqlx não salva configuração ruim de SetMaxOpenConns; releia o guia de pool do database/sql.
  6. Concatenar filtros dinâmicos sem builder cuidadoso — prefira trechos estáticos + args, ou uma biblioteca de query builder só na montagem, mantendo execução no sqlx.
  7. Não propagar context — cancelamento de request precisa chegar em GetContext/SelectContext/ExecContext.

Checklist de produção com sqlx

  • DSN via ambiente/segredo, nunca hardcoded
  • Ping/Connect no bootstrap
  • SetMaxOpenConns, SetMaxIdleConns, SetConnMaxLifetime explícitos
  • Todas as queries usam *Context
  • Tags db explícitas nas structs de persistência
  • sqlx.In + Rebind para listas
  • NamedExec para inserts/updates largos
  • Tratamento explícito de sql.ErrNoRows
  • Migrations versionadas fora do sqlx (guia de migrations)
  • Testes de integração com banco real ou Testcontainers
  • Observabilidade de queries lentas e pool (métricas / logs estruturados)

Perguntas frequentes

sqlx ainda vale a pena em 2026?

Sim, para times que querem SQL explícito sem codegen. O pacote é estável, amplamente usado e combina bem com PostgreSQL, MySQL e SQLite via database/sql. Se o projeto já nasceu em sqlc ou GORM com disciplina, não há obrigação de migrar.

Posso usar sqlx com pgx?

Sim. O caminho mais comum é o driver stdlib (github.com/jackc/pgx/v5/stdlib) com sqlx.Connect("pgx", dsn). Se você precisa das APIs nativas do pgx (listen/notify, pipeline, tipos ricos), avalie pgxpool diretamente e reserve sqlx para o estilo database/sql.

sqlx substitui prepared statements?

Não automaticamente. Você ainda pode preparar statements quando o perfil de carga exige. Em muitos serviços o ganho maior vem de índices corretos, pool dimensionado e menos queries por request — meça com pprof antes de micro-otimizar.

Como testo repositórios sqlx?

Suba um Postgres/MySQL de teste (Testcontainers ou compose) e exercite o SQL real. Mockar *sqlx.DB quase nunca vale a pena. Cubra ErrNoRows, constraints e uma transação de escrita+leitura. O guia de mocks e fakes ajuda a decidir a fronteira.

Qual a diferença prática entre sqlx e sqlc no dia a dia?

No sqlx você edita a query e o struct na mão; o compilador não valida colunas contra o schema. No sqlc, a query SQL gera o método Go e o CI quebra se schema e query divergirem. sqlx otimiza velocidade de iteração; sqlc otimiza segurança de contrato.

Conclusão

sqlx ocupa o meio-termo mais útil do acesso a banco em Go: SQL visível, structs tipadas, named queries e bem menos Scan manual. Ele não tenta ser ORM e não exige codegen. Para APIs, workers e backends brasileiros que já pensam em SQL, é uma base sólida — desde que pool, context, migrations e testes de integração estejam no lugar.

Para continuar, compare com o guia de GORM, o tutorial de sqlc e o pool do database/sql. Se a próxima etapa for a API completa, volte ao tutorial de API REST em Go e ao Chi Router para produção. Para o mercado, acompanhe as vagas Go no Brasil e o panorama de salários de desenvolvedor Go.

Referências oficiais