PostgreSQL wire protocol

BoilStream accepts PostgreSQL wire-protocol connections for server-side DuckDB SQL. It supports the client workflows listed in the compatibility matrix, but it is not a PostgreSQL server and does not claim complete PostgreSQL dialect, extension, system-catalog, or client compatibility.

Connect

Get temporary PGWire credentials from the Web Auth GUI, then use the TLS endpoint supplied by your deployment:

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

Replace the connection values and CA path with your deployment settings; enter the temporary password when prompted. For the ingestion examples below, replace STREAMING_CATALOG with an authorized catalog whose name ends in __stream (for example, boil__stream if it has been provisioned). Credentials expire, so obtain fresh credentials when needed.

SQL workflows

Available operations include:

• simple queries and extended queries;
• prepared statements with parameter binding for tested data types;
• reads against authorized DuckLake catalogs and streaming hot/cold views;
• CREATE TABLE, supported ALTER TABLE, and DROP TABLE lifecycle operations;
• INSERT into authorized streaming DuckLakes; and
• catalog, schema, table, and column discovery used by tested clients.

SQL uses DuckDB semantics. A client that happens to speak PostgreSQL wire protocol can still depend on PostgreSQL-specific behavior that BoilStream does not implement. Validate the exact client and workflow before relying on it in production.

Select a catalog

The database name is the catalog display name visible to the authenticated user. The default warehouse catalog is duckie when automatic provisioning is enabled. Each tenant has its own catalog with that display name. Use a __stream catalog for streaming ingestion.

SHOW ALL TABLES;

-- After creating and populating events as shown below:
SELECT *
FROM main.events
WHERE event_time >= current_timestamp - INTERVAL 1 HOUR;

Catalog sharing reuses the owner's physical catalog after BoilStream authorizes the requester. Display names do not determine storage placement or authorization.

Create and ingest

DDL is authorized against the selected catalog:

CREATE TABLE main.events (
    event_time TIMESTAMP,
    event_type VARCHAR,
    value DOUBLE
);

Low-latency streaming ingestion is available only for a streaming DuckLake, whose display name ends in __stream:

INSERT INTO main.events VALUES (current_timestamp, 'click', 1.0);

For high-volume producers, use Kafka, HTTP/2 Arrow, or FlightRPC.

Availability and retries

In a three-node deployment, a client can reconnect to a healthy PGWire endpoint after a node or leader failure. Connections are not migrated between servers. If a connection is lost while a write is in flight, do not assume the write was rejected; use application identifiers or another idempotency strategy before retrying.

Validate the required client operations and recovery behavior with your server release. See the compatibility matrix for current limits.

Known limits

• COPY FROM STDIN ingestion is unavailable. Use streaming INSERT or a producer API.
• PostgreSQL server extensions, replication, and arbitrary PostgreSQL administrative commands are not part of this interface.
• Compatibility is operation-specific; support for psql does not imply support for every JDBC, ODBC, BI, or PostgreSQL client feature.
• DuckDB SQL and type behavior take precedence where PostgreSQL and DuckDB differ.
• Browser DuckDB-WASM does not use PGWire for managed catalog attachment.