Install for Rust

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 Rust 1.85 or newer on macOS, Linux, or Windows. Install curl for HTTPS downloads.

A Tauri application uses the same crate. The Tauri page gives the commands.

Installation

Add the dependency to your manifest.

cargo add potluckdb

The build downloads potluckdb-c-sdk-0.1.0-<target>.zip for your target from https://downloads.potluckdb.com/releases/0.1.0/c-sdk/. It checks the SHA-256 digest recorded in the crate before extracting the runtime and storage libraries.

If you build offline, do these steps:

1. Place the archives in a directory.
2. Set POTLUCKDB_ARCHIVE_DIR to that directory.

The build checks and uses those archives instead of downloading them. On musl targets, it links the runtime into the binary and downloads no storage library.

On other targets, the crate loads both libraries when the program runs. During development, it uses paths recorded during the build. A deployed application uses the executable’s directory or a macOS bundle’s Frameworks directory.

Setting	Purpose
POTLUCKDB_RUNTIME_LIBRARY	Select another runtime location when the program runs.
POTLUCKDB_STORAGE_LIBRARY	Select another storage library location when the program runs.
POTLUCKDB_RUNTIME_LIBRARY_PATH	Override the recorded runtime path and omit its download during the build.
POTLUCKDB_STORAGE_LIBRARY_PATH	Override the recorded storage library path and omit its download during the build.

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.

use potluckdb::storage::{from_s3, S3Options};

fn main() -> Result<(), potluckdb::PotluckDBError> {
    let remote = from_s3(S3Options::new("my-bucket", "notes").region("eu-west-1"))?;
    let mut db = potluckdb::open_with_remote("app.potluckdb", &remote)?;
    db.close()?;
    Ok(())
}

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 force_path_style.

Analytics

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

1. Enable the dependency’s analytics feature.

potluckdb = { version = "0.1.0", features = ["analytics"] }

The build downloads the upstream DuckDB archive for your target and checks the recorded SHA-256 digest. The runtime loads it without further configuration. The analytics engine page lists each archive’s URL and digest.

2. If you build offline, place the DuckDB archive beside the C SDK archive in POTLUCKDB_ARCHIVE_DIR.

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.