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ção | Escolha inicial |
|---|---|
SQL explícito, pouco boilerplate de Scan | sqlx |
| CRUD administrativo com muitos relacionamentos | GORM |
| SQL versionado + tipos gerados no CI | sqlc |
| Script curto ou uma query isolada | database/sql puro |
| Queries críticas e estáveis de leitura | sqlc ou sqlx |
| Time odeia codegen, mas também odeia ORM | sqlx |
Precisa de Preload, hooks e AutoMigrate | GORM |
| Precisa só de pool e timeouts | Configure 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/Selectpara ler uma ou várias linhas direto em structs ou slicesStructScanpara mapear a linha atual do cursorNamedExec/NamedQuerypara parâmetros:nomea partir de structs ou mapssqlx.Inpara expandirIN (?)com slices com segurançaMustBegin,Bind,Rebinde 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:
- Mantenha a struct de persistência perto do SQL, não misturada com DTO de HTTP.
- Não force a mesma struct a servir JSON da API e linha do banco se os contratos divergirem.
- Prefira tipos explícitos (
int64,string,time.Time) e trate null comsql.Null*ou tipos do driver. - 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:
Getespera exatamente uma linha. Zero linhas virasql.ErrNoRows; mais de uma também é erro.Selectpreenche um slice. Zero linhas devolve slice vazio enilerror.StructScanentra quando você itera um*sqlx.Rowsmanualmente, ú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ério | database/sql | sqlx | sqlc | GORM |
|---|---|---|---|---|
| Controle do SQL | Total | Total | Total | Baixo/médio |
Boilerplate de Scan | Alto | Baixo | Gerado | Baixo |
| Type safety | Manual | Manual | Gerada | Parcial |
| Relacionamentos | Manual | Manual | Manual | Fácil |
| Codegen | Não | Não | Sim | Não |
| Curva para quem vem de ORM | Média | Média | Média | Baixa |
| Risco de N+1 | Baixo | Baixo | Baixo | Alto se descuidar |
| Ideal para | Scripts, bases simples | APIs com SQL explícito | Domínios SQL-first | CRUD 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
- Esquecer
Rebinddepois desqlx.Inno PostgreSQL — a query fica com?e quebra em runtime. - Usar
Getquando zero linhas é caso normal — tratesql.ErrNoRowsou mude para uma query que devolva ausência de forma explícita. - Struct compartilhada entre JSON e banco — tags
jsonedbmisturadas escondem campos sensíveis ou nomes divergentes. - Abrir
sqlx.DBpor request — o pool é recurso de processo; crie uma vez no bootstrap. - Ignorar pool — sqlx não salva configuração ruim de
SetMaxOpenConns; releia o guia de pool do database/sql. - 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.
- 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/Connectno bootstrap -
SetMaxOpenConns,SetMaxIdleConns,SetConnMaxLifetimeexplícitos - Todas as queries usam
*Context - Tags
dbexplícitas nas structs de persistência -
sqlx.In+Rebindpara listas -
NamedExecpara 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.