sqlcipher3: DB-API 2.0 interface for SQLCipher 4.x

0.6.2 verified Fri May 01 auth: no python

sqlcipher3 provides a DB-API 2.0 compatible interface for SQLCipher 4.x, allowing encrypted SQLite databases. It wraps SQLCipher's C library and supports transparent 256-bit AES encryption of database files. Current version 0.6.2, requires Python >=3.9. Pre-built wheels available for many platforms; on some systems you may need to compile from source.

pip install sqlcipher3

Common errors

error ImportError: libsqlcipher.so.0: cannot open shared object file ↓

cause SQLCipher system library (libsqlcipher) is not installed or not found by the dynamic linker.

fix

Install libsqlcipher (e.g., apt install libsqlcipher-dev on Debian/Ubuntu, brew install sqlcipher on macOS) or use sqlcipher3-binary which bundles the library.

error sqlcipher3.dbapi2.DatabaseError: file is not a database ↓

cause Either the file exists and is encrypted but no key was provided, or the file is not a valid SQLite database.

fix

Ensure you call PRAGMA key='...' immediately after connecting. If opening an existing encrypted database, make sure the key matches the one used when it was created.

error RuntimeError: cipher settings can't be changed while a cipher operation is in progress ↓

cause Attempting to change PRAGMA key or cipher settings after executing other SQL statements on the same connection.

fix

Move all PRAGMA cipher settings (key, cipher_page_size, etc.) to immediately after connect(), before any other database operations.

Warnings

breaking sqlcipher3 is NOT compatible with sqlcipher (version 2.x) or pysqlcipher3. It only works with SQLCipher 4.x. If you have SQLCipher 3.x, you need a different library (e.g., `pysqlcipher3`). ↓

fix Ensure SQLCipher 4.x is installed (system library). Use `sqlcipher3-binary` if you cannot compile.

gotcha Opening a database without setting the key will fail with 'DatabaseError: file is not a database' if the file exists and is encrypted, or create an unencrypted database if new. Always set PRAGMA key immediately after connect. ↓

fix Call `PRAGMA key='your_key'` as first operation after `connect()`. For an existing DB, the key must match.

gotcha PRAGMA key and PRAGMA cipher_* settings must be executed on the same connection before any other queries. Changing these after data has been written can corrupt the database. ↓

fix Set all PRAGMAs immediately after opening the connection, before any CREATE/INSERT/UPDATE.

Install

pip install sqlcipher3-binary

Imports

connect

wrong

from pysqlcipher3 import dbapi2 as sqlite

correct

from sqlcipher3 import connect

Old pattern for pysqlcipher3, not compatible with sqlcipher3

dbapi2
wrong
```
import sqlcipher3 as sqlite
```
correct
```
from sqlcipher3 import dbapi2
```
Incorrect: sqlcipher3 itself is not a module with connect; use dbapi2 submodule

Quickstart

Create an in-memory encrypted database. PRAGMA key must be set before any other operations.

import os
from sqlcipher3 import dbapi2 as sqlite

conn = sqlite.connect(':memory:')
conn.execute("PRAGMA key='secret'")
conn.execute('CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)')
conn.execute('INSERT INTO test VALUES (1, "hello")')
print(conn.execute('SELECT * FROM test').fetchone())
conn.close()