安装
WCDB提供了多种安装方式，请参考 README
类字段绑定（ORM）
在WCDB内，ORM（Object Relational Mapping）是指
- 将一个ObjC的类，映射到数据库的表和索引；
- 将类的property，映射到数据库表的字段；
这一过程。通过ORM，可以达到直接通过Object进行数据库操作，省去拼装过程的目的。
WCDB通过内建的宏实现ORM的功能。如下：
//Message.h @interface Message : NSObject @property int localID; @property(retain) NSString *content; @property(retain) NSDate *createTime; @property(retain) NSDate *modifiedTime; @property(assign) int unused; //You can only define the properties you need @end
//Message.mm #import "Message.h" @implementation Message WCDB_IMPLEMENTATION(Message) WCDB_SYNTHESIZE(Message, localID) WCDB_SYNTHESIZE(Message, content) WCDB_SYNTHESIZE(Message, createTime) WCDB_SYNTHESIZE(Message, modifiedTime) WCDB_PRIMARY(Message, localID) WCDB_INDEX(Message, "_index", createTime) @end
//Message+WCTTableCoding.h #import "Message.h" #import <WCDB/WCDB.h> @interface Message (WCTTableCoding) <WCTTableCoding> WCDB_PROPERTY(localID) WCDB_PROPERTY(content) WCDB_PROPERTY(createTime) WCDB_PROPERTY(modifiedTime) @end
将一个已有的ObjC类进行ORM绑定的过程如下：
- 定义该类遵循
WCTTableCoding协议。可以在类声明上定义，也可以通过文件模版在category内定义。 - 使用
WCDB_PROPERTY宏在头文件声明需要绑定到数据库表的字段。 - 使用
WCDB_IMPLEMENTATIO宏在类文件定义绑定到数据库表的类。 - 使用
WCDB_SYNTHESIZE宏在类文件定义需要绑定到数据库表的字段。
简单几行代码，就完成了将类和需要的字段绑定到数据库表的过程。这三个宏在名称和使用习惯上，也都和定义一个ObjC类相似，以此便于记忆。
除此之外，WCDB还提供了许多可选的宏，用于定义数据库索引、约束等，如：
-
WCDB_PRIMARY用于定义主键 -
WCDB_INDEX用于定义索引 -
WCDB_UNIQUE用于定义唯一约束 -
WCDB_NOT_NULL用于定义非空约束 - ...
定义完成后，只需要调用createTableAndIndexesOfName:withClass:接口，即可创建表和索引。
WCTDatabase *database = [[WCTDatabase alloc] initWithPath:path]; /* CREATE TABLE messsage (localID INTEGER PRIMARY KEY, content TEXT, createTime BLOB, modifiedTime BLOB) */ BOOL result = [database createTableAndIndexesOfName:@"message" withClass:Message.class];
接口会根据ORM的定义，创建对应表和索引。
更多关于ORM定义，请参考：ORM使用教程
增删改查（CRUD）
得益于ORM的定义，WCDB可以直接进行通过object进行增删改查（CRUD）操作。开发者可以通过WCTDatabase和WCTTable两个类进行一般的增删改查操作。如下：
//插入 Message *message = [[Message alloc] init]; message.localID = 1; message.content = @"Hello, WCDB!"; message.createTime = [NSDate date]; message.modifiedTime = [NSDate date]; /* INSERT INTO message(localID, content, createTime, modifiedTime) VALUES(1, "Hello, WCDB!", 1496396165, 1496396165); */ BOOL result = [database insertObject:message into:@"message"];
//删除 //DELETE FROM message WHERE localID>0; BOOL result = [database deleteObjectsFromTable:@"message" where:Message.localID > 0];
//修改 //UPDATE message SET content="Hello, Wechat!"; Message *message = [[Message alloc] init]; message.content = @"Hello, Wechat!"; BOOL result = [database updateRowsInTable:@"message" onProperties:Message.content withObject:message];
//查询 //SELECT * FROM message ORDER BY localID NSArray<Message *> *message = [database getObjectsOfClass:Message.class fromTable:@"message" orderBy:Message.localID.order()];
WCTTable相当于预设了表名和类名的WCTDatabase对象，接口和WCTDatabase基本一致。
WCTTable *table = [database getTableOfName:@"message" withClass:Message.class]; //查询 //SELECT * FROM message ORDER BY localID NSArray<Message *> *message = [table getObjectsOrderBy:Message.localID.order()];
更多关于增删改查的接口，请参考：基础类、CRUD与Transaction
事务（Transaction）
WCDB内可通过两种方式执行事务，一是runTransaction:接口，如下：
BOOL commited = [database runTransaction:^BOOL { [database insertObject:message into:@"message"]; return YES; //return YES to commit transaction and return NO to rollback transaction. }];
这种方式要求数据库操作在一个BLOCK内完成，简单易用。
另一种方式则是获取WCTTransaction对象，如下：
WCTTransaction *transaction = [database getTransaction]; BOOL result = [transaction begin]; [transaction insertObject:message into:@"message"]; result = [transaction commit]; if (!result) { [transaction rollback]; NSLog(@"%@", [transaction error]); }
WCTTransaction对象可以在类或函数间传递，因此这种方式也更具灵活性。
更多关于事务的注意事项，请参考：基础类、CRUD与Transaction。
WINQ（WCDB语言集成查询）
WINQ（WCDB Integrated Query，音'wink'），是将自然查询的SQL集成到WCDB框架中的技术，基于C++实现。
传统的SQL语句，通常是开发者拼接字符串完成。这种方式不仅繁琐、易错，而且出错后很难定位到问题所在。同时也容易给SQL注入留下可乘之机。
而WINQ将查询语言集成到了C++中，可以通过类似函数调用的方式来写SQL查询。借用IDE的代码提示和编译器的语法检查，达到易用、纠错的效果。
字段映射与运算符
对于一个已绑定ORM的类，可以通过className.propertyName的方式，获得数据库内字段的映射，以此书写SQL的条件、排序、过滤等等所有语句。如下是几个例子：
/* SELECT MAX(createTime), MIN(createTime) FROM message WHERE localID>0 AND content IS NOT NULL */ [database getObjectsOnResults:{Message.createTime.max(), Message.createTime.min()} fromTable:@"message" where:Message.localID > 0 && Message.content.isNotNull()];
/* SELECT DISTINCT localID FROM message ORDER BY modifiedTime ASC LIMIT 10 */ [database getObjectsOnResults:Message.localID.distinct() fromTable:@"message" orderBy:Message.modifiedTime.order(WCTOrderedAscending) limit:10];
/* DELETE FROM message WHERE localID BETWEEN 10 AND 20 OR content LIKE 'Hello%' */ [database deleteObjectsFromtable:@"message" where:Message.local.between(10, 20) || Message.content.like("Hello%")];
由于WINQ通过接口调用实现SQL查询，因此在书写过程中会有IDE的代码提示和编译器的语法检查，从而提升开发效率，避免写错。
WINQ的接口包括但不限于：
- 一元操作符：+、-、!等
- 二元操作符：||、&&、+、-、*、/、|、&、<<、>>、<、<=、==、!=、>、>=等
- 范围比较：IN、BETWEEN等
- 字符串匹配：LIKE、GLOB、MATCH、REGEXP等
- 聚合函数：AVG、COUNT、MAX、MIN、SUM等
- ...
凡是SQLite支持的语法规则，WINQ基本都有其对应的接口。且接口名称与SQLite的语法规则基本保持一致。
字段组合
多个字段映射可通过大括号{}进行组合，如：
/* SELECT localID, content FROM message */ [database getAllObjectsOnResults:{Message.localID, Message.content} fromTable:@"message"];
/* SELECT * FROM message ORDER BY createTime ASC, localID DESC */ [database getObjectsOfClass:Message.class fromTable:@"message" orderBy:{Message.createTime.order(WCTOrderedAscending), Message.localID.order(WCTOrderedDescending)}];
AllProperties
在上述的组合中，大括号{}的语法实质是C++中列表std::list的隐式初始化。而className.AllProperties则用于获取类定义的所有字段映射的列表，如：
/* SELECT localID, content, createTime, modifiedTime FROM message */ [database getAllObjectsOnResults:Message.AllProperties fromTable:@"message"];
AnyProperty
className.AnyProperty用于指代SQL中的*，如：
/* SELECT count(*) FROM message */ [database getOneValueOnResult:Message.AnyProperty.count() fromTable:@"message"];
WINQ的使用上接近于C函数调用。对于熟悉SQL的开发者，无须特别学习即可立刻上手使用。
更多WINQ的具体实现，请参考：WINQ原理。
加密
WCDB提供基于sqlcipher的数据库加密功能，如下：
WCTDatabase *database = [[WCTDatabase alloc] initWithPath:path]; NSData *password = [@"MyPassword" dataUsingEncoding:NSASCIIStringEncoding]; [database setCipherKey:password];
全局监控
WCDB提供了对错误和性能的全局监控，可用于调试错误和性能。
//Error Monitor [WCTStatistics SetGlobalErrorReport:^(WCTError *error) { NSLog(@"[WCDB]%@", error); }];
//Performance Monitor [WCTStatistics SetGlobalPerformanceTrace:^(WCTTag tag, NSDictionary<NSString *, NSNumber *> *sqls, NSInteger cost) { NSLog(@"Database with tag:%d", tag); NSLog(@"Run :"); [sqls enumerateKeysAndObjectsUsingBlock:^(NSString *sqls, NSNumber *count, BOOL *) { NSLog(@"SQL %@ %@ times", sqls, count); }]; NSLog(@"Total cost %lld nanoseconds", cost); }];
//SQL Execution Monitor [WCTStatistics SetGlobalSQLTrace:^(NSString *sql) { NSLog(@"SQL: %@", sql); }];
更多全局监控的细节，请参考：全局监控与错误处理
损坏修复
WCDB内建了修复工具，以应对数据库损坏，无法使用的情况。
开发者需要在数据库未损坏时，对数据库元信息定时进行备份，如下：
NSData *backupPassword = [@"MyBackupPassword" dataUsingEncoding:NSASCIIStringEncoding]; [database backupWithCipher:backupPassword];
当检测到数据库损坏，即WCTError的type为WCTErrorTypeSQLite，code为11或26（SQLITE_CORRUPT或SQLITE_NOTADB）时，可以进行修复。
//Since recovering is a long time operation, you'd better call it in sub-thread. [view startLoading]; dispatch_async(DISPATCH_QUEUE_PRIORITY_BACKGROUND, ^{ WCTDatabase *recover = [[WCTDatabase alloc] initWithPath:recoverPath]; NSData *password = [@"MyPassword" dataUsingEncoding:NSASCIIStringEncoding]; NSData *backupPassword = [@"MyBackupPassword" dataUsingEncoding:NSASCIIStringEncoding]; int pageSize = 4096;//Default to 4096 on iOS and 1024 on macOS. [database close:^{ [recover recoverFromPath:path withPageSize:pageSize backupCipher:cipher databaseCipher:password]; }]; [view stopLoading]; });
更多关于损坏修复的使用、原理以及修复工具2.0，请参考：TODO
本文使用 文章同步助手 同步
