Skip to content

Commit 0e12bfc

Browse files
spicyfalafelclaude
andcommitted
docs: add retry, reconnect, and crash recovery details to BigQuery tutorial
Expand "Delivery Guarantees and Retry" section with: - gRPC reconnect behavior (UNAVAILABLE, ABORTED, etc.) - Worker crash recovery with exponential backoff - Initial export retry details and failure behavior Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 3132671 commit 0e12bfc

1 file changed

Lines changed: 15 additions & 2 deletions

File tree

docs/tutorials/subscriptions-tutorials/bigquery-aidboxtopicdestination.md

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -628,9 +628,22 @@ The emulator has a known limitation: `DATE` columns may return `null` when data
628628

629629
The module provides **at-least-once delivery**. Messages are persisted in a PostgreSQL queue before being sent to BigQuery. If delivery fails, the message remains in the queue and is retried on the next batch cycle (every `sendIntervalMs`). There is a 1-second backoff between failed delivery attempts to prevent log storms.
630630

631-
If the gRPC connection to BigQuery drops (network issue, server maintenance), the writer is automatically reconnected with exponential backoff. Messages are not lost during reconnection — they stay in the PG queue.
631+
### gRPC Reconnect
632632

633-
Initial export retries up to 3 times with exponential backoff (1s, 2s, 4s) on failure.
633+
If the gRPC connection to BigQuery drops (e.g., `UNAVAILABLE`, `ABORTED`, `INTERNAL`, stream closed, or connection reset), the module automatically closes and recreates both the `JsonStreamWriter` and `BigQueryWriteClient`. Messages are not lost during reconnection — they stay in the PostgreSQL queue and are delivered once the connection is restored.
634+
635+
### Worker Crash Recovery
636+
637+
If the delivery worker thread crashes with an unexpected error, it automatically restarts with exponential backoff (1 second initially, up to 60 seconds maximum). The PostgreSQL queue ensures no messages are lost between restarts.
638+
639+
### Initial Export Retry
640+
641+
Initial export retries up to 3 times with exponential backoff (1s → 2s → 4s, capped at 30s). If all attempts fail:
642+
643+
- The `initialExportStatus` is set to `failed`
644+
- The error message is available via the `$status` endpoint
645+
- Real-time delivery continues to work — only the initial export is affected
646+
- To retry, delete and recreate the destination
634647

635648
## Multiple Destinations
636649

0 commit comments

Comments
 (0)