Install for 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 a C++17 compiler and CMake on macOS, Linux, or Windows.

A Qt application links the same archive. The Qt page gives the CMake configuration.

Installation

1. Download potluckdb-c-sdk-0.1.0-<target>.zip for your platform.
2. Extract the archive, for example under /opt.

Use individual archive links on the macOS, Linux, or Windows page. The download server has no browsable directory. Extraction there creates /opt/potluckdb-c-sdk-0.1.0-<target>.

The archive contains these files:

• The header.
• The runtime as static and shared libraries.
• The storage library.
• The CMake package.
• The pkg-config file.

3. Link the potluckdb::cpp target with CMake.

find_package(potluckdb CONFIG REQUIRED)
target_link_libraries(app PRIVATE potluckdb::cpp)

Add these lines to your CMakeLists.txt after the executable target. The example names the target app.

4. Configure your build with the archive’s path.

cmake -S . -B build -DCMAKE_PREFIX_PATH=/opt/potluckdb-c-sdk-0.1.0-<target>

On macOS and Linux, potluckdb::cpp and pkg-config link the shared runtime library. CMake sets a runtime search path so that the program runs from its build directory. On Windows, they link the import library, which refers to a separate DLL.

Deploy the runtime library beside the executable. On macOS and Linux, set a runtime search path relative to the executable. On Windows, copy potluckdb_runtime_ffi.dll beside the executable. The Qt page also describes deployment with Qt.

Without CMake on macOS and Linux, set PKG_CONFIG_PATH to include /opt/potluckdb-c-sdk-0.1.0-<target>/lib/pkgconfig. Add the archive’s library directory to the runtime search path when you link the program. Replace <target> with your archive’s target.

c++ -std=c++17 main.cpp $(pkg-config --cflags --libs potluckdb) -Wl,-rpath,/opt/potluckdb-c-sdk-0.1.0-<target>/lib -o app

This command runs while the archive stays at that path. For deployment, change the runtime search path to the directory beside the executable.

If your remote uses a storage service, copy the storage library beside your program.

Platform	Storage library in the archive
macOS	lib/libpotluckdb_storage.dylib
Linux	lib/libpotluckdb_storage.so
Windows	bin/potluckdb_storage.dll

The program does not link the storage library. Its first storage service constructor loads the library. It searches beside the executable, then Contents/Frameworks in a macOS bundle, then the platform’s library locations. When set, POTLUCKDB_STORAGE_LIBRARY names the library, and the binary does not search. A directory remote never loads the library.

The CMake package sets potluckdb_STORAGE_LIBRARY to the archive’s library path. The pkg-config file exposes that path through storage_library. You can use either value to copy the library after 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.

#include "potluckdb.hpp"

int main() {
    potluckdb::storage::S3Options options;
    options.bucket = "my-bucket";
    options.namespace_ = "notes";
    options.region = "eu-west-1";
    auto remote = potluckdb::storage::from_s3(options);
    auto db = potluckdb::open("app.potluckdb", remote);
    db.close();
    return 0;
}

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. Download your platform’s library from the analytics engine page.
2. Specify the library in the open options.

potluckdb::OpenOptions options;
options.analytical_engine = "/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.