Interface compatibility
Choose an interface by the operation you need. A working connection does not mean that all clients, SQL features, or failure cases behave the same way.
This page describes the available interfaces and their current limits. Use matching server and client versions, and confirm the required workflow for your release before production use. See Reliability and completion for acknowledgement and recovery boundaries.
SQL and catalog access
| Interface | Use it for | Limits |
|---|---|---|
| PGWire | DuckDB SQL, parameterized queries, catalog DDL and streaming INSERT | PostgreSQL wire protocol, not a full PostgreSQL server. COPY FROM STDIN ingestion is not implemented. |
| Managed DuckDB | Native DuckDB using the BoilStream extension to run SQL remotely | Attach by catalog UUID. Direct DuckDB-WASM attachment is unavailable. |
| FlightSQL | Arrow query results and metadata discovery | Preview: use within a trusted deployment. Prepared statements, writes, bulk ADBC ingestion and cross-tenant authorization are outside the supported contract. |
PGWire streaming queries combine committed recent data with published history. Managed DuckDB and FlightSQL do not currently promise equivalent access to unpublished recent rows. An early empty result does not mean an ingestion request failed.
Streaming INSERT and ordinary warehouse SQL have different completion rules. See Reliability and completion before choosing retries.
Produce and consume rows
| Interface | Data format | What completion means |
|---|---|---|
| Kafka produce | RecordBatch v2 containing Confluent Avro records | acks=1 confirms memory admission; acks=0 sends no response. Replication acknowledgements and transactions are unavailable. |
| HTTP/2 Arrow | Arrow IPC stream | The response reports admitted rows. A request can be partly accepted. |
| FlightRPC | Arrow batches through DoExchange | Completion depends on the storage settings. It does not establish publication or completion of every view, index or consumer. |
| SSE | Base64-encoded Arrow IPC events | Preview live delivery with reconnect catch-up. Gaps and repeated batches remain possible. |
| Kafka Fetch | Live data and retained local hot rows | Preview consumption; replay is limited to retained recent data. |
| Flight live cursors | Live Arrow batches | A subscription, not a durable SQL snapshot or a replay guarantee. |
Create the target table in a streaming catalog before producing rows. Use each API's scoped token and TLS settings. Kafka, HTTP/2 and FlightRPC acceptance does not imply that rows have survived a node failure or are visible to every reader.
Retries and recovery
A lost connection can leave a write outcome unknown. Replaying the request may create duplicates. Preserve the original input until its outcome is known; use application identifiers and reconciliation where necessary. An identifier alone does not make the server deduplicate a write.
Clients may need to reconnect or reattach after a server failure. Catalog recovery, stored data and live delivery have different recovery limits. Test the required workload with the server and client versions you intend to deploy.