Unlock High‑Performance Mobile Data with WCDB: iOS/Mac ORM & WINQ Guide

Preface

WCDB (WeChat Database) is the official mobile database component of WeChat, aiming to provide an efficient, easy‑to‑use, complete mobile storage solution.

It includes three modules:

WCDB‑iOS/Mac

WCDB‑Android

Database corruption repair tool WCDBRepair

It is currently being prepared for open‑source release.

Background

For iOS developers, choosing a database has always been a headache.

Because Apple’s CoreData framework is unsatisfactory, developers turn to the open‑source community for better storage solutions.

WeChat also faces the same problem. Databases are a fundamental component of WeChat; messaging, contacts, Moments, etc., all rely on them. We compared existing solutions:

Mobile database solutions can be divided into two categories:

Relational databases , e.g., CoreData, FMDB.

CoreData

FMDB

Key‑value databases , e.g., Realm, LevelDB, RocksDB.

Realm

Thus each solution has its own strengths and weaknesses; there is no universally best choice, only the most suitable one.

WeChat expects a database that satisfies:

Efficiency : fast CRUD and support for high‑concurrency multithreaded operations.

Ease of use : hide the boilerplate glue code required by raw SQLite.

Completeness : cover scenarios such as corruption repair, monitoring, complex queries, anti‑injection, etc.

None of the existing solutions fully meet these requirements, so we built our own “wheel” – WCDB‑iOS/Mac.

WCDB‑iOS/Mac

WCDB‑iOS/Mac (hereafter WCDB) is an Objective‑C++ component built on SQLite, offering:

Convenient ORM and CRUD interfaces : define tables and indexes without writing glue code.

WINQ (WCDB Integrated Query) : write SQL conditions, ordering, filtering without string concatenation.

Multithreaded high concurrency : basic CRUD interfaces support multithreaded access; reads can run concurrently, writes are serialized with SQLite‑based performance optimizations.

Corruption repair : built‑in WCDBRepair tool (see related articles).

Statistics : APIs to obtain SQL execution time for performance monitoring.

Anti‑injection : framework prevents SQL injection.

…

WCDB covers most database usage scenarios and has been validated by WeChat’s massive user base.

This article, the first in the WCDB series, introduces basic usage of WCDB‑iOS/Mac, including:

ORM, CRUD and Transaction

WINQ

Advanced usage

ORM

In WCDB, ORM (Object Relational Mapping) maps an ObjC class to a database table and its properties to table columns.

WCDB implements ORM via built‑in macros:

For an existing ObjC class:

Import the WCDB header #import <WCDB/WCDB.h> and adopt the WCTTableCoding protocol.

Use WCDB_PROPERTY in the header to declare fields bound to the table.

Use WCDB_IMPLEMENTATION in the implementation file to define the class and automatically implement WCTTableCoding.

Use WCDB_SYNTHESIZE to define bound fields.

These three macros resemble normal ObjC syntax, making them easy to remember.

WCDB also provides optional macros for defining indexes, constraints, etc., such as WCDB_PRIMARY, WCDB_INDEX, WCDB_UNIQUE, WCDB_NOT_NULL, …

After defining, call createTableAndIndexesOfName:withClass: to create the table and indexes.

CRUD

Thanks to ORM, WCDB enables object‑based CRUD operations.

Transaction

WCDB supports two ways to execute transactions:

Using the runTransaction: block‑based API.

Obtaining a WCTTransaction object that can be passed between classes or functions for more flexible control.

WINQ

WINQ (WCDB Integrated Query) integrates natural SQL queries into the WCDB framework using C++.

Traditional SQL requires string concatenation, which is error‑prone and vulnerable to injection. WINQ provides function‑like calls with IDE code completion and compiler checks.

For a class bound by ORM, you can write queries like Message.localID > 0, Message.content, Message.localID.order(), etc.

WINQ supports most SQLite syntax: unary operators (+, -, !), binary operators (||, &&, +, -, *, /, |, &, <<, >>, <, <=, ==, !=, >, >=), range comparisons (IN, BETWEEN), string matching (LIKE, GLOB, MATCH, REGEXP), aggregate functions (AVG, COUNT, MAX, MIN, SUM), …

Thus developers familiar with SQL can start using WINQ immediately.

Advanced Usage

as Redirection

Using ORM, you can fetch an object directly, but sometimes you need to map query results to a different field. The as(...) syntax redirects a query result to a specific property.

Chained Calls

WCDB provides chainable interfaces for CRUD operations, allowing calls like where, orderBy, limit to return self for fluent syntax.

Multi‑Table Queries

SQLite supports join queries; WCDB exposes them via WCTMultiSelect to fetch objects from multiple tables simultaneously.

Class Field Binding

WCDB supports binding many Objective‑C types (C strings, integers, floats, enums, NSString, NSData, NSArray, NSDictionary, NSSet, NSDate, NSNumber, NSURL, etc.). For unsupported types, developers can implement the WCTColumnCoding protocol with methods columnTypeForWCDB, unarchiveWithWCTValue:, and archivedWCTValue.

WCDB also provides file templates to simplify creating custom field bindings.

Summary

WCDB’s ORM and WINQ demonstrate its ease of use, eliminating complex glue code. Chainable calls provide performance metrics, and advanced features extend its capabilities.

Due to length limits, this article only covers WCDB’s surface features; future articles will dive into architecture, high‑concurrency solutions, and WINQ implementation details.