gosuda.org/sqlite3: Un controlador database/sql de inserción directa que ejecuta SQLite en C nativo sobre memoria compartida

gosuda.org/sqlite3 es un controlador de database/sql con CGO_ENABLED=0 para Go que ejecuta la amalgamación en C de SQLite upstream 3.54.1 dentro de un proceso de trabajador aislado a través de anillos de memoria compartida HQQ. Se registra bajo el nombre de controlador estándar "sqlite3", es compatible con los parámetros de consulta DSN de github.com/mattn/go-sqlite3, incrusta binarios de servidor precompilados y certificados por SLSA para seis objetivos de sistemas operativos y arquitecturas, y utiliza canalización de solicitudes con preejecución por lotes de 64 KiB para superar al rendimiento del cgo en proceso en consultas de múltiples filas.

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

¿Por qué otro controlador de Go para SQLite?

SQLite es uno de los programas más implementados en el mundo; sin embargo, utilizarlo desde Go ha forzado históricamente a los ingenieros a tomar una decisión incómoda entre la simplicidad de compilación y la fidelidad del motor.

Por un lado se encuentra github.com/mattn/go-sqlite3, el estándar de la comunidad durante mucho tiempo. Este envuelve la amalgamación oficial en C de SQLite directamente mediante cgo. Se obtiene el planificador de consultas real de C, la semántica completa de concurrencia WAL y una gestión de memoria predecible en C. El costo es CGO_ENABLED=1: las compilaciones locales y las canalizaciones de integración continua (CI) se ralentizan, las imágenes de contenedores mínimos o sin distribución requieren bibliotecas de tiempo de ejecución de C coincidentes, la compilación cruzada hacia otro sistema operativo o arquitectura de CPU requiere una cadena de herramientas cruzadas de C completa, y cualquier corrupción de memoria en C comparte el espacio de direcciones del proceso de Go.

Por otro lado se encuentran las adaptaciones de SQLite puramente en Go generadas al traducir mecánicamente la amalgamación de C en código fuente de Go sobre un tiempo de ejecución de C emulado (libc). Estas restauran CGO_ENABLED=0, lo que simplifica las compilaciones. Sin embargo, bajo cargas de trabajo sostenidas, el montón de C traducido y las asignaciones en Go por cada fila aumentan la presión del recolector de basura, y los casos límite sutiles en el bloqueo, los tiempos de espera por ocupado o la interrupción de declaraciones pueden divergir de las compilaciones nativas de C.

Construimos gosuda.org/sqlite3 para que las aplicaciones en Go no tengan que elegir entre CGO_ENABLED=0 y el motor real de SQLite en C. Al compilar la amalgamación en C oficial 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 de Go se compila con CGO_ENABLED=0 mientras ejecuta código de C SQLite sin modificar y optimizado con -O3 a través de un límite de procesos.

Ejecución sin configuración: De go get a sql.Open

Reemplazar github.com/mattn/go-sqlite3 en una base de código existente en Go requiere cambiar únicamente la ruta de importación en blanco. El controlador se registra como "sqlite3" (y "hqq-sqlite" para 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 trabajadores incrustados y certificados por SLSA

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

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

Cuando sql.Open establece su primera conexión, autolaunch.go materializa el binario incrustado en el directorio de caché del usuario ($XDG_CACHE_HOME/hqq/bin/<sha256>/), verifica su resumen criptográfico SHA-256 con el mapa fijado de ReleaseHashes en hashes.go a través de gosuda.org/hqq/secureexec, e inicia el trabajador con --parent-stdin para que su ciclo de vida esté estrictamente ligado a su proceso de Go.

Compatibilidad con DSN de mattn/go-sqlite3 en sala limpia

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

Transformación del aislamiento de procesos en una ventaja de rendimiento

A primera vista, ejecutar SQLite en un proceso separado puede parecer necesariamente más lento que invocar sqlite3_step dentro del proceso mediante cgo. En la práctica, ocurre lo contrario tan pronto como una consulta devuelve más de una sola fila.

El costo oculto de las llamadas de cgo fila por fila

En un controlador de SQLite convencional basado en cgo, database/sql dirige la iteración una fila y una columna a la vez. Leer 1,000 filas con 4 columnas activa:

• 1,000 llamadas de cgo a sqlite3_step
• 4,000 llamadas de cgo a sqlite3_column_type y sqlite3_column_int64 / sqlite3_column_text
• Miles de cruces individuales de límites entre el planificador de Go y la pila de C

Canalización de solicitudes y preejecución por lotes de 64 KiB

gosuda.org/sqlite3 elimina los cruces de límites por fila mediante el rediseño del protocolo de red en torno a dos mecanismos ubicados en stmt.go, rows.go y sqlite3/server/sqlite3_hooks.c:

 1Go Client (stmt.go / rows.go)                       C11 Worker (sqlite3_hooks.c)
 2-----------------------------                       ----------------------------
 31. Pipeline in 1 flight:
 4   ResetAsync + BindValuesAsync
 5   + StmtInfoAsync + FetchRowsAsync(128)  =======>  reset -> bind -> stmt_info ->
 6                                                    loop sqlite3_step() up to 128 rows
 7                                          <=======  Batch 1 (rows 1..128 packed in 64 KiB slot)
 82. Immediately fire prefetch:
 9   FetchRowsAsync(128) (Batch 2)          =======>  loop sqlite3_step() for rows 129..256
10   While C steps Batch 2, Go caller
11   scans rows 1..128 from Batch 1!        <=======  Batch 2 ready in shared memory

1. Canalización de consultas de vuelo único (stmt.go): Cuando QueryContext o Stmt.QueryContext ejecuta una declaración de solo lectura, s.query() envía reset, bind_values, stmt_info (en la primera ejecución) y fetch_rows de manera asíncrona en un solo vuelo de memoria compartida. Las cuatro operaciones se ejecutan consecutivamente en el trabajador de C y retornan en un solo viaje de ida y vuelta.
2. Bucles de lotes ajustados en C y preejecución asíncrona (rows.go): Dentro de fetch_rows (sqlite3_hooks.c), el trabajador de C ejecuta iteraciones de sqlite3_step(stmt) en un bucle nativo de C, codificando hasta FetchSize filas (por defecto 128) directamente en la ranura de respuesta de memoria compartida de 64 KiB hasta que se alcanza el límite del lote, la ranura se llena o ocurre SQLITE_DONE. Tan pronto como rows.ingest() decodifica el Lote 1, activa FetchRowsAsync para el Lote 2 antes de devolver la primera fila al invocador. Mientras su código de Go analiza el Lote 1, el trabajador de C ya está procesando el Lote 2 en otro núcleo de CPU.

En Apple M4 (darwin/arm64), al comparar gosuda.org/sqlite3 (CGO_ENABLED=0) con github.com/mattn/go-sqlite3 (CGO_ENABLED=1) en la misma base de datos SQLite, se observa el efecto del procesamiento por lotes y la canalización:

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

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

• Cancelación determinista de contextos (conn.go y errors.go): Cada llamada del controlador arma un protector ligero de tipo context.AfterFunc (cn.guard). Si el context.Context del invocador se cancela o su plazo expira mientras se ejecuta una consulta recursiva lenta o una espera de bloqueo en el servidor, el protector marca la conexión como defectuosa, interrumpe el enlace de la sesión local y envía una trama de cancelación fuera de banda (Cancel()). El trabajador de C invoca sqlite3_interrupt(db) inmediatamente, desbloqueando sqlite3_step, mientras que el controlador de Go asigna el estado SQLITE_INTERRUPT resultante a context.Canceled o context.DeadlineExceeded y da instrucciones a database/sql para reemplazar la conexión en el grupo.
• Aislamiento de directorios (sqlsrv_pathrules.c): El trabajador de C aplica reglas de ruta --allow-dir en cada llamada a open_v2, resolviendo enlaces simbólicos y rechazando la navegación relativa con .. fuera del directorio permitido. sqlite3_load_extension y SQLITE_LIMIT_ATTACHED están deshabilitados por defecto para que la inyección de código SQL no pueda escapar del directorio de la base de datos ni cargar objetos compartidos arbitrarios.

Estructura del repositorio

El repositorio está estructurado de manera que el paquete de nivel superior proporciona el controlador directo para database/sql, mientras que launcher/ y sqlite3/ permanecen accesibles para implementaciones avanzadas de servidores personalizados:

 1gosuda.org/sqlite3
 2├── driver.go / api.go         # Registro del controlador database/sql ("sqlite3") y API de Connector
 3├── dsn.go                     # Analizador de DSN y configuración de directivas (pragmas) compatible con mattn/go-sqlite3
 4├── conn.go / tx.go            # Ciclo de vida de la sesión, protector de contexto y máquina de estados de transacciones
 5├── stmt.go / rows.go          # Canalización de solicitudes de vuelo único y preejecución por lotes de 64 KiB
 6├── errors.go                  # Códigos de error primarios/extendidos tipados de SQLite y coincidencia de centinelas
 7├── autolaunch.go / hashes.go  # Materialización del servidor incrustado sin configuración y fijación SHA-256
 8├── internal/embedded/         # Binarios con etiquetas de plataforma //go:embed (linux, darwin, windows)
 9├── launcher/                  # Supervisor de procesos configurable para implementaciones de servidores personalizados
10└── sqlite3/                   # Cliente de Go generado por hqq-bindgen y código fuente del servidor C11 de SQLite
11    └── server/                # Implementación del servidor en 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 directivas (Pragma): docs/DSN.md
• Arquitectura y protocolo de red: docs/ARCHITECTURE.md