fluidb/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), follow the tutorial first and then read the manual. You can run all the queries described in the tutorial with an in-browser DB here.

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

Only the storage-sqlite 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.2.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-<VERSION>.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.

Using the library

import CozoSwiftBridge

...

let path = NSHomeDirectory()
let file = path + "/cozo-data.db"
let db = new_cozo_db("sqlite", file, "");
let result: String! = db?.run_script_str("::relations", "").toString();

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

let db = new_cozo_db("mem", "", "");

API

The function new_cozo_db can be used to create a database, passing in the engine type, the storage path, and options. The following methods are available on the returned database object:

extension DbInstanceRef {
    /**
     * Run query against a database.
     *
     * `payload`: a UTF-8 encoded C-string for the CozoScript to execute.
     * `params`:  a UTF-8 encoded C-string for the params of the query,
     *            in JSON format. You must always pass in a valid JSON map,
     *            even if you do not use params in your query
     *            (pass "{}" in this case).
     */
    public func run_script_str(_ payload: GenericToRustStr, _ params: GenericToRustStr) -> RustString;
    
    /**
     * Import data into relations
     * `data`: a UTF-8 encoded JSON payload, see the manual for the expected fields.
     */
    public func import_relations_str(_ data: GenericToRustStr) -> RustString;
    
    /**
     * Export relations into JSON
     *
     * `data`: a UTF-8 encoded JSON payload, , in the same form as returned by exporting relations
     */
    public func export_relations_str(_ data: GenericToRustStr) -> RustString;
   
    /**
     * Backup the database.
     *
     * `out_file`: path of the output file.
     */
    public func backup_db_str(_ out_file: GenericToRustStr) -> RustString;
    
    /**
     * Restore the database from a backup.
     *
     * `in_file`: path of the input file.
     */
    public func restore_backup_str(_ in_file: GenericToRustStr) -> RustString;
    
    /**
     * Import data into a relation
     *
     * `data`: a UTF-8 encoded JSON payload: `{"path": ..., "relations": [...]}`
     */
    public func import_from_backup_str(_ data: GenericToRustStr) -> RustString;
}

You can pass Swift strings as arguments. The returned types are all RustString: you need to call .toString() on them to convert to Swift strings, and then parse them as JSON objects (for example, by using SwiftyJSON.

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!