*** DRAFT ***

SQLite Requirement Matrix Details
wal.html

Index Summary Markup Original


R-58297-14483-40146-32998-13341-07144-06303-13895 tcl slt th3 src

WAL databases can be created, read, and written even if shared memory is unavailable as long as the locking_mode is set to EXCLUSIVE before the first attempted access.

tcl/e_wal.test:22   th3/req1/pragma05.test:188

/* IMP: R-58297-14483 */
# EVIDENCE-OF: R-58297-14483 WAL databases can be created, read, and
# written even if shared memory is unavailable as long as the
# locking_mode is set to EXCLUSIVE before the first attempted access.

R-00449-33772-33919-59402-60829-28733-22208-04727 tcl slt th3 src

This feature allows WAL databases to be created, read, and written by legacy VFSes that lack the "version 2" shared-memory methods xShmMap, xShmLock, xShmBarrier, and xShmUnmap on the sqlite3_io_methods object.

tcl/e_wal.test:26   th3/req1/pragma05.test:192

/* IMP: R-00449-33772 */
# EVIDENCE-OF: R-00449-33772 This feature allows WAL databases to be
# created, read, and written by legacy VFSes that lack the "version 2"
# shared-memory methods xShmMap, xShmLock, xShmBarrier, and xShmUnmap on
# the sqlite3_io_methods object.

R-31969-57825-42101-14521-32158-26846-01551-49036 tcl slt th3 src

If EXCLUSIVE locking mode is set prior to the first WAL-mode database access, then SQLite never attempts to call any of the shared-memory methods and hence no shared-memory wal-index is ever created.

tcl/e_wal.test:81   th3/req1/pragma05.test:217

/* IMP: R-31969-57825 */
# EVIDENCE-OF: R-31969-57825 If EXCLUSIVE locking mode is set prior to
# the first WAL-mode database access, then SQLite never attempts to call
# any of the shared-memory methods and hence no shared-memory wal-index
# is ever created.

R-36328-16367-14145-21377-30808-40796-28392-26990 tcl slt th3 src

In that case, the database connection remains in EXCLUSIVE mode as long as the journal mode is WAL; attempts to change the locking mode using "PRAGMA locking_mode=NORMAL;" are no-ops.

tcl/e_wal.test:96   th3/req1/pragma05.test:237

/* IMP: R-36328-16367 */
# EVIDENCE-OF: R-36328-16367 In that case, the database connection
# remains in EXCLUSIVE mode as long as the journal mode is WAL; attempts
# to change the locking mode using "PRAGMA locking_mode=NORMAL;" are
# no-ops.

R-63522-46088-33895-54497-03733-53184-07098-33228 tcl slt th3 src

The only way to change out of EXCLUSIVE locking mode is to first change out of WAL journal mode.

tcl/e_wal.test:111   th3/req1/pragma05.test:247

/* IMP: R-63522-46088 */
# EVIDENCE-OF: R-63522-46088 The only way to change out of EXCLUSIVE
# locking mode is to first change out of WAL journal mode.

R-57239-11845-16463-18106-13303-34365-12787-00637 tcl slt th3 src

If NORMAL locking mode is in effect for the first WAL-mode database access, then the shared-memory wal-index is created.

tcl/e_wal.test:134   th3/req1/pragma05.test:256

/* IMP: R-57239-11845 */
# EVIDENCE-OF: R-57239-11845 If NORMAL locking mode is in effect for the
# first WAL-mode database access, then the shared-memory wal-index is
# created.

R-46197-42811-45122-27334-03540-14095-05781-43695 tcl slt th3 src

This means that the underlying VFS must support the "version 2" shared-memory.

tcl/e_wal.test:183   th3/req1/pragma05.test:260

/* IMP: R-46197-42811 */
# EVIDENCE-OF: R-46197-42811 This means that the underlying VFS must
# support the "version 2" shared-memory.

R-55316-21772-61172-01789-50748-54713-63157-59070 tcl slt th3 src

If the VFS does not support shared-memory methods, then the attempt to open a database that is already in WAL mode, or the attempt convert a database into WAL mode, will fail.

tcl/e_wal.test:186   th3/req1/pragma05.test:290

/* IMP: R-55316-21772 */
# EVIDENCE-OF: R-55316-21772 If the VFS does not support shared-memory
# methods, then the attempt to open a database that is already in WAL
# mode, or the attempt convert a database into WAL mode, will fail.

R-13779-07711-12405-44335-29719-17285-28240-52263 tcl slt th3 src

As long as exactly one connection is using a shared-memory wal-index, the locking mode can be changed freely between NORMAL and EXCLUSIVE.

tcl/e_wal.test:149   th3/req1/pragma05.test:277

/* IMP: R-13779-07711 */
# EVIDENCE-OF: R-13779-07711 As long as exactly one connection is using
# a shared-memory wal-index, the locking mode can be changed freely
# between NORMAL and EXCLUSIVE.

R-10993-11647-55800-55293-06436-13332-42842-10882 tcl slt th3 src

It is only when the shared-memory wal-index is omitted, when the locking mode is EXCLUSIVE prior to the first WAL-mode database access, that the locking mode is stuck in EXCLUSIVE.

tcl/e_wal.test:164   th3/req1/pragma05.test:312

/* IMP: R-10993-11647 */
# EVIDENCE-OF: R-10993-11647 It is only when the shared-memory wal-index
# is omitted, when the locking mode is EXCLUSIVE prior to the first
# WAL-mode database access, that the locking mode is stuck in EXCLUSIVE.

R-45540-25505-12705-13417-45651-45483-56013-24623 tcl slt th3 src

To prevent older versions of SQLite (prior to version 3.7.0, 2010-07-22) from trying to recover a WAL-mode database (and making matters worse) the database file format version numbers (bytes 18 and 19 in the database header) are increased from 1 to 2 in WAL mode.

tcl/e_wal.test:204

/* IMP: R-45540-25505 */
# EVIDENCE-OF: R-45540-25505 To prevent older versions of SQLite (prior
# to version 3.7.0, 2010-07-22) from trying to recover a WAL-mode
# database (and making matters worse) the database file format version
# numbers (bytes 18 and 19 in the database header) are increased from 1
# to 2 in WAL mode.

R-02535-05811-23269-15824-03293-63258-54375-28501 tcl slt th3 src

One can explicitly change out of WAL mode using a pragma such as this:

PRAGMA journal_mode=DELETE;

tcl/e_wal.test:217

/* IMP: R-02535-05811 */
# EVIDENCE-OF: R-02535-05811 One can explicitly change out of WAL mode
# using a pragma such as this: PRAGMA journal_mode=DELETE;

R-60175-02388-07986-54483-25650-07763-57471-09194 tcl slt th3 src

Deliberately changing out of WAL mode changes the database file format version numbers back to 1 so that older versions of SQLite can once again access the database file.

tcl/e_wal.test:225

/* IMP: R-60175-02388 */
# EVIDENCE-OF: R-60175-02388 Deliberately changing out of WAL mode
# changes the database file format version numbers back to 1 so that
# older versions of SQLite can once again access the database file.