gosuda.org/sqlite3: CGO_ENABLED=0 database/sql Driver nad IPC so zdieľanou pamäťou

gosuda.org/sqlite3 je ovládač database/sql pre Go s CGO_ENABLED=0, ktorý spúšťa upstream C SQLite 3.54.1 amalgamáciu v izolovanom pracovnom procese cez zdieľané pamäťové kruhové buffery HQQ. Registruje sa pod štandardným názvom ovládača "sqlite3", podporuje parametre DSN dotazu z github.com/mattn/go-sqlite3, obsahuje vopred zostavené serverové binárky s SLSA atestáciou pre šesť cieľových operačných systémov a architektúr a využíva pipelining požiadaviek a predbežné načítavanie dávok po 64 KiB, vďaka čomu prekonáva in-process cgo pri dotazoch vracajúcich viacero riadkov.

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

Prečo ďalší ovládač SQLite pre Go?

SQLite patrí medzi najrozšírenejšie softvérové komponenty na svete, no jeho používanie v Go historicky nútilo vývojárov k nepríjemnej voľbe medzi jednoduchosťou zostavenia a vernosťou k engine.

Na jednej strane stojí github.com/mattn/go-sqlite3, dlhoročný komunitný štandard. Priamo obaľuje oficiálnu C amalgamáciu SQLite cez cgo. Získate skutočný C plánovač dotazov, plnú sémantiku súbežnosti WAL a predvídateľnú správu pamäte v C. Cenou je CGO_ENABLED=1: lokálne zostavenia a CI pipeline sa spomaľujú, minimálne scratch alebo distroless kontajnerové obrazy vyžadujú zodpovedajúce C runtime knižnice, krížová kompilácia pre iný operačný systém alebo architektúru procesora vyžaduje úplný C krížový toolchain a akákoľvek poškodená pamäť v C zdieľa adresný priestor procesu Go.

Na druhej strane sú čisto Go porty SQLite, generované mechanickým prekladom C amalgamácie do zdrojového kódu Go nad emulovaným C runtime (libc). Obnovujú CGO_ENABLED=0, čo robí zostavenie triviálnym. Pri dlhotrvajúcej záťaži však preložená C halda a alokácie Go pre jednotlivé riadky zvyšujú tlak na garbage collector a jemné hraničné prípady v zamykaní, časoch čakania (busy timeout) alebo prerušení príkazov sa môžu odchyľovať od natívnych C zostavení.

Vytvorili sme gosuda.org/sqlite3, aby aplikácie v Go nemuseli voliť medzi CGO_ENABLED=0 a skutočným C enginom SQLite. Skompilovaním oficiálnej C amalgamácie SQLite 3.54.1 do špecializovaného serveru so zdieľanou pamäťou (hqq-sqlite-server) a komunikáciou cez gosuda.org/hqq sa vaša binárka v Go zostavuje s CGO_ENABLED=0 a zároveň vykonáva nezmenenú, -O3 optimalizovanú C SQLite naprieč hranicou procesu.

Konfigurácia nulovej záťaže: Od go get po sql.Open

Nahradenie github.com/mattn/go-sqlite3 v existujúcom kóde v Go vyžaduje zmenu iba cesty anonymného importu. Ovládač sa registruje ako "sqlite3" (a "hqq-sqlite" pre explicitný výber) a akceptuje rovnaké reťazce 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}

Vložené serverové binárky s SLSA atestáciou

Prirodzenou otázkou, keď sa dozviete, že knižnica používa pracovný proces v C, je: „Musím so svojím programom v Go inštalovať alebo distribuovať samostatnú C binárku?“

Nie. gosuda.org/sqlite3 vkladá vopred zostavené binárky hqq-sqlite-server pre všetkých šesť hlavných cieľov priamo do Go súborov označených podľa platformy (internal/embedded/embed_<goos>_<goarch>.go). Keďže obmedzenia zostavenia v Go kompilujú iba súbor zodpovedajúci vášmu cieľovému GOOS a GOARCH, krížová kompilácia príkazom GOOS=linux GOARCH=arm64 go build automaticky vloží iba binárku servera linux/arm64 s veľkosťou približne 1,4 MiB.

Keď sql.Open nadviaže svoje prvé spojenie, autolaunch.go materializuje vloženú binárku do používateľského adresára vyrovnávacej pamäte ($XDG_CACHE_HOME/hqq/bin/<sha256>/), overí jej kryptografický digest SHA-256 voči pevne určenej mape ReleaseHashes v hashes.go pomocou gosuda.org/hqq/secureexec a spustí pracovný proces s parametrom --parent-stdin, aby jeho životnosť bola prísne viazaná na váš proces Go.

Čistá reimplementácia DSN kompatibility s mattn/go-sqlite3

Aby fungoval ako skutočná náhrada bez úprav, analyzátor DSN (dsn.go) implementuje čistú reimplementáciu pripojení a nastavení pragma, ktoré sa používajú naprieč kódovými základňami mattn/go-sqlite3:

Premena izolácie procesov na výhodu priepustnosti

Na prvý pohľad sa môže zdať, že spustenie SQLite v samostatnom procese musí byť pomalšie ako volanie sqlite3_step v rámci procesu cez cgo. V praxi sa však deje opak hneď, ako dotaz vráti viac než jeden riadok.

Skrytá cena volaní cgo riadok po riadku

V bežnom ovládači SQLite cez cgo database/sql iteruje jeden riadok a jeden stĺpec naraz. Čítanie 1 000 riadkov so 4 stĺpcami spôsobí:

• 1 000 volaní cgo na sqlite3_step
• 4 000 volaní cgo na sqlite3_column_type a sqlite3_column_int64 / sqlite3_column_text
• tisíce jednotlivých prechodov hranicou medzi plánovačom Go a zásobníkom C

Pipelining požiadaviek a predbežné načítavanie dávok po 64 KiB

gosuda.org/sqlite3 odstraňuje prechody hranicou pre jednotlivé riadky tým, že ppretvára protokol komunikácie okolo dvoch mechanizmov v stmt.go, rows.go a 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 dotazu v jednom lete (stmt.go): Keď QueryContext alebo Stmt.QueryContext spustí príkaz len na čítanie, s.query() odošle reset, bind_values, stmt_info (pri prvom vykonaní) a fetch_rows asynchrónne v jedinom lete cez zdieľanú pamäť. Všetky štyri operácie sa vykonajú za sebou na pracovnom procese v C a vrátia sa v jednom obehu.
2. Tesné dávkové slučky v C a asynchrónne predbežné načítavanie (rows.go): Vnútri fetch_rows (sqlite3_hooks.c) pracovný proces v C volá sqlite3_step(stmt) v natívnej slučke C a kóduje až FetchSize riadkov (predvolene 128) priamo do odpovedného slotu zdieľanej pamäte o veľkosti 64 KiB, kým sa nedosiahne limit dávky, slot sa nezaplní alebo nenastane SQLITE_DONE. Hneď ako rows.ingest() dekóduje dávku 1, odošle FetchRowsAsync pre dávku 2 skôr, než vráti prvý riadok volajúcemu. Kým váš kód v Go prechádza dávku 1, pracovný proces v C už na inom jadre procesora spracúva dávku 2.

Na Apple M4 (darwin/arm64) ukazuje porovnanie gosuda.org/sqlite3 (CGO_ENABLED=0) s github.com/mattn/go-sqlite3 (CGO_ENABLED=1) nad tou istou databázou SQLite efekt dávkovania a pipeliningu:

Zrušenie, izolácia ciest a obnova poolu pripojení

Spustenie SQLite v izolovanom pracovnom procese tiež posilňuje spôsob, akým ovládač spracúva časové limity, nedôveryhodný SQL a hranice súborového systému:

• Deterministické zrušenie kontextu (conn.go a errors.go): Každé volanie ovládača aktivuje ľahkú stráž context.AfterFunc (cn.guard). Ak je context.Context volajúceho zrušený alebo jeho termín vyprší, kým na serveri beží pomalý rekurzívny dotaz alebo čakanie na zámok, stráž označí pripojenie ako chybné, ukončí lokálne prepojenie relácie a odošle mimopásmový rámec Cancel(). Pracovný proces v C okamžite zavolá sqlite3_interrupt(db), čím uvoľní sqlite3_step, zatiaľ čo ovládač v Go mapuje výsledný stav SQLITE_INTERRUPT na context.Canceled alebo context.DeadlineExceeded a pokyne database/sql, aby nahradil pripojenie v poole.
• Izolácia adresárov (sqlsrv_pathrules.c): Pracovný proces v C vynucuje pravidlá ciest --allow-dir pri každom volaní open_v2, rieši symbolické odkazy a odmieta relatívne prechody .. mimo povoleného adresára. sqlite3_load_extension a SQLITE_LIMIT_ATTACHED sú predvolene vypnuté, takže SQL injekcia nemôže uniknúť z adresára databázy ani načítať ľubovoľné zdieľané objekty.

Štruktúra repozitára

Repozitár je usporiadaný tak, že hlavný balík poskytuje ovládač database/sql pripravený na okamžité použitie, zatiaľ čo launcher/ a sqlite3/ zostávajú dostupné pre pokročilé nasadenia vlastných serverov:

 1gosuda.org/sqlite3
 2├── driver.go / api.go         # database/sql driver registration ("sqlite3") and Connector API
 3├── dsn.go                     # Clean-room mattn/go-sqlite3 DSN parser and pragma configuration
 4├── conn.go / tx.go            # Session lifecycle, context guard, and transaction state machine
 5├── stmt.go / rows.go          # Single-flight request pipelining and 64 KiB batch prefetching
 6├── errors.go                  # Typed SQLite primary/extended error codes and sentinel matching
 7├── autolaunch.go / hashes.go  # Zero-config embedded server materialization and SHA-256 pinning
 8├── internal/embedded/         # Platform-tagged //go:embed binaries (linux, darwin, windows)
 9├── launcher/                  # Configurable process supervisor for custom server deployments
10└── sqlite3/                   # Generated hqq-bindgen Go client and C11 SQLite server source
11    └── server/                # C11 server implementation (sqlite3_hooks.c, sqlsrv_policy.c)

Začíname

Nainštalujte modul pomocou go get a otvorte svoju databázu pomocou sql.Open("sqlite3", dsn):

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

• GitHub repozitár: https://github.com/gosuda/hqq-sqlite3
• Referencia DSN a pragma: docs/DSN.md
• Architektúra a protokol komunikácie: docs/ARCHITECTURE.md