sqlc para Go: generación de código type-safe desde SQL

sqlc es un compilador que genera código Go a partir de tus consultas SQL. En lugar de escribir manualmente funciones para interactuar con la base de datos, escribes SQL puro y sqlc crea por ti funciones tipadas, seguras y eficientes. Este enfoque es fundamentalmente diferente al de un ORM: mantienes el control total sobre el SQL, pero te liberas de la tediosa escritura de código repetitivo (boilerplate).

¿Por qué es útil? Primero, sqlc garantiza type-safety en tiempo de compilación. Si modificas el esquema de una tabla o una consulta, sqlc regenera el código y el compilador de Go te señala al instante todos los lugares que necesitan ajustes. Segundo, rendimiento: el código generado no usa reflexión ni hace asignaciones innecesarias, lo que lo hace casi tan rápido como escribir las consultas manualmente con database/sql. Tercero, simplifica las revisiones de código: las consultas SQL son claramente visibles en archivos .sql, no están ocultas dentro de métodos de un ORM.

sqlc es ideal para proyectos donde el rendimiento y el control de las consultas son críticos: APIs de alta carga, sistemas financieros, plataformas de análisis. También se integra perfectamente con migraciones (por ejemplo, golang-migrate) y no te ata a un motor de base de datos específico, ya que soporta PostgreSQL, MySQL y SQLite.

Instalación

sqlc no es una librería, sino una herramienta de línea de comandos. Puedes instalarla de varias formas:

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

# Con Homebrew (macOS/Linux)
brew install sqlc

# Descargando el binario desde GitHub
# https://github.com/sqlc-dev/sqlc/releases

Después de instalar, verifica la versión:

sqlc version

Inicio rápido

Vamos a crear un proyecto mínimo que demuestre el funcionamiento de sqlc.

1. Estructura del proyecto

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

2. Configuración de sqlc

Crea el archivo sqlc.yaml en la raíz del proyecto:

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

3. Esquema de la base de datos

Archivo schema.sql:

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

4. Consultas SQL

Archivo 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. Generación de código

sqlc generate

Después de ejecutar el comando, en la carpeta db/ aparecerán los archivos generados. Ahora puedes usarlos en tu 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://user:pass@localhost:5432/testdb")
    if err != nil {
        log.Fatal(err)
    }
    defer pool.Close()

    queries := db.New(pool)

    // Creamos un autor
    author, err := queries.CreateAuthor(ctx, db.CreateAuthorParams{
        Name: "Brian Kernighan",
        Bio:  "Coautor de El lenguaje de programación C",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Autor creado: %+v\n", author)

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