WCDB
中文版本请参看这里
WCDB is an efficient, complete, easy-to-use mobile database framework used in the WeChat application. It's currently available on iOS, macOS and Android.
WCDB for iOS/macOS
Features
-
Easy-to-use. Through WCDB, you can get objects from database in one line code.
-
WINQ (WCDB language integrated query): WINQ is a native data querying capability which frees developers from writing glue code to concatenate SQL query strings.
-
ORM (Object Relational Mapping): WCDB provides a flexible, easy-to-use ORM for creating tables, indices and constraints, as well as CRUD through ObjC objects.
[database getObjectsOfClass:WCTSampleConvenient.class fromTable:tableName where:WCTSampleConvenient.intValue>=10 limit:20];
-
-
Efficient. Through the framework layer and sqlcipher source optimization, WCDB have more efficient performance.
- Multi-threaded concurrency: WCDB supports concurrent read-read and read-write access via connection pooling.
- Batch Write Performance Test. For more benchmark data, please refer to our benchmark.
-
Complete.
- Encryption Support: WCDB supports database encryption via SQLCipher.
- Corruption recovery: WCDB provides a built-in repair kit for database corruption recovery.
- Anti-injection: WCDB provides a built-in protection from SQL injection.
Getting Started
Prerequisites
- Apps using WCDB can target: iOS 7 or later, macOS 10.9 or later.
- Xcode 8.0 or later required.
- Objective-C++ required.
Installation
- Via Cocoapods:
- Install CocoaPods.
- Run
pod repo update
to make CocoaPods aware of the latest available WCDB versions. - In your Podfile, add
pod 'WCDB'
to your app target. - From the command line, run
pod install
. - Use the
.xcworkspace
file generated by CocoaPods to work on your project! - Add
#import <WCDB/WCDB.h>
at the top of your Objective-C++ source files and start your WCDB journey. - **Since WCDB is an Objective-C++ framework, for those files in your project that includes WCDB, you should rename their extension
.m
to.mm
.
- Via Carthage:
- Install Carthage;
- Add
github "Tencent/WCDB"
to your Cartfile; - Run
carthage update
. - Drag
WCDB.framework
from the appropriate platform directory inCarthage/Build/
to theLinked Binary and Libraries
section of your Xcode project’sBuild Phases
settings; - On your application targets'
Build Phases
settings tab, click the "+" icon and chooseNew Run Script Phase
. Create a Run Script withcarthage copy-frameworks
and add the paths to the frameworks underInput Files
:$(SRCROOT)/Carthage/Build/iOS/WCDB.framework
or$(SRCROOT)/Carthage/Build/Mac/WCDB.framework
; - Add
#import <WCDB/WCDB.h>
at the top of your Objective-C++ source files and start your WCDB journey. - Since WCDB is an Objective-C++ framework, for those files in your project that includes WCDB, you should rename their extension
.m
to.mm
.
- Via Dynamic Framework:
Note that Dynamic frameworks are not compatible with iOS 7. See “Static Framework” for iOS 7 support.
- Getting source code from git repository and update the submodule of sqlcipher.
git clone https://github.com/Tencent/wcdb.git
cd wcdb
git submodule update --init sqlcipher
- Drag
WCDB.xcodeproj
inwcdb/apple/
into your project; - Add
WCDB.framework
to theEnbedded Binaries
section of your Xcode project'sGeneral settings
; Note that there are two frameworks here and the dynamic one should be chosen. You can check it atBuild Phases
->Target Dependencies
. The right one isWCDB
while `WCDB iOS Static is used for static lib. - Add
#import <WCDB/WCDB.h>
at the top of your Objective-C++ source files and start your WCDB journey. - Since WCDB is an Objective-C++ framework, for those files in your project that includes WCDB, you should rename their extension
.m
to.mm
.
- Getting source code from git repository and update the submodule of sqlcipher.
- Via Static Framework:
- Getting source code from git repository and update the submodule of sqlcipher.
git clone https://github.com/Tencent/wcdb.git
cd wcdb
git submodule update --init sqlcipher
- Drag
WCDB.xcodeproj
inwcdb/apple/
into your project; - Add
WCDB iOS Static
to theTarget Dependencies
section of your Xcode project'sBuild Phases
settings; - Add
WCDB.framework
,libz.tbd
to theLinked Binary and Libraries
section of your Xcode project'sBuild Phases
settings; Note that there are twoWCDB.framework
, you should choose the one fromWCDB iOS Static
target. - Add
-all_load
and-ObjC
to theOther Linker Flags
section of your Xcode project'sBuild Settings
. - Add
#import <WCDB/WCDB.h>
at the top of your Objective-C++ source files and start your WCDB journey. - Since WCDB is an Objective-C++ framework, for those files in your project that includes WCDB, you should rename their extension
.m
to.mm
.
- Getting source code from git repository and update the submodule of sqlcipher.
Tutorials
Tutorials can be found here.
Documentations
- Documentations can be found on our Wiki.
- API references for iOS/macOS can be found here.
- Performence data can be found on our benchmark.
WCDB for Android
Features
- Database encryption via SQLCipher.
- Concurrent access via connection pooling from modern Android framework.
- Repair toolkit for database corruption recovery.
- Database backup and recovery utility optimized for small backup size.
- Log redirection and various tracing facilities.
- API 12 (Android 3.1) and above are supported.
Getting Started
To include WCDB to your project, choose either way: import via Maven or via AAR package.
Import via Maven
To import WCDB via Maven repositories, add the following lines to build.gradle
on your
app module:
dependencies {
compile 'com.tencent.wcdb:wcdb-android:1.0.5'
// Replace "1.0.2" to any available version.
}
This will cause Gradle to download AAR package from jcenter while building your application.
Import Prebuilt AAR Package
1. Download AAR package from release page.
2. Import the AAR as new module. In Android Studio, select File -> New -> New Module...
menu and choose "Import JAR/AAR Package"
.
3. Add a dependency on the new module. This can be done using File -> Project Structure...
in Android Studio, or by adding following code to application's build.gradle
:
dependencies {
// Change "wcdb" to the actual module name specified in step 2.
compile project(':wcdb')
}
Migrate from Plain-text SQLite Databases
WCDB has interfaces very similar to Android SQLite Database APIs. To migrate you application from
AOSP API, change import path from android.database.*
to com.tencent.wcdb.*
, and
android.database.sqlite.*
to com.tencent.wcdb.database.*
. After import path update,
your application links to WCDB instead of AOSP API.
To open or create an encrypted database, use with-password versions of
SQLiteDatabase.openOrCreateDatabase()
, SQLiteOpenHelper.getWritableDatabase()
,
or Context.openOrCreateDatabase()
.
Note: WCDB uses byte[]
for password instead of String
in SQLCipher Android Binding.
String password = "MyPassword";
SQLiteDatabase db = SQLiteDatabase.openOrCreateDatabase("/path/to/database", password.getBytes(),
null, null);
See sample-encryptdb
for sample for transferring data between plain-text and encrypted
databases.
Corruption Recovery
See sample-repairdb
for instructions how to recover corrupted databases using RepairKit
.
Redirect Log Output
By default, WCDB prints its log message to system logcat. You may want to change this
behavior in order to, for example, save logs for troubleshooting. WCDB can redirect
all of its log outputs to user-defined routine using Log.setLogger(LogCallback)
method.
Build from Sources
Build WCDB Android with Prebuilt Dependencies
WCDB itself can be built apart from its dependencies using Gradle or Android Studio.
To build WCDB Android library, run Gradle on android
directory:
$ cd android
$ ./gradlew build
Building WCDB requires Android NDK installed. If Gradle failed to find your SDK and/or
NDK, you may need to create a file named local.properties
on the android
directory
with content:
sdk.dir=path/to/sdk
ndk.dir=path/to/ndk
Android Studio will do this for you when the project is imported.
Build Dependencies from Sources
WCDB depends on OpenSSL crypto library and SQLCipher. You can rebuild all dependencies if you wish. In this case, a working C compiler on the host system, Perl 5, Tcl and a bash environment is needed to be installed on your system.
To build dependencies, checkout all submodules, set ANDROID_NDK_ROOT
environment
variable to your NDK path, then run build-depends-android.sh
:
$ export ANDROID_NDK_ROOT=/path/to/ndk
$ ./build-depends-android.sh
This will build OpenSSL crypto library and generate SQLCipher amalgamation sources and place them to proper locations suitable for WCDB library building.