feat(vfs): add FileControl support for PRAGMA handling

[corylanou]

Summary

• Add FileController interface for handling file control operations
• Implement SQLITE_FCNTL_PRAGMA support to enable custom PRAGMA commands
• Bridge C file control callbacks to Go implementations
• Add tests for PRAGMA set and query operations

Context

This change addresses the need for custom PRAGMA support in Go-based SQLite VFS implementations, as discussed in benbjohnson/litestream#849.

When implementing time travel queries for Litestream, @asg017 suggested using custom PRAGMAs (e.g., PRAGMA litestream_time = '[date]') instead of SQL functions. This approach is cleaner and more suitable for read-only environments like Datasette. However, implementing custom PRAGMAs requires FileControl support in the VFS layer, which was previously unavailable.

Changes

1. New FileController interface (file.go): Optional interface that File implementations can implement to handle file control operations, specifically SQLITE_FCNTL_PRAGMA.

2. C bridge update (sqlite3vfs.c): s3vfsFileControl now delegates to the Go implementation instead of returning SQLITE_NOTFOUND.

3. Go implementation (sqlite3vfscgo.go): goVFSFileControl handles PRAGMA operations by:

   • Extracting pragma name and optional value from SQLite's argument array
   • Calling the FileController interface if implemented by the file
   • Returning results back to SQLite

4. Tests (sqlite3vfs_test.go, tmpvfs_test.go): Verify PRAGMA set and query operations work correctly.

Usage

VFS implementers can now handle custom PRAGMAs by implementing the FileController interface:

func (f *MyFile) FileControl(op int, pragmaName string, pragmaValue *string) (*string, error) {
    if pragmaName == "my_custom_pragma" {
        if pragmaValue != nil {
            // Set operation: PRAGMA my_custom_pragma = 'value'
            return nil, f.setCustomValue(*pragmaValue)
        }
        // Query operation: PRAGMA my_custom_pragma
        result := f.getCustomValue()
        return &result, nil
    }
    return nil, nil // Unknown pragma, let SQLite handle it
}

---

Happy to adjust the approach or implementation if you have any preferred direction - just let us know!

[psanford]

Thanks for the pr! This seems like a reasonable improvement.

It looks like the tests are not passing right now though.

[corylanou]

@psanford whooops! Missed that somehow. Should be fixed. Let me know if you need anything else.

[psanford]

I cleaned up the git history and merged it. Thank you for the PR!