Skip to content

Add the nocurrenttime VFS and the sqlite_omit_localtime tag for deterministic date and time - #5

Merged
laodouya merged 9 commits into
developfrom
feature/nocurrenttime-vfs
Nov 4, 2026
Merged

laodouya merged 9 commits into
developfrom
feature/nocurrenttime-vfs

Conversation

@laodouya

@laodouya laodouya commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

CovenantSQL runs the same statements on every miner of a database and needs them to produce the same values. Its query sanitizer rejects date('now') and similar literals, but that cannot catch 'now' passed as an argument, stored in a column or built by an expression such as 'n' || 'ow', nor date functions called without a time value, which default to now. The localtime and utc modifiers depend on the time zone of the host in the same way. This makes both deterministic in SQLite itself:

  • The nocurrenttime VFS, selected with vfs=nocurrenttime in the DSN, is a copy of the default VFS whose current time is unavailable. SQLite then treats the current time as unknown, so 'now' in any form, date functions without a time value, and the CURRENT_* keywords give NULL. It is registered when a DSN first selects it. Besides date and time functions, SQLite only reads the VFS clock to time statements for profiling callbacks, and in debug builds of the sorter; busy timeouts, WAL, locking and SQLCipher do not use it.
  • The sqlite_omit_localtime build tag builds SQLite with SQLITE_OMIT_LOCALTIME, which removes the localtime and utc modifiers; they give NULL as well. The tag only changes the bundled SQLite, so with the libsqlite3 tag, Open fails unless the system SQLite is built with SQLITE_OMIT_LOCALTIME, instead of the tag silently having no effect. This uses the same compile option check as _crypto_key.
  • A DSN with more than one vfs parameter is refused. The driver used the first one and SQLite the last one, so vfs=nocurrenttime&vfs=unix opened the database with the default VFS.
  • The README describes both options and their side effects: a NOT NULL DEFAULT CURRENT_TIMESTAMP column cannot get its default, and profile events (sqlite_trace, SQLCipher's PRAGMA cipher_profile) disappear, because SQLite skips them without a start time. A code comment notes that the VFS is a shallow copy of the default one, which suits the unix and win32 VFSes.

c0d2635 added a stronger test of the Exec fix of #4 and is reverted here, as it does not belong to this change; the same test is in mattn#1471 and comes back with the next update from go-sqlite3.

Testing

On linux/amd64 with Go 1.27.3, go vet and go test pass with the default tags, with the tags CovenantSQL builds its miner with plus sqlite_omit_localtime, and with libsqlite3.

  • TestNoCurrentTimeVFS checks that a WAL database is read and written through the VFS, that date('now'), date(?) with 'now', date('n' || 'ow'), datetime(), julianday('now'), unixepoch(), strftime('%Y') and CURRENT_TIMESTAMP give NULL with it, and that the default VFS still has the current time. TestMoreThanOneVFS checks the refused DSN.
  • TestOmitLocaltime, with the tag, checks that both modifiers give NULL. TestOmitLocaltimeWithoutTheOption, with the tag and libsqlite3 against the Debian SQLite, checks that Open fails. With that combination every Open fails by design, so the other tests that open a database fail too.

A copy of the default VFS without the current time, selected with
vfs=nocurrenttime. Date and time functions then give NULL for 'now', for
calls without a time value and for the CURRENT_* keywords, so replicas
that execute the same statements store the same values, whatever way
'now' reaches the function.
It builds SQLite with SQLITE_OMIT_LOCALTIME, which removes the localtime
and utc modifiers whose results depend on the time zone of the host.
TestNotEnoughArgsErrorMessage only checks the error, which an Exec that
ran the statement before failing would pass too.
This reverts commit c0d2635, which does
not belong to this change. The same test is in mattn#1471 and
comes back with the next update from go-sqlite3.
The tag only changes the bundled SQLite. With the libsqlite3 tag, a
system SQLite kept the localtime and utc modifiers and the tag had no
effect, without any sign of it. Open now fails then, as with
_crypto_key and a SQLite without SQLCipher, and both checks share
compileOptionUsed.
The driver took the first one and SQLite the last one, so
vfs=nocurrenttime&vfs=unix registered the nocurrenttime VFS but opened
the database with the default one, which has the current time.
The doc comment of Open now lists date and time functions without a
time value like the README, and the comment of the VFS no longer claims
that all results are the same whenever a query runs: random() is not.
Describe NOT NULL DEFAULT CURRENT_TIMESTAMP columns, the missing profile
events, the libsqlite3 tag and the shallow copy of the default VFS.
go.mod requires Go 1.21, which only reads //go:build.
@laodouya
laodouya merged commit 9231dfc into develop Nov 4, 2026
18 checks passed
@laodouya
laodouya deleted the feature/nocurrenttime-vfs branch November 4, 2026 07:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant