gosuda.org/sqlite3: En Drop-In database/sql-drivrutin som kör inhemsk C-SQLite över delat minne

gosuda.org/sqlite3 är en CGO_ENABLED=0 database/sql-drivrutin för Go som kör den uppströms C SQLite 3.54.1-amalgameringen inuti en isolerad arbetarprocess över HQQ delade minnesringar. Den registreras under standardnamnet "sqlite3", stöder DSN-frågeparametrar för github.com/mattn/go-sqlite3, inbäddar SLSA-attesterade förbyggda serverbinärer för sex operativsystem- och arkitekturmål, och använder anropspipelining med 64 KiB batchförhämtning för att överträffa processintern cgo vid frågor med flera rader.

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

Varför ännu en Go SQLite-drivrutin?

SQLite är en av de mest distribuerade mjukvarukomponenterna i världen, men att använda den från Go har historiskt sett tvingat ingenjörer till ett obekvämt val mellan byggenkelhet och motortrogenhet.

På ena sidan står github.com/mattn/go-sqlite3, den långvariga gemenskapsstandarden. Den omsluter den officiella C SQLite-amalgameringen direkt via cgo. Du får den verkliga C-frågeplaneraren, fullständiga WAL-konkurrenssemantiker och förutsägbar C-minneshantering. Kostnaden är CGO_ENABLED=1: lokala byggen och CI-pipelines saktar ner, minimala scratch- eller distrolösa behållaravbilder kräver matchande C-runtime-bibliotek, korskompilering till ett annat operativsystem eller CPU-arkitektur kräver en fullständig C-korsverktygskedja, och eventuell minneskorruption i C delar Go-processens adressrymd.

På andra sidan finns rena Go-SQLite-portar som genereras genom att mekaniskt översätta C-amalgameringen till Go-källkod över en emulerad C-runtime (libc). De återställer CGO_ENABLED=0, vilket gör byggen triviala. Under ihållande arbetsbelastningar ökar dock den översatta C-högen och radvisa Go-allokeringar skräpsamlingstrycket, och subtila gränsfall vid låsning, upptagen-tidsgränser (busy timeouts) eller avbrott av satser kan divergera från inhemska C-byggen.

Vi byggde gosuda.org/sqlite3 för att Go-applikationer inte ska behöva välja mellan CGO_ENABLED=0 och den verkliga C SQLite-motorn. Genom att kompilera den officiella SQLite 3.54.1 C-amalgameringen till en dedikerad server för delat minne (hqq-sqlite-server) och kommunicera över gosuda.org/hqq, kompileras ditt Go-binär med CGO_ENABLED=0 samtidigt som omodifierad, -O3-optimerad C SQLite exekveras över en processgräns.

Nollkonfigurationsutförande: Från go get till sql.Open

Att ersätta github.com/mattn/go-sqlite3 i en befintlig Go-kodbas kräver att endast den blanka importvägen ändras. Drivrutinen registreras som "sqlite3" (och "hqq-sqlite" för explicit val) och accepterar samma DSN-frågesträngar:

 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}

Inbäddade SLSA-attesterade arbetarbinärer

En naturlig fråga när man hör att ett bibliotek använder en C-arbetarprocess är: "Måste jag installera eller skicka med en separat C-binär vid sidan av mitt Go-program?"

Nej. gosuda.org/sqlite3 inbäddar förbyggda hqq-sqlite-server-binärer för alla sex stora mål direkt inuti plattformstaggade Go-filer (internal/embedded/embed_<goos>_<goarch>.go). Eftersom Gos byggnadsvillkor enbart komilerar den fil som matchar ditt mål GOOS och GOARCH, inbäddar korskompilering av GOOS=linux GOARCH=arm64 go build automatiskt endast den ~1,4 MiB stora linux/arm64-serverbinären.

När sql.Open etablerar sin första anslutning materialiserar autolaunch.go den inbäddade binären till användarens cachekatalog ($XDG_CACHE_HOME/hqq/bin/<sha256>/), verifierar dess kryptografiska SHA-256-sammanfattning mot den fastlåsta ReleaseHashes-kartan i hashes.go via gosuda.org/hqq/secureexec, och startar arbetaren med --parent-stdin så att dess livslängd är strikt bunden till din Go-process.

Clean-Room mattn/go-sqlite3 DSN-kompatibilitet

För att fungera som en äkta direktersättning implementerar DSN-tolken (dsn.go) en clean-room-replika av de anslutnings- och pragma-reglage som används över mattn/go-sqlite3-kodbaser:

Att förvandla processisolering till en genomströmningsfördel

Vid en första anblick kan det låta som att köra SQLite i en separat process måste vara långsammare än att anropa sqlite3_step internt via cgo. I praktiken inträffar det motsatta så snart en fråga returnerar mer än en enda rad.

Den dolda kostnaden för radvisa cgo-anrop

I en konventionell cgo SQLite-drivrutin driver database/sql iterationen en rad och en kolumn i taget. Att läsa 1 000 rader med 4 kolumner utlöser:

• 1 000 cgo-anrop till sqlite3_step
• 4 000 cgo-anrop till sqlite3_column_type och sqlite3_column_int64 / sqlite3_column_text
• Tusentals individuella gränsövergångar mellan Go-schemaläggaren och C-stacken

Begäranpipelining och 64 KiB batchförhämtning

gosuda.org/sqlite3 eliminerar radvisa gränsövergångar genom att omforma nätverksprotokollet kring två mekanismer i stmt.go, rows.go och sqlite3/server/sqlite3_hooks.c:

 1Go-klient (stmt.go / rows.go)                       C11-arbetare (sqlite3_hooks.c)
 2-----------------------------                       ----------------------------
 31. Pipelina i 1 skick:
 4   ResetAsync + BindValuesAsync
 5   + StmtInfoAsync + FetchRowsAsync(128)  =======>  återställ -> bind -> stmt_info ->
 6                                                    loopa sqlite3_step() upp till 128 rader
 7                                          <=======  Batch 1 (rader 1..128 packade i 64 KiB-fack)
 82. Avfyra förhämtning omedelbart:
 9   FetchRowsAsync(128) (Batch 2)          =======>  loopa sqlite3_step() för rader 129..256
10   Medan C utför steg för Batch 2,
11   läser Go-anroparen av rader 1..128
12   från Batch 1!                          <=======  Batch 2 klar i delat minne

1. Enkelsänd frågepipelining (stmt.go): När QueryContext eller Stmt.QueryContext kör en skrivskyddad sats, skickar s.query() asynkront reset, bind_values, stmt_info (vid första exekveringen) och fetch_rows i en enda gemensam minnessändning. Alla fyra operationer exekveras i direkt anslutning till varandra på C-arbetaren och returneras i en enda anropsrunda.
2. Korta C-batchloopar och asynkron förhämtning (rows.go): Inne i fetch_rows (sqlite3_hooks.c) kör C-arbetaren sqlite3_step(stmt) i en inhemsk C-loop, vilket kodar upp till FetchSize rader (standard 128) direkt i svarsfacket för det delade minnet på 64 KiB tills batchgränsen nås, facket är fullt eller SQLITE_DONE inträffar. Så snart rows.ingest() avkodar Batch 1, avfyrar den FetchRowsAsync för Batch 2 innan den första raden returneras till anroparen. Medan din Go-kod skannar Batch 1, kör C-arbetaren redan steg för Batch 2 på en annan CPU-kärna.

På Apple M4 (darwin/arm64), visar en jämförelse av gosuda.org/sqlite3 (CGO_ENABLED=0) mot github.com/mattn/go-sqlite3 (CGO_ENABLED=1) på samma SQLite-databas effekten av batchning och pipelining:

Avbokning, sökvägssandlådor och återställning av anslutningspool

Att köra SQLite i en isolerad arbetare stärker också hur drivrutinen hanterar tidsgränser, otillförlitlig SQL och filsystemsgränser:

• Deterministisk kontextavbokning (conn.go och errors.go): Varje drivrutinsanrop aktiverar ett lättvikts context.AfterFunc-skydd (cn.guard). Om anroparens context.Context avbryts eller dess tidsfrist löper ut medan en långsam rekursiv fråga eller låsväntan körs på servern, markerar skyddet anslutningen som dålig, avbryter den lokala sessionslänken och skickar en utomsegments Cancel()-ram. C-arbetaren anropar sqlite3_interrupt(db) omedelbart, vilket avblockerar sqlite3_step, medan Go-drivrutinen mappar den resulterande SQLITE_INTERRUPT-statusen till context.Canceled eller context.DeadlineExceeded och instruerar database/sql att ersätta anslutningen i poolen.
• Katalogsandlådor (sqlsrv_pathrules.c): C-arbetaren upprätthåller --allow-dir-sökvägsregler för varje open_v2-anrop, löser symboliska länkar och avvisar relativ ..-traversering utanför den tillåtna katalogen. sqlite3_load_extension och SQLITE_LIMIT_ATTACHED är inaktiverade som standard så att SQL-injektion inte kan lämna databaskatalogen eller läsa in godtyckliga delade objekt.

Repositoriestruktur

Repositoriet är strukturerat så att paketet på toppnivå tillhandahåller den direkt inbyggbara database/sql-drivrutinen medan launcher/ och sqlite3/ förblir tillgängliga för avancerade anpassade serverdistributioner:

 1gosuda.org/sqlite3
 2├── driver.go / api.go         # database/sql-drivrutinsregistrering ("sqlite3") och Connector-API
 3├── dsn.go                     # Clean-room mattn/go-sqlite3 DSN-tolk och pragma-konfiguration
 4├── conn.go / tx.go            # Sessionslivscykel, kontextskydd och transaktionstillståndsmaskin
 5├── stmt.go / rows.go          # Enkelsänd frågepipelining och 64 KiB batchförhämtning
 6├── errors.go                  # Typade primära/utökade SQLite-felkoder och sentinel-matchning
 7├── autolaunch.go / hashes.go  # Nollkonfigurationsinbäddad servermaterialisering och SHA-256-fastlåsning
 8├── internal/embedded/         # Plattformstaggade //go:embed-binärer (linux, darwin, windows)
 9├── launcher/                  # Konfigurerbar processövervakare för anpassade serverdistributioner
10└── sqlite3/                   # Genererad hqq-bindgen Go-klient och C11 SQLite-serverkällkod
11    └── server/                # C11-serverimplementering (sqlite3_hooks.c, sqlsrv_policy.c)

Komma igång

Installera modulen med go get och öppna din databas med sql.Open("sqlite3", dsn):

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

• GitHub-repositorium: https://github.com/gosuda/hqq-sqlite3
• DSN- & Pragma-referens: docs/DSN.md
• Arkitektur & Nätverksprotokoll: docs/ARCHITECTURE.md