gosuda.org/sqlite3: CGO_ENABLED=0 database/sql-Treiber über Shared-Memory-IPC

gosuda.org/sqlite3 ist ein database/sql-Treiber für Go mit CGO_ENABLED=0, der den upstream C-SQLite-3.54.1-Amalgamation innerhalb eines isolierten Worker-Prozesses über HQQ-Shared-Memory-Ringe ausführt. Er registriert sich unter dem standardmäßigen Treibernamen "sqlite3", unterstützt die DSN-Query-Parameter von github.com/mattn/go-sqlite3, bettet SLSA-attestierte, vorkompilierte Server-Binaries für sechs Betriebssystem- und Architektur-Zielplattformen ein und nutzt Request-Pipelining sowie 64-KiB-Batch-Prefetching, um In-Process-cgo bei mehrzeiligen Abfragen zu übertreffen.

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

Warum ein weiterer Go-SQLite-Treiber?

SQLite gehört zu den am weitesten verbreiteten Softwarekomponenten der Welt, dennoch zwang die Nutzung aus Go Entwickler bisher zu einer unbequemen Wahl zwischen Build-Einfachheit und Engine-Treue.

Auf der einen Seite steht github.com/mattn/go-sqlite3, der langjährige Standard der Community. Er bindet das offizielle C-SQLite-Amalgamation direkt über cgo ein. Man erhält den echten C-Query-Planer, die vollständige WAL-Nebenläufigkeitssemantik und ein vorhersagbares C-Speichermanagement. Der Preis ist CGO_ENABLED=1: Lokale Builds und CI-Pipelines werden langsamer, minimale Scratch- oder Distroless-Container-Images benötigen passende C-Laufzeitbibliotheken, die Cross-Kompilierung für ein anderes Betriebssystem oder eine andere CPU-Architektur erfordert eine vollständige C-Cross-Toolchain, und jede Speicherkorruption im C-Code teilt sich den Adressraum des Go-Prozesses.

Auf der anderen Seite stehen reine Go-Portierungen von SQLite, die durch mechanische Übersetzung des C-Amalgamation in Go-Quellcode über eine emulierte C-Laufzeitumgebung (libc) entstanden sind. Sie stellen CGO_ENABLED=0 wieder her, wodurch Builds trivial werden. Unter dauerhafter Last erhöhen der übersetzte C-Heap und die Go-Allokationen pro Zeile jedoch den Druck auf die Garbage Collection, und subtile Randfälle bei Sperren, Busy-Timeouts oder Statement-Unterbrechung können von nativen C-Builds abweichen.

Wir haben gosuda.org/sqlite3 entwickelt, damit Go-Anwendungen nicht zwischen CGO_ENABLED=0 und der echten C-SQLite-Engine wählen müssen. Indem das offizielle C-Amalgamation von SQLite 3.54.1 in einen dedizierten Shared-Memory-Server (hqq-sqlite-server) kompiliert wird und die Kommunikation über gosuda.org/hqq erfolgt, wird Ihr Go-Binary mit CGO_ENABLED=0 gebaut, während unveränderte, mit -O3 optimierte C-SQLite-Engine über eine Prozessgrenze hinweg ausgeführt wird.

Zero-Config-Ausführung: Von go get bis sql.Open

Der Ersatz von github.com/mattn/go-sqlite3 in einer bestehenden Go-Codebasis erfordert nur die Änderung des Blank-Import-Pfads. Der Treiber registriert sich als "sqlite3" (sowie "hqq-sqlite" zur expliziten Auswahl) und akzeptiert dieselben DSN-Query-Strings:

 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}

Eingebettete SLSA-attestierte Worker-Binaries

Eine naheliegende Frage, wenn man hört, dass eine Bibliothek einen C-Worker-Prozess verwendet, lautet: „Muss ich ein separates C-Binary installieren oder zusammen mit meinem Go-Programm ausliefern?“

Nein. gosuda.org/sqlite3 bettet vorkompilierte hqq-sqlite-server-Binaries für alle sechs wichtigen Zielplattformen direkt in plattformgekennzeichnete Go-Dateien ein (internal/embedded/embed_<goos>_<goarch>.go). Da die Build-Constraints von Go nur die Datei kompilieren, die zu Ihrem Ziel-GOOS und GOARCH passt, bettet eine Cross-Kompilierung mit GOOS=linux GOARCH=arm64 go build automatisch nur das etwa 1,4 MiB große Server-Binary für linux/arm64 ein.

Wenn sql.Open die erste Verbindung herstellt, materialisiert autolaunch.go das eingebettete Binary im Benutzer-Cache-Verzeichnis ($XDG_CACHE_HOME/hqq/bin/<sha256>/), verifiziert dessen kryptographischen SHA-256-Digest gegen die fixierte ReleaseHashes-Map in hashes.go über gosuda.org/hqq/secureexec und startet den Worker mit --parent-stdin, sodass seine Lebensdauer strikt an Ihren Go-Prozess gebunden ist.

Clean-Room-DSN-Kompatibilität zu mattn/go-sqlite3

Um als echter Drop-in-Ersatz zu funktionieren, implementiert der DSN-Parser (dsn.go) eine Clean-Room-Nachbildung der Verbindungs- und Pragma-Schalter, die in mattn/go-sqlite3-Codebasen verwendet werden:

Prozessisolation als Durchsatzvorteil

Auf den ersten Blick scheint das Ausführen von SQLite in einem separaten Prozess langsamer sein zu müssen als der In-Process-Aufruf von sqlite3_step über cgo. In der Praxis geschieht das Gegenteil, sobald eine Abfrage mehr als eine einzige Zeile zurückgibt.

Die versteckten Kosten zeilenweiser cgo-Aufrufe

In einem herkömmlichen cgo-SQLite-Treiber iteriert database/sql jeweils eine Zeile und eine Spalte nach der anderen. Das Lesen von 1.000 Zeilen mit 4 Spalten löst aus:

• 1.000 cgo-Aufrufe von sqlite3_step
• 4.000 cgo-Aufrufe von sqlite3_column_type und sqlite3_column_int64 / sqlite3_column_text
• Tausende einzelne Grenzübergänge zwischen dem Go-Scheduler und dem C-Stack

Request-Pipelining und 64-KiB-Batch-Prefetching

gosuda.org/sqlite3 eliminiert zeilenweise Grenzübergänge, indem das Wire-Protokoll um zwei Mechanismen in stmt.go, rows.go und sqlite3/server/sqlite3_hooks.c neu gestaltet wird:

 1Go-Client (stmt.go / rows.go)                       C11-Worker (sqlite3_hooks.c)
 2-----------------------------                       ----------------------------
 31. Pipeline in 1 Flug:
 4   ResetAsync + BindValuesAsync
 5   + StmtInfoAsync + FetchRowsAsync(128)  =======>  reset -> bind -> stmt_info ->
 6                                                    Schleife sqlite3_step() bis zu 128 Zeilen
 7                                          <=======  Batch 1 (Zeilen 1..128 gepackt in 64-KiB-Slot)
 82. Sofort Prefetch auslösen:
 9   FetchRowsAsync(128) (Batch 2)          =======>  Schleife sqlite3_step() für Zeilen 129..256
10   Während C Batch 2 abarbeitet, scannt der
11   Go-Aufrufer Zeilen 1..128 aus Batch 1!  <=======  Batch 2 bereit im Shared Memory

1. Single-Flight-Query-Pipelining (stmt.go): Wenn QueryContext oder Stmt.QueryContext eine schreibgeschützte Anweisung ausführt, übermittelt s.query() reset, bind_values, stmt_info (bei der ersten Ausführung) und fetch_rows asynchron in einem einzigen Shared-Memory-Flug. Alle vier Operationen laufen auf dem C-Worker nacheinander ab und kehren in einem einzigen Roundtrip zurück.
2. Enge C-Batch-Schleifen und asynchrones Prefetching (rows.go): Innerhalb von fetch_rows (sqlite3_hooks.c) führt der C-Worker sqlite3_step(stmt) in einer nativen C-Schleife aus und kodiert bis zu FetchSize Zeilen (Standard 128) direkt in den 64-KiB-Shared-Memory-Antwortslot, bis das Batch-Limit erreicht ist, der Slot voll ist oder SQLITE_DONE auftritt. Sobald rows.ingest() Batch 1 dekodiert, löst es FetchRowsAsync für Batch 2 aus, bevor die erste Zeile an den Aufrufer zurückgegeben wird. Während Ihr Go-Code Batch 1 scannt, führt der C-Worker bereits auf einem anderen CPU-Kern sqlite3_step für Batch 2 aus.

Auf Apple M4 (darwin/arm64) zeigt der Vergleich von gosuda.org/sqlite3 (CGO_ENABLED=0) mit github.com/mattn/go-sqlite3 (CGO_ENABLED=1) auf derselben SQLite-Datenbank den Effekt von Batching und Pipelining:

Abbruch, Pfad-Sandboxing und Wiederherstellung des Connection-Pools

Die Ausführung von SQLite in einem isolierten Worker stärkt außerdem den Umgang des Treibers mit Timeouts, nicht vertrauenswürdigem SQL und Dateisystemgrenzen:

• Deterministischer Context-Abbruch (conn.go und errors.go): Jeder Treiberaufruf aktiviert eine leichtgewichtige context.AfterFunc-Schutzfunktion (cn.guard). Wird der context.Context des Aufrufers abgebrochen oder läuft seine Deadline ab, während auf dem Server eine langsame rekursive Abfrage oder ein Sperrwartevorgang läuft, markiert der Guard die Verbindung als fehlerhaft, beendet die lokale Sitzungsverbindung und sendet ein Out-of-Band-Cancel()-Frame. Der C-Worker ruft sofort sqlite3_interrupt(db) auf, wodurch sqlite3_step entblockiert wird, während der Go-Treiber den resultierenden SQLITE_INTERRUPT-Status auf context.Canceled oder context.DeadlineExceeded abbildet und database/sql anweist, die Verbindung im Pool zu ersetzen.
• Verzeichnis-Sandboxing (sqlsrv_pathrules.c): Der C-Worker erzwingt die --allow-dir-Pfadregeln bei jedem open_v2-Aufruf, löst Symlinks auf und weist relative ..-Traversierung außerhalb des erlaubten Verzeichnisses zurück. sqlite3_load_extension und SQLITE_LIMIT_ATTACHED sind standardmäßig deaktiviert, sodass SQL-Injection weder das Datenbankverzeichnis verlassen noch beliebige Shared Objects laden kann.

Repository-Struktur

Das Repository ist so aufgebaut, dass das Paket auf oberster Ebene den Drop-in-database/sql-Treiber bereitstellt, während launcher/ und sqlite3/ für fortgeschrittene Deployments mit eigenem Server zugänglich bleiben:

 1gosuda.org/sqlite3
 2├── driver.go / api.go         # Registrierung des database/sql-Treibers ("sqlite3") und Connector-API
 3├── dsn.go                     # Clean-Room-DSN-Parser für mattn/go-sqlite3 und Pragma-Konfiguration
 4├── conn.go / tx.go            # Sitzungslebenszyklus, Context-Guard und Zustandsautomat für Transaktionen
 5├── stmt.go / rows.go          # Single-Flight-Request-Pipelining und 64-KiB-Batch-Prefetching
 6├── errors.go                  # Typisierte primäre/erweiterte SQLite-Fehlercodes und Sentinel-Abgleich
 7├── autolaunch.go / hashes.go  # Zero-Config-Materialisierung des eingebetteten Servers und SHA-256-Fixierung
 8├── internal/embedded/         # Plattformgekennzeichnete //go:embed-Binaries (linux, darwin, windows)
 9├── launcher/                  # Konfigurierbarer Prozess-Supervisor für eigene Serverdeployments
10└── sqlite3/                   # Generierter hqq-bindgen-Go-Client und C11-SQLite-Serverquellcode
11    └── server/                # C11-Serverimplementierung (sqlite3_hooks.c, sqlsrv_policy.c)

Erste Schritte

Installieren Sie das Modul mit go get und öffnen Sie Ihre Datenbank mit sql.Open("sqlite3", dsn):

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

• GitHub-Repository: https://github.com/gosuda/hqq-sqlite3
• DSN- und Pragma-Referenz: docs/DSN.md
• Architektur und Wire-Protokoll: docs/ARCHITECTURE.md