WCDB — WeChat Cross-Platform Database Framework

Introduction

WCDB is an efficient, complete, and easy-to-use mobile database framework created by the WeChat team at Tencent. It wraps SQLite with an ORM layer, built-in encryption via SQLCipher, automatic corruption repair, and schema migration tools. WCDB powers the database layer inside WeChat, handling billions of records across its user base.

What WCDB Does

• Provides a language-integrated ORM for Swift, Objective-C, Java, and Kotlin
• Encrypts databases transparently via an integrated SQLCipher layer
• Repairs corrupted database files automatically with its built-in recovery tool
• Supports schema migration without manual ALTER TABLE statements
• Offers full-text search using the FTS5 module with a simplified API

Architecture Overview

WCDB layers an ORM, connection pooling, and a CRUD interface on top of a customized SQLite build. The framework compiles SQLCipher into the same binary for seamless encryption. A write-ahead logging (WAL) mode and connection pool allow concurrent read/write access. The repair module can reconstruct a valid database from a corrupted file by reading raw B-tree pages.

Self-Hosting & Configuration

• Add WCDB via CocoaPods, Swift Package Manager, or Gradle for Android
• Encryption is enabled by passing a cipher key when opening the database
• Schema migrations are declared in code and applied automatically on open
• Enable WAL mode for better concurrent read/write performance (on by default)
• Configure the repair module to run automatically when corruption is detected

Key Features

• Integrated SQLCipher encryption with no separate dependency
• Automatic database repair recovers data from corrupted files
• ORM maps class properties to columns with compile-time type safety
• Connection pool with reader-writer separation for concurrent access
• Full-text search with Chinese tokenizer support

Comparison with Similar Tools

• Raw SQLite — requires manual SQL strings; WCDB provides ORM and encryption out of the box
• Realm — custom storage engine; WCDB stays on SQLite for broad compatibility
• Room (Android) — annotation-based ORM without encryption or repair; WCDB includes both
• FMDB — thin Objective-C wrapper; WCDB adds ORM, encryption, migration, and repair

FAQ

Q: Is WCDB only for WeChat? A: No. It is a general-purpose open-source framework usable in any iOS or Android application.

Q: Does WCDB support Kotlin Multiplatform? A: WCDB has native SDKs for iOS (Swift/ObjC) and Android (Java/Kotlin). It is not a Kotlin Multiplatform library.

Q: How does the repair feature work? A: WCDB reads raw SQLite B-tree pages and reconstructs a valid database, salvaging as much data as possible from the corrupt file.

Q: Can I use WCDB without encryption? A: Yes. Encryption is optional; omit the cipher key to use a plain SQLite database.

Sources

• https://github.com/Tencent/wcdb
• https://tencent.github.io/wcdb