diff options
Diffstat (limited to 'vendor/github.com/ncruces/go-sqlite3/vfs/README.md')
| -rw-r--r-- | vendor/github.com/ncruces/go-sqlite3/vfs/README.md | 38 |
1 files changed, 21 insertions, 17 deletions
diff --git a/vendor/github.com/ncruces/go-sqlite3/vfs/README.md b/vendor/github.com/ncruces/go-sqlite3/vfs/README.md index 77991486b..cf0e3c30f 100644 --- a/vendor/github.com/ncruces/go-sqlite3/vfs/README.md +++ b/vendor/github.com/ncruces/go-sqlite3/vfs/README.md @@ -15,24 +15,23 @@ The main differences are [file locking](#file-locking) and [WAL mode](#write-ahe POSIX advisory locks, which SQLite uses on Unix, are [broken by design](https://github.com/sqlite/sqlite/blob/b74eb0/src/os_unix.c#L1073-L1161). - -On Linux and macOS, this package uses +Instead, on Linux and macOS, this package uses [OFD locks](https://www.gnu.org/software/libc/manual/html_node/Open-File-Description-Locks.html) to synchronize access to database files. -OFD locks are fully compatible with POSIX advisory locks. This package 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 package uses `LockFileEx` and `UnlockFileEx`, like SQLite. +You can also opt into a cross-platform locking implementation +with the `sqlite3_dotlk` build tag. +The only requirement is an atomic `os.Mkdir`. + 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)) @@ -46,7 +45,7 @@ to check if your build supports file locking. ### Write-Ahead Logging -On little-endian Unix, this package uses `mmap` to implement +On Unix, this package may use `mmap` to implement [shared-memory for the WAL-index](https://sqlite.org/wal.html#implementation_of_shared_memory_for_the_wal_index), like SQLite. @@ -55,6 +54,11 @@ a WAL database can only be accessed by a single proccess. Other processes that attempt to access a database locked with BSD locks, will fail with the [`SQLITE_PROTOCOL`](https://sqlite.org/rescode.html#protocol) error code. +On Windows, this package may use `MapViewOfFile`, like SQLite. + +You can also opt into a cross-platform, in-process, memory sharing implementation +with the `sqlite3_dotlk` build tag. + 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 @@ -67,7 +71,7 @@ to check if your build supports shared memory. ### Batch-Atomic Write -On 64-bit Linux, this package supports +On Linux, this package may support [batch-atomic writes](https://sqlite.org/cgi/src/technote/714) on the F2FS filesystem. @@ -86,27 +90,27 @@ The implementation is compatible with SQLite's ### 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 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. +- `sqlite3_flock` forces the use of BSD locks. +- `sqlite3_dotlk` forces the use of dot-file locks. +- `sqlite3_nosys` prevents importing [`x/sys`](https://pkg.go.dev/golang.org/x/sys). > [!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` builds are compatible with the -> [`unix-flock` VFS](https://sqlite.org/compile.html#enable_locking_style). +> [`unix-flock` VFS](https://sqlite.org/compile.html#enable_locking_style); +> `sqlite3_dotlk` builds are compatible with the +> [`unix-dotfile` 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. ### Custom VFSes -- [`github.com/ncruces/go-sqlite3/vfs/adiantum`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs/adiantum) - wraps a VFS to offer encryption at rest. - [`github.com/ncruces/go-sqlite3/vfs/memdb`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs/memdb) implements an in-memory VFS. - [`github.com/ncruces/go-sqlite3/vfs/readervfs`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs/readervfs) implements a VFS for immutable databases. +- [`github.com/ncruces/go-sqlite3/vfs/adiantum`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs/adiantum) + wraps a VFS to offer encryption at rest. - [`github.com/ncruces/go-sqlite3/vfs/xts`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs/xts) - wraps a VFS to offer encryption at rest.
\ No newline at end of file + wraps a VFS to offer encryption at rest. |