Installation and loading#

Stardust runs inside your application. Install the library and the binding for your language from the same release.

Each release is one ZIP. It holds the bindings, the examples and, in lib/<os>_<arch>/, the libraries for every supported platform: linux_amd64, linux_arm64, darwin_amd64, darwin_arm64 and windows_amd64. The bindings use the directory of the platform they run on or build for, so keep lib/ beside abi/ as the package has it.

Verify the download#

Check every download with minisign before you extract or load it. Each ZIP has a signature file beside it, <zip>.minisig. Inside the package, SHA256SUMS.minisig signs the list of file checksums.

1. Get the public key#

Key ID 07C74C0889E4B63A:

RWQ6tuSJCEzHB/QKjYG53zTssyTHd5YQquQc5Yhghw0NcvnoFMjkgkSf

The same key is at www.stardustdb.com/releases/minisign.pub, and in each signed package's README.txt. Compare downloaded keys with the key on this page. Do not trust a key supplied only by an archive. The key file's first line names the key ID; compare it with the ID above.

curl -fsSLO https://www.stardustdb.com/releases/minisign.pub

2. Install minisign#

macOS:

brew install minisign

Debian or Ubuntu:

sudo apt install minisign

Fedora:

sudo dnf install minisign

Windows:

winget install jedisct1.minisign

On Windows, open a new terminal after the install so that minisign is on PATH.

3. Verify the ZIP#

From Account / Releases, download both the ZIP and its signature file. Keep both files in the same folder. The signature filename must be the ZIP filename followed by .minisig. For example:

stardust-alpha-2610112101.zip
stardust-alpha-2610112101.zip.minisig

Run this in that folder before you extract the ZIP. Replace the version with the one you downloaded:

minisign -Vm stardust-<version>.zip -P RWQ6tuSJCEzHB/QKjYG53zTssyTHd5YQquQc5Yhghw0NcvnoFMjkgkSf

-p minisign.pub in place of -P <key> reads the downloaded key file. A good signature prints:

Signature and comment signature verified
Trusted comment: stardust <version>

The trusted comment names the version, for example stardust alpha-2610110018. Check that it matches the file you wanted.

4. Verify the files in the package#

Extract the ZIP, enter the package folder, and verify the checksum list:

minisign -Vm SHA256SUMS -P RWQ6tuSJCEzHB/QKjYG53zTssyTHd5YQquQc5Yhghw0NcvnoFMjkgkSf

Then check every file against it. Linux:

sha256sum -c SHA256SUMS

macOS:

shasum -a 256 -c SHA256SUMS

On Windows, in PowerShell:

& {
    $lines = @(Get-Content -LiteralPath SHA256SUMS -ErrorAction Stop)
    if ($lines.Count -eq 0) { throw "SHA256SUMS is empty" }
    foreach ($line in $lines) {
        if ($line -notmatch '^([0-9a-fA-F]{64})  (.+)$') { throw "Invalid checksum line: $line" }
        $expected = $Matches[1]
        $file = $Matches[2]
        $actual = (Get-FileHash -Algorithm SHA256 -LiteralPath $file -ErrorAction Stop).Hash
        if ($actual -ne $expected) { throw "Checksum mismatch: $file" }
    }
    "All files OK"
}

Success is a line ending in OK for every file, or All files OK in PowerShell.

When a check fails#

A failed check can mean a missing signature, a wrong key, or damaged files. Use the table below to correct the cause. Do not extract or load the ZIP until verification succeeds.

5. Clear the download mark#

Browsers mark downloaded files, and macOS and Windows then block or warn about them. Clear the mark only after steps 3 and 4 succeed. Run this next to the extracted folder. macOS:

xattr -dr com.apple.quarantine stardust-<version>

Windows, in PowerShell:

Get-ChildItem -Recurse stardust-<version> | Unblock-File

Linux needs no step.

Code signatures#

Releases carry no third-party publisher signature: no Apple Developer ID and no Windows Authenticode. The macOS libraries carry ad-hoc code signatures. ARM64 macOS refuses to load unsigned code, and an ad-hoc signature satisfies that rule. It names no publisher, so it does not show who built the file and does not replace minisign.

Install the core#

Extract the release archive. It contains the libraries for every platform under lib/<os>_<arch>/, bindings under abi/bindings/, and runnable examples under abi/examples/.

Keep every file in a platform directory together. The core library loads its plugin libraries only from its own directory, and only those it was built with. Plugin installation describes the plugin libraries and how a plugin becomes available. Each platform directory also holds the static archive, libstardust_full.a (stardust_full.lib on Windows), for static linking.

Use the installation quickstart for your language's build and run commands. The release examples use relative paths to the supplied library.

Language prerequisites#

Use a 64-bit runtime or compiler target that matches your release's operating system and CPU.

Before running a packaged example, set STARDUST_TEST_LICENSE to your downloaded license token.

Use Python 3.12 or newer with ctypes available. The binding and generated SDK use standard-library asyncio. Await native operations and use async with for their returned owners. For example, async with await stardust.open(path) as database opens and closes a database. Read subscription events and query rows with async for. Run these examples inside an async def function, then call asyncio.run(main()) at the program entry point. Put python3 on PATH, or use py -3 on Windows. The interpreter must have the same architecture as the release libraries. The packaged examples select abi/bindings/python automatically. For your application, install that package or add its directory to PYTHONPATH. The binding finds lib/<os>_<arch>/ for the platform it runs on when you preserve the release layout. Set STARDUST_LIBRARY to the core library file when using another layout. On Windows, PATH alone does not select libraries for ctypes.

python3 --version
python3 -c 'import ctypes; import struct; print(struct.calcsize("P") * 8)'

Run python3 evaluate.py from abi/examples/python, or py -3 evaluate.py on Windows.

See Linking for the build commands and runtime library search paths for your language.

Load the core#

The bindings use the C ABI. Go, Rust, Odin, and C link against the shared library by default, or link the static archive instead. Python and Clojure load the shared library at runtime. For the shared library, the runtime loader must find the core library when the application starts.

Python and Clojure can select a library file with STARDUST_LIBRARY. With Clojure release bindings, this file path or the -J-Dstardust.library=<file> system property is necessary for the core library's SHA-256 check. A loader search path alone does not supply the file path for this check.

Each binding in a release package carries the SHA-256 of that release's core library, and the signed SHA256SUMS covers both. Python and Clojure read the core library file and check it before they load it. Go, Rust, and Odin applications link the core library, so the system loader loads it first. These bindings check the loaded file before the first operation. A different core library fails every operation with the core_digest error, which names the file and both digests. Use each binding with the core library from the same release package. Bindings generated from a source checkout carry no digest and skip this check. A statically linked program has no core library file: the core is part of the executable, so the bindings skip this check. Verify the download before you link the archive. On Linux and macOS, executable PATH does not select shared libraries. On Windows, linked applications also need the supplied stardust.lib import library at build time.

Activate the core#

Call the binding's activate operation with your license token after loading the library. How your application gets the token is up to you: load it from a file you ship or deploy, or embed it in the application. Check its result before you create resources.

A successful activation verifies the token signature, dates, and library build date. A failed activation preserves the current license. The license operation reports the active state and the last activation failure.

The support-end date limits which library builds a license covers. It does not stop an eligible build from running later. An optional expiry date is checked at activation and database open. Existing resources keep working after expiry or license replacement, until you close them. This includes creating queries and mutations against an already open database. Replacing a license applies its plugin permissions to new databases.

Static linking#

Each platform directory of the release package also holds the static archive: libstardust_full.a on Linux and macOS, stardust_full.lib on Windows. Go, Rust, Odin and C programs can link it into one self-contained executable. The archive contains the core and every plugin of its release, so a statically linked program ships no library files: no core library and no plugin libraries. Linking gives each language's commands for both modes. The plugin set is fixed when you link the program. Plugins in a static link describes the differences.

Select plugins#

After loading the core, select any required plugins when you open a database. Plugin installation explains which plugins are available.

Troubleshooting#

S3 backup targets report a missing libcurl#

On Linux and macOS, S3 backup targets send their requests through the system libcurl. The backups plugin loads libcurl when the first S3 target opens. The core library, the plugin library and local file targets do not need it.

S3 targets need libcurl 7.84.0 or newer, built with thread-safe initialization and asynchronous DNS resolution. These capabilities keep initialization safe in a multithreaded application and let cancellation and deadlines interrupt DNS waits.

Older distribution packages can be below the minimum. Install a newer libcurl if necessary.

Without a usable libcurl, only the S3 targets fail. Their status names the cause and the minimum version, for example:

the system libcurl (libcurl.so.4) could not be loaded; libcurl 7.84.0 or newer is required

On Linux, the dynamic loader must find libcurl.so.4 in its default directories or in LD_LIBRARY_PATH. On macOS, the backend uses the system copy. Update macOS if that copy does not meet these requirements. Windows uses WinHTTP, which is part of Windows.

S3 requests do not follow redirects. Set the endpoint to the URL that answers directly. libcurl uses the https_proxy, http_proxy and no_proxy environment variables. WinHTTP uses the system WinHTTP proxy setting (netsh winhttp show proxy).