Skip to content

Add db.setWalHook()#16

Merged
indutny-signal merged 4 commits into
mainfrom
wal-hook
May 26, 2026
Merged

Add db.setWalHook()#16
indutny-signal merged 4 commits into
mainfrom
wal-hook

Conversation

@jamiebuilds-signal
Copy link
Copy Markdown
Member

This adds the ability to call sqlite3_wal_hook() to setup a JS callback.

The callback is invoked by SQLite after the commit has taken place and the associated write-lock on the database released, so the implementation may read, write or checkpoint the database as required.

Importantly, setting your own WAL hook replaces/disables sqlite3_wal_autocheckpoint:

From sqlite3_wal_hook()

A single database handle may have at most a single write-ahead log callback registered at one time. Calling sqlite3_wal_hook() replaces the default behavior or previously registered write-ahead log callback.

From sqlite3_wal_autocheckpoint

The sqlite3_wal_autocheckpoint(D,N) is a wrapper around sqlite3_wal_hook() [...]

If the JS callback throws, the WalHookWrap::Call function will swallow the exception and return SQLITE_OK. The alternative is that that the statement that triggered the commit would throw.

The callback function should normally return SQLITE_OK. If an error code is returned, that error will propagate back up through the SQLite code base to cause the statement that provoked the callback to report an error, though the commit will have still occurred.

The implementation is basically the same as db.createFunction() but it differs in how it gets cleaned up since we don't have the xFinal param to call the destructor at FunctionWrap::Final. Instead its stored at Database::wal_hook_wrap_ which then needs to be cleaned up on database close.

Copy link
Copy Markdown
Contributor

@indutny-signal indutny-signal left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, formatted the C++ code.

@indutny-signal indutny-signal merged commit f6c6098 into main May 26, 2026
4 checks passed
@indutny-signal indutny-signal deleted the wal-hook branch May 26, 2026 16:49
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.

3 participants