From 1a223fa69fa4d95cada9ae03a465c3d7776d750a Mon Sep 17 00:00:00 2001 From: Nuno Cruces Date: Mon, 6 May 2024 00:41:56 +0100 Subject: [PATCH] Update README.md --- vfs/README.md | 56 ++++++++++++++++++++++++--------------------------- 1 file changed, 26 insertions(+), 30 deletions(-) diff --git a/vfs/README.md b/vfs/README.md index d9b1638..88059a4 100644 --- a/vfs/README.md +++ b/vfs/README.md @@ -2,15 +2,14 @@ This package implements the SQLite [OS Interface](https://sqlite.org/vfs.html) (aka VFS). -It replaces the default SQLite VFS with a **pure Go** implementation. - -It also exposes [interfaces](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs#VFS) +It replaces the default SQLite VFS with a **pure Go** implementation, +and exposes [interfaces](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs#VFS) 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](#file-locking) and [WAL mode](write-ahead-logging) support. +The main differences are [file locking](#file-locking) and [WAL mode](#write-ahead-logging) support. ### File Locking @@ -22,21 +21,22 @@ On Linux and macOS, this module uses to synchronize access to database files. OFD locks are fully compatible with POSIX advisory locks. -On BSD Unixes, this module uses -[BSD locks](https://man.freebsd.org/cgi/man.cgi?query=flock&sektion=2). -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. +This module can also use +[BSD locks](https://man.freebsd.org/cgi/man.cgi?query=flock&sektion=2), +albeit with reduced concurrency (`BEGIN IMMEDIATE` behaves like `BEGIN EXCLUSIVE`). +On BSD, macOS, and illumos, BSD locks are fully compatible with POSIX advisory locks; +on Linux and z/OS, they are fully functional, but incompatible; +elsewhere, they are very likely broken. +BSD locks are the default on BSD and illumos, +but you can opt into them 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 +Otherwise, file locking is not supported, and you must use [`nolock=1`](https://sqlite.org/uri.html#urinolock) (or [`immutable=1`](https://sqlite.org/uri.html#uriimmutable)) -to open database files.\ +to open database files. To use the [`database/sql`](https://pkg.go.dev/database/sql) driver with `nolock=1` you must disable connection pooling by calling [`db.SetMaxOpenConns(1)`](https://pkg.go.dev/database/sql#DB.SetMaxOpenConns). @@ -50,41 +50,37 @@ On 64-bit Linux and macOS, this module uses `mmap` to implement [shared-memory for the WAL-index](https://sqlite.org/wal.html#implementation_of_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, +To allow `mmap` to work, each connection needs to reserve up to 4GB of address space. +To limit the address space each connection reserves, use [`WithMemoryLimitPages`](../tests/testcfg/testcfg.go). -On Windows, and with BSD locks, [WAL](https://sqlite.org/wal.html) support is -[limited](https://sqlite.org/wal.html#noshm). -`EXCLUSIVE` locking mode can be set to create, read, and write WAL databases.\ +Otherwise, [WAL support is limited](https://sqlite.org/wal.html#noshm), +and `EXCLUSIVE` locking mode must be set to create, read, and write WAL databases. To use `EXCLUSIVE` locking mode with the [`database/sql`](https://pkg.go.dev/database/sql) driver you must disable connection pooling by calling [`db.SetMaxOpenConns(1)`](https://pkg.go.dev/database/sql#DB.SetMaxOpenConns). -On all other platforms, where file locking is not supported, WAL mode is disabled. - You can use [`vfs.SupportsSharedMemory`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs#SupportsSharedMemory) to check if your build supports shared memory. ### Batch-Atomic Write On 64-bit Linux, this module supports [batch-atomic writes](https://sqlite.org/cgi/src/technote/714) -with the F2FS filesystem. +on the F2FS filesystem. ### Build Tags The VFS can be customized with a few build tags: -- `sqlite3_flock` forces the use of BSD locks; it can be used on z/OS for locking support, - and elsewhere to test the BSD locks. +- `sqlite3_flock` forces the use of BSD locks; it can be used on z/OS to enable locking, + and elsewhere to test BSD locks. - `sqlite3_nosys` prevents importing [`x/sys`](https://pkg.go.dev/golang.org/x/sys); disables locking _and_ shared memory on all platforms. - `sqlite3_noshm` disables 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 SQLite [`unix-flock`](https://sqlite.org/compile.html#enable_locking_style) VFS -> is always compatible with `sqlite3_flock`. +> [!IMPORTANT] +> The default configuration of this package is compatible with +> the standard [Unix and Windows SQLite VFSes](https://sqlite.org/vfs.html#multiple_vfses); +> `sqlite3_flock` is compatible with the [`unix-flock` VFS](https://sqlite.org/compile.html#enable_locking_style). +> If incompatible file locking is used, accessing databases concurrently with _other_ SQLite libraries +> will eventually corrupt data.