gosuda.org/sqlite3: En Drop-In database/sql-driver, der kører indbygget C SQLite over delt hukommelse

gosuda.org/sqlite3 er en CGO_ENABLED=0 database/sql-driver til Go, som kører den opstrøms C SQLite 3.54.1-amalgamation inde i en isoleret arbejderproces over HQQ shared-memory-ringer. Den registrerer sig under standardnavnet "sqlite3", understøtter DSN-forespørgselsparametre fra github.com/mattn/go-sqlite3, indlejrer SLSA-attesterede forudbyggede serverbinærfiler til seks OS- og arkitekturmål, og anvender forespørgselspipelining med 64 KiB batch-prefetching for at præstere bedre end in-process cgo ved forespørgsler med flere rækker.

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

Hvorfor endnu en Go SQLite-driver?

SQLite er en af de mest udrullede softwarekomponenter i verden, men alligevel har brugen af den fra Go historisk set tvunget ingeniører ud i et ubehageligt valg mellem bygningssimplicitet og motortroskab.

På den ene side står github.com/mattn/go-sqlite3, den langvarige fællesskabsstandard. Den indkapsler den officielle C SQLite-amalgamation direkte via cgo. Man får den ægte C-forespørgselsplanlægger, fuld WAL-konkurrenssemantik og forudsigelig C-hukommelsesadministration. Prisen er CGO_ENABLED=1: lokale byggeri og CI-pipelines bliver langsommere, minimale scratch- eller distroless-containerbilleder kræver matchende C-runtime-biblioteker, krydskompilering til et andet OS eller CPU-arkitektur kræver en fuld C-krydskompileringsværktøjskæde, og enhver hukommelseskorruption i C deler Go-processens adresserum.

På den anden side findes pure-Go SQLite-porte genereret ved mekanisk at oversætte C-amalgamationen til Go-kildekode over en emuleret C-runtime (libc). De genskaber CGO_ENABLED=0, hvilket gør byggerier trivielle. Under vedvarende arbejdsbelastninger øger den oversatte C-heap og de rækkespecifikke Go-allokeringer dog garbage collection-trykket, og subtile grænsetilfælde i låsning, busy timeouts eller sætningsafbrydelser kan afvige fra oprindelige C-byggerier.

Vi har bygget gosuda.org/sqlite3, så Go-applikationer ikke behøver at vælge mellem CGO_ENABLED=0 og den ægte C SQLite-motor. Ved at kompilere den officielle SQLite 3.54.1 C-amalgamation til en dedikeret shared-memory-server (hqq-sqlite-server) og kommunikere over gosuda.org/hqq, kompilerer dit Go-binær med CGO_ENABLED=0, mens der eksekveres uændret, -O3-optimeret C SQLite på tværs af en procesgrænse.

Nul-konfigurations-eksekvering: Fra go get til sql.Open

Udskiftning af github.com/mattn/go-sqlite3 i en eksisterende Go-kildekodebase kræver kun ændring af den blinde importsti. Driveren registreres som "sqlite3" (og "hqq-sqlite" for eksplicit valg) og accepterer de samme DSN-forespørgselsstrenge:

 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}

Indlejrede SLSA-attesterede arbejderbinærfiler

Et naturligt spørgsmål, når man hører, at et bibliotek bruger en C-arbejderproces, er: "Skal jeg installere eller distribuere en separat C-binærfil sammen med mit Go-program?"

Nej. gosuda.org/sqlite3 indlejrer forudbyggede hqq-sqlite-server-binærfiler til alle seks vigtigste mål direkte inde i platform-taggede Go-filer (internal/embedded/embed_<goos>_<goarch>.go). Fordi Gos byggeforgreb kun kompilerer den fil, der matcher dit mål GOOS og GOARCH, indlejrer krydskompilering af GOOS=linux GOARCH=arm64 go build automatisk kun den ca. 1,4 MiB store linux/arm64-serverbinærfil.

Når sql.Open etablerer sin første forbindelse, materialiserer autolaunch.go den indlejrede binærfil i brugerens cacheniveau ($XDG_CACHE_HOME/hqq/bin/<sha256>/), verificerer dens kryptografiske SHA-256-digest mod ReleaseHashes-map'en i hashes.go via gosuda.org/hqq/secureexec, og starter arbejderen med --parent-stdin, så dens levetid er strengt bundet til din Go-proces.

Clean-Room mattn/go-sqlite3 DSN-kompatibilitet

For at fungere som en reel drop-in-erstatning implementerer DSN-parseren (dsn.go) en clean-room-replika af de forbindelses- og pragma-knapper, der bruges på tværs af mattn/go-sqlite3-kodebaser:

Omsætning af procesisolation til en gennemløbsfordel

Ved første øjekast lyder det som om, at kørsel af SQLite i en separat proces skal være langsommere end at kalde sqlite3_step in-process via cgo. I praksis sker det modsatte, så snart en forespørgsel returnerer mere end en enkelt række.

De skjulte omkostninger ved række-for-række cgo-kald

I en konventionel cgo SQLite-driver styrer database/sql iterationen én række og én kolonne ad gangen. Læsning af 1.000 rækker med 4 kolonner udløser:

• 1.000 cgo-kald til sqlite3_step
• 4.000 cgo-kald til sqlite3_column_type og sqlite3_column_int64 / sqlite3_column_text
• Tusindvis af individuelle grænsepassager mellem Go-planlæggeren og C-stakken

Forespørgselspipelining og 64 KiB batch-prefetching

gosuda.org/sqlite3 eliminerer rækkespecifikke grænsepassager ved at redesigne netværksprotokollen omkring to mekanismer i stmt.go, rows.go og sqlite3/server/sqlite3_hooks.c:

 1Go-klient (stmt.go / rows.go)                       C11-arbejder (sqlite3_hooks.c)
 2-----------------------------                       ----------------------------
 31. Pipeline i 1 omgang:
 4   ResetAsync + BindValuesAsync
 5   + StmtInfoAsync + FetchRowsAsync(128)  =======>  reset -> bind -> stmt_info ->
 6                                                    løkke i sqlite3_step() op til 128 rækker
 7                                          <=======  Batch 1 (rækker 1..128 pakket i 64 KiB-slot)
 82. Udløs prefetch med det samme:
 9   FetchRowsAsync(128) (Batch 2)          =======>  løkke i sqlite3_step() for rækker 129..256
10   Mens C udfører træk for Batch 2, scanner
11   Go-klienten rækker 1..128 fra Batch 1! <=======  Batch 2 klar i delt hukommelse

1. Enkelt-omgangs forespørgselspipelining (stmt.go): Når QueryContext eller Stmt.QueryContext kører en skrivebeskyttet sætning, sender s.query() reset, bind_values, stmt_info (ved første eksekvering) og fetch_rows asynkront i en enkelt delt-hukommelses-omgang. Alle fire operationer eksekveres ryg-mod-ryg på C-arbejderen og returnerer i én tur-retur.
2. Stramme C-batch-løkker og asynkronal prefetch (rows.go): Inden i fetch_rows (sqlite3_hooks.c) udfører C-arbejderen sqlite3_step(stmt) i en oprindelig C-løkke, hvor op til FetchSize rækker (standard 128) kodes direkte ind i 64 KiB shared-memory-svar-slotten, indtil batchgrænsen er nået, slotten er fuld, eller SQLITE_DONE forekommer. Så snart rows.ingest() afkoder Batch 1, udløser den FetchRowsAsync for Batch 2, før den første række returneres til kalderen. Mens din Go-kode scanner Batch 1, udfører C-arbejderen allerede Batch 2 på en anden CPU-kerne.

På Apple M4 (darwin/arm64) viser sammenligning af gosuda.org/sqlite3 (CGO_ENABLED=0) med github.com/mattn/go-sqlite3 (CGO_ENABLED=1) på den samme SQLite-database effekten af batching og pipelining:

Annullering, stisandboxing og gendannelse af forbindelsespulje

Kørsel af SQLite i en isoleret arbejder styrker også den måde, driveren håndterer timeouts, utiltalt SQL og filsystemgrænser på:

• Deterministisk kontekstannullering (conn.go og errors.go): Hvert driverkald aktiverer en letvægts context.AfterFunc-beskyttelse (cn.guard). Hvis kalderens context.Context annulleres, eller dens tidsfrist udløber, mens en langsom rekursiv forespørgsel eller låseventning kører på serveren, markerer beskyttelsen forbindelsen som dårlig, dræber det lokale sessionslink og sender en out-of-band Cancel()-ramme. C-arbejderen anmoder om sqlite3_interrupt(db) med det samme, hvilket ophæver blokeringen af sqlite3_step, mens Go-driveren mapper den resulterende SQLITE_INTERRUPT-status til context.Canceled eller context.DeadlineExceeded og instruerer database/sql til at udskifte forbindelsen i puljen.
• Mappesandboxing (sqlsrv_pathrules.c): C-arbejderen håndhæver --allow-dir-stiregler ved hvert open_v2-kald, opløser symbolske links og afviser relativ ..-gennemgang uden for den tilladte mappe. sqlite3_load_extension og SQLITE_LIMIT_ATTACHED er deaktiveret som standard, så SQL-injektion ikke kan undslippe databasemappen eller indlæse vilkårlige delte objekter.

Repositoriestruktur

Repositoriet er struktureret således, at top-level-pakken leverer drop-in database/sql-driveren, mens launcher/ og sqlite3/ forbliver tilgængelige for avancerede tilpassede serverudrulninger:

 1gosuda.org/sqlite3
 2├── driver.go / api.go         # database/sql-driverregistrering ("sqlite3") og Connector API
 3├── dsn.go                     # Clean-room mattn/go-sqlite3 DSN-parser og pragma-konfiguration
 4├── conn.go / tx.go            # Sessionslivscyklus, kontekstbeskyttelse og transaktions-tilstandsmaskine
 5├── stmt.go / rows.go          # Enkelt-omgangs forespørgselspipelining og 64 KiB batch-prefetching
 6├── errors.go                  # Typede SQLite primære/udvidede fejlkoder og sentinel-matchning
 7├── autolaunch.go / hashes.go  # Nul-konfigurations indlejret servermaterialisering og SHA-256-fastlåsning
 8├── internal/embedded/         # Platform-taggede //go:embed binærfiler (linux, darwin, windows)
 9├── launcher/                  # Konfigurerbar processupervisor til tilpassede serverudrulninger
10└── sqlite3/                   # Genereret hqq-bindgen Go-klient og C11 SQLite-serverkilde
11    └── server/                # C11-serverimplementering (sqlite3_hooks.c, sqlsrv_policy.c)

Kom i gang

Installer modulet med go get og åbn din database med sql.Open("sqlite3", dsn):

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

• GitHub-repositorie: https://github.com/gosuda/hqq-sqlite3
• DSN- & Pragma-reference: docs/DSN.md
• Arkitektur & Netværksprotokol: docs/ARCHITECTURE.md