wxSQLite3 wraps SQLite for wxWidgets, with seven cipher schemes

A wrapper that leaves the database visible

wxSQLite3 is a C++ wrapper around the public domain SQLite 3.x database, specifically designed for use in programs based on the wxWidgets library, and the homepage is utelle.github.io/wxsqlite3.

The design decision that defines the library is stated in the second paragraph of the README. wxSQLite3 does not try to hide the underlying database, and in contrast almost all special features of the current SQLite3 version are supported, with the example given being the creation of user defined scalar or aggregate functions. That is the opposite of what an ORM does, and it is the right call for a desktop application, where the database file is something the user may well want to inspect with an external tool.

The second decision is about text. Since SQLite stores strings in UTF-8 encoding, the wxSQLite3 methods provide automatic conversion between wxStrings and UTF-8 strings. The README is careful about the conditions: this works best for the Unicode builds of wxWidgets, and in ANSI builds the current locale conversion object, `wxConvCurrent`, is used for conversion to and from UTF-8. Special care has to be taken if external administration tools are used to modify the database contents, since not all of these tools operate in Unicode or UTF-8 mode.

That last warning is the one to remember. A file written by the library can be read by other tools, and the reverse is where the surprises live, because an ANSI build writing through a system encoding and a tool reading as UTF-8 will not agree.

Seven cipher schemes, with ChaCha20 as the default

Since version 1.7.0 wxSQLite3 includes a key based SQLite3 encryption extension, and starting with version 4.0.0 the extension allows the cipher scheme to be selected at runtime. The scheme list in the README is worth reading as a menu of what an encrypted SQLite file can be made compatible with.

AES 128 Bit CBC with no HMAC, and AES 256 Bit CBC with no HMAC, are provided by wxSQLite3 itself. ChaCha20 with Poly1305 HMAC comes from sqleet and is the default. AES 256 Bit CBC with SHA1, SHA256 or SHA512 HMAC covers the SQLCipher versions 1 to 4. RC4 with no HMAC comes from System.Data.SQLite. Ascon 128 with the Ascon Tag has been supported since version 4.9.8, and AEGIS with the AEGIS Tag since version 4.10.0.

The presence of the SQLCipher and RC4 entries is the important part, and it cuts both ways. Being able to open a database that SQLCipher wrote is what makes migration between tools possible, which matters when a desktop application is handing a user's data to other software. Being able to open a file written with RC4 or with AES CBC and no HMAC means the file format carries no integrity guarantee, and the README does not claim otherwise.

So the default, ChaCha20 with Poly1305, is the one that provides both confidentiality and authentication, and the others exist for compatibility rather than for preference.

The encryption extension had to be rewritten after SQLite 3.32

The Important Notes section of the README tells a story that explains why the project is on a separate encryption codebase.

With the release of SQLite version 3.32.0 on May 22, 2020, critical changes to the public SQLite code finally took officially effect, although they were not officially announced, and they were introduced on Feb 7, 2020. The change was to simplify the code by removing the unsupported and undocumented `SQLITE_HAS_CODEC` compile-time option. The consequence for this project was direct and severe: updating the wxSQLite3 encryption extension to support SQLite version 3.32.0 and later was no longer possible.

The fix was a rewrite rather than a patch. Since August 2020 a new implementation of an encryption extension capable of supporting SQLite 3.32.0 and later has been available as a separate project, SQLite3 Multiple Ciphers, and starting with the release of wxSQLite3 4.6.0 that new implementation is used.

The current release line continues that dependency. Version 5.0.2, from October 2026, upgrades to SQLite3 Multiple Ciphers version 2.6.1 with SQLite version 3.54.0, and the parallel 4.x release 4.12.8 is also based on SQLite 3.54.0.

One more packaging note, which is old news but changes what you install. Starting with wxSQLite3 version 3.5.0 the SQLite3 library is compiled as an integrated part of wxSQLite3, so a separate SQLite3 DLL is not required.

Windows builds are generated with Premake 5

The build files for Windows platforms are now generated with Premake 5, at version Premake 5.0 beta 5, and the repository carries a `premake5.lua` and a `premake/` directory to match.

The output is ready to use project files for Visual C++ 2015, 2017, 2019, 2022 and 2026, and additionally GNU Makefiles supporting for example MinGW-w64. So the current Visual Studio versions are covered out of the box, and there is an autotools path as well, with `configure.ac` and `Makefile.am` in the repository root for the Unix side.

Configuration is per machine, and the mechanism is worth understanding. For the Visual Studio solutions you can customise the build by creating a `wx_local.props` file in the build directory, which the projects use if it exists, and whose settings override the defaults. The typical way to make the file is to copy `wx_setup.props` to `wx_local.props` and then edit it locally. For the GNU Makefiles the file `config.gcc` serves the same purpose. Both allow you to customise settings such as the version number and the root directory of the wxWidgets library, which is the one setting every build machine has to change.

wxMSW details: the property file, WXWIN and the DLL path

The wxMSW section is a list of small things that will stop a build if you do not know them, and each is documented.

On Win32 or Win64 you can use the makefiles or one of the Microsoft Visual Studio solution files in the `build` folder. The Visual Studio solutions reference the property file `wx_setup.props` in the build subdirectory, and that file is configured in a way to allow running AppVeyor CI without any modifications. Specifically, specific library directories are used for different compiler versions, as it is used by the pre-built wxWidgets libraries, by adding the toolkit version, 141 for VS 2015 and 142 for VS 2019, to the library path name.

If you compile wxWidgets yourself and do not have those pre-built libraries, you adjust two parameters in `wx_setup.props`:

<wxCompilerPrefix>vc</wxCompilerPrefix>
<wxMsvcVersionAuto></wxMsvcVersionAuto>

The property file also assumes that the environment variable `WXWIN` is defined and points to the root directory of the wxWidgets installation, and the README tells you to make sure `WXWIN` is set up properly, or to replace it with an environment variable of your choice or an absolute path specification.

Finally, the debugging properties are set up so that debugging the sample applications works out of the box, but for release builds you may need to copy the wxSQLite3 DLL or add the `lib` folder path to the Windows search path. That last one is the classic packaging bug, where a debug build runs and the release build fails to start because a DLL is missing.

5.x breaks source compatibility and 4.x is in maintenance

The version history section is short because the current release is the only news. Version 5.0.2, from October 2026, upgrades to SQLite3 Multiple Ciphers 2.6.1 with SQLite 3.54.0, and further version information is in the CHANGELOG.

What version 5 is, though, is a modern C++ API. The wxSQLite3 API has been extended with template-based methods for retrieving values from result sets, template-based methods for binding values to prepared statements, iterator support for `wxSQLite3::ResultSet`, and support for range-based for loops when processing result sets. The intent is that result set and prepared statement code can be written in a more concise and type-oriented style, and these features complement rather than replace the existing API.

The catch is stated plainly. wxSQLite3 5.x is a major update with a modernised C++ API, it is not fully source-compatible with wxSQLite3 4.x, and therefore wxSQLite3 4.x will receive maintenance updates, including updates to the bundled SQLite version, for a limited period following the release of 5.0.0. No new API features will be added to 4.x, and the End-of-Life date of version 4.x will be announced separately.

So there is a window. During it, 4.x is the safe choice for an existing application and 5.x is the one to start new work on, and the documentation has a Migrating from 4.x to 5.x page and a Modern C++ Interface page that spell out both sides of that move.

Where the build story is still incomplete

One thing the README flags without hedging is the build system. Currently the CMake support is experimental and limited to Windows platforms, and may or may not work. So the supported, documented path today is the Premake and Visual Studio route on Windows, and the autotools and GNU Make route elsewhere, and CMake is something you try rather than something you depend on.

The repository layout also shows how the project is packaged. There is `include/` and `src/` for the library, `lib/`, `samples/`, `build/`, `premake/`, `admin/`, `docs/`, a `wxsqlite3.pc.in` for pkg-config, and a set of licence files, `LICENCE.txt`, `COPYING.txt`, `GPL-3.0.txt`, `LGPL-3.0.txt`, `LICENSE.spdx` and a `WxWindows-exception-3.1.txt`.

That last file is a reminder of the licensing question, which is genuinely unclear from the outside. The repository metadata classifies the licence as one GitHub cannot categorise, the licence directory contains both GPL and LGPL texts plus a wxWidgets exception file, and the README's table of contents points at a licence section whose content is not in the copy available here. For a library that gets linked into a desktop application, that is the document to read before you ship.

The samples are also worth a look, and they are more than a minimal program. Alongside `samples/minimal.cpp` and a treeview sample there are prepared test databases for each cipher, with `persons-aegis-testkey.db3` and `persons-ascon128-testkey.db3` for the two most recent additions, and files named for the SQLCipher versions from 1.1.8 through 4.0, which is a convenient way to confirm that your build really can read what other tools wrote.

Editorial conclusion

Adopt wxSQLite3 when you are writing a wxWidgets desktop application that needs a local SQLite database and want the encryption extension, the wxString conversion and the result set API in one library. Do not adopt it if your code must stay source compatible with the 4.x API, since 5.0 is not fully source compatible and 4.x is now maintenance only, and do not plan around the CMake build, which the README calls experimental and limited to Windows. Verify first which version line your project is on, that the cipher you want is available in it, that `WXWIN` points at your wxWidgets root, and that the licence terms in the repository match what you need, since the repository carries several licence files.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. utelle/wxsqlite3 on GitHub