Go SQLite VFS API
This package implements the SQLite OS Interface (aka VFS).
It replaces the default SQLite VFS with a pure Go implementation.
It also exposes interfaces that should allow you to implement your own custom VFSes.
Since it is a from scratch reimplementation, there are naturally some ways it deviates from the original.
The main differences are file locking and WAL mode support.
File Locking
POSIX advisory locks, which SQLite uses on Unix, are broken by design.
On Linux and macOS, this module uses OFD locks to synchronize access to database files. OFD locks are fully compatible with POSIX advisory locks.
On BSD Unixes, this module uses
BSD locks.
On BSD, macOS, and illumos, these locks are fully compatible with POSIX advisory locks;
on Linux and z/OS, they are fully functional, but incompatible with POSIX advisory locks.
However, concurrency is always reduced with BSD locks
(BEGIN IMMEDIATE behaves the same as BEGIN EXCLUSIVE).
You can opt into BSD locks with the sqlite3_flock build tag.
On Windows, this module uses LockFileEx and UnlockFileEx,
like SQLite.
On all other platforms, file locking is not supported, and you must use
nolock=1
(or immutable=1)
to open database files.
To use the database/sql driver
with nolock=1 you must disable connection pooling by calling
db.SetMaxOpenConns(1).
You can use vfs.SupportsFileLocking
to check if your build supports file locking.
Write-Ahead Logging
On 64-bit Linux and macOS, this module uses mmap to implement
shared-memory for the WAL-index,
like SQLite.
To allow mmap to work, each connection needs to reserve up to 4GB of address space.
To limit the amount of address space each connection needs,
use WithMemoryLimitPages.
On Windows, and with BSD locks, WAL support is
limited.
EXCLUSIVE locking mode can be set to create, read, and write WAL databases.
To use EXCLUSIVE locking mode with the
database/sql driver
you must disable connection pooling by calling
db.SetMaxOpenConns(1).
On all other platforms, where file locking is not supported, WAL mode is disabled.
You can use vfs.SupportsSharedMemory
to check if your build supports shared memory.
Batch-Atomic Write
On 64-bit Linux, this module supports batch-atomic writes with the F2FS filesystem.
Build Tags
The VFS can be customized with a few build tags:
sqlite3_flockforces the use of BSD locks; it can be used on z/OS for locking support, and elsewhere to test the BSD locks.sqlite3_nosysprevents importingx/sys; disables locking and shared memory on all platforms.sqlite3_noshmdisables shared memory on all platforms.
Caution
If file locking is incompatible with POSIX advisory locks, accessing databases concurrently with this package and other SQLite implementations is unsafe, and will eventually corrupt data. This will only be the case if you explicitly opt into BSD locks with
sqlite3_flock. The SQLiteunix-flockVFS is always compatible withsqlite3_flock.