Connect native DuckDB

tutorial

TL;DR

Use the BoilStream extension in native DuckDB to authenticate, discover catalog UUIDs and attach a catalog under a local alias. The extension runs SQL remotely and handles short-lived credentials. Match its build to your DuckDB version and server release. Direct managed DuckDB-Wasm attachment is unavailable, and recent-row visibility differs from PGWire.

Message sequenceDiscover an authorized catalog before attaching it

Discovery does not attach a database. The native managed path and browser DuckDB-WASM have different capabilities.

Native DuckDB clients

Use DuckDB 1.5 or newer with the BoilStream extension. Its build must match your DuckDB version, platform and server release. Login and catalog discovery do not attach a catalog automatically.

INSTALL boilstream FROM community;
LOAD boilstream;

PRAGMA boilstream_bootstrap_session('https://your-server.example/secrets:<token>');
FROM boilstream_ducklakes();

-- Replace <catalog-uuid> with the selected catalog_id from the result.
PRAGMA boilstream_attach_ducklake('<catalog-uuid>', 'my_catalog');
USE my_catalog;
SELECT * FROM main.events LIMIT 10;

The alias my_catalog belongs to the client session. Use the catalog UUID returned by BoilStream. Queries run remotely, and the extension handles short-lived authentication. Clients verify the server’s TLS certificate and do not need catalog object-storage credentials. Direct managed attachment from DuckDB-WASM is unavailable.

For interactive login instead of a bootstrap token:

PRAGMA boilstream_login('https://your-server.example/user@example.com',
    'password', '123456');

Use the actual MFA code. Keep credentials out of saved scripts, logs and screenshots.

Verify access

Run a query against an existing authorized table and check its schema and expected rows. For unpublished recent streaming rows, use PGWire; an empty remote result does not justify resending input.

Reference

See extension commands and catalog creation.