cozo-lib-swift

Cozo for Swift on Apple Hardware

This document describes how to set up the Cozo module for use in Swift on Apple hardware. To learn how to use CozoDB (CozoScript), read the docs.

This package can be used for MacOS (both Apple ARM and Intel) and iOS (iPad, iPhone and simulators).

Only the storage-sqlite persistent engine is enabled for the Swift prebuilt binaries, as using other storage engines on desktop or mobile does not make too much sense. If you disagree, see the Building section below.

Installation

CocoaPods

target 'YourApp' do
  use_frameworks!

  pod 'CozoSwiftBridge', '~> 0.7.1'
end

Swift Package Manager (SPM)

The package is published as an archive containing a Swift package. Download it from the release page (look for CozoSwiftBridge.tgz). Uncompress.

In XCode of your project, select from the menu File > Add Packages, select Add Local ... on the bottom, choose the folder you just decompressed (the one containing a Package.swift at the root), then click Add Package.

Then click your project on the left pane, and go to General > Frameworks, Libraries, and Embedded Content, click on the plus sign, and add Workspace > CozoSwiftBridge > CozoSwiftBridge (with a library icon).

If you did everything right, you should also see CozoSwiftBridge under Build Phases > Link Binary With Libraries.

You cannot download swift packages directly from GitHub repo, since in order to support that we would need to check the binaries into version control, and GitHub does not like it (we tried to work this around with Git LFS, but no luck).

Using the library

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()
}

Above we created an SQLite-based database. For memory-based ones:

let db = CozoDB()

API

public class CozoDB {
    public let db: DbInstance

    /**
    * Constructs an in-memory database.
    */
    public init();

    /**
    * Constructs a database.
    *
    * `kind`: the engine kind, can be `mem` or `sqlite`.
    * `path`: specifies the path to the storage file, only used for `sqlite` engine
    */
    public init(kind: String, path: String) throws;
    
    /**
     * Run query against the database.
     *
     * `query`:   the CozoScript to execute.
     */
    public func run(_ query: String) throws -> [NamedRow];
        
    /**
     * Run query against the database.
     *
     * `query`:   the CozoScript to execute.
     * `params`:  the params of the query in JSON format.
     */
    public func run(_ query: String, params: JSON) throws -> [NamedRow];
    
    /**
     * Export relations as JSON
     *
     * `relations`: the stored relations to export
     */
    public func exportRelations(relations: [String]) throws -> JSON;
    
    /**
     * Import data into relations
     * 
     * Note that triggers are _not_ run for the relations, if any exists.
     * If you need to activate triggers, use queries with parameters.
     * 
     * `data`: the payload, in the same format as returned by `exportRelations`. 
     */
    public func importRelations(data: JSON) throws;
   
    /**
     * Backup the database.
     *
     * `path`: path of the output file.
     */
    public func backup(path: String) throws;
    
    /**
     * Restore the database from a backup.
     *
     * `path`: path of the input file.
     */
    public func restore(path: String) throws;
    
    /**
     * Import data into a relation from a backup.
     *
     * Note that triggers are _not_ run for the relations, if any exists.
     * If you need to activate triggers, use queries with parameters.
     *
     * `path`:      path of the input file.
     * `relations`: the stored relations to import into.
     */
    public func importRelationsFromBackup(path: String, relations: [String]) throws;
}

More information are here.

Building the Swift Package

First, install the Rust toolchain. Then run the build script in this directory. It is recommended to also set the environment variable CARGO_PROFILE_RELEASE_LTO=fat: this makes the building process much longer, but in turn the library runs a little bit faster.

When everything goes well, you should find the compiled Swift package in a directory called CozoSwiftBridge.

If you want to use the RocksDB engine on Desktop, in the build script change the two lines

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

to

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

Then you also need to link your executable with libc++: in XCode, click on your project in the left drawer, then on the right go to Build phases > Link Binary With Libraries, click the plus sign, search for libc++, then add libc++.tbd found under Apple SDKs.

Similar same process goes if you want to enable other features. Note that building the RocksDB engine for mobile is a very demanding task!