Skip to content
BoilStream

PGWire operations and limits

reference
TL;DR

Look up the supported SQL workflows and PostgreSQL-protocol limits before configuring a client. SQL follows DuckDB semantics, and compatibility is operation-specific. Streaming inserts are available in streaming catalogs; COPY FROM STDIN is unavailable. Clients must reconnect after node loss and reconcile interrupted writes before repeating them.

Message sequenceA PostgreSQL client opens a catalog-scoped SQL session
A PostgreSQL client opens a catalog-scoped SQL sessionThe client establishes TLS and authenticates to the selected catalog with temporary credentials. SQL requests and result rows travel through the same PGWire connection.psql / SQL toolBoilStreamTLS connection and credentialsAuthentication resultSQL for selected catalogRows, status or SQL errorTime moves downward · dashed arrows are responsesA PostgreSQL client opens a catalog-scoped SQL sessionThe client establishes TLS and authenticates to the selected catalog with temporary credentials. SQL requests and result rows travel through the same PGWire connection.psql / SQLtoolBoilStreamTLS connection andcredentialsAuthentication resultSQL for selected catalogRows, status or SQL errorTime moves downward · dashed arrows are responses
Use the catalog display name as the database name. Check expiry and permissions separately when a connection fails.
Jump to reference ↓

SQL workflows

Section titled “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.

Availability and retries

Section titled “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

Section titled “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.