From 5535abcdd28e8641d03bb3530b7a78140d83ce84 Mon Sep 17 00:00:00 2001 From: Nuno Cruces Date: Mon, 18 Sep 2023 14:47:55 +0100 Subject: [PATCH] Build tags, docs. --- .github/workflows/go.yml | 10 +++++++--- README.md | 18 +++++++----------- vfs/README.md | 26 +++++++++++++++++++++++++- vfs/os_bsd.go | 2 +- vfs/os_darwin.go | 2 +- vfs/os_nolock.go | 2 +- vfs/os_ofd.go | 2 +- vfs/os_std_alloc.go | 2 +- vfs/os_std_sync.go | 2 +- 9 files changed, 45 insertions(+), 21 deletions(-) diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index bfbbe2ce..cee465b5 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -47,8 +47,12 @@ jobs: - name: Test run: go test -v ./... + - name: Test no locks + run: go test -v -tags sqlite3_nolock . + if: matrix.os == 'ubuntu-latest' + - name: Test BSD locks - run: go test -v -tags sqlite3_bsd ./... + run: go test -v -tags sqlite3_flock ./... if: matrix.os == 'macos-latest' - name: Coverage report @@ -58,6 +62,6 @@ jobs: amend: 'true' reuse-go: 'true' if: | - matrix.os == 'ubuntu-latest' && - github.event_name == 'push' + github.event_name == 'push' && + matrix.os == 'ubuntu-latest' continue-on-error: true diff --git a/README.md b/README.md index 61adf2f6..975f60d0 100644 --- a/README.md +++ b/README.md @@ -57,29 +57,25 @@ On Linux, macOS and illumos, this module uses to synchronize access to database files. OFD locks are fully compatible with process-associated POSIX advisory locks. -On BSD Unixes, this module uses +On BSD Unixes, this module may use [BSD locks](https://man.freebsd.org/cgi/man.cgi?query=flock&sektion=2). -BSD locks may _not_ be compatible with process-associated POSIX advisory locks -(they are on FreeBSD). +BSD locks may _not_ be compatible with process-associated POSIX advisory locks. ##### TL;DR In all platforms for which this package builds, -it is safe to use it to access databases concurrently from multiple goroutines. - -Additionally, on Windows, Linux, macOS, illumos and FreeBSD, -it is _also_ safe to use it to access databases concurrently +it should be safe to use it to access databases concurrently, +from multiple goroutines, processes, and with _other_ implementations of SQLite. -On other BSDs, where this might be unsafe, -[this test](vfs/lock_test.go) should fail. +If the package does not build for your platform, +see [this](vfs/README.md#portability). #### Testing The pure Go VFS is tested by running SQLite's [mptest](https://github.com/sqlite/sqlite/blob/master/mptest/mptest.c) -on Linux, macOS and Windows; -BSD code paths are tested on macOS using the `sqlite3_bsd` build tag. +on Linux, macOS and Windows. Performance is tested by running [speedtest1](https://github.com/sqlite/sqlite/blob/master/test/speedtest1.c). diff --git a/vfs/README.md b/vfs/README.md index f028964c..382c8d76 100644 --- a/vfs/README.md +++ b/vfs/README.md @@ -6,4 +6,28 @@ It replaces the default VFS with a pure Go implementation, that is tested on Linux, macOS and Windows, but which should also work on illumos and the various BSDs. -It also exposes interfaces that should allow you to implement your own custom VFSes. \ No newline at end of file +It also exposes interfaces that should allow you to implement your own custom VFSes. + +## Portability + +This package is tested on Linux, macOS and Windows, +but it should also work on FreeBSD and illumos +(code paths for those plaforms are tested on macOS and Linux, respectively). + +In all platforms for which this package builds, +it should be safe to use it to access databases concurrently, +from multiple goroutines, processes, and +with _other_ implementations of SQLite. + +If the package does not build for your platform, +you may try to use the `sqlite3_flock` and `sqlite3_nolock` build tags. +These are only minimally tested and concurrency test failures should be expected. + +The `sqlite3_flock` tag uses +[BSD locks](https://man.freebsd.org/cgi/man.cgi?query=flock&sektion=2). +It should be safe to access databases concurrently from multiple goroutines and processes, +but **not** with _other_ implementations of SQLite +(_unless_ these are _also_ configured to use `flock`). + +The `sqlite3_nolock` tag uses no locking at all. +Database corruption is the likely result from concurrent write access. \ No newline at end of file diff --git a/vfs/os_bsd.go b/vfs/os_bsd.go index 916a1750..1147556d 100644 --- a/vfs/os_bsd.go +++ b/vfs/os_bsd.go @@ -1,4 +1,4 @@ -//go:build freebsd || openbsd || netbsd || dragonfly || (darwin && sqlite3_bsd) +//go:build sqlite3_flock || freebsd package vfs diff --git a/vfs/os_darwin.go b/vfs/os_darwin.go index 90439711..c366313b 100644 --- a/vfs/os_darwin.go +++ b/vfs/os_darwin.go @@ -1,4 +1,4 @@ -//go:build !sqlite3_bsd +//go:build !sqlite3_flock package vfs diff --git a/vfs/os_nolock.go b/vfs/os_nolock.go index 499cce69..21a5648a 100644 --- a/vfs/os_nolock.go +++ b/vfs/os_nolock.go @@ -1,4 +1,4 @@ -//go:build sqlite3_nolock && solaris && !illumos +//go:build sqlite3_nolock && unix && !(linux || darwin || freebsd || illumos) package vfs diff --git a/vfs/os_ofd.go b/vfs/os_ofd.go index 1d9fb1df..a728cd3f 100644 --- a/vfs/os_ofd.go +++ b/vfs/os_ofd.go @@ -1,4 +1,4 @@ -//go:build linux || illumos +//go:build (linux || illumos) && !sqlite3_flock package vfs diff --git a/vfs/os_std_alloc.go b/vfs/os_std_alloc.go index 619061dd..bb6f8be0 100644 --- a/vfs/os_std_alloc.go +++ b/vfs/os_std_alloc.go @@ -1,4 +1,4 @@ -//go:build !linux && (!darwin || sqlite3_bsd) +//go:build !linux && (!darwin || sqlite3_flock) package vfs diff --git a/vfs/os_std_sync.go b/vfs/os_std_sync.go index 45dba18b..889e95ae 100644 --- a/vfs/os_std_sync.go +++ b/vfs/os_std_sync.go @@ -1,4 +1,4 @@ -//go:build !linux && (!darwin || sqlite3_bsd) +//go:build !linux && (!darwin || sqlite3_flock) package vfs