Install for JVM

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 JDK 17 or newer on macOS, Linux, or Windows.

For Android 13 or newer, use the Android package.

Installation

The packages use potluckdb’s Maven repository.

1. For a desktop application, add this repository and dependency.

repositories {
    maven("https://downloads.potluckdb.com/maven")
}
dependencies {
    implementation("dev.potluckdb:potluckdb-jvm:0.1.0")
}

The jar contains the runtime and storage library for every desktop target. It extracts both libraries beside each other. It loads the runtime through JNI.

2. With JDK 24 or newer, start the JVM with --enable-native-access=ALL-UNNAMED to avoid the library warning.

The quickstart includes this option.

For Android, the same repository provides dev.potluckdb:potluckdb:0.1.0. Its AAR, Android’s library archive, contains the runtime for arm64-v8a and x86_64. The Android page gives the module configuration and a Kotlin quickstart.

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 dev.potluckdb.*;

public class App {
    public static void main(String[] args) {
        Remote remote = Storage.fromS3(S3Options.builder("my-bucket", "notes").region("eu-west-1").build());
        Database db = PotluckDB.open("app.potluckdb", remote);
        db.close();
        remote.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.

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.

OpenOptions options = OpenOptions.builder().analyticalEngine("/opt/potluckdb/lib/libduckdb.so").build();

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 Android, place the library under the module’s jniLibs/<abi> directory.

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.