Installation

Table of contents

• Overview
  • Releases and Binaries
  • Language Bindings
  • Drop-in replacement for SQLite
• Windows builds
• Linux / OSX builds
• WebAssembly
• Support for ICU (International Components for Unicode)
• Default settings
• Optional features
• TCL Interface

Overview

Build files for the supported platforms - Windows, Linux, and OSX - are provided.

The build files for Windows platforms are generated with Premake 5. For regenerating the build files it is recommended to use Premake 5.0 alpha 15 or later.

For Linux and OSX build files based on the autoconf/automake toolchain are provided.

Releases and Binaries

Releases of SQLite3 Multiple Ciphers are typically made available shortly after releases of SQLite. Usually, an archive with the amalgamated source code, pre-built binaries for Windows and Android (see SQLite Android Bindings) are provided with every release.

Language Bindings

Several language bindings for SQLite3 Multiple Ciphers exist in separate projects:

• Node.js. wrapper better-sqlite3-multiple-ciphers, (GitHub)
• SQLite JDBC Driver for Java
• SQLDelight driver for Kotlin
• .NET NuGet package SQLitePCLRaw.bundle_e_sqlite3mc via Eric Sink’s project SQLitePCL.raw
• Python3 package apsw-sqlite3mc, (GitHub) based on Roger Binns’ project apsw
• Jonathan Giannuzzi’s fork of go-sqlite3 for the Go language. Integration into mattn/go-sqlite3 is discussed in PR 1109, but it is unclear, if and when this will happen.
• Qt plugin for SQLite QtCipherSqlitePlugin or QSQLite3MultipleCiphers

Note

If you know about further language bindings, please drop a note (for example, via a GitHub discussion).

Drop-in replacement for SQLite

In principle, the SQLite3 Multiple Ciphers source code or binaries can be used as a drop-in replacement for SQLite.

If your project uses the SQLite amalgamation source file sqlite3.c, this file could be replaced by the SQLite3 Multiple Ciphers amalgamation source file sqlite3mc_amalgamation.c (as distributed with the releases).

If your project references SQLite’s shared library (for example, sqlite3.dll on Windows), SQLite3 Multiple Ciphers’ shared library could be referenced instead by renaming the shared library and making it available on the library search path.

Windows builds

Ready to use project files are provided for Visual C++ 2010, 2012, 2013, 2015, 2017, 2019, and 2022. Additionally, GNU Makefiles are provided supporting GCC (for example, Mingw-w64 or recent versions of tdm-gcc).

For Visual Studio 2010+ solutions it is possible to customize the build by creating a wx_local.props file in the build directory which is used by the projects, if it exists. The settings in that file override the default values for the properties. The typical way to make the file is to copy wx_setup.props to wx_local.props and then edit locally.

For GNU Makefiles the file config.gcc serves the same purpose as the file wx_setup.props for Visual C++ projects.

The customization files wx_setup.props resp. config.gcc allow to customize certain settings like for example the default cipher scheme.

For adjusting the build configuration edit file premake5.lua in the root directory, and then run

premake5 [action]

where action is one of the following: vs2010, vs2012, vs2013, vs2015, vs2017, vs2019, or gmake2.

When building on Win32 or Win64, you can use the makefiles or one of the Microsoft Visual Studio solution files in the build folder.

For Visual C++ the debugging properties are set up in such a way that debugging the sample applications should work right out of the box.

Linux / OSX builds

When building on Linux or OSX, the first setup is to recreate the configure script doing:

  autoreconf

Thereafter you should create a build directory

  mkdir build-gtk [or any other suitable name]
  cd build-gtk
  ../configure
  make

Type ../configure --help for more info.

The autoconf-based system also supports a make install target which builds the library and then copies the headers of the component to /usr/local/include and the lib to /usr/local/lib.

WebAssembly

Starting with version 3.40 the SQLite project provides WebAssembly- and JavaScript-related APIs, which enable the use of SQLite3 in modern WASM-capable browsers.

SQLite3 Multiple Ciphers can add encryption support to WASM-based applications. In principle, building JS/WASM support for SQLite3 Multiple Ciphers follows closely the documentation given on the SQLite website.

The build process is very similar to the description of Building for SQLite Encryption Extension (SEE), the official (commercial) SQLite Encryption Extension.

The following steps describe the preliminary actions:

1. Generate or download the amalgamation source code of SQLite3 Multiple Ciphers, matching the SQLite version, you want to build WASM support for,
2. Copy the file sqlite3mc_amalgamation.c to the top-most directory of the SQLite source tree,
3. Rename sqlite3mc_amalgamation.c to sqlite3-see.c, or pass sqlite3.c=/path/to/sqlite3mc_amalgamation.c when running make or gmake from the ext/wasm directory,
4. Adjust the file ext/wasm/GNUmakefile by adding the compile time flag -D__WASM__ (2 places),
5. (Optional) Add support for the SQLite3 Multiple Ciphers C API:
   • Add the SQLite3 Multiple Ciphers API function names to file ext/wasm/api/EXPORTED_FUNCTIONS.sqlite3-see, prefixing them with an underscore character,
   • Add the signatures of the SQLite3 Multiple Ciphers API functions to ext/wasm/api/sqlite3-api-glue.js (search for sqlite3_activate_see).

Thereafter WASM support can be built according to the SQLite documentation.

Support for ICU (International Components for Unicode)

On Windows the SQLite3 Multiple Ciphers library can be built with or without ICU support. ICU support for SQLite3 is currently based on pre-built ICU Libraries, which were compiled with Visual Studio 2019. The required ICU DLLs are not included in the repository, but can be downloaded from the latest ICU release. However, the pre-built binary packages for Windows include the required ICU DLLs.

Using the build files coming with SQLite3 Multiple Ciphers for building the library with ICU support, requires to define the environment variable LIBICU_PATH that must point to the directory to which the archive with the pre-built ICU libraries was extracted.

In addition, the Visual C++ 2019 runtime is required to be installed, because the ICU DLLs depend on it.

In principle, the ICU DLLs should be compatible with Visual C++ 2015 and Visual C++ 2017 as well.

Default settings

Currently the cipher scheme sqleet: ChaCha20 is set as the default. However, this can be changed by setting the preprocessor symbol CODEC_TYPE to one of the values listed in the following table:

Notes

• If compatibility with legacy sqleet is required, it is necessary to explicitly define the preprocessor symbol SQLITE3MC_USE_SQLEET_LEGACY.
• If compatibility with legacy SQLCipher is required, it is necessary to explicitly define the preprocessor symbol SQLITE3MC_USE_SQLCIPHER_LEGACY. If not the latest SQLCipher version, but a specific older one, should be selected, then the preprocessor symbol SQLCIPHER_VERSION_DEFAULT=version needs to be defined, where version can have one of the values 1, 2, 3, or 4.

Optional features

SQLite has many optional features and offers a vast number of optional extensions. The below table lists the features that are enabled for SQLite3 Multiple Ciphers as default. For details, please see SQLite Compile Time Options.

Note

• In case of memory constraints it is of course possible to disable unneeded features. However, this will require to modify the build files.

The source code of 3 extensions that require ZLIB support is also included, but is not enabled by default:

• COMPRESS
• SQLAR
• ZIPFILE

To enable one or more of those extensions, it is required to specify the corresponding preprocessor symbol:

To successfully compile these extensions it is required to specify for the compiler, where the ZLIB header can be found, and for the linker, the name and location of the ZLIB library. Alternatively, it is possible to use the included MINIZ library, a subset of ZLIB, by specifying the preprocessor symbol SQLITE3MC_USE_MINIZ=1. This allows to remove the external dependency on the ZLIB library.

TCL Interface

SQLite offers an implementation of a TCL interface and a TCL command shell. The source code of this interface is included with SQLite3 Multiple Ciphers.

Please consult the original SQLite documentation Compiling the TCL interface for further information, how to build the TCL interface and TCL command shell, since SQLite3 Multiple Ciphers does not contain build support for this feature.