gosuda.org/sqlite3: Um Driver database/sql Integrado que Executa SQLite em C Nativo Sobre Memória Compartilhada

gosuda.org/sqlite3 é um driver database/sql com CGO_ENABLED=0 para Go que executa a amalgamada upstream C SQLite 3.54.1 dentro de um processo trabalhador isolado sobre anéis de memória compartilhada HQQ. Ele se registra sob o nome de driver padrão "sqlite3", suporta os parâmetros de consulta DSN de github.com/mattn/go-sqlite3, incorpora binários de servidor pré-compilados e atestados por SLSA para seis alvos de sistemas operacionais e arquiteturas, e utiliza pipelining de solicitações com pré-busca em lote de 64 KiB para superar o desempenho do cgo em processo em consultas de múltiplas linhas.

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

Por Que Outro Driver Go SQLite?

O SQLite é um dos softwares mais implantados no mundo, mas utilizá-lo a partir de Go historicamente forçou os engenheiros a uma escolha desconfortável entre a simplicidade de compilação e a fidelidade do mecanismo.

De um lado está github.com/mattn/go-sqlite3, o padrão de longa data da comunidade. Ele encapsula a amalgamada oficial em C do SQLite diretamente via cgo. Você obtém o planejador de consultas real em C, semântica completa de concorrência WAL e gerenciamento de memória previsível em C. O custo é CGO_ENABLED=1: as compilações locais e os pipelines de CI tornam-se lentos, imagens mínimas de contêineres scratch ou distroless exigem bibliotecas de tempo de execução em C correspondentes, a compilação cruzada para outro sistema operacional ou arquitetura de CPU requer uma cadeia de ferramentas de compilação cruzada em C completa, e qualquer corrupção de memória em C compartilha o espaço de endereçamento do processo Go.

Do outro lado estão as portas puramente em Go do SQLite geradas pela tradução mecânica da amalgamada em C para o código-fonte Go sobre um tempo de execução em C emulado (libc). Elas restauram CGO_ENABLED=0, o que torna as compilações triviais. Sob cargas de trabalho sustentadas, no entanto, o heap em C traduzido e as alocações em Go por linha aumentam a pressão do coletor de lixo, e casos extremos sutis em bloqueios, tempos limite de ocupado ou interrupção de instruções podem divergir das compilações nativas em C.

Construímos gosuda.org/sqlite3 para que as aplicações Go não precisem escolher entre CGO_ENABLED=0 e o mecanismo real de C SQLite. Compilando a amalgamada oficial C do SQLite 3.54.1 em um servidor de memória compartilhada dedicado (hqq-sqlite-server) e comunicando através de gosuda.org/hqq, seu binário Go é compilado com CGO_ENABLED=0 enquanto executa o C SQLite original otimizado com -O3 através de um limite de processo.

Execução Sem Configuração: De go get a sql.Open

Substituir github.com/mattn/go-sqlite3 em uma base de código Go existente requer alterar apenas o caminho de importação em branco. O driver se registra como "sqlite3" (e "hqq-sqlite" para seleção explícita) e aceita as mesmas strings 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}

Binários Trabalhadores Incorporados Atestados por SLSA

Uma pergunta natural ao ouvir que uma biblioteca usa um processo trabalhador em C é: "Eu preciso instalar ou distribuir um binário em C separado junto com o meu programa Go?"

Não. gosuda.org/sqlite3 incorpora binários pré-compilados do hqq-sqlite-server para todos os seis principais alvos diretamente dentro de arquivos Go marcados por plataforma (internal/embedded/embed_<goos>_<goarch>.go). Como as restrições de compilação do Go compilam apenas o arquivo correspondente ao seu GOOS e GOARCH de destino, a compilação cruzada GOOS=linux GOARCH=arm64 go build incorpora automaticamente apenas o binário de servidor linux/arm64 de ~1,4 MiB.

Quando sql.Open estabelece sua primeira conexão, autolaunch.go materializa o binário incorporado no diretório de cache do usuário ($XDG_CACHE_HOME/hqq/bin/<sha256>/), verifica seu resumo criptográfico SHA-256 em relação ao mapa fixo ReleaseHashes em hashes.go via gosuda.org/hqq/secureexec, e inicia o trabalhador com --parent-stdin para que seu tempo de vida esteja estritamente vinculado ao seu processo Go.

Compatibilidade DSN em Sala Limpa de mattn/go-sqlite3

Para funcionar como um substituto direto genuíno, o analisador DSN (dsn.go) implementa uma réplica de sala limpa dos controles de conexão e pragma usados nas bases de código de mattn/go-sqlite3:

Transformando o Isolamento de Processos em uma Vantagem de Vazão

À primeira vista, executar o SQLite em um processo separado parece ser mais lento do que chamar sqlite3_step em processo via cgo. Na prática, o oposto acontece assim que uma consulta retorna mais do que uma única linha.

O Custo Oculto de Chamadas cgo Linha por Linha

Em um driver cgo convencional do SQLite, database/sql conduz a iteração de uma linha e uma coluna por vez. Ler 1.000 linhas com 4 colunas aciona:

• 1.000 chamadas cgo para sqlite3_step
• 4.000 chamadas cgo para sqlite3_column_type e sqlite3_column_int64 / sqlite3_column_text
• Milhares de travessias de limite individuais entre o agendador do Go e a pilha C

Pipelining de Solicitações e Pré-busca em Lote de 64 KiB

gosuda.org/sqlite3 elimina as travessias de limite por linha ao reformular o protocolo de rede em torno de dois mecanismos em stmt.go, rows.go e 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. Pipelining de Consulta de Voo Único (stmt.go): Quando QueryContext ou Stmt.QueryContext executa uma instrução somente leitura, s.query() envia reset, bind_values, stmt_info (na primeira execução) e fetch_rows de forma assíncrona em um único voo de memória compartilhada. Todas as quatro operações são executadas consecutivamente no trabalhador C e retornam em uma única viagem de ida e volta.
2. Loops de Lote C Apertados e Pré-busca Assíncrona (rows.go): Dentro de fetch_rows (sqlite3_hooks.c), o trabalhador C executa sqlite3_step(stmt) em um loop C nativo, codificando até FetchSize linhas (padrão 128) diretamente no slot de resposta de memória compartilhada de 64 KiB até que o limite do lote seja atingido, o slot esteja cheio ou ocorra SQLITE_DONE. Assim que rows.ingest() decodifica o Lote 1, ele dispara FetchRowsAsync para o Lote 2 antes de retornar a primeira linha para o chamador. Enquanto seu código Go examina o Lote 1, o trabalhador C já está avançando o Lote 2 em outro núcleo de CPU.

No Apple M4 (darwin/arm64), comparar gosuda.org/sqlite3 (CGO_ENABLED=0) com github.com/mattn/go-sqlite3 (CGO_ENABLED=1) no mesmo banco de dados SQLite demonstra o efeito do lote e do pipelining:

Cancelamento, Isolamento de Caminho e Recuperação de Pool de Conexões

Executar o SQLite em um trabalhador isolado também fortalece a forma como o driver lida com tempos limite, SQL não confiável e limites do sistema de arquivos:

• Cancelamento Determinístico de Contexto (conn.go e errors.go): Cada chamada de driver arma um protetor context.AfterFunc leve (cn.guard). Se o context.Context do chamador for cancelado ou seu prazo expirar enquanto uma consulta recursiva lenta ou espera de bloqueio estiver em execução no servidor, o protetor marca a conexão como defeituosa, encerra o link da sessão local e envia um quadro Cancel() fora de banda. O trabalhador C invoca sqlite3_interrupt(db) imediatamente, desbloqueando sqlite3_step, enquanto o driver Go mapeia o status SQLITE_INTERRUPT resultante para context.Canceled ou context.DeadlineExceeded e instrui database/sql a substituir a conexão no pool.
• Isolamento de Diretório (sqlsrv_pathrules.c): O trabalhador C impõe regras de caminho --allow-dir em cada chamada open_v2, resolvendo links simbólicos e rejeitando a travessia relativa .. fora do diretório permitido. sqlite3_load_extension e SQLITE_LIMIT_ATTACHED são desabilitados por padrão para que a injeção de SQL não possa escapar do diretório do banco de dados ou carregar objetos compartilhados arbitrários.

Layout do Repositório

O repositório é estruturado de forma que o pacote de nível superior forneça o driver database/sql direto, enquanto launcher/ e sqlite3/ permanecem acessíveis para implantações de servidores personalizados avançados:

 1gosuda.org/sqlite3
 2├── driver.go / api.go         # Registro do driver database/sql ("sqlite3") e API Connector
 3├── dsn.go                     # Analisador DSN mattn/go-sqlite3 em sala limpa e configuração pragma
 4├── conn.go / tx.go            # Ciclo de vida da sessão, protetor de contexto e máquina de estados de transação
 5├── stmt.go / rows.go          # Pipelining de solicitações de voo único e pré-busca em lote de 64 KiB
 6├── errors.go                  # Códigos de erro primários/estendidos tipados do SQLite e correspondência de sentinela
 7├── autolaunch.go / hashes.go  # Materialização de servidor incorporado sem configuração e fixação de SHA-256
 8├── internal/embedded/         # Binários marcados por plataforma //go:embed (linux, darwin, windows)
 9├── launcher/                  # Supervisor de processos configurável para implantações de servidores personalizados
10└── sqlite3/                   # Cliente Go hqq-bindgen gerado e código-fonte do servidor C11 SQLite
11    └── server/                # Implementação do servidor C11 (sqlite3_hooks.c, sqlsrv_policy.c)

Primeiros Passos

Instale o módulo com go get e abra seu banco de dados com sql.Open("sqlite3", dsn):

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

• Repositório GitHub: https://github.com/gosuda/hqq-sqlite3
• Referência de DSN e Pragma: docs/DSN.md
• Arquitetura e Protocolo de Rede: docs/ARCHITECTURE.md