:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
Person batch writing configuration flags
This document describes the configuration flags that control person batch writing behavior during the transition period.
Flag matrix
| Flag | Type | Default | Description |
|---|---|---|---|
PERSON_BATCH_WRITING_DB_WRITE_MODE |
'NO_ASSERT' | 'ASSERT_VERSION' |
'NO_ASSERT' |
Controls concurrency handling strategy |
PERSON_BATCH_WRITING_USE_BATCH_UPDATES |
boolean |
true |
Use batch SQL queries vs individual queries |
PERSON_BATCH_WRITING_OPTIMISTIC_UPDATES_ENABLED |
boolean |
false |
Enable optimistic locking with retries |
PERSON_BATCH_WRITING_MAX_CONCURRENT_UPDATES |
number |
10 |
Max concurrent individual update queries |
PERSON_BATCH_WRITING_MAX_OPTIMISTIC_UPDATE_RETRIES |
number |
5 |
Max retries for optimistic update conflicts |
PERSON_BATCH_WRITING_OPTIMISTIC_UPDATE_RETRY_INTERVAL_MS |
number |
50 |
Delay between retry attempts (ms) |
Mode combinations
NO_ASSERT mode (default)
Writes the latest in-memory value to the database without version checks.
USE_BATCH_UPDATES |
Behavior |
|---|---|
true (default) |
Single batch SQL query for all updates. Falls back to individual queries on partial failure. |
false |
Individual queries per person, with merge retry logic. |
ASSERT_VERSION mode
Asserts the database version matches the in-memory version before writing. Enables optimistic concurrency control.
USE_BATCH_UPDATES |
Behavior |
|---|---|
true |
Not supported - falls through to individual queries |
false |
Individual queries with version assertion and retry logic |
Dependency constraints
ASSERT_VERSION mode
└── Requires: USE_BATCH_UPDATES = false (batching not compatible with version assertions)
└── Uses: MAX_OPTIMISTIC_UPDATE_RETRIES for conflict resolution
USE_BATCH_UPDATES = true
└── Only works with: NO_ASSERT mode
└── Fallback: Individual queries on batch partial failure
Flush code paths
flush()
├── NO_ASSERT + USE_BATCH_UPDATES=true → flushBatchNoAssert()
│ └── On partial failure → individual fallback with withMergeRetry()
├── NO_ASSERT + USE_BATCH_UPDATES=false → flushIndividualNoAssert()
│ └── Each update → withMergeRetry(updatePersonNoAssert)
└── ASSERT_VERSION → flushIndividualAssertVersion()
└── Each update → withOptimisticRetry(updatePersonAssertVersion)
Rollout strategy
- Current state:
NO_ASSERT+USE_BATCH_UPDATES=true(batch writes, no version checks) - Transition: Can disable batching with
USE_BATCH_UPDATES=falseto test individual writes