sqlcipher3-wheels

0.5.7 verified Sat May 09 auth: no python

A DB-API 2.0 interface for SQLCipher 3.x, providing encrypted SQLite databases. The 'wheels' variant includes precompiled SQLCipher binaries for easier installation. Current version: 0.5.7.

pip install sqlcipher3-binary

Common errors

error ImportError: No module named sqlcipher3 ↓

cause The package is installed as sqlcipher3-binary, not sqlcipher3. Importing sqlcipher3 works but is not the standard pattern.

fix

Ensure you have installed 'sqlcipher3-binary' and use 'from sqlcipher3 import dbapi2'.

error sqlite3.OperationalError: file is not a database ↓

cause Forgetting to set the encryption key with PRAGMA key before any other operation, or using an incorrect key.

fix

Immediately after conn = sqlite.connect(...), execute conn.execute("PRAGMA key = 'your_key'").

error cffi.error.CDefError: cannot parse 'void sqlcipher_codec_ctx_set_passphrase(...)' ↓

cause Incompatible version of cffi or missing C library headers.

fix

Upgrade cffi: pip install --upgrade cffi. If using a custom build, ensure the SQLCipher library is installed.

Warnings

breaking The package name on PyPI is sqlcipher3-binary, not sqlcipher3. Installing sqlcipher3 gives a different (often broken) version. ↓

fix pip install sqlcipher3-binary

gotcha The database connection must be closed explicitly (conn.close()) or used as a context manager to avoid locking issues. ↓

fix Use 'with sqlite.connect('db') as conn:' or ensure conn.close() is called.

deprecated PRAGMA key must be set immediately after opening the connection, before any other SQL commands. Failing to do so will result in "file is not a database" errors. ↓

fix Always run 'PRAGMA key = ...' as the first operation on the connection.

gotcha SQLCipher 3.x uses a different default encryption algorithm (AES-256-CBC) compared to SQLCipher 4.x (AES-256-CBC with PBKDF2). Ensure compatibility with your database files. ↓

fix Check the SQLCipher version and use consistent settings if sharing databases with other applications.

Imports

sqlcipher3
wrong
```
import sqlcipher3
```
correct
```
from sqlcipher3 import dbapi2 as sqlite
```
sqlcipher3 is a package; dbapi2 is the module that provides the connect function and DB-API 2.0 interface.
dbapi2
wrong
```
from sqlcipher3 import connect
```
correct
```
import sqlcipher3.dbapi2 as sqlite
```
connect function is inside dbapi2 module, you must import dbapi2 or use sqlcipher3.dbapi2.connect().

Quickstart

Create an encrypted SQLite database, set the encryption key with PRAGMA key, and execute a query.

import sqlcipher3.dbapi2 as sqlite
conn = sqlite.connect('encrypted.db')
conn.execute("PRAGMA key = 'secret'")
cursor = conn.execute("SELECT 'Hello, encrypted world!'")
print(cursor.fetchone()[0])
conn.close()