3.4 KiB
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, macOS and illumos, 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 Unixes, BSD locks are fully compatible with POSIX advisory locks.
However, concurrency is reduced with BSD locks
(BEGIN IMMEDIATE behaves the same as BEGIN EXCLUSIVE).
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 platform supports file locking.
Write-Ahead Logging
On 64-bit Linux, macOS and illumos, 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 all other platforms, WAL support is limited.
To work around this limitation, SQLite is patched
to automatically use EXCLUSIVE locking mode for WAL databases on such platforms.
To use the database/sql driver
with EXCLUSIVE locking mode you should disable connection pooling by calling
db.SetMaxOpenConns(1).
You can use vfs.SupportsSharedMemory
to check if your platform supports shared memory.
Batch-Atomic Write
On 64-bit Linux, this module supports batch-atomic writes on 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 macOS to test the BSD locking implementation.sqlite3_nosysprevents importingx/sys; disables locking and shared memory on all platforms.sqlite3_noshmdisables shared memory on all platforms.