Installation¶

cysqlite can be installed four ways. Pick the one that fits:

Binary wheel, SQLite embedded, no build needed: pip install cysqlite.
Source build against the system SQLite: pip install --no-binary :all: cysqlite.
Self-contained build embedding a SQLite of your choosing, see Custom Builds.
Encrypted builds, see SQLCipher or SQLite Multiple Ciphers.

Wheels¶

pip install cysqlite

Wheels embed the SQLite release current at the time the cysqlite release was made, compiled with FTS3/FTS4/FTS5, JSON, R*Tree, STAT4, math functions, soundex, update/delete limit, load-extension support and SQLITE_MAX_VARIABLE_NUMBER=250000. Check any build with compile_option():

>>> import cysqlite
>>> cysqlite.sqlite_version
'3.53.3'
>>> cysqlite.compile_option('ENABLE_FTS5')
True

Building from source¶

Source builds need a C compiler and the Python development headers. Building against the system SQLite additionally needs the SQLite development headers (libsqlite3-dev on Debian, sqlite-devel on Fedora):

# Build against the system sqlite.
pip install --no-binary :all: cysqlite

To install the very latest commit:

# (note: links against system sqlite)
pip install -e git+https://github.com/coleifer/cysqlite.git#egg=cysqlite

Custom Builds¶

When a sqlite3.c / sqlite3.h pair is present in the root of the cysqlite checkout, it is compiled into the extension and the result is fully self-contained. The fetch_sqlite script downloads an amalgamation into place, either the current release or any release you name:

git clone https://github.com/coleifer/cysqlite
cd cysqlite/

./scripts/fetch_sqlite         # Current release, or:
./scripts/fetch_sqlite 3.51.2  # A specific version.

pip install .

The build prints the mode it resolved, e.g. cysqlite: building with bundled sqlite3.c. Verify the result:

>>> import cysqlite
>>> cysqlite.sqlite_version
'3.51.2'

When switching between build flavors, remove the build/ directory first so no stale objects are reused.

Self-contained sdist¶

A source distribution built from a checkout containing an amalgamation includes it, and installing that sdist produces a self-contained build. This is useful for distributing a pinned cysqlite+SQLite internally:

./scripts/fetch_sqlite 3.51.2
python -m build --sdist  # dist/cysqlite-*.tar.gz embeds sqlite 3.51.2.

SQLCipher¶

SQLCipher provides encryption. It does not publish a source amalgamation, so cysqlite includes a script that builds one. The script requires git, make, a C compiler and the OpenSSL development headers (libssl-dev on Debian):

git clone https://github.com/coleifer/cysqlite
cd cysqlite/

./scripts/fetch_sqlcipher         # Latest, or:
./scripts/fetch_sqlcipher v4.7.0  # A specific tag.

pip install .

SQLCipher sources are detected automatically and the build announces cysqlite: building with bundled sqlite3.c (sqlcipher). Set SQLCIPHER=0 to compile the same sources with the codec disabled. Verify:

>>> db = cysqlite.connect('app.db')
>>> db.execute_one('PRAGMA cipher_version')
('4.17.0 community',)

SQLite Multiple Ciphers¶

SQLite3 Multiple Ciphers also provides encryption, with no external crypto dependency. The fetch_sqlite3mc script downloads a release amalgamation and renames it into place:

git clone https://github.com/coleifer/cysqlite
cd cysqlite/

./scripts/fetch_sqlite3mc         # Latest release, or:
./scripts/fetch_sqlite3mc v2.5.0  # A specific tag.

pip install .

Or do the same by hand with a zip from the releases page:

unzip sqlite3mc-*-amalgamation.zip 'sqlite3mc_amalgamation.*'
mv sqlite3mc_amalgamation.c cysqlite/sqlite3.c
mv sqlite3mc_amalgamation.h cysqlite/sqlite3.h

Older amalgamation zips also contain the original SQLite sqlite3.c and sqlite3.h. Those are not the files to use.

The build announces cysqlite: building with bundled sqlite3.c (sqlite3mc). Verify:

>>> db = cysqlite.connect('app.db')
>>> db.execute("PRAGMA key='passphrase'")
>>> db.execute_one('PRAGMA cipher')
('chacha20',)