Skip to content

Conversation

@smoreinis
Copy link
Collaborator

@smoreinis smoreinis commented Dec 25, 2025

Summary

Optimize the event write path by using PostgreSQL's RETURNING clause to get the auto-generated sequence_id in a single query instead of two.

Before (2 queries per event)

session.add(orm)
await session.commit()
await session.refresh(orm)  # Extra SELECT to get sequence_id

After (1 query per event)

stmt = insert(EventORM).values(...).returning(EventORM)
result = await session.execute(stmt)
orm = result.scalar_one()
await session.commit()

Benchmark Results

Tested with 200 iterations on docker-to-docker network:

Metric OLD (add+refresh) NEW (RETURNING) Improvement
Mean latency 0.812ms 0.684ms 15.8% faster
Median 0.780ms 0.644ms 17.4% faster
P95 1.050ms 0.887ms 15.5% faster
P99 1.780ms 1.009ms 43.3% faster
Throughput 1,231 events/sec 1,462 events/sec +231 events/sec

Note: Docker-to-docker latency is ~0.1ms. In production with typical network latency (1-5ms), the improvement would be more significant since we're eliminating an entire network round-trip.

Test plan

  • All 20 event-related tests pass
  • All 188 unit tests pass
  • Verified sequence_id is correctly populated in returned entity
  • Benchmarked locally with 200 iterations

Replace session.add() + session.refresh() with insert().returning()
to get the auto-generated sequence_id in a single database round-trip.

Before: 2 queries per event (INSERT + SELECT)
After: 1 query per event (INSERT ... RETURNING *)

Expected ~33% reduction in database queries for event writes.
@smoreinis smoreinis requested a review from a team as a code owner December 25, 2025 00:10
Extends the single-query INSERT RETURNING pattern to all PostgreSQL
repositories by optimizing the base class create() method.

Key changes:
- Use insert().values().returning() instead of add() + refresh()
- Return explicit columns to avoid lazy-loading relationships
- Exclude None values to preserve server defaults (e.g., created_at)

This reduces database round-trips from 2 to 1 for all PostgreSQL
create operations across agents, spans, tasks, and other entities.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants