Install for Node

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

An Electron application uses this package in its main process. See the Electron page for an example. A React Native application uses the module on the React Native page.

Installation

Install the package with this command.

npm install @potluckdb/potluckdb

The package uses CommonJS. An optional dependency installs the runtime for your platform with the storage library beside it. The package exports storage service constructors from @potluckdb/potluckdb/storage. You need no other installation steps.

A browser uses the separate @potluckdb/potluckdb-browser package. @potluckdb/potluckdb-node-wasm provides the Runtime Interface compiled to WebAssembly. That low-level interface differs from this application API.

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.

const potluckdb = require("@potluckdb/potluckdb");
const storage = require("@potluckdb/potluckdb/storage");

const remote = storage.fromS3({ bucket: "my-bucket", namespace: "notes", region: "eu-west-1" });

// The package is CommonJS, so `open` is awaited inside a function, as the
// quickstart's `main` does. A top-level `await` beside `require` is refused
// before the program runs.
async function main() {
  const db = await potluckdb.open("app.potluckdb", remote);
}

main();

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.

For an S3-compatible storage service other than Amazon S3, such as Cloudflare R2, MinIO, Wasabi or IDrive e2, set endpoint to its address.

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

A Node Worker is a thread created through worker_threads. In this release, the closing rules apply to every database a Worker opens, whatever its remote.

If you write your own storage adapter in JavaScript, pass it to Remote.fromStorage. A storage adapter implements storage operations for the remote.

Node Workers

Close every database and snapshot before the Worker that opened it ends or is terminated. In this release, a database left open cannot be opened again in that process.

Terminating a Worker while automatic synchronization waits on its JavaScript storage adapter keeps the Worker running. The process does not exit on its own. Close a JavaScript-backed remote after the databases and snapshots that use it. 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.

Install @potluckdb/potluckdb-analytics with this command.

npm install @potluckdb/potluckdb-analytics

The runtime loads the engine without further configuration.

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.