Skip to content

Latest commit

 

History

History
45 lines (34 loc) · 2.28 KB

README.md

File metadata and controls

45 lines (34 loc) · 2.28 KB

sqlite3vfsshim

Go APIs for SQLite VFSes, as two independent Go modules (use both together via the go.work workspace at the repository root):

https://www.sqlite.org/vfs.html

Module Import path What it is
pkg/vfs github.com/sqlited-org/sqlite3vfsshim/pkg/vfs Implement a complete, standard VFS in Go (like psanford/sqlite3vfs). No parent VFS.
pkg/vfsshim github.com/sqlited-org/sqlite3vfsshim/pkg/vfsshim Write a VFS shim that stacks on an existing VFS (unix, another shim, ...) and hooks only the calls you need (observe/veto); the parent is called from C, so WAL works unchanged.
pkg/vfscore github.com/sqlited-org/sqlite3vfsshim/pkg/vfscore Pure-Go types shared by both libraries (errors, flags, File, helpers). Import it for vfscore.OpenFlag, vfscore.File, etc.
examples github.com/sqlited-org/sqlite3vfsshim/examples Runnable examples (own module, depends on both).

Both are cgo libraries with no dependency on each other (the shared flag/error types and URI live in pkg/vfscore), both work with mattn/go-sqlite3, and both can be built as SQLite loadable extensions (-tags SQLITE3VFS_LOADABLE_EXT / SQLITE3VFSSHIM_LOADABLE_EXT, see each README).

Which one?

  • Storing the database somewhere else (memory, object store, encrypted blob...): vfs.
  • Observing, modifying or failing operations of a normal file-based database (tracing, fault injection, encryption of pages, clock override...): vfsshim.

Examples

Example Library Shows
memvfs vfs in-memory database
memvfs-ext vfs the same as a loadable extension
trace vfsshim logging every file operation
traceshim-ext vfsshim the trace shim as a loadable extension

Development

go test ./pkg/vfscore ./pkg/vfs ./pkg/vfsshim   # from the repository root (workspace mode)
go run ./examples/memvfs

The loadable-extension tests build the example extensions and load them into the sqlite3 CLI (skipped when the CLI is not installed).