Function withSerializableTransaction

packages/internal/src/db/transaction.ts:176–235

({
  callback,
  context = {},
  logger,
}: {
  callback: TransactionCallback<T>
  context: Record<string, unknown>
  logger: Logger
})

 * @returns The result of the transaction
 */
export async function withSerializableTransaction<T>({
  callback,
  context = {},
  logger,
}: {
  callback: TransactionCallback<T>
  context: Record<string, unknown>
  logger: Logger
}): Promise<T> {
  return withRetry(
    async () => {
      return await db.transaction(callback, { isolationLevel: 'serializable' })
    },
    {
      maxRetries: 5, // Allow more retries for connection errors to recover
      retryDelayMs: INITIAL_RETRY_DELAY, // 1s, 2s, 4s, 8s, 16s exponential backoff
      retryIf: (error) => {
        // Only determine if error is retryable; logging happens in onRetry
        return getRetryableErrorDescription(error) !== null
      },
      onRetry: (error, attempt) => {
        const errorCode = getPostgresErrorCode(error) ?? 'unknown'
        const errorDescription =
          getRetryableErrorDescription(error) ?? 'unknown'
        // Calculate cumulative retry delay: 1s + 2s + 4s + ... (geometric series)
        const cumulativeDelayMs = INITIAL_RETRY_DELAY * (Math.pow(2, attempt) - 1)

        // Only log at WARN level after significant cumulative delay to avoid excessive logging
        // First few quick retries are expected behavior; extended retries indicate real issues
        if (cumulativeDelayMs >= SIGNIFICANT_RETRY_DELAY_MS) {
          logger.warn(
            {
              ...context,
              attempt,
              pgErrorCode: errorCode,
              pgErrorDescription: errorDescription,
              cumulativeDelayMs,
            },
            `Serializable transaction retry ${attempt}: ${errorDescription} (${errorCode}), cumulative delay ${(cumulativeDelayMs / 1000).toFixed(1)}s`,
          )

          // Track in PostHog for analytics
          trackEvent({
            event: AnalyticsEvent.TRANSACTION_RETRY_THRESHOLD_EXCEEDED,
            userId: getUserIdForAnalytics(context),
            properties: {
              ...context,
              transactionType: 'serializable',
              attempt,
              pgErrorCode: errorCode,
              pgErrorDescription: errorDescription,
              cumulativeDelayMs,
            },
            logger,
          })
        }
      },
    },