Install for Objective-C

Python · Node · Go · Rust · Swift · Dart · JVM · .NET · C++ · Objective-C

See Concepts for the runtime, remote, and synchronization terms used on this page.

Requirements

Use Xcode with Swift 5.9 or newer on macOS 11 or newer, or iOS 15 or newer.

Installation

The Objective-C interface belongs to the Swift package.

1. Add the package through Xcode’s File → Add Package Dependencies or through Package.swift.
2. Link the potluckdbObjC product.

dependencies: [
    .package(url: "https://github.com/potluckdb/potluckdb-swift", from: "0.1.0"),
],
targets: [
    .executableTarget(name: "App", dependencies: [.product(name: "potluckdbObjC", package: "potluckdb-swift")]),
]

Use the repository URL in the example for Xcode. The package includes the runtime as a binary framework. The storage library has one binary target per platform: a framework on iOS and a dylib on macOS.

A swift build product finds the storage library beside itself. An application bundle finds it in its Frameworks directory. When set, POTLUCKDB_STORAGE_LIBRARY names the library, and the binary does not search.

3. Import PotluckDBObjC.h.

You need no other installation steps.

Remote storage

A remote is the shared copy of a database that devices synchronize with. The quickstart uses a directory as its remote.

1. To use a storage service, replace the directory constructor with a storage service constructor.

#import "PotluckDBObjC.h"

static int fail(NSError *error) {
    fprintf(stderr, "%s\n", (error.localizedDescription ?: @"Operation failed").UTF8String);
    return 1;
}

int main(void) {
    int result = 0;
    @autoreleasepool {
        NSError *error = nil;
        PLKRemote *remote = [PLKStorage remoteFromS3Bucket:@"my-bucket"
                                               inNamespace:@"notes"
                                                    region:@"eu-west-1"
                                                  endpoint:nil
                                            forcePathStyle:NO
                                               accessKeyID:nil
                                           secretAccessKey:nil
                                              sessionToken:nil
                                                   options:nil
                                                     error:&error];
        if (remote == nil) return fail(error);
        PLKDatabase *db = [PLKDatabase openAtPath:@"app.potluckdb" remote:remote options:nil error:&error];
        if (db == nil) result = fail(error);
        else if (![db closeWithError:&error]) result = fail(error);
        if (![remote closeWithError:&error]) result = fail(error);
    }
    return result;
}

The rest of the program stays the same. The Google Cloud Storage and Azure Blob Storage constructors use the same form.

A credential chain tries the storage service’s standard sources for credentials. If you do not pass credentials, the constructor uses these sources:

• Environment variables.
• A profile.
• The host’s identity.

2. Configure the credential chain before you open the database.

The storage reference gives each constructor’s signature and parameters, including endpoint, region, and forcePathStyle.

Analytics

Analytical reads use DuckDB, a separate SQL engine for analysis. The core package does not contain DuckDB.

1. Download your platform’s library from the analytics engine page.
2. Specify the library in the open options.

PLKOpenOptions *options = [PLKOpenOptions new];
options.analyticalEngine = @"/opt/potluckdb/lib/libduckdb.dylib";

The analytics engine page lists each file’s URL and digest. POTLUCKDB_DUCKDB_LIBRARY selects a library for every database in the process.

3. On iOS, embed the library in the application bundle.

Licensing

Without a license key, potluckdb uses a trial. The licensing page explains the trial’s length and start, license key sources, and purchase steps.

Continue with the quickstart.