SQLiteVfs.hpp

Single header with classes for easily implementing SQLite VFS shims in C++11.

Features

• Single header: copy SQLiteVfs.hpp to your project, #include <SQLiteVfs.hpp> and that's it
• Supports C++11 and above
• Subclass sqlite3vfs::SQLiteVfsImpl<> to override any VFS methods
  • Default implementations forward execution to the default VFS. This makes it easy to implement VFS shims.
• Subclass sqlite3vfs::SQLiteFileImpl to override any File methods
  • Default implementations forward execution to the File opened by SQLiteVfsImpl::xOpen. This makes it easy to implement File shims.

Usage example

This sample code shows how to create a SQLite extension DLL that registers a simple VFS shim + File shim that logs read/write operations:

// 1. Include <SQLiteVfs.hpp> header
// If you are building an extension DLL, make sure to include
// <sqlite3ext.h> and call SQLITE_EXTENSION_INIT1 first.
#include <sqlite3ext.h>
SQLITE_EXTENSION_INIT1
#include <SQLiteVfs.hpp>

#include <iostream>

using namespace sqlitevfs;
using namespace std;

// 2. Implement your own `SQLiteFileImpl` subclass.
// Override any IO methods necessary. Reference: https://www.sqlite.org/c3ref/io_methods.html
// Default implementation will forward execution to the `original_file` opened by `SQLiteVfsImpl::xOpen`.
// Default constructor will be called before `SQLiteVfsImpl::xOpen`.
// Destructor will be called right after `xClose`, or after a failed `SQLiteVfsImpl::xOpen`.
struct LogIOFileShim : public SQLiteFileImpl {
	LogIOFileShim() {
		cout << "> Constructing file!" << endl;
	}
	int xRead(void *p, int iAmt, sqlite3_int64 iOfst) override {
		cout << "> READ " << iAmt << " bytes starting at " << iOfst << endl;
		return SQLiteFileImpl::xRead(p, iAmt, iOfst);
	}
	int xWrite(const void *p, int iAmt, sqlite3_int64 iOfst) override {
		cout << "> WRITE " << iAmt << " bytes starting at " << iOfst << endl;
		return SQLiteFileImpl::xWrite(p, iAmt, iOfst);
	}
	int xClose() override {
		cout << "> CLOSE" << endl;
		return SQLiteFileImpl::xClose();
	}
	~LogIOFileShim() {
		cout << "> Destroying file!" << endl;
	}
};

// 3. Implement your own `SQLiteVfsImpl<>` subclass.
// Pass your SQLiteFileImpl subclass as template parameter.
// Override any methods necessary. Reference: https://www.sqlite.org/c3ref/vfs.html
// Default implementation will forward execution to the `original_vfs` passed in `SQLiteVfs` construtor.
// Notice that `xOpen` receives a `SQLiteFile<LogIOFileImpl> *` instead of `sqlite3_file`.
// `file` is guaranteed to be fully constructed before this method is called.
struct LogIOVfsShim : public SQLiteVfsImpl<LogIOFileShim> {
	int xOpen(sqlite3_filename zName, SQLiteFile<LogIOFileShim> *file, int flags, int *pOutFlags) override {
		int result = SQLiteVfsImpl::xOpen(zName, file, flags, pOutFlags);
		if (result == SQLITE_OK) {
			cout << "> OPENED '" << zName << "'" << endl;
		}
		else {
			cout << "> ERROR OPENING '" << zName << "': " << sqlite3_errstr(result) << endl;
		}
		return result;
	}
};

// If implementing an extension DLL, export the function as SQLite expects
extern "C" int sqlite3_logiovfs_init(sqlite3 *db, char **pzErrMsg, const sqlite3_api_routines *pApi) {
	SQLITE_EXTENSION_INIT2(pApi);

	// 4. Create a `SQLiteVfs<>`.
	// Pass your `SQLiteVfsImpl<>` subclass as template parameter.
	static SQLiteVfs<LogIOVfsShim> logiovfs("logiovfs");
	
	// 5. Register your newly created VFS.
	// Optionally make it the default VFS.
	int rc = logiovfs.register_vfs(false);
	if (rc == SQLITE_OK) {
		rc = SQLITE_OK_LOAD_PERMANENTLY;
	}
	return rc;
}

// 6. (optional) Unregister your VFS using `my_vfs.unregister_vfs()`

Samples

• logiovfs: shows how to create a SQLite extension DLL that registers a simple VFS shim + File shim that logs read/write operations

Building and running samples:

# build
mkdir build
cd build
cmake ..
make

# run from build folder
samples/logiovfs-sample