feat(vfs): thread-safe config registry for per-database VFS configuration

[corylanou]

Description

Add a thread-safe Go config registry for the VFS extension, eliminating the need for setenv() which is not thread-safe on Linux. Library users who don't know VFS config values at process startup can now safely configure each database connection at runtime via the registry API without calling os.Setenv.

Key changes:

• Config registry (vfs_config.go): SetVFSConfig/GetVFSConfig/DeleteVFSConfig keyed by database name, protected by sync.RWMutex with defensive copies on set/get to prevent concurrent mutation
• Per-connection clients: openMainDB() checks registry and creates a per-connection ReplicaClient when config specifies replica_url; cleaned up on VFSFile.Close() and on Open() failure
• Optional env vars: LitestreamVFSRegister() no longer requires LITESTREAM_REPLICA_URL, enabling per-database config via registry
• C export: GoLitestreamConfigure() for Python/C callers to set per-database config before opening VFS connections
• Nil client guard: openMainDB() returns a clear error if no replica client is available from either the VFS default or per-database config

Motivation and Context

setenv() is not thread-safe on Linux. Library users who don't know VFS config values at process startup cannot safely call os.Setenv later. The current VFS extension requires all config via env vars set before registration. URI query parameters are not viable without upstream changes to psanford/sqlite3vfs (follow-up issue).

Fixes #1150

How Has This Been Tested?

• go test -tags vfs -race — 7 new tests pass with race detector:
  • TestVFSConfig_SetGet — basic set/get/delete
  • TestVFSConfig_ConcurrentAccess — 100 goroutines, race detector
  • TestVFSConfig_OverridesDefaults — config values override VFS defaults
  • TestVFSConfig_NilOptionalFields — nil field handling
  • TestVFSConfig_CopyOnSetAndGet — defensive copies prevent shared mutation
  • TestVFSConfig_PerConnectionOverrides — per-db config applied in openMainDB()
  • TestVFS_NilClientReturnsError — clear error when no client configured
• go build -tags "SQLITE3VFS_LOADABLE_EXT vfs" ./cmd/litestream-vfs — loadable extension builds
• All existing VFS tests continue to pass (only pre-existing TestVFSFile_PendingIndexRace race on main)

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist

• My code follows the code style of this project (go fmt, go vet)
• I have tested my changes (go test ./...)
• I have updated the documentation accordingly (if needed)

[benbjohnson]

I'm okay with setting parameters in the URL but I think the PRAGMA part is overkill. These should all be set at initialization time and PRAGMAs can be used anytime.

[github-actions]

PR Build Metrics

✅ All clear — no issues detected

Check	Status	Summary
Binary size	✅	35.90 MB (0.0 KB / 0.00%)
Dependencies	✅	No changes
Vulnerabilities	✅	None detected
Go toolchain	✅	1.25.8 (latest)
Module graph	✅	1204 edges (0)

Binary Size

	Size	Change
Base (bd2c6e6)	35.90 MB
PR (85f55ab)	35.90 MB	0.0 KB (0.00%)

Dependency Changes

No dependency changes.

govulncheck Output

No vulnerabilities found.

Build Info

Metric	Value
Build time	42s
Go version	go1.25.8
Commit	85f55ab

History (1 previous)

Commit	Updated	Status	Summary
e9ad8b7	2026-03-11 01:02 UTC	✅	35.82 MB (0.0 KB / 0.00%)

---

_{🤖 Updated on each push.}