Install for Go

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 Go 1.22 or newer with cgo. cgo requires a C compiler.

The module includes a runtime library for these platforms:

Platform	Processor	C compiler
macOS	arm64, amd64	Xcode command line tools
Linux with glibc	amd64, arm64	gcc
Windows	amd64	MinGW-w64 gcc

The Linux library uses glibc. The module does not include a musl library because Go build constraints cannot distinguish these C libraries. The module does not include a Windows arm64 library because no GNU toolchain targets that platform through cgo. A build for either unsupported target fails during linking.

Installation

Directory remotes need only the Go module. Remotes that use a storage service also need the storage library.

1. Install the Go module with this command.

go get github.com/potluckdb/potluckdb-go

The module includes the header and static runtime libraries under lib/<release target>/. Its cgo directives select the directory for GOOS and GOARCH. The build links the runtime into your binary. This step downloads no separate runtime and needs no environment variable. The binary needs no runtime library file when it runs.

2. If you use your own runtime library, set CGO_LDFLAGS to its directory.

export CGO_LDFLAGS="-L/opt/potluckdb-c-sdk-0.1.0-<target>/lib -Wl,-rpath,/opt/potluckdb-c-sdk-0.1.0-<target>/lib"

This can select a local build or a shared library in your deployment. Environment flags precede the module’s flags, so the linker searches your directory first. On macOS and Linux, the -rpath option records the directory in the binary. The binary finds a shared library there when it runs.

3. On Windows, use only the -L option.
4. If that directory contains a DLL, put the DLL beside your binary.

If your remote uses a storage service, do these steps:

1. On your macOS, Linux, or Windows page, choose the row whose Go column matches your platform.
2. Download the C SDK archive from that row’s link.
3. Extract the archive.
4. Copy the storage library beside your binary.

The download server has no browsable directory.

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

The module does not include or link the storage library. The first storage service constructor loads it by name. The binary searches these locations in order:

• Beside its executable.
• In Contents/Frameworks for a macOS application bundle.
• In the platform’s library search locations.

When set, POTLUCKDB_STORAGE_LIBRARY names the library, and the binary does not search. A directory remote never loads the storage library.

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.

package main

import (
  "log"

  "github.com/potluckdb/potluckdb-go"
)

func main() {
  remote, err := potluckdb.FromS3(potluckdb.S3Options{Bucket: "my-bucket", Namespace: "notes", Region: "eu-west-1"})
  if err != nil {
    log.Fatal(err)
  }
  db, err := potluckdb.Open("app.potluckdb", remote, nil)
  if err != nil {
    log.Fatal(err)
  }
  defer 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.

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.

options := potluckdb.DefaultOpenOptions()
analyticalEngine := "/opt/potluckdb/lib/libduckdb.so"
options.AnalyticalEngine = &analyticalEngine

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.