Quick Start

Create a streaming table, insert a few rows and choose a query path. Start with a small dataset so you can check the returned rows before connecting a continuous producer.

Prerequisites

• A BoilStream server and an account with permission to create catalogs and tables.
• The TLS endpoint and login or bootstrap token supplied by your administrator.
• DuckDB 1.5 or newer, with the BoilStream extension for your server release. The extension must match the DuckDB version and platform. Do not assume an older DuckDB version works with a newer server or extension build.

Download server binaries and deployment instructions from the release repository. For a new server, run ./boilstream to generate its configuration, then follow Configuration and Authentication.

Development storage

The generated development configuration can use NoOp storage and temporary local paths. That setup does not provide object-storage durability. Configure a real storage backend before relying on persisted data.

Connect and create a catalog

In native DuckDB, install the extension build appropriate for your release. The community installation command is:

INSTALL boilstream FROM community;
LOAD boilstream;

-- Replace the URL and token with the bootstrap token from your dashboard.
PRAGMA boilstream_bootstrap_session('https://your-server.example/secrets:<token>');

PRAGMA boilstream_create_ducklake('events__stream', 'Quick Start events');
FROM boilstream_ducklakes();

The __stream suffix enables ingestion-topic provisioning for tables in the catalog. From the result, copy the catalog_id for the catalog you created. Creating or listing a catalog does not attach it to your DuckDB session.

-- Replace <catalog-uuid> with that catalog_id. events is a local SQL alias.
PRAGMA boilstream_attach_ducklake('<catalog-uuid>', 'events');
USE events;

CREATE TABLE main.activity (
    event_id BIGINT,
    event_type VARCHAR,
    event_time TIMESTAMP
);

INSERT INTO main.activity VALUES
    (1, 'view', TIMESTAMP '2026-01-01 12:00:00'),
    (2, 'click', TIMESTAMP '2026-01-01 12:00:01');

Keep the catalog UUID; it identifies the catalog even if its display name or local alias changes. Do not repeat the insert blindly after a lost connection: its outcome may be unknown, and event_id alone does not enable server-side deduplication.

Query recent streaming data

PGWire's streaming read path combines committed local hot rows with registered cold data. Get temporary PGWire credentials from the dashboard and connect to the streaming catalog:

psql "host=HOST port=PORT user=USER dbname=events__stream sslmode=verify-full sslrootcert=/path/to/ca.pem"

Replace the endpoint, user and CA path with your deployment values; enter the temporary password when prompted. Then run:

SELECT event_id, event_type, event_time
FROM main.activity
ORDER BY event_id;

After the hot commit, the expected rows are IDs 1 and 2, with event types view and click. Visibility depends on the configured commit cycle. Queue acceptance is not a read-visibility guarantee.

Query through managed DuckDB

In the DuckDB session attached above:

SELECT event_id, event_type, event_time
FROM events.main.activity
ORDER BY event_id;

This runs SQL remotely. Managed DuckDB does not currently promise the same visibility of unpublished recent data as PGWire. Use PGWire to check recent streaming rows, and do not interpret an early empty remote result as permission to resend the input.

Connect a producer

Once the table exists, use its scoped ingestion credentials:

• Kafka: Confluent Avro in RecordBatch v2; use acks=1 for admission responses. Replication acknowledgements and transactions are unavailable.
• HTTP/2 Arrow: upload Arrow IPC and check the admitted row count.
• FlightRPC: Arrow batches through DoExchange.
• PGWire: streaming INSERT; COPY FROM STDIN is unavailable.

See Interface compatibility and Reliability and completion before choosing retries or durability requirements. Examples builds on this same catalog and attachment workflow.