SQLCipher 4.7.0 Release

2025-03-25 08:00:00 -0400

We’re pleased to announce SQLCipher 4.7.0, which updates the baseline to SQLite 3.49.1 and includes several major improvements to memory management, library initialization, and cryptographic operations. This release represents the largest set of improvements since SQLCipher 4 and it should prove to be much faster and more efficient for most integrating applications.

Core Improvements and Breaking Changes

The new version of SQLCipher incorporates a major build system change introduced by upstream SQLite’s transition to use autosetup in version 3.48.0. This restructuring required corresponding changes to SQLCipher that substantially diverge from the historical build process. This resulted in several “breaking changes” to build flags and file output naming. We’ve taken advantage of this opportunity to introduce additional optimizations and security enhancements that also required major changes.

Since these changes mainly affect the library and executable build steps, they should primary affect integrators that are building from source (i.e. the Open Source Community Edition of SQLCipher). We have worked hard to minimize impact for Commercial and Enterprise customers; our official packages abstract away most of the underlying build system changes.

One notable inherited change from SQLite could affect all SQLCipher packages: the behavior of SELECT statements on encrypted databases prior to keying. SQLCipher’s documentation has always stated that applications should provide a key to the database via sqlite3_key(), sqlite3_key_v2(), or PRAGMA key as the first operation on a database connection. However, in previous versions of SQLCipher, it was technically possible to invoke schema-less statements (those that would not read from the database, e.g. SELECT 1) prior to keying. That is no longer possible in this release. Applications now MUST set the key prior to executing these types of statements as they do read the database file. This new requirement stems from a change to SQLite’s internal query parsing logic. Note that this change should not affect well-behaved applications that previously adhered to SQLCipher integration guidelines, but it still presents potential as a breaking change in some limited cases.

The following summarizes the breaking changes required for alignment with upstream SQLite and other improvements:

All packages:

• SELECT statements (including schema independent queries like SELECT 1) cannot be executed prior to setting the database key on encrypted database

Build system only:

• Renamed configure flag --enable-tempstore=yes to --with-tempstore=yes for alignment with SQLite
• Renamed default executable and library build outputs from sqlcipher and libsqlcipher to sqlite3 and libsqlite3
• Removed configure flag --with-crypto-lib (replace with appropriate -DSQLCIPHER_CRYPTO_* CFLAG)
• Required defining SQLITE_EXTRA_INIT=sqlcipher_extra_init and SQLITE_EXTRA_SHUTDOWN=sqlcipher_extra_shutdown at compile time
• Enforced thread safe mode (i.e. SQLITE_THREADSAFE of 1 or 2) and temporary storage (i.e. SQLITE_TEMP_STORE of 2 or 3) settings at compile time

This release also includes a substantial change to the library initialization and cleanup to reduce overhead and improve performance. As part of this change, SQLCipher now allocates most required memory at startup. This approach is more efficient, improves memory locking on constrained platforms while reducing memory fragmentation. It should reduce or eliminate mlock and VirtualLock warnings on Android and Windows respectively.

Additional core changes and improvements include:

• Fast random overwrite of freed memory segments
• Dynamic on-demand generation of keyspecs
• Expanded keyspec/raw key format to accept key, HMAC key, and salt values
• Basic obfuscation of context key material
• Expanded sqlcipher_provider interface with init and shutdown functions
• Support for .recover shell command on corrupt databases with a full plaintext first page
• Improved error handling in sqlcipher_export() and PRAGMA cipher_migrate
• Custom compile-time default cryptographic provider via the SQLCIPHER_CRYPTO_CUSTOM macro
• Removed support for OpenSSL versions older than 3.0

SQLCipher for Android

SQLCipher for Android includes two major library changes:

1. A new Cursor Window implementation makes fetching data much faster by avoiding round trips through Java and JNI layers. It also makes more efficient use of memory for objects of different sizes.
2. Adjustments to connection pool initialization during startup improves first-statement execution time for WAL-based Room databases by using the primary connection first and deferring pool expansion until it is strictly required.

Applications using SQLCipher for Android can expect to see measurable performance improvements with this upgrade, as evidenced by the following benchmarks:

UPDATE 2025-03-31: A 4.7.2 patch release is now available for the following: SQLCipher for Android (All Editions), SQLCipher for Android FIPS (Enterprise), and SQLCipher for React Native (Enterprise). It fixes two unpredictable defects in SQLCipher for Android 4.7.0’s new Cursor Window implementation that could cause a crash when a large query result set triggers a window resize with a fragmented heap. Applications using affected 4.7.0 packages should upgrade. Earlier versions of SQLCipher for Android below 4.7.0 are unaffected.

Commercial and Enterprise Editions

Most notably, the new version of SQLCipher Commercial and Enterprise packages include a massive performance improvement for multi-connection workloads. Applications with connection-heavy use cases that use multiple database handles to the same databases can expect to see a 100%+ speedup when establishing new connections. This can greatly enhance throughput for applications, especially with numerous concurrent connections or when using connection pools (e.g. on Java, Android, ADO.NET, EntityFrameworkCore, etc). These performance improvements are exclusive to Commercial and Enterprise builds.

For example, the following benchmarks show single and multi-threaded scenarios between 4.6.1 and 4.7.0, where each test executes 100 iterations, split up across threads, using a mixed set of operations. Numbers in parentheses reflect the number of threads and iterations per thread. While these were measured using EntityFrameworkCore in .NET, similar performance improvements are seen across all 4.7.0 packages.

In addition to the speed boost, there are a number of other improvements available solely to Commercial and Enterprise:

• ARM64 support in Windows FIPS packages
• ARM and ARM64 Linux FIPS packages
• Support for 16K page sizes in the Android FIPS package
• Updated Linux FIPS build for glibc 2.28 compatibility
• Support for code signing and embedded app bundles in macOS FIPS packages
• Improved error handling for FIPS module initialization
• Updated FIPS package cryptographic provider versions
• Excluded cryptographic symbols in the exposed API from libraries
• Modernized Android example project
• Updated System.Data.SQLite to version 1.0.119.0
• Changed .NET RIDs from win10 to win for improved compatibility
• Updated NuGet package dependencies to SQLitePCLRaw 2.1.11
• Enabled URI Filename processing
• Added WinUI sample project for .NET and removal of deprecated / legacy sample project
• Updated OpenSSL packages to 3.0.16 LTS
• Improved sample projects for .NET Microsoft.Data.Sqlite and EntityFramework Core

Important Note: Official SQLCipher packages shield customers from most of the breaking changes in the community edition, but there are two changes that customers must be aware of:

• Commercial and Enterprise edition upgrades now require a new license code from the SQLCipher fulfillment site for each version release. Going forward, when you upgrade your SQLCipher package, you should also update the license code in your application.
• As noted above, SELECT statements (including schema independent queries like SELECT 1) should not be executed on encrypted databases prior to setting the database key

Upgrading and Availability

SQLCipher 4.7.0 is available for download now. Due to the potentially breaking changes, we recommend testing your applications thoroughly with the new version before deploying to production.

Commercial and Enterprise - On-demand access to new releases of SQLCipher packages are available to all licensees with an active CipherCare support subscription from the Customer Downloads fulfillment site. Subscribers will also receive a separate email notification regarding the update and can contact us at any time for private support directly from the SQLCipher development team. Don’t forget to update your license code with this upgrade.

Community Edition - SQLCipher Community Edition source code is available on GitHub, via AAR packaging for Android, and CocoaPods for iOS.

For feedback and questions, please visit our Community Forum or private support channels.