diff --git a/src/examples/README.md b/src/examples/README.md index 211f9bc..f161604 100644 --- a/src/examples/README.md +++ b/src/examples/README.md @@ -10,9 +10,11 @@ These implementations store database pages in memory. The default SQLite VFS alr ### IDBBatchAtomicVFS This VFS stores database pages in IndexedDB. IndexedDB works on all contexts - Window, Worker, SharedWorker, service worker, extension - which makes IDBBatchAtomicVFS a good general purpose VFS. -SQLite supports a special mode for filesystems that can make "batch atomic" writes, i.e. guaranteeing that an arbitrary set of changes is made either completely or not at all, and IDBBatchAtomicVFS leverages IndexedDB to do this. When this mode can be used, an external journal file is not needed which improves performance. +SQLite supports a special mode for filesystems that can make "batch atomic" writes, i.e. guaranteeing that an arbitrary set of changes is made either completely or not at all, and IDBBatchAtomicVFS leverages IndexedDB to do this. When this mode can be used, an external journal file is not needed which improves performance. The journal will instead be kept in the page cache, so a requirement for triggering batch atomic mode is that the cache size must be set large enough to hold the journal. -Changing the page size after the database is created is not supported. +IDBBatchAtomicVFS can trade durability for performance by setting `PRAGMA synchronous=normal`. + +Changing the page size after the database is created is not supported (this is a change from pre-1.0). ### OPFSAdaptiveVFS This VFS is fundamentally a straightforward mapping of OPFS access handles to VFS methods, but adds two different techniques to support multiple connections. @@ -21,29 +23,33 @@ The current OPFS spec allows only one open access handle on a file at a time. Su A proposed change to OPFS allows there to be multiple open access handles on a file. OPFSAdaptiveVFS will take advantage of this on browsers that support it, and this will improve performance as well as allow overlapping multiple read transactions with a write transaction. -If the new modes are not supported then only journaling modes "delete" (default), "memory", and "off" are allowed. +If multiple open access handles are not supported then only journaling modes "delete" (default), "memory", and "off" are allowed. ### AccessHandlePoolVFS This is an OPFS VFS that has all synchronous methods, i.e. they don't return Promises. This allows it to be used with a with a synchronous WebAssembly build and that has definite performance advantages. AccessHandlePoolVFS works by pre-opening a number of access handles and associating them with SQLite open requests as needed. Operation is restricted to a single wa-sqlite instance, so multiple connections are not supported. +The silver lining to not allowing multiple connections is that there is no drawback to using `PRAGMA locking_mode=exclusive`. This in turn allows `PRAGMA journal_mode=wal`, which can significantly reduce write transaction overhead. + This VFS is not filesystem transparent, which means that its database files in OPFS cannot be directly imported and exported. ### OPFSCoopSyncVFS -This VFS is a synchronous OPFS VFS (like AccessHandlePoolVFS) that allows multiple connections (unlike AccessHandlePoolVFS). +This VFS is a synchronous OPFS VFS (like AccessHandlePoolVFS) that allows multiple connections and is filesystem transparent (unlike AccessHandlePoolVFS). OPFSCoopSyncVFS uses an access handle pool for files other than the main database and its journal file. For the shared files, it closes them lazily (like OPFSAdaptiveVFS) to support multiple connections while retaining performance with a single connection. To keep all the methods synchronous, when asynchronous operations are necessary (e.g. for locking) a method returns an error. The library wrapper API internally handles the error, waits for the asynchronous operation to complete, and then repeats the operation. This is not very efficient, but is only necessary when opening a database or under active multiple connection contention. -Transactions involving more than one main (non-temporary) database are not supported. +Transactions that write to more than one main (non-temporary) database are not supported. ### OPFSPermutedVFS -This is a hybrid OPFS/IndexedDB VFS that allows high concurrency - simultaneous access by multiple readers and a single writer. It requires the proposed "readwrite-unsafe" locking mode for OPFS access handles. +This is a hybrid OPFS/IndexedDB VFS that allows high concurrency - simultaneous access by multiple readers and a single writer. It requires the proposed "readwrite-unsafe" locking mode for OPFS access handles (only on Chromium browsers as of June 2024). OPFSPermutedVFS is a lot like SQLite WAL except that it writes directly to the database file instead of a separate write-ahead log file, so there may be more than one version of a page in the file and the location of pages is generally not sequential. All the page data is stored in the file and IndexedDB is used to manage the page versions and locations. +OPFSPermutedVFS can trade durability for performance by setting `PRAGMA synchronous=normal`. + Changing the page size after the database is created is not supported. Not filesystem transparent except immediately after VACUUM. ## VFS Comparison