# wcdb

**Repository Path**: ouyangpengdev/wcdb

## Basic Information

- **Project Name**: wcdb
- **Description**: WCDB is a cross-platform database framework developed by WeChat.
- **Primary Language**: C
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-03-23
- **Last Updated**: 2024-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WCDB

**中文版本请参看[这里][wcdb-wiki]**

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

* **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.
* **Multi-threaded concurrency**: WCDB supports concurrent read-read and read-write access via connection pooling.
* **Encryption Support**: WCDB supports database encryption via [SQLCipher][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 Carthage:** 
  1. Install [Carthage][install-carthage];
  2. Add `github "Tencent/WCDB"` to your Cartfile;
  3. Run `carthage update`.
  4. Drag `WCDB.framework` from the appropriate platform directory in `Carthage/Build/` to the `Linked Binary and Libraries` section of your Xcode project’s `Build Phases` settings;
  5. On your application targets' `Build Phases` settings tab, click the "+" icon and choose `New Run Script Phase`. Create a Run Script with  `carthage copy-frameworks` and add the paths to the frameworks under `Input Files`: `$(SRCROOT)/Carthage/Build/iOS/WCDB.framework` or `$(SRCROOT)/Carthage/Build/Mac/WCDB.framework`;
  6. Add `#import <WCDB/WCDB.h>` at the top of your Objective-C++ source files and start your WCDB journey.
  7. **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 Cocoapods:**
  1. Install [CocoaPods.](https://guides.cocoapods.org/using/getting-started.html)
  2. Run `pod repo update` to make CocoaPods aware of the latest available WCDB versions.
  3. In your Podfile, add `pod 'WCDB'` to your app target.
  4. From the command line, run `pod install`.
  5. Use the `.xcworkspace` file generated by CocoaPods to work on your project!
  6. Add `#import <WCDB/WCDB.h>` at the top of your Objective-C++ source files and start your WCDB journey.
  7. **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.**
  1. Getting source code from git repository. If cloning from git, submodules are required: `git submodule update --init --recursive`.
  2. Drag `WCDB.xcodeproj` in `wcdb/apple/` into your project;
  3. Add `WCDB.framework` to the `Target Dependencies` section and `Linked Binary and Libraries` of your Xcode project's `Build Phases` settings;
  4. Add `WCDB.framework` to the "Enbedded Binaries" section of your Xcode project's `General settings`;
  5. Add `#import <WCDB/WCDB.h>` at the top of your Objective-C++ source files and start your WCDB journey.
  6. **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 Static Framework:**
  1. Getting source code from git repository. If cloning from git, submodules are required: `git submodule update --init --recursive`.
  2. Drag `WCDB.xcodeproj` in `wcdb/apple/` into your project;
  3. Add `WCDB iOS Static` to the `Target Dependencies` section of your Xcode project's `Build Phases` settings;
  4. Add `WCDB.framework`， `libz.tbd` to the `Linked Binary and Libraries` section of your Xcode project's `Build Phases` settings; Note that there are two `WCDB.framework`, you should choose the one from `WCDB iOS Static` target.
  5. Add `-all_load` and `-ObjC` to the `Other Linker Flags` section of your Xcode project's `Build Settings`.
  6. Add `#import <WCDB/WCDB.h>` at the top of your Objective-C++ source files and start your WCDB journey.
  7. **Since WCDB is an Objective-C++ framework, for those files in your project that includes WCDB, you should rename their extension `.m` to `.mm`.**

## Tutorials

Tutorials can be found [here][iOS-tutorial].

## Documentations

* Documentations can be found on [our Wiki][wcdb-wiki].
* API references for iOS/macOS can be found [here][wcdb-docs-ios].

# WCDB for Android

## Features

* Database encryption via [SQLCipher][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: 

```gradle
dependencies {
    compile 'com.tencent.wcdb:wcdb-android:1.0.0'
    // Replace "1.0.0" 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`:

```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.*

```java
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:

```bash
$ 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`:

```bash
$ 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.

## Documentations

* Documentations can be found on [our Wiki][wcdb-wiki].
* API references for Android can be found [here][wcdb-docs-android].

[install-carthage]: https://github.com/Carthage/Carthage#installing-carthage
[wcdb-wiki]: https://github.com/Tencent/wcdb/wiki
[wcdb-docs-ios]: https://tencent.github.io/wcdb/references/ios/index.html
[wcdb-docs-android]: https://tencent.github.io/wcdb/references/android/index.html
[sqlcipher]: https://github.com/sqlcipher/sqlcipher
[iOS-tutorial]: https://github.com/Tencent/wcdb/wiki/iOS-macOS-Tutorial