gosuda.org/sqlite3: A Drop-In database/sql Driver Running Native C SQLite Over Shared Memory

gosuda.org/sqlite3 is een CGO_ENABLED=0 database/sql-driver voor Go die de upstream C SQLite 3.54.1-amalgamatie uitvoert binnen een geïsoleerd werkproces via HQQ shared-memory-ringen. Het registreert zich onder de standaard "sqlite3"-drivernaam, ondersteunt github.com/mattn/go-sqlite3-DSN-queryparameters, sluit SLSA-geattesteerde voorgebouwde serverbinaries in voor zes besturingssysteem- en architectuurdoelen, en gebruikt request pipelining met 64 KiB batch-prefetching om in-process cgo te overtreffen bij queries met meerdere rijen.

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

Waarom nog een Go SQLite-driver?

SQLite is een van de meest ingezette softwarecomponenten ter wereld, maar het gebruik vanuit Go heeft technici historisch gezien gedwongen tot een oncomfortabele keuze tussen bouweenvoud en engine-getrouwheid.

Aan de ene kant staat github.com/mattn/go-sqlite3, de langdurige gemeenschapsstandaard. Deze omvat de officiële C SQLite-amalgamatie rechtstreeks via cgo. Men verkrijgt de echte C-queryplanner, volledige WAL-concurrency-semantiek en voorspelbaar C-geheugenbeheer. De prijs hiervan is CGO_ENABLED=1: lokale builds en CI-pipelines vertragen, minimale scratch- of distroless-container-afbeeldingen vereisen overeenkomstige C-runtime-bibliotheken, cross-compilen naar een ander besturingssysteem of CPU-architectuur vereist een volledige C-cross-toolchain, en elke geheugenbeschadiging in C deelt de adresruimte van het Go-proces.

Aan de andere kant bevinden zich pure-Go SQLite-ports die zijn gegenereerd door de C-amalgamatie mechanisch te vertalen naar Go-broncode over een geëmuleerde C-runtime (libc). Deze herstellen CGO_ENABLED=0, wat builds triviaal maakt. Onder aanhoudende workloads verhogen de vertaalde C-heap en Go-allocaties per rij echter de garbage-collection-druk, en subtiele randgevallen in vergrendeling, busy timeouts of statement-onderbreking kunnen afwijken van native C-builds.

Wij hebben gosuda.org/sqlite3 gebouwd zodat Go-applicaties niet hoeft te kiezen tussen CGO_ENABLED=0 en de echte C SQLite-engine. Door de officiële SQLite 3.54.1 C-amalgamatie te compileren naar een toegewijde shared-memory-server (hqq-sqlite-server) en te communiceren via gosuda.org/sqlite3, compileert uw Go-binary met CGO_ENABLED=0 terwijl ongewijzigde, -O3-geoptimaliseerde C SQLite over een procesgrens wordt uitgevoerd.

Nul-configuratie-uitvoering: Van go get naar sql.Open

Het vervangen van github.com/mattn/go-sqlite3 in een bestaande Go-codebase vereist slechts het wijzigen van het blinde importpad. De driver registreert zich als "sqlite3" (en "hqq-sqlite" voor expliciete selectie) en accepteert dezelfde DSN-querystringent:

 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}

Ingesloten SLSA-geattesteerde werkprocesbinaries

Een natuurlijke vraag bij het vernemen dat een bibliotheek een C-werkproces gebruikt is: "Moet ik een afzonderlijke C-binary installeren of meeleveren naast mijn Go-programma?"

Nee. gosuda.org/sqlite3 sluit voorgebouwde hqq-sqlite-server-binaries in voor alle zes de belangrijkste doelen direct binnen platform-getagde Go-bestanden (internal/embedded/embed_<goos>_<goarch>.go). Omdat de bouwbeperkingen van Go alleen het bestand compileren dat overeenkomt met uw doeltekenreeks GOOS en GOARCH, sluit cross-compiling met GOOS=linux GOARCH=arm64 go build automatisch alleen de ~1,4 MiB grote linux/arm64-serverbinary in.

Wanneer sql.Open zijn eerste verbinding tot stand brengt, materialiseert autolaunch.go de ingesloten binary in de cachemap van de gebruiker ($XDG_CACHE_HOME/hqq/bin/<sha256>/), verifieert diens cryptografische SHA-256-samenvatting tegen de vastgelegde ReleaseHashes-map in hashes.go via gosuda.org/hqq/secureexec, en start het werkproces met --parent-stdin zodat de levensduur strikt gebonden is aan uw Go-proces.

Clean-Room mattn/go-sqlite3 DSN-compatibiliteit

Om te fungeren als een ware directe vervanging, implementeert de DSN-parser (dsn.go) een clean-room-replica van de verbindings- en pragma-knoppen die worden gebruikt in mattn/go-sqlite3-codebases:

Procesisolatie omzetten in een doorvoercapaciteitsvoordeel

Op het eerste gezicht klinkt het uitvoeren van SQLite in een afzonderlijk proces alsof het trager moet zijn dan het in-process aanroepen van sqlite3_step via cgo. In de praktijk gebeurt het tegenovergestelde zodra een query meer dan één rij retourneert.

De verborgen kosten van cgo-aanroepen per rij

In een conventionele cgo SQLite-driver stuurt database/sql de iteratie één rij en één kolom tegelijk aan. Het lezen van 1.000 rijen met 4 kolommen activeert:

• 1.000 cgo-aanroepen naar sqlite3_step
• 4.000 cgo-aanroepen naar sqlite3_column_type en sqlite3_column_int64 / sqlite3_column_text
• Duizenden individuele grensoverschrijdingen tussen de Go-scheduler en de C-stack

Request Pipelining en 64 KiB Batch Prefetching

gosuda.org/sqlite3 elimineert grensoverschrijdingen per rij door het transmissieprotocol opnieuw te ontwerpen rondom twee mechanismen in stmt.go, rows.go en sqlite3/server/sqlite3_hooks.c:

 1Go-client (stmt.go / rows.go)                       C11-werkproces (sqlite3_hooks.c)
 2-----------------------------                       --------------------------------
 31. Pipeline in 1 vlucht:
 4   ResetAsync + BindValuesAsync
 5   + StmtInfoAsync + FetchRowsAsync(128)  =======>  reset -> bind -> stmt_info ->
 6                                                    lus sqlite3_step() tot 128 rijen
 7                                          <=======  Batch 1 (rijen 1..128 verpakt in 64 KiB slot)
 82. Direct prefetch activeren:
 9   FetchRowsAsync(128) (Batch 2)          =======>  lus sqlite3_step() voor rijen 129..256
10   Terwijl C Batch 2 doorloopt, scant de
11   Go-aanroeper rijen 1..128 uit Batch 1! <=======  Batch 2 gereed in shared memory

1. Query-pipelining in één vlucht (stmt.go): Wanneer QueryContext of Stmt.QueryContext een alleen-lezen-statement uitvoert, dient s.query() reset, bind_values, stmt_info (bij de eerste uitvoering) en fetch_rows asynchroon in in één enkele gedeelde-geheugenvlucht. Alle vier de bewerkingen worden direct achter elkaar uitgevoerd op het C-werkproces en keren terug in één ronde.
2. Compacte C-batchlussen en asynchrone prefetch (rows.go): Binnen fetch_rows (sqlite3_hooks.c) doorloopt het C-werkproces sqlite3_step(stmt) in een native C-lus, waarbij maximaal FetchSize-rijen (standaard 128) rechtstreeks worden gecodeerd in het 64 KiB grote shared-memory-antwoord-slot totdat de batchlimiet is bereikt, het slot vol is, of SQLITE_DONE optreedt. Zodra rows.ingest() Batch 1 decodeert, activeert het FetchRowsAsync voor Batch 2 alvorens de eerste rij aan de aanroeper te retourneren. Terwijl uw Go-code Batch 1 scant, doorloopt het C-werkproces al Batch 2 op een andere CPU-kern.

Op Apple M4 (darwin/arm64) toont een vergelijking van gosuda.org/sqlite3 (CGO_ENABLED=0) tegenover github.com/mattn/go-sqlite3 (CGO_ENABLED=1) op dezelfde SQLite-database het effect van batching en pipelining:

Annulering, pad-sandboxing en herstel van verbindingspools

Het uitvoeren van SQLite in een geïsoleerd werkproces versterkt tevens de wijze waarop de driver omgaat met timeouts, niet-vertrouwde SQL en bestandsysteemgrenzen:

• Deterministische contextannulering (conn.go en errors.go): Elke driveraanroep bewapent een lichtgewicht context.AfterFunc-beveiliging (cn.guard). Indien de context.Context van de aanroeper wordt geannuleerd of diens deadline verstrijkt terwijl een trage recursieve query of vergrendelingswachtrij wordt uitgevoerd op de server, markeert de beveiliging de verbinding als slecht, beëindigt de lokale sessielink en verzendt een out-of-band Cancel()-frame. Het C-werkproces roept direct sqlite3_interrupt(db) aan, waardoor sqlite3_step wordt gedeblokkeerd, terwijl de Go-driver de resulterende SQLITE_INTERRUPT-status toewijst aan context.Canceled of context.DeadlineExceeded en database/sql opdraagt de verbinding in de pool te vervangen.
• Map-sandboxing (sqlsrv_pathrules.c): Het C-werkproces handhaaft --allow-dir-padregels bij elke open_v2-aanroep, lost symbolische koppelingen op en weigert relatieve ..-traversal buiten de toegestane map. sqlite3_load_extension en SQLITE_LIMIT_ATTACHED zijn standaard uitgeschakeld zodat SQL-injectie niet kan ontsnappen aan de databasemap of willekeurige gedeelde objecten kan laden.

Repository-indeling

De repository is dusdanig gestructureerd dat het pakket op het hoogste niveau de direct bruikbare database/sql-driver levert, terwijl launcher/ en sqlite3/ toegankelijk blijven voor geavanceerde implementaties van aangepaste servers:

 1gosuda.org/sqlite3
 2├── driver.go / api.go         # database/sql-driverregistratie ("sqlite3") en Connector API
 3├── dsn.go                     # Clean-room mattn/go-sqlite3 DSN-parser en pragma-configuratie
 4├── conn.go / tx.go            # Sessielevenscyclus, contextbeveiliging en transactiestatusmachine
 5├── stmt.go / rows.go          # Request pipelining in één vlucht en 64 KiB batch-prefetching
 6├── errors.go                  # Getypeerde primaire/uitgebreide SQLite-foutcodes en sentinel-matching
 7├── autolaunch.go / hashes.go  # Nul-configuratie ingesloten servermaterialisatie en SHA-256-vastlegging
 8├── internal/embedded/         # Platform-getagde //go:embed-binaries (linux, darwin, windows)
 9├── launcher/                  # Configureerbare procesbeheerder voor implementaties van aangepaste servers
10└── sqlite3/                   # Gegenereerde hqq-bindgen Go-client en C11 SQLite-serverbroncode
11    └── server/                # C11-serverimplementatie (sqlite3_hooks.c, sqlsrv_policy.c)

Aan de slag

Installeer de module met go get en open uw database met sql.Open("sqlite3", dsn):

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

• GitHub-repository: https://github.com/gosuda/hqq-sqlite3
• DSN- & Pragma-referentie: docs/DSN.md
• Architectuur & transmissieprotocol: docs/ARCHITECTURE.md