Reliability and completion
A write can be accepted before it is durable or queryable. Choose the completion boundary your application needs, and keep the original input until that boundary is established.
When is a write complete?
| Result | What it tells you | What it does not tell you |
|---|---|---|
| Admission response | The service accepted rows for processing | The rows are durable or visible to queries |
| Local commit | Recent rows were committed on the receiving server | They are published to object storage or visible through every client |
| Object upload | A data file reached object storage | The file is available in table queries |
| Published table data | The data is available through the table's stored history | Every view, index or live subscriber has caught up |
| Live event | A batch reached a subscription | The receiving application processed or durably stored it |
Kafka acks=1 and HTTP success report admission. HTTP requests can also be partly accepted. FlightRPC completion depends on the deployment's storage settings. See the interface matrix and each API's response description.
A development deployment using NoOp storage provides no object-storage durability.
Query visibility
PGWire streaming queries combine committed recent data with published history. Managed DuckDB and FlightSQL do not currently promise the same recent-data visibility. An early empty query result is not evidence that an ingestion request failed.
Views, full-text search and live subscriptions can lag behind the source table. Check the result you need instead of treating source-write success as completion of every operation.
Failures and recovery
A healthy cluster needs a majority of its replicas for metadata-dependent operations. Clients must reconnect after their serving node fails. Existing connections do not move between servers.
Recovery of catalog metadata does not imply recovery of all recently ingested rows. After complete loss of local state, recovery is limited to the latest completed backup and data that reached its documented durable boundary. Preserve the configured storage, encryption keys and cluster identity needed for restoration.
A cache of published historical files can be rebuilt from object storage. Unpublished recent data cannot be treated as that kind of disposable cache.
Retry decisions
A lost response can leave a write outcome unknown. The server may already have accepted some or all of the input. Replaying it can create duplicates.
- Keep the original input after a partial or unknown result.
- Reconcile accepted rows before replaying an uncertain request.
- Retry confirmed pre-admission rejections with bounded backoff.
- Use application event IDs to support reconciliation; an ID alone does not enable automatic server deduplication.
Automatic reconnection is not an exactly-once delivery guarantee.
Plan for your release
Use matching server, extension and client versions. Confirm the required write, read, authentication and recovery behavior for that release before production use. The interface matrix identifies preview features and current limits; these pages do not promise that every client or failure scenario is supported.
For operating procedures, see Cluster mode, Kubernetes and Metadata availability.