Install for Dart

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 Dart 3.10 or newer on the supported desktop targets.

For Flutter, use the version and platforms listed for the integration.

Installation

1. Add the package with this command.

dart pub add potluckdb

The package calls the runtime through dart:ffi. Its build hook runs when Dart builds your application. The hook downloads potluckdb-c-sdk-0.1.0-<target>.zip from https://downloads.potluckdb.com/releases/0.1.0/c-sdk/ for your target. Targets include iOS devices, iOS simulators, and Android ABIs.

The hook checks the archive’s SHA-256 digest against the value recorded in the package. The hook bundles the runtime and storage libraries as dynamic code assets for dart run and flutter build. The hook never compiles or relinks native libraries.

2. If you build offline or use a cache, specify your downloaded archive in pubspec.yaml.

hooks:
  user_defines:
    potluckdb:
      archive: /opt/potluckdb/potluckdb-c-sdk-0.1.0-macos-arm64.zip

The archive must match the requested target and recorded digest. archive is the only hook setting in 0.1.0. It changes neither the download URL nor the target. The hook resolves relative paths against the pubspec.yaml that declares the setting.

POTLUCKDB_RUNTIME_LIBRARY selects a runtime library when the application runs. It does not configure the build hook.

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 'package:potluckdb/potluckdb.dart';

void main() {
  final remote = Storage.fromS3(S3Options(bucket: 'my-bucket', namespace: 'notes', region: 'eu-west-1'));
  final db = open('app.potluckdb', remote: remote);
  db.close();
}

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.

Isolates

Dart isolates

Close every database before the Dart isolate that opened it ends. In this release, if an isolate ends while a database with an onSync hook remains open, the process aborts when its next automatic synchronization completes.

With Isolate.run, close the database inside the computation’s finally block. Before production gives the other closing rules.

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.

final options = OpenOptions(analyticalEngine: '/opt/potluckdb/lib/libduckdb.so');

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

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.