sqlc para Go: geração de código type-safe a partir de SQL

sqlc é um compilador que gera código Go a partir das suas consultas SQL. Em vez de escrever manualmente funções para interagir com o banco de dados, você escreve SQL puro, e o sqlc cria funções tipadas, seguras e eficientes para você. Essa é uma abordagem fundamentalmente diferente dos ORMs: você mantém o controle total sobre o SQL, mas elimina o trabalho repetitivo de escrever código boilerplate.

Por que usar isso? Primeiro, o sqlc garante type-safety em tempo de compilação. Se você alterar o esquema da tabela ou uma consulta, o sqlc regenera o código, e o compilador Go aponta imediatamente todos os lugares que precisam de ajustes. Segundo, performance: o código gerado não usa reflexão nem faz alocações desnecessárias, tornando-o praticamente tão rápido quanto escrever consultas manualmente com database/sql. Terceiro, isso simplifica a revisão de código: as consultas SQL ficam visíveis em arquivos .sql, e não escondidas em métodos de ORM.

sqlc é ideal para projetos onde performance e controle sobre as consultas são essenciais: APIs de alta carga, sistemas financeiros, plataformas de análise. Ele também se integra perfeitamente com migrações (como golang-migrate) e não te prende a um SGBD específico — suporta PostgreSQL, MySQL e SQLite.

Instalação

sqlc não é uma biblioteca, mas uma ferramenta de linha de comando. Você pode instalá-la de várias formas:

# Via go install (recomendado)
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest

# Via Homebrew (macOS/Linux)
brew install sqlc

# Baixar o binário do GitHub
# https://github.com/sqlc-dev/sqlc/releases

Após a instalação, verifique a versão:

sqlc version

Primeiros passos

Vamos criar um projeto mínimo para demonstrar o funcionamento do sqlc.

1. Estrutura do projeto

mkdir sqlc-demo && cd sqlc-demo
go mod init sqlc-demo

2. Configuração do sqlc

Crie o arquivo sqlc.yaml na raiz do projeto:

version: "2"
sql:
  - engine: "postgresql"
    queries: "queries.sql"
    schema: "schema.sql"
    gen:
      go:
        package: "db"
        out: "db"
        sql_package: "pgx/v5"

3. Esquema do banco de dados

Arquivo schema.sql:

CREATE TABLE authors (
    id   BIGSERIAL PRIMARY KEY,
    name text NOT NULL,
    bio  text
);

4. Consultas SQL

Arquivo queries.sql:

-- name: GetAuthor :one
SELECT * FROM authors
WHERE id = $1;

-- name: ListAuthors :many
SELECT * FROM authors
ORDER BY name;

-- name: CreateAuthor :one
INSERT INTO authors (name, bio)
VALUES ($1, $2)
RETURNING *;

-- name: DeleteAuthor :exec
DELETE FROM authors
WHERE id = $1;

5. Geração do código

sqlc generate

Após a execução, os arquivos gerados aparecerão na pasta db/. Agora você pode usá-los no seu código:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/jackc/pgx/v5/pgxpool"
    "sqlc-demo/db"
)

func main() {
    ctx := context.Background()
    pool, err := pgxpool.New(ctx, "postgres://usuario:senha@localhost:5432/testdb")
    if err != nil {
        log.Fatal(err)
    }
    defer pool.Close()

    queries := db.New(pool)

    // Criando um autor
    author, err := queries.CreateAuthor(ctx, db.CreateAuthorParams{
        Name: "Brian Kernighan",
        Bio:  "Coautor de The C Programming Language",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Autor criado: %+v\n", author)

    // Buscando autor por ID
    fetched, err := queries.GetAuthor(ctx, author.ID)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Autor encontrado: %+v\n", fetched)
}