Unlock WCDB Android: Encryption, Migration, FTS, and Performance Tips

Encryption Interface

WCDB uses the SQLCipher C library but abstracts away the manual PRAGMA statements required by SQLCipher Android. It introduces SQLiteCipherSpec to configure encryption parameters, which can be passed directly to the SQLiteDatabase factory method, eliminating the need to manage PRAGMA order.

Because SQLiteCipherSpec shares the same structure as the RepairKit interface, the same object can be used for database repair without a separate API.

WCDB also changes the password type from String to byte[], allowing non‑printable characters such as hash(user id) and maintaining compatibility with SQLCipher Android.

Data Migration

SQLCipher provides the sqlcipher_export function for exporting data to another database, but using it with SQLiteOpenHelper is cumbersome. WCDB extends this function to accept a second argument indicating the source, effectively turning it into an import operation without closing the original database, and remains compatible with SQLiteOpenHelper callbacks.

Full‑Text Search Tokenizer and Dynamic ICU Loading

WCDB Android ships with an FTS3/4 tokenizer named mmicu. It works like SQLite’s built‑in simple or icu tokenizers but adds special handling for Chinese characters and dynamic ICU library loading.

Because Android’s system ICU versions differ and include large data files, WCDB implements an icucompat layer that detects the system ICU version, uses dlopen to load the correct symbols, and provides a macro‑based compatibility shim. This allows developers to use ICU tokenization and normalization without bundling the heavy ICU library, saving over 10 MB in APK size.

Log Redirection and Performance Monitoring

By default, SQLite and WCDB log to logcat, which may expose sensitive information or be unsuitable for analysis. WCDB offers an API to redirect logs to a file or other destination; for high‑performance persistence, the Mars xlog component can be used.

WCDB also provides a SQLiteTrace interface that, when bound to a SQLiteDatabase, delivers callbacks on each SQL execution and connection‑pool contention, enabling fine‑grained performance monitoring.

The SQLiteDatabase.dump() method can print the current database state, including connection pool usage and recent SQL statements with execution times, aiding debugging of performance and deadlock issues.

Optimized Cursor Implementation

For simple query‑cursor‑iterate‑close patterns, WCDB offers SQLiteDirectCursor, which operates directly on SQLite’s query engine and avoids the overhead of allocating a CursorWindow. Developers must close the direct cursor promptly, as it holds a database connection until closed. Using it together with WAL and avoiding other DB operations on the same thread yields the best performance.

Follow WCDB

For the latest updates, visit the WCDB GitHub repository.