{"id":23172,"library":"sqlcipher3","title":"sqlcipher3: DB-API 2.0 interface for SQLCipher 4.x","description":"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.","status":"active","version":"0.6.2","language":"python","source_language":"en","source_url":"https://github.com/coleifer/sqlcipher3","tags":["sqlcipher","encryption","database","sqlite","db-api"],"install":[{"cmd":"pip install sqlcipher3","lang":"bash","label":"Standard install (recommended)"},{"cmd":"pip install sqlcipher3-binary","lang":"bash","label":"Pre-compiled binary (avoids compilation)"}],"dependencies":[{"reason":"Required for compiling sqlcipher3 from source if no pre-built wheel available.","package":"libsqlcipher-dev","optional":true}],"imports":[{"note":"Old pattern for pysqlcipher3, not compatible with sqlcipher3","wrong":"from pysqlcipher3 import dbapi2 as sqlite","symbol":"connect","correct":"from sqlcipher3 import connect"},{"note":"Incorrect: sqlcipher3 itself is not a module with connect; use dbapi2 submodule","wrong":"import sqlcipher3 as sqlite","symbol":"dbapi2","correct":"from sqlcipher3 import dbapi2"}],"quickstart":{"code":"import os\nfrom sqlcipher3 import dbapi2 as sqlite\n\nconn = sqlite.connect(':memory:')\nconn.execute(\"PRAGMA key='secret'\")\nconn.execute('CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)')\nconn.execute('INSERT INTO test VALUES (1, \"hello\")')\nprint(conn.execute('SELECT * FROM test').fetchone())\nconn.close()","lang":"python","description":"Create an in-memory encrypted database. PRAGMA key must be set before any other operations."},"warnings":[{"fix":"Ensure SQLCipher 4.x is installed (system library). Use `sqlcipher3-binary` if you cannot compile.","message":"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`).","severity":"breaking","affected_versions":"all"},{"fix":"Call `PRAGMA key='your_key'` as first operation after `connect()`. For an existing DB, the key must match.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Set all PRAGMAs immediately after opening the connection, before any CREATE/INSERT/UPDATE.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"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.","cause":"SQLCipher system library (libsqlcipher) is not installed or not found by the dynamic linker.","error":"ImportError: libsqlcipher.so.0: cannot open shared object file"},{"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.","cause":"Either the file exists and is encrypted but no key was provided, or the file is not a valid SQLite database.","error":"sqlcipher3.dbapi2.DatabaseError: file is not a database"},{"fix":"Move all PRAGMA cipher settings (key, cipher_page_size, etc.) to immediately after `connect()`, before any other database operations.","cause":"Attempting to change PRAGMA key or cipher settings after executing other SQL statements on the same connection.","error":"RuntimeError: cipher settings can't be changed while a cipher operation is in progress"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}