fluidb/cozo-lib-swift/README-zh.md

Cozo Swift 库（仅支持苹果硬件）

本文叙述的是如何安装设置库本身。有关如何使用 CozoDB（CozoScript）的信息，见 文档 。

本库可在 macOS（苹果 ARM 或 Intel 芯片）以及 iOS（iPad、iPhone、模拟器）中使用。

预编译的二进制包里，持久化引擎中，只有 storage-sqlite 在此库中可用。如果需要其他引擎请从源码编译。

安装

CocoaPods

target 'YourApp' do
  use_frameworks!

  pod 'CozoSwiftBridge', '~> 0.6.0'
end

Swift Package Manager (SPM)

从 GitHub 发布页面 下载名为 CozoSwiftBridge.tgz 的包，然后手动导入至 XCode 中。详见 英文文档。

基本使用

import CozoSwiftBridge

{
    let path = NSHomeDirectory()
    let file = path + "/cozo-data.db"
    let db = CozoDB("sqlite", file)
    let res = try! db.run("?[] <- [[1,2,3]]").toString()
}

上例中创建了一个 SQLite 引擎支持的数据库。如果要用纯内存引擎：

let db = CozoDB()

API

public class CozoDB {
    public let db: DbInstance

    /**
    * 构造一个纯内存引擎的数据库
    */
    public init();

    /**
    * 构造一个数据库
    *
    * `kind`: 引擎类型，`mem` 或 `sqlite`。
    * `path`: 存储文件的路径，仅在 `sqlite` 引擎下有效。
    */
    public init(kind: String, path: String) throws;
    
    /**
     * 执行查询文本
     *
     * `query`:   查询文本
     */
    public func run(_ query: String) throws -> [NamedRow];
        
    /**
     * 执行查询文本
     *
     * `query`:   查询文本
     * `params`:  文本中可用的参数
     */
    public func run(_ query: String, params: JSON) throws -> [NamedRow];
    
    /**
     * 导出纯出表至 JSON
     *
     * `relations`: 需导出的表名
     */
    public func exportRelations(relations: [String]) throws -> JSON;
    
    /**
     * 导入数据至存储表中
     * 
     * 注意此方法不会激活任何触发器。
     * 
     * `data`: 导入内容，与 `exportRelations` 返回的格式相同 
     */
    public func importRelations(data: JSON) throws;
   
    /**
     * 备份数据库
     *
     * `path`: 备份路径
     */
    public func backup(path: String) throws;
    
    /**
     * 将备份恢复到当前数据库
     *
     * `path`: 备份路径
     */
    public func restore(path: String) throws;
    
    /**
     * 将备份中表里的数据插入当前数据库中选定的同名表中
     *
     * 注意此方法不会激活任何触发器。
     *
     * `path`:      备份路径
     * `relations`: 需要导入数据的表名
     */
    public func importRelationsFromBackup(path: String, relations: [String]) throws;
}

更多信息 见此 。

编译

首先安装 Rust 工具链。然后执行 此批处理文件 。建议执行时设置环境变量CARGO_PROFILE_RELEASE_LTO=fat：编译时间会变长，但是生成的库更快。

如果一切都没问题，则 CozoSwiftBridge 文件夹里会有编译好的文件。

如果想使用 RocksDB 引擎，则在批处理文件中，将以下两行

cargo build -p cozo-swift -F compact --target x86_64-apple-darwin --release
cargo build -p cozo-swift -F compact --target aarch64-apple-darwin --release

改为

cargo build -p cozo-swift -F compact -F storage-rocksdb --target x86_64-apple-darwin --release
cargo build -p cozo-swift -F compact -F storage-rocksdb --target aarch64-apple-darwin --release

注意，给 iOS 编译 RocksDB 不是一件简单的事情。

在使用生成的库时，需要在 XCode 中选择链接至 libc++ 动态库。