安装
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