gosuda.org/sqlite3: Controlador database/sql con CGO_ENABLED=0 sobre IPC de memoria compartida

gosuda.org/sqlite3 es un controlador database/sql para Go con CGO_ENABLED=0 que ejecuta la amalgama C de SQLite 3.54.1 upstream dentro de un proceso trabajador aislado, comunicándose a través de anillos de memoria compartida de HQQ. Se registra bajo el nombre de controlador estándar "sqlite3", admite los parámetros de consulta del DSN de github.com/mattn/go-sqlite3, incluye binarios de servidor precompilados con atestación SLSA para seis objetivos de sistema operativo y arquitectura, y utiliza segmentación de solicitudes (pipelining) con precarga de lotes de 64 KiB para superar a cgo en proceso en consultas de múltiples filas.

1go get gosuda.org/sqlite3@v0.3.3540100

¿Por qué otro controlador SQLite para Go?

SQLite es uno de los componentes de software más desplegados del mundo; sin embargo, su uso desde Go ha obligado históricamente a los ingenieros a elegir entre la simplicidad de compilación y la fidelidad del motor.

Por un lado se encuentra github.com/mattn/go-sqlite3, el estándar comunitario de larga trayectoria. Envuelve directamente la amalgama oficial de C de SQLite mediante cgo. Se obtiene el planificador de consultas real de C, la semántica completa de concurrencia de WAL y una gestión de memoria en C predecible. El costo es CGO_ENABLED=1: las compilaciones locales y las canalizaciones de CI se ralentizan, las imágenes de contenedor mínimas (scratch o distroless) requieren bibliotecas de tiempo de ejecución de C compatibles, la compilación cruzada hacia otro sistema operativo o arquitectura de CPU exige una cadena de herramientas cruzada de C completa, y cualquier corrupción de memoria en C comparte el espacio de direcciones del proceso Go.

Por otro lado, existen los ports de SQLite puros en Go, generados mediante la traducción mecánica de la amalgama de C a código fuente Go sobre un entorno de ejecución de C emulado (libc). Estos restablecen CGO_ENABLED=0, lo que hace trivial la compilación. Sin embargo, bajo cargas de trabajo sostenidas, el heap de C traducido y las asignaciones de Go por fila aumentan la presión sobre el recolector de basura, y casos límite sutiles en el bloqueo, los tiempos de espera ocupados (busy timeouts) o la interrupción de sentencias pueden divergir de las compilaciones nativas en C.

Creamos gosuda.org/sqlite3 para que las aplicaciones Go no tengan que elegir entre CGO_ENABLED=0 y el motor real de C SQLite. Al compilar la amalgama oficial de C de SQLite 3.54.1 en un servidor dedicado de memoria compartida (hqq-sqlite-server) y comunicarse a través de gosuda.org/hqq, su binario Go se compila con CGO_ENABLED=0 mientras ejecuta C SQLite sin modificaciones y optimizado con -O3 a través de un límite de proceso.

Ejecución sin configuración: desde go get hasta sql.Open

Reemplazar github.com/mattn/go-sqlite3 en una base de código Go existente requiere cambiar únicamente la ruta de importación en blanco. El controlador se registra como "sqlite3" (y como "hqq-sqlite" para una selección explícita) y acepta las mismas cadenas de consulta DSN:

 1package main
 2
 3import (
 4	"context"
 5	"database/sql"
 6	"fmt"
 7	"log"
 8
 9	_ "gosuda.org/sqlite3"
10)
11
12func main() {
13	dsn := "file:app.db?_journal_mode=WAL&_busy_timeout=5000&_txlock=immediate&_foreign_keys=on"
14	db, err := sql.Open("sqlite3", dsn)
15	if err != nil {
16		log.Fatal(err)
17	}
18	defer db.Close()
19
20	ctx := context.Background()
21	if _, err := db.ExecContext(ctx, `CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)`); err != nil {
22		log.Fatal(err)
23	}
24	if _, err := db.ExecContext(ctx, `INSERT INTO users (name) VALUES (?)`, "Ada Lovelace"); err != nil {
25		log.Fatal(err)
26	}
27
28	var id int64
29	var name string
30	if err := db.QueryRowContext(ctx, `SELECT id, name FROM users WHERE name = ?`, "Ada Lovelace").Scan(&id, &name); err != nil {
31		log.Fatal(err)
32	}
33	fmt.Printf("user #%d: %s\n", id, name)
34}

Binarios de trabajador embebidos con atestación SLSA

Una pregunta natural al saber que una biblioteca usa un proceso trabajador en C es: "¿Tengo que instalar o distribuir un binario de C separado junto a mi programa Go?"

No. gosuda.org/sqlite3 incorpora binarios precompilados de hqq-sqlite-server para los seis objetivos principales directamente dentro de archivos Go con etiquetas de plataforma (internal/embedded/embed_<goos>_<goarch>.go). Dado que las restricciones de compilación de Go solo compilan el archivo que coincide con su GOOS y GOARCH de destino, la compilación cruzada con GOOS=linux GOARCH=arm64 go build incorpora automáticamente únicamente el binario de servidor linux/arm64 de aproximadamente 1,4 MiB.

Cuando sql.Open establece su primera conexión, autolaunch.go materializa el binario embebido en el directorio de caché del usuario ($XDG_CACHE_HOME/hqq/bin/<sha256>/), verifica su resumen criptográfico SHA-256 frente al mapa fijado ReleaseHashes de hashes.go mediante gosuda.org/hqq/secureexec, y lanza el trabajador con --parent-stdin para que su tiempo de vida quede estrictamente vinculado a su proceso Go.

Compatibilidad de DSN con mattn/go-sqlite3 mediante reimplementación limpia

Para funcionar como un reemplazo directo real, el analizador de DSN (dsn.go) implementa una réplica de diseño limpio de los parámetros de conexión y de pragmas utilizados en las bases de código de mattn/go-sqlite3:

Convertir el aislamiento de procesos en una ventaja de rendimiento

A primera vista, ejecutar SQLite en un proceso separado parece que debe ser más lento que invocar sqlite3_step en proceso mediante cgo. En la práctica, ocurre lo contrario en cuanto una consulta devuelve más de una fila.

El costo oculto de las llamadas cgo fila por fila

En un controlador SQLite convencional basado en cgo, database/sql recorre el resultado una fila y una columna a la vez. Leer 1.000 filas con 4 columnas provoca:

• 1.000 llamadas cgo a sqlite3_step
• 4.000 llamadas cgo a sqlite3_column_type y sqlite3_column_int64 / sqlite3_column_text
• Miles de cruces de frontera individuales entre el planificador de Go y la pila de C

Segmentación de solicitudes y precarga de lotes de 64 KiB

gosuda.org/sqlite3 elimina los cruces de frontera por fila rediseñando el protocolo de comunicación en torno a dos mecanismos en stmt.go, rows.go y sqlite3/server/sqlite3_hooks.c:

 1Cliente Go (stmt.go / rows.go)                      Trabajador C11 (sqlite3_hooks.c)
 2------------------------------                      --------------------------------
 31. Segmentar en 1 vuelo:
 4   ResetAsync + BindValuesAsync
 5   + StmtInfoAsync + FetchRowsAsync(128)  =======>  reset -> bind -> stmt_info ->
 6                                                    bucle sqlite3_step() hasta 128 filas
 7                                          <=======  Lote 1 (filas 1..128 empaquetadas en slot de 64 KiB)
 82. Disparar inmediatamente la precarga:
 9   FetchRowsAsync(128) (Lote 2)           =======>  bucle sqlite3_step() para filas 129..256
10   Mientras C avanza el Lote 2, el código
11   Go escanea las filas 1..128 del Lote 1!  <=======  Lote 2 listo en memoria compartida

1. Segmentación de consultas de vuelo único (stmt.go): Cuando QueryContext o Stmt.QueryContext ejecutan una sentencia de solo lectura, s.query() envía de forma asíncrona reset, bind_values, stmt_info (en la primera ejecución) y fetch_rows en un único vuelo de memoria compartida. Las cuatro operaciones se ejecutan consecutivamente en el trabajador C y devuelven el resultado en un solo viaje de ida y vuelta.
2. Bucles de lote C ajustados y precarga asíncrona (rows.go): Dentro de fetch_rows (sqlite3_hooks.c), el trabajador C ejecuta sqlite3_step(stmt) en un bucle C nativo, codificando hasta FetchSize filas (por defecto 128) directamente en el slot de respuesta de memoria compartida de 64 KiB hasta alcanzar el límite del lote, llenar el slot o producirse SQLITE_DONE. En cuanto rows.ingest() decodifica el Lote 1, dispara FetchRowsAsync para el Lote 2 antes de devolver la primera fila al llamador. Mientras su código Go escanea el Lote 1, el trabajador C ya está avanzando el Lote 2 en otro núcleo de CPU.

En Apple M4 (darwin/arm64), la comparación de gosuda.org/sqlite3 (CGO_ENABLED=0) frente a github.com/mattn/go-sqlite3 (CGO_ENABLED=1) sobre la misma base de datos SQLite muestra el efecto del agrupamiento por lotes y la segmentación:

Cancelación, aislamiento de rutas y recuperación del pool de conexiones

Ejecutar SQLite en un trabajador aislado también fortalece la forma en que el controlador gestiona los tiempos de espera, el SQL no confiable y los límites del sistema de archivos:

• Cancelación de contexto determinista (conn.go y errors.go): Cada llamada del controlador activa un guardia ligero context.AfterFunc (cn.guard). Si el context.Context del llamador se cancela o expira su plazo mientras una consulta recursiva lenta o una espera de bloqueo se ejecuta en el servidor, el guardia marca la conexión como inválida, cierra el enlace de sesión local y envía un marco Cancel() fuera de banda. El trabajador C invoca sqlite3_interrupt(db) de inmediato, desbloqueando sqlite3_step, mientras el controlador Go traduce el estado SQLITE_INTERRUPT resultante a context.Canceled o context.DeadlineExceeded e indica a database/sql que reemplace la conexión en el pool.
• Aislamiento de directorios (sqlsrv_pathrules.c): El trabajador C aplica las reglas de ruta --allow-dir en cada llamada a open_v2, resolviendo enlaces simbólicos y rechazando el recorrido relativo .. fuera del directorio permitido. sqlite3_load_extension y SQLITE_LIMIT_ATTACHED están deshabilitados por defecto, de modo que una inyección SQL no pueda salir del directorio de la base de datos ni cargar objetos compartidos arbitrarios.

Estructura del repositorio

El repositorio está organizado de modo que el paquete de nivel superior proporciona el controlador database/sql de reemplazo directo, mientras que launcher/ y sqlite3/ permanecen accesibles para despliegues avanzados con servidor personalizado:

 1gosuda.org/sqlite3
 2├── driver.go / api.go         # Registro del controlador database/sql ("sqlite3") y API Connector
 3├── dsn.go                     # Analizador DSN de diseño limpio compatible con mattn/go-sqlite3 y configuración de pragmas
 4├── conn.go / tx.go            # Ciclo de vida de la sesión, guardia de contexto y máquina de estados de transacciones
 5├── stmt.go / rows.go          # Segmentación de solicitudes de vuelo único y precarga de lotes de 64 KiB
 6├── errors.go                  # Códigos de error primarios/extendidos de SQLite tipados y coincidencia de centinelas
 7├── autolaunch.go / hashes.go  # Materialización del servidor embebido sin configuración y fijación SHA-256
 8├── internal/embedded/         # Binarios //go:embed con etiquetas de plataforma (linux, darwin, windows)
 9├── launcher/                  # Supervisor de procesos configurable para despliegues de servidor personalizados
10└── sqlite3/                   # Cliente Go hqq-bindgen generado y código fuente del servidor C11 de SQLite
11    └── server/                # Implementación del servidor C11 (sqlite3_hooks.c, sqlsrv_policy.c)

Primeros pasos

Instale el módulo con go get y abra su base de datos con sql.Open("sqlite3", dsn):

1go get gosuda.org/sqlite3@v0.3.3540100

• Repositorio de GitHub: https://github.com/gosuda/hqq-sqlite3
• Referencia de DSN y pragmas: docs/DSN.md
• Arquitectura y protocolo de comunicación: docs/ARCHITECTURE.md