: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
// sort-imports-ignore
import { DateTime } from 'luxon'
import { Group, GroupTypeIndex, ProjectId, TeamId } from '~/types'
import { parseJSON } from '~/common/utils/json-parse'
import { RaceConditionError } from '~/common/utils/utils'
import { BatchWritingGroupStore } from './batch-writing-group-store'
import { groupCacheOperationsCounter } from './metrics'
import { ClickhouseGroupRepository } from '~/common/groups/repositories/clickhouse-group-repository'
import { GroupCreateResult, GroupRepository } from '~/common/groups/repositories/group-repository.interface'
import { PostgresGroupRepository } from '~/common/groups/repositories/postgres-group-repository'
import { PostgresRouter, PostgresUse } from '~/common/utils/db/postgres'
import { GroupsOutput } from '~/common/outputs'
import { IngestionOutputs } from '~/common/outputs/ingestion-outputs'
// Mock the DB class
describe('BatchWritingGroupStore', () => {
let groupRepository: GroupRepository
let groupStore: BatchWritingGroupStore
let clickhouseGroupRepository: ClickhouseGroupRepository
let mockQueueMessages: jest.Mock
let teamId: TeamId
let projectId: ProjectId
let group: Group
beforeEach(() => {
teamId = 1
projectId = 1 as ProjectId
// Create a mock DB instance with all required methods
group = {
id: 1,
team_id: teamId,
group_type_index: 1,
group_key: 'test',
group_properties: { test: 'test' },
created_at: DateTime.now(),
version: 1,
properties_last_updated_at: {},
properties_last_operation: {},
}
let dbCounter = 0
// Create a mock GroupRepository
groupRepository = {
fetchGroup: jest.fn().mockImplementation(() => {
return Promise.resolve(group)
}),
fetchGroupsByKeys: jest.fn().mockResolvedValue([]),
updateGroupsBatch: jest.fn().mockResolvedValue([]),
insertGroupsBatch: jest.fn().mockResolvedValue([]),
insertGroup: jest.fn().mockImplementation(() => {
return Promise.resolve(1)
}),
updateGroup: jest.fn().mockImplementation(() => {
dbCounter++
return Promise.resolve(dbCounter)
}),
updateGroupOptimistically: jest.fn().mockImplementation(() => {
dbCounter++
return Promise.resolve(dbCounter)
}),
inTransaction: jest.fn().mockImplementation(async (_description, transaction) => {
// Create a proper mock transaction with the required methods
const mockTransaction = {
fetchGroup: jest.fn().mockImplementation(() => {
return Promise.resolve(group)
}),
insertGroup: jest.fn().mockImplementation(() => {
return Promise.resolve(1)
}),
updateGroup: jest.fn().mockImplementation(() => {
dbCounter++
return Promise.resolve(dbCounter)
}),
}
return await transaction(mockTransaction)
}),
} as unknown as GroupRepository
// Store the transaction mock for assertions
;(groupRepository as any).lastTransactionMock = null
groupRepository.inTransaction = jest.fn().mockImplementation(async (_description, transaction) => {
const mockTransaction = {
fetchGroup: jest.fn().mockImplementation(() => {
return Promise.resolve(group)
}),
insertGroup: jest.fn().mockImplementation(() => {
return Promise.resolve(1)
}),
updateGroup: jest.fn().mockImplementation(() => {
dbCounter++
return Promise.resolve(dbCounter)
}),
}
;(groupRepository as any).lastTransactionMock = mockTransaction
return await transaction(mockTransaction)
})
// Reset the counter before each test
groupCacheOperationsCounter.reset()
// Real repository over a mocked producer: buildUpsertMessage is pure,
// and only the inline create/fallback paths call queueMessages.
mockQueueMessages = jest.fn().mockResolvedValue(undefined)
clickhouseGroupRepository = new ClickhouseGroupRepository({
queueMessages: mockQueueMessages,
} as unknown as IngestionOutputs<GroupsOutput>)
// Pin the individual CAS flush path: it remains the fallback for
// missing rows and failed batch statements, so this block keeps it
// covered while `useBatchUpdates` describes the default batched path.
groupStore = new BatchWritingGroupStore(groupRepository, clickhouseGroupRepository, {
useBatchUpdates: false,
})
})
afterEach(async () => {
// Clear the metric-emission interval started in the constructor;
// unref() prevents it from blocking process exit, but we still want
// a clean slate between tests. Tests may leave dirty entries behind,
// so flush first — shutdown() throws on dirty cache by design.
try {
await groupStore?.flush()
} catch {
// ignore — some tests intentionally fail flush
}
try {
await groupStore?.shutdown()
} catch {
// ignore — some tests intentionally leave the cache dirty
}
jest.clearAllMocks()
})
it('should accumulate writes in cache, write once to db', async () => {
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: 'test' }, DateTime.now())
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { b: 'test' }, DateTime.now())
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { c: 'test' }, DateTime.now())
const results = await groupStore.flush()
expect(groupRepository.fetchGroup).toHaveBeenCalledTimes(1)
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(1)
expect(groupRepository.updateGroup).toHaveBeenCalledTimes(0)
expect(groupRepository.insertGroup).toHaveBeenCalledTimes(0)
expect(groupRepository.inTransaction).toHaveBeenCalledTimes(0) // Uses optimistic update for existing groups
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledWith(
teamId,
1,
'test',
1,
{ a: 'test', b: 'test', c: 'test', test: 'test' },
group.created_at,
{},
{}
)
// The ClickHouse message is returned for side-effect production, not produced inline.
expect(results).toHaveLength(1)
expect(results[0]).toMatchObject({ teamId, groupTypeIndex: 1, groupKey: 'test' })
expect(results[0].messages).toHaveLength(1)
expect(mockQueueMessages).not.toHaveBeenCalled()
const cacheMetrics = groupStore.getCacheMetrics()
expect(cacheMetrics.cacheHits).toBe(2)
expect(cacheMetrics.cacheMisses).toBe(0)
})
it('should immediately write to db if new group', async () => {
jest.spyOn(groupRepository, 'fetchGroup').mockResolvedValue(undefined)
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: 'test' }, DateTime.now())
expect(groupRepository.fetchGroup).toHaveBeenCalledTimes(1)
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(0)
expect(groupRepository.updateGroup).toHaveBeenCalledTimes(0)
// Creation is a single ON CONFLICT insert — no wrapping transaction.
expect(groupRepository.inTransaction).toHaveBeenCalledTimes(0)
expect(groupRepository.insertGroup).toHaveBeenCalledTimes(1)
// The ClickHouse message is NOT awaited inline (delivery reports on a
// backpressured producer stall the sequential per-distinct-id lane);
// it rides the next flush's side effects instead.
expect(mockQueueMessages).not.toHaveBeenCalled()
const results = await groupStore.flush()
expect(results).toHaveLength(1)
expect(results[0]).toMatchObject({ teamId, groupTypeIndex: 1, groupKey: 'test' })
})
it('should accumulate changes in cache after db write, even if new group', async () => {
jest.spyOn(groupRepository, 'fetchGroup').mockResolvedValue(undefined)
const createdAt = DateTime.now()
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: 'test' }, createdAt)
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { b: 'test' }, createdAt)
await groupStore.flush()
expect(groupRepository.fetchGroup).toHaveBeenCalledTimes(1)
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(1)
expect(groupRepository.updateGroup).toHaveBeenCalledTimes(0)
expect(groupRepository.inTransaction).toHaveBeenCalledTimes(0)
expect(groupRepository.insertGroup).toHaveBeenCalledTimes(1)
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledWith(
teamId,
1,
'test',
1,
{ a: 'test', b: 'test' },
createdAt,
{},
{}
)
})
it('should retry optimistic update if version mismatch', async () => {
let fetchCounter = 0
let updateCounter = 0
jest.spyOn(groupRepository, 'fetchGroup').mockImplementation(() => {
fetchCounter++
if (fetchCounter === 1) {
return Promise.resolve(group)
} else {
const updatedGroup = {
...group,
version: fetchCounter,
}
return Promise.resolve(updatedGroup)
}
})
jest.spyOn(groupRepository, 'updateGroupOptimistically').mockImplementation(() => {
updateCounter++
if (updateCounter < 3) {
// Fail the first two updates
return Promise.resolve(undefined)
}
return Promise.resolve(updateCounter)
})
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: 'test' }, DateTime.now())
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { b: 'test' }, DateTime.now())
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { c: 'test' }, DateTime.now())
await groupStore.flush()
// Should fetch 3 times, 1 for initial fetch, 2 for retries
expect(groupRepository.fetchGroup).toHaveBeenCalledTimes(3)
// Should make 3 updates, 2 failed, 1 successful
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(3)
expect(groupRepository.updateGroup).toHaveBeenCalledTimes(0)
expect(groupRepository.inTransaction).toHaveBeenCalledTimes(0) // Uses optimistic updates, not transactions
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledWith(
teamId,
1,
'test',
3,
{ a: 'test', b: 'test', c: 'test', test: 'test' },
group.created_at,
{},
{}
)
})
it('should fall back to direct upsert if optimistic update fails', async () => {
jest.spyOn(groupRepository, 'updateGroupOptimistically').mockResolvedValue(undefined)
jest.spyOn(groupRepository, 'updateGroup').mockResolvedValue(2)
// Conflict refetches return a group WITHOUT our properties, so the
// short-circuit doesn't kick in and every attempt retries.
jest.spyOn(groupRepository, 'fetchGroup').mockResolvedValue(group)
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: 'updated' }, DateTime.now())
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(0)
expect(groupRepository.updateGroup).toHaveBeenCalledTimes(0)
expect(mockQueueMessages).toHaveBeenCalledTimes(0)
const results = await groupStore.flush()
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(5)
expect(groupRepository.inTransaction).toHaveBeenCalledTimes(1)
expect((groupRepository as any).lastTransactionMock.updateGroup).toHaveBeenCalledTimes(1)
// The fallback path's ClickHouse message rides this flush's results
// instead of being produced inline.
expect(mockQueueMessages).not.toHaveBeenCalled()
expect(results).toHaveLength(1)
})
it('should share cache between distinct ids', async () => {
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: 'test' }, DateTime.now())
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { b: 'test' }, DateTime.now())
await groupStore.flush()
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(1)
expect(groupRepository.inTransaction).toHaveBeenCalledTimes(0) // Uses optimistic update for existing groups
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledWith(
teamId,
1,
'test',
1,
{ a: 'test', b: 'test', test: 'test' },
group.created_at,
{},
{}
)
})
it('keeps separate cache entries for two group types sharing a group key', async () => {
// A cache key without group_type_index would make the second upsert
// read the first type's cached row, merge both types' properties into
// one entry, and flush a single contaminated write.
jest.spyOn(groupRepository, 'fetchGroup').mockImplementation((_teamId, groupTypeIndex) =>
Promise.resolve({ ...group, group_type_index: groupTypeIndex, group_properties: {} })
)
await groupStore.upsertGroup(teamId, projectId, 0, 'shared-key', { a: '1' }, DateTime.now())
await groupStore.upsertGroup(teamId, projectId, 1, 'shared-key', { b: '2' }, DateTime.now())
await groupStore.flush()
expect(groupRepository.fetchGroup).toHaveBeenCalledTimes(2)
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(2)
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledWith(
teamId,
0,
'shared-key',
1,
{ a: '1' },
group.created_at,
{},
{}
)
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledWith(
teamId,
1,
'shared-key',
1,
{ b: '2' },
group.created_at,
{},
{}
)
})
it('should not write to db if no properties are changed', async () => {
// Mock the groupRepository.fetchGroup to return a group with the same properties
jest.spyOn(groupRepository, 'fetchGroup').mockResolvedValue(group)
await groupStore.upsertGroup(teamId, projectId, 1, 'test', group.group_properties, DateTime.now())
await groupStore.flush()
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(0)
expect(groupRepository.updateGroup).toHaveBeenCalledTimes(0)
expect(groupRepository.inTransaction).toHaveBeenCalledTimes(0)
// No transaction calls expected since no properties changed
})
it('should retry on race condition error and clear cache', async () => {
let fetchCounter = 0
jest.spyOn(groupRepository, 'fetchGroup').mockImplementation(() => {
fetchCounter++
if (fetchCounter === 1) {
return Promise.resolve(undefined)
} else {
return Promise.resolve(group)
}
})
// The group was created by another pod between our fetch and insert.
jest.spyOn(groupRepository, 'insertGroup').mockRejectedValueOnce(
new RaceConditionError('Parallel posthog_group inserts, retry')
)
// track cache delete
const groupCache = groupStore.getGroupCache()
const cacheDeleteSpy = jest.spyOn(groupCache, 'delete')
// Add to cache to verify it gets cleared on race condition
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: 'test' }, DateTime.now())
await groupStore.flush()
expect(groupRepository.insertGroup).toHaveBeenCalledTimes(1)
expect(groupRepository.fetchGroup).toHaveBeenCalledTimes(2) // Once for initial fetch, once for retry
expect(cacheDeleteSpy).toHaveBeenCalledWith(teamId, 1, 'test')
// The retry found the winning row and flushed our properties onto it.
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(1)
expect(groupRepository.updateGroupOptimistically).toHaveBeenLastCalledWith(
teamId,
1,
'test',
1, // version from second fetch
{ a: 'test', test: 'test' },
group.created_at,
{},
{}
)
})
it('should not write when object-valued properties are deeply equal', async () => {
// Object values arrive as fresh JSON parses each event; a reference
// compare here would dirty the group on every event and re-open the
// no-op write storm this store had in production.
group.group_properties = { nested: { plan: 'scale', seats: 5 } }
await groupStore.upsertGroup(
teamId,
projectId,
1,
'test',
{ nested: { plan: 'scale', seats: 5 } },
DateTime.now()
)
const results = await groupStore.flush()
expect(results).toHaveLength(0)
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(0)
})
it('should skip the retry when a conflicting writer already persisted the same properties', async () => {
jest.spyOn(groupRepository, 'updateGroupOptimistically').mockResolvedValue(undefined)
jest.spyOn(groupRepository, 'fetchGroup')
.mockResolvedValueOnce(group)
.mockResolvedValue({ ...group, group_properties: { test: 'test', a: 'test' }, version: 7 })
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: 'test' }, DateTime.now())
const results = await groupStore.flush()
// One failed CAS, then the refetch shows the winner already wrote our
// properties — no retries, no fallback, no ClickHouse message.
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(1)
expect(groupRepository.inTransaction).toHaveBeenCalledTimes(0)
expect(results).toHaveLength(0)
expect(groupStore.getGroupCache().get(teamId, 1, 'test')?.version).toBe(7)
})
describe('useBatchUpdates', () => {
beforeEach(() => {
groupStore = new BatchWritingGroupStore(groupRepository, clickhouseGroupRepository, {
useBatchUpdates: true,
})
})
it('flushes all dirty groups in one statement, routing each merged row and fallback to its own group', async () => {
// Each group gets its own row back, distinct rows include keys the
// DB merged from other pods, and one group is missing from the
// result (deleted or never created) so it falls back to an
// individual write.
jest.spyOn(groupRepository, 'fetchGroup').mockImplementation((_teamId, groupTypeIndex, groupKey) =>
Promise.resolve({ ...group, group_type_index: groupTypeIndex, group_key: groupKey })
)
const rowA = {
...group,
group_type_index: 0 as GroupTypeIndex,
group_key: 'g-a',
group_properties: { test: 'test', a: '1', from_other_pod: 'x' },
version: 5,
}
const rowB = {
...group,
group_type_index: 1 as GroupTypeIndex,
group_key: 'g-b',
group_properties: { test: 'test', b: '2' },
version: 9,
}
jest.spyOn(groupRepository, 'updateGroupsBatch').mockResolvedValue([rowA, rowB])
await groupStore.upsertGroup(teamId, projectId, 0, 'g-a', { a: '1' }, DateTime.now())
await groupStore.upsertGroup(teamId, projectId, 1, 'g-b', { b: '2' }, DateTime.now())
await groupStore.upsertGroup(teamId, projectId, 0, 'g-missing', { c: '3' }, DateTime.now())
const results = await groupStore.flush()
expect(groupRepository.updateGroupsBatch).toHaveBeenCalledTimes(1)
expect(groupRepository.updateGroupsBatch).toHaveBeenCalledWith([
{
teamId,
groupTypeIndex: 0,
groupKey: 'g-a',
propertiesToSet: { a: '1' },
createdAt: group.created_at,
},
{
teamId,
groupTypeIndex: 1,
groupKey: 'g-b',
propertiesToSet: { b: '2' },
createdAt: group.created_at,
},
{
teamId,
groupTypeIndex: 0,
groupKey: 'g-missing',
propertiesToSet: { c: '3' },
createdAt: group.created_at,
},
])
// Only the group missing from the batch result goes through the individual path.
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(1)
expect(jest.mocked(groupRepository.updateGroupOptimistically).mock.calls[0][2]).toBe('g-missing')
// Each ClickHouse message reflects that group's own authoritative row.
expect(results).toHaveLength(3)
const messagesByKey = new Map(
results.map((result) => [result.groupKey, parseJSON(result.messages[0].value.toString())])
)
expect(parseJSON(messagesByKey.get('g-a').group_properties)).toEqual(rowA.group_properties)
expect(messagesByKey.get('g-a').version).toBe(5)
expect(messagesByKey.get('g-a').group_type_index).toBe(0)
expect(parseJSON(messagesByKey.get('g-b').group_properties)).toEqual(rowB.group_properties)
expect(messagesByKey.get('g-b').version).toBe(9)
expect(messagesByKey.get('g-b').group_type_index).toBe(1)
// The cache converges on each group's own merged row.
expect(groupStore.getGroupCache().get(teamId, 0, 'g-a')?.version).toBe(5)
expect(groupStore.getGroupCache().get(teamId, 0, 'g-a')?.group_properties).toEqual(rowA.group_properties)
expect(groupStore.getGroupCache().get(teamId, 1, 'g-b')?.version).toBe(9)
expect(groupStore.getGroupCache().get(teamId, 1, 'g-b')?.group_properties).toEqual(rowB.group_properties)
})
it('falls back to individual writes when the batch statement fails', async () => {
jest.spyOn(groupRepository, 'updateGroupsBatch').mockRejectedValue(new Error('connection lost'))
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: '1' }, DateTime.now())
const results = await groupStore.flush()
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(1)
expect(results).toHaveLength(1)
})
})
describe('useBatchCreates', () => {
beforeEach(() => {
// Updates pinned to the individual path so create-routing
// assertions stay independent of the update flush mode.
groupStore = new BatchWritingGroupStore(groupRepository, clickhouseGroupRepository, {
useBatchCreates: true,
useBatchUpdates: false,
})
})
it('defers new groups to flush and inserts them in one statement, leaving updates on their own path', async () => {
const timestamp = DateTime.now()
// 'test' exists; the two new keys don't.
jest.spyOn(groupRepository, 'fetchGroup').mockImplementation((_teamId, _groupTypeIndex, groupKey) =>
Promise.resolve(groupKey === 'test' ? group : undefined)
)
const rowA = {
...group,
group_type_index: 0 as GroupTypeIndex,
group_key: 'new-a',
group_properties: { a: '1' },
created_at: timestamp,
version: 1,
inserted: true,
}
const rowB = {
...group,
group_type_index: 1 as GroupTypeIndex,
group_key: 'new-b',
group_properties: { b: '2' },
created_at: timestamp,
version: 1,
inserted: true,
}
jest.spyOn(groupRepository, 'insertGroupsBatch').mockResolvedValue([rowA, rowB])
await groupStore.upsertGroup(teamId, projectId, 0, 'new-a', { a: '1' }, timestamp)
await groupStore.upsertGroup(teamId, projectId, 1, 'new-b', { b: '2' }, timestamp)
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { u: '1' }, timestamp)
// No inline insert during event processing.
expect(groupRepository.insertGroup).not.toHaveBeenCalled()
expect(groupRepository.insertGroupsBatch).not.toHaveBeenCalled()
const results = await groupStore.flush()
expect(groupRepository.insertGroup).not.toHaveBeenCalled()
expect(groupRepository.insertGroupsBatch).toHaveBeenCalledTimes(1)
expect(groupRepository.insertGroupsBatch).toHaveBeenCalledWith([
{ teamId, groupTypeIndex: 0, groupKey: 'new-a', groupProperties: { a: '1' }, createdAt: timestamp },
{ teamId, groupTypeIndex: 1, groupKey: 'new-b', groupProperties: { b: '2' }, createdAt: timestamp },
])
// The existing group still goes through the regular update path.
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(1)
expect(jest.mocked(groupRepository.updateGroupOptimistically).mock.calls[0][2]).toBe('test')
// Each created group's ClickHouse message reflects its returned row.
expect(results).toHaveLength(3)
const messagesByKey = new Map(
results.map((result) => [result.groupKey, parseJSON(result.messages[0].value.toString())])
)
expect(parseJSON(messagesByKey.get('new-a').group_properties)).toEqual({ a: '1' })
expect(messagesByKey.get('new-a').version).toBe(1)
expect(parseJSON(messagesByKey.get('new-b').group_properties)).toEqual({ b: '2' })
expect(messagesByKey.get('new-b').version).toBe(1)
// The cache converges on the authoritative inserted rows.
expect(groupStore.getGroupCache().get(teamId, 0, 'new-a')?.version).toBe(1)
expect(groupStore.getGroupCache().get(teamId, 1, 'new-b')?.version).toBe(1)
})
it('accumulates repeated events for a new group into a single creation', async () => {
const timestamp = DateTime.now()
jest.spyOn(groupRepository, 'fetchGroup').mockResolvedValue(undefined)
jest.spyOn(groupRepository, 'insertGroupsBatch').mockResolvedValue([
{ ...group, group_key: 'new-key', group_properties: { a: '2', b: 'x' }, version: 1, inserted: true },
])
await groupStore.upsertGroup(teamId, projectId, 1, 'new-key', { a: '1' }, timestamp)
await groupStore.upsertGroup(teamId, projectId, 1, 'new-key', { a: '2', b: 'x' }, timestamp)
await groupStore.flush()
// One fetch, one batched insert carrying the merged view (later event wins).
expect(groupRepository.fetchGroup).toHaveBeenCalledTimes(1)
expect(groupRepository.insertGroupsBatch).toHaveBeenCalledTimes(1)
expect(groupRepository.insertGroupsBatch).toHaveBeenCalledWith([
{
teamId,
groupTypeIndex: 1,
groupKey: 'new-key',
groupProperties: { a: '2', b: 'x' },
createdAt: timestamp,
},
])
})
it('takes the merged row when a creation lost the cross-pod race, without extra round trips', async () => {
const timestamp = DateTime.now()
jest.spyOn(groupRepository, 'fetchGroup').mockResolvedValueOnce(undefined)
// The row already existed: the statement merged our properties onto
// the winner's row and flags it as not-inserted.
jest.spyOn(groupRepository, 'insertGroupsBatch').mockResolvedValue([
{
...group,
group_key: 'new-key',
group_properties: { test: 'test', a: '1' },
version: 6,
inserted: false,
},
])
await groupStore.upsertGroup(teamId, projectId, 1, 'new-key', { a: '1' }, timestamp)
const results = await groupStore.flush()
// No refetch, no CAS, no per-row insert — the merge already happened.
expect(groupRepository.insertGroup).not.toHaveBeenCalled()
expect(groupRepository.updateGroupOptimistically).not.toHaveBeenCalled()
expect(groupRepository.fetchGroup).toHaveBeenCalledTimes(1)
expect(results).toHaveLength(1)
const message = parseJSON(results[0].messages[0].value.toString())
expect(parseJSON(message.group_properties)).toEqual({ test: 'test', a: '1' })
expect(message.version).toBe(6)
expect(groupStore.getGroupCache().get(teamId, 1, 'new-key')?.version).toBe(6)
})
it('routes rows missing from the batch result through the individual update path', async () => {
// Postgres returns one row per input, but a misbehaving repository
// implementation (or a dropped guard) must not silently lose
// creations — the residue converges through the standard CAS path.
const timestamp = DateTime.now()
jest.spyOn(groupRepository, 'fetchGroup')
.mockResolvedValueOnce(undefined)
.mockResolvedValue({ ...group, group_key: 'new-key', version: 5 })
jest.spyOn(groupRepository, 'insertGroupsBatch').mockResolvedValue([])
jest.spyOn(groupRepository, 'updateGroupOptimistically')
.mockResolvedValueOnce(undefined) // version-0 CAS fails
.mockResolvedValueOnce(6)
await groupStore.upsertGroup(teamId, projectId, 1, 'new-key', { a: '1' }, timestamp)
const results = await groupStore.flush()
expect(groupRepository.insertGroup).not.toHaveBeenCalled()
// Rebased onto the winner: version 5, our delta merged on top.
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(2)
expect(groupRepository.updateGroupOptimistically).toHaveBeenLastCalledWith(
teamId,
1,
'new-key',
5,
{ test: 'test', a: '1' },
timestamp,
{},
{}
)
expect(results).toHaveLength(1)
expect(parseJSON(results[0].messages[0].value.toString()).version).toBe(6)
})
it('falls back to individual inserts when the batch create statement fails', async () => {
const timestamp = DateTime.now()
jest.spyOn(groupRepository, 'fetchGroup').mockResolvedValue(undefined)
jest.spyOn(groupRepository, 'insertGroupsBatch').mockRejectedValue(new Error('connection lost'))
await groupStore.upsertGroup(teamId, projectId, 0, 'new-a', { a: '1' }, timestamp)
await groupStore.upsertGroup(teamId, projectId, 1, 'new-b', { b: '2' }, timestamp)
const results = await groupStore.flush()
expect(groupRepository.insertGroup).toHaveBeenCalledTimes(2)
expect(results).toHaveLength(2)
const messagesByKey = new Map(
results.map((result) => [result.groupKey, parseJSON(result.messages[0].value.toString())])
)
expect(parseJSON(messagesByKey.get('new-a').group_properties)).toEqual({ a: '1' })
expect(parseJSON(messagesByKey.get('new-b').group_properties)).toEqual({ b: '2' })
})
it('claims pending creates synchronously at flush so a concurrent flush cannot double-insert', async () => {
const timestamp = DateTime.now()
jest.spyOn(groupRepository, 'fetchGroup').mockResolvedValue(undefined)
let resolveInsert: (rows: GroupCreateResult[]) => void = () => {}
jest.spyOn(groupRepository, 'insertGroupsBatch').mockImplementation(
() => new Promise<GroupCreateResult[]>((resolve) => (resolveInsert = resolve))
)
jest.spyOn(groupRepository, 'updateGroupOptimistically').mockResolvedValue(2)
await groupStore.upsertGroup(teamId, projectId, 1, 'new-key', { a: '1' }, timestamp)
// Kick off flush WITHOUT awaiting: the claim must happen before any
// DB I/O, so pendingCreate is already cleared here.
const firstFlush = groupStore.flush()
const entry = groupStore.getGroupCache().get(teamId, 1, 'new-key')
expect(entry?.pendingCreate).toBe(false)
expect(entry?.needsWrite).toBe(false)
// Re-dirty the key while the insert is still in flight — a second
// flush must capture it as a regular update, not a second insert.
await groupStore.upsertGroup(teamId, projectId, 1, 'new-key', { b: '2' }, timestamp)
const secondFlush = groupStore.flush()
resolveInsert([
{ ...group, group_key: 'new-key', group_properties: { a: '1' }, version: 1, inserted: true },
])
await Promise.all([firstFlush, secondFlush])
expect(groupRepository.insertGroupsBatch).toHaveBeenCalledTimes(1)
expect(groupRepository.insertGroup).not.toHaveBeenCalled()
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(1)
// The insert's older row (version 1) must not regress the cache
// entry the second flush already synced to its newer write.
expect(groupStore.getGroupCache().get(teamId, 1, 'new-key')?.version).toBe(2)
})
})
describe('prefetchGroups', () => {
it('serves subsequent upserts from the prefetched cache without single-row fetches', async () => {
jest.spyOn(groupRepository, 'fetchGroupsByKeys').mockResolvedValue([
{
team_id: teamId,
group_type_index: 1,
group_key: 'test',
group_properties: { test: 'test' },
created_at: group.created_at,
version: 1,
},
])
await groupStore.prefetchGroups([
{ teamId, groupTypeIndex: 1, groupKey: 'test', batchId: 0 },
{ teamId, groupTypeIndex: 1, groupKey: 'missing', batchId: 0 },
])
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: '1' }, DateTime.now(), 0)
// The missing key was negative-cached, so the create path goes
// straight to insert without another read.
await groupStore.upsertGroup(teamId, projectId, 1, 'missing', { b: '2' }, DateTime.now(), 0)
expect(groupRepository.fetchGroupsByKeys).toHaveBeenCalledTimes(1)
expect(groupRepository.fetchGroup).not.toHaveBeenCalled()
expect(groupRepository.insertGroup).toHaveBeenCalledTimes(1)
})
it('resolves when the read replica cancels the prefetch read for a recovery conflict', async () => {
// The caller does not await prefetchGroups, so a rejection here would stop the server.
const router = new PostgresRouter({ DATABASE_URL: 'postgres://fake', POSTGRES_CONNECTION_POOL_SIZE: 1 })
const replica = {
query: jest.fn().mockRejectedValue(new Error('Canceling statement due to conflict with recovery.')),
}
;(router as any).pools.set(PostgresUse.PERSONS_READ, replica)
const store = new BatchWritingGroupStore(new PostgresGroupRepository(router), clickhouseGroupRepository)
await expect(
store.prefetchGroups([{ teamId, groupTypeIndex: 1, groupKey: 'test', batchId: 0 }])
).resolves.toBeUndefined()
expect(replica.query).toHaveBeenCalledTimes(1)
})
})
describe('persistent cache (concurrentBatches > 1)', () => {
it('clears needsWrite on dirty entries synchronously during flush', async () => {
// Linearization point: flush() must clear needsWrite BEFORE awaiting
// any DB I/O. Any code path that introduces an await between the
// dirty-filter pass and the clear would re-open the cross-batch
// race documented in the design doc — this test guards against it.
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: 'test' }, DateTime.now())
const groupCache = groupStore.getGroupCache()
const dirtyBefore = Array.from(groupCache.entries()).filter(([_, u]) => u && u.needsWrite)
expect(dirtyBefore.length).toBeGreaterThan(0)
// Kick off flush WITHOUT awaiting it, then synchronously inspect
// needsWrite. If flush yields before clearing the flag, this will
// catch it — the assertion runs at the first microtask boundary.
const flushPromise = groupStore.flush()
const stillDirty = Array.from(groupCache.entries()).filter(([_, u]) => u && u.needsWrite)
expect(stillDirty).toHaveLength(0)
await flushPromise
})
it('re-dirty during flush window drives the next flush', async () => {
// After an entry is written and cleaned by a flush, a subsequent
// upsert with new properties re-dirties it, and the next flush picks
// up the delta.
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: '1' }, DateTime.now())
await groupStore.flush()
;(groupRepository.updateGroupOptimistically as jest.Mock).mockClear()
// Re-dirty via a second update with new properties. The cache is
// still referenced by batch 0 until releaseBatch() runs, so the
// second update merges with the first batch's cached properties.
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { b: '2' }, DateTime.now())
const dirtyAfter = Array.from(groupStore.getGroupCache().entries()).filter(([_, u]) => u && u.needsWrite)
expect(dirtyAfter.length).toBeGreaterThan(0)
await groupStore.flush()
// Second flush wrote the updated properties merged onto the still-referenced cache.
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledTimes(1)
expect(groupRepository.updateGroupOptimistically).toHaveBeenCalledWith(
teamId,
1,
'test',
1,
{ test: 'test', a: '1', b: '2' },
group.created_at,
{},
{}
)
})
})
describe('releaseBatch()', () => {
it('is a no-op for an unknown batchId', () => {
expect(() => groupStore.releaseBatch(999)).not.toThrow()
})
it('reports dirty entries and referenced batches in flush stats', async () => {
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: '1' }, DateTime.now(), 0)
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { b: '2' }, DateTime.now(), 1)
expect(groupStore.getFlushStats()).toEqual({
dirtyEntryCount: 1,
referencedBatchCount: 2,
cacheEntryCount: 1,
})
})
it('removes clean entries from cache after flush and release', async () => {
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: '1' }, DateTime.now())
await groupStore.flush()
expect(groupStore.getGroupCache().getSize()).toBe(1)
groupStore.releaseBatch(0)
expect(groupStore.getGroupCache().getSize()).toBe(0)
})
it('keeps entries that were re-dirtied during the DB write', async () => {
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: '1' }, DateTime.now())
// Re-dirty the entry during the async DB write after the linearization point.
jest.spyOn(groupRepository, 'updateGroupOptimistically').mockImplementationOnce(() => {
const entry = groupStore.getGroupCache().get(teamId, 1, 'test')
if (entry) {
entry.needsWrite = true
}
return Promise.resolve(2)
})
await groupStore.flush()
expect(groupStore.getGroupCache().getSize()).toBe(1)
expect(groupStore.getGroupCache().get(teamId, 1, 'test')?.needsWrite).toBe(true)
})
it('defers eviction of dirty entries until after flush', async () => {
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: '1' }, DateTime.now())
groupStore.releaseBatch(0)
expect(groupStore.getGroupCache().getSize()).toBe(1)
await groupStore.flush()
expect(groupStore.getGroupCache().getSize()).toBe(0)
})
it('keeps overlapping batch entries until the last release', async () => {
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: '1' }, DateTime.now(), 0)
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { b: '2' }, DateTime.now(), 1)
await groupStore.flush()
groupStore.releaseBatch(0)
expect(groupStore.getGroupCache().getSize()).toBe(1)
groupStore.releaseBatch(1)
expect(groupStore.getGroupCache().getSize()).toBe(0)
})
})
describe('shutdown()', () => {
it('succeeds without calling flush when no dirty entries exist', async () => {
const flushSpy = jest.spyOn(groupStore, 'flush')
await groupStore.shutdown()
expect(flushSpy).not.toHaveBeenCalled()
})
it('throws when dirty entries exist — caller must flush first', async () => {
// upsertGroup on an existing group with new properties marks the cache entry dirty
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: '1' }, DateTime.now())
expect(() => groupStore.shutdown()).toThrow(/dirty cache entries/)
})
it('emits accumulated metrics before throwing on dirty cache', async () => {
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: '1' }, DateTime.now())
const emitSpy = jest.spyOn(groupStore as any, 'emitAccumulatedMetrics')
expect(() => groupStore.shutdown()).toThrow()
expect(emitSpy).toHaveBeenCalledTimes(1)
})
it('explicit flush before shutdown succeeds', async () => {
await groupStore.upsertGroup(teamId, projectId, 1, 'test', { a: '1' }, DateTime.now())
await groupStore.flush()
await expect(groupStore.shutdown()).resolves.not.toThrow()
})
})
})