add URI parameter support via optional URIOpener interface

[corylanou]

Motivation

Expose SQLite URI parameters to VFS implementations at open time.

I hit this while building Litestream as a SQLite loadable extension + VFS. When a user loads a VFS extension and opens a database with URI parameters, for example:

.load ./litestream
ATTACH 'file:app.db?vfs=litestream&poll_interval=5s' AS db;

The VFS needs those params during xOpen to initialize the connection. Environment variables are process-wide, PRAGMAs run after open, and SQLite URI parameters are the per-connection mechanism available during xOpen.

Relevant downstream issues: benbjohnson/litestream#1150 and benbjohnson/litestream#1231.

Changes

Adds an optional interface:

type URIOpener interface {
    OpenURI(name string, params map[string]string, flags OpenFlag) (File, OpenFlag, error)
}

When a registered VFS implements URIOpener, the cgo bridge reads the URI parameters from SQLite's filename pointer using sqlite3_uri_key() and sqlite3_uri_parameter(), then calls OpenURI. Existing VFS implementations continue to use Open unchanged.

defaultVFSv1 forwards OpenURI to wrapped VFS values that implement URIOpener, so callers can register a plain VFS that optionally implements the URI-aware method.

Tests

TestURIOpener registers a capturing VFS, opens file:test.db?vfs=...&poll_interval=5s&cache_size=128, and verifies that OpenURI receives the filename and URI parameter map.

Verified with:

go test -race ./...

[psanford]

I am fine with doing this conceptually, but this pr is a bit of a mess. It looks like you asked claude-code to implement this and threw a pr up with no real thought about it.

A reasonable interface would probably look more like:

type URIOpener interface {
    OpenURI(name string, params map[string]string, flags OpenFlags) (File, OpenFlag, error)
}

If you are going to use claude-code at least use a new session to critique the pr before you submit it.

[corylanou]

Thanks for the feedback. I reworked this around the narrower URIOpener interface shape you suggested, removed the Filename wrapper and the unrelated test-helper cleanup, and force-pushed the branch as a single focused commit. I also updated the PR description to match the current diff.\n\nVerified locally with go test -race ./...; the GitHub stable and oldstable checks are green now too.

[corylanou]

Hi @psanford just following up to get your thoughts on this last change? Thanks again for all your work on this repo!

[psanford]

Thanks for fixing this up!