Skip to content

Commit ae36f0a

Browse files
authored
Bound cursor pagination by the timestamp (#4469)
1 parent 107dffd commit ae36f0a

9 files changed

Lines changed: 90 additions & 0 deletions

File tree

‎contributing/DATABASE.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,3 +84,29 @@ Keep locked regions short and bounded. See `LOCKING.md` for how to take advisory
8484
`DSTACK_DB_COMMAND_TIMEOUT` (default 300 seconds) bounds every operation on a Postgres connection, so a coroutine waiting on a connection whose socket died silently gets an error and releases the slot instead of holding it forever. It applies to migrations too, since they run on the same engine, so it must leave room for index builds and backfills.
8585

8686
`DSTACK_DB_POOL_SIZE` and `DSTACK_DB_MAX_OVERFLOW` size the pool per process. Raising them lets more coroutines hold connections at once, which hides a long hold rather than fixing it, and each replica needs `pool_size + max_overflow` connections from the Postgres `max_connections` budget.
87+
88+
## Queries
89+
90+
### Cursor pagination
91+
92+
List APIs paginate with a cursor: the timestamp and id of the last returned row, e.g. `prev_created_at` and `prev_id`. Rows with the same timestamp are ordered by id in the opposite direction, so the cursor filter is an OR:
93+
94+
```python
95+
or_(
96+
Model.created_at > prev_created_at,
97+
and_(Model.created_at == prev_created_at, Model.id < prev_id),
98+
)
99+
```
100+
101+
Always add the timestamp bound next to it, `>=` for ascending and `<=` for descending:
102+
103+
```python
104+
filters.append(Model.created_at >= prev_created_at)
105+
filters.append(or_(...))
106+
```
107+
108+
The bound doesn't change the results, but without it a request can read the whole table. Postgres can use the OR with an index only by looking up each branch separately and sorting the combined result. When it expects many rows after the cursor, it reads the timestamp index in order instead, and it can start that scan only from a single condition such as `created_at >= value`, which it doesn't derive from the OR. Then the scan starts at the oldest row and filters out everything before the cursor. Postgres expects many rows after the cursor when the cursor is old, and always with a generic plan of a prepared statement, which is planned without the cursor value. See [#4465](https://github.com/dstackai/dstack/issues/4465).
109+
110+
A row comparison such as `(created_at, id) > (prev_created_at, prev_id)` would avoid the OR, but it requires both columns to be ordered in the same direction.
111+
112+
The bound only removes reading rows before the cursor. A request still reads rows after the cursor until it finds `limit` rows that match its other filters, so on a large table a filter that matches few rows, such as one project's rows, also needs an index that starts with the filter column.

‎src/dstack/_internal/server/services/events.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -418,6 +418,9 @@ async def list_events(
418418
if prev_id is None:
419419
event_filters.append(EventModel.recorded_at > prev_recorded_at)
420420
else:
421+
# Redundant with the OR below, but unlike the OR it lets the database
422+
# start the index scan at the cursor instead of scanning from the start.
423+
event_filters.append(EventModel.recorded_at >= prev_recorded_at)
421424
event_filters.append(
422425
or_(
423426
EventModel.recorded_at > prev_recorded_at,
@@ -428,6 +431,7 @@ async def list_events(
428431
if prev_id is None:
429432
event_filters.append(EventModel.recorded_at < prev_recorded_at)
430433
else:
434+
event_filters.append(EventModel.recorded_at <= prev_recorded_at)
431435
event_filters.append(
432436
or_(
433437
EventModel.recorded_at < prev_recorded_at,

‎src/dstack/_internal/server/services/fleets.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -277,6 +277,9 @@ async def list_projects_fleet_models(
277277
if prev_id is None:
278278
filters.append(FleetModel.created_at > prev_created_at)
279279
else:
280+
# Redundant with the OR below, but unlike the OR it lets the database
281+
# start the index scan at the cursor instead of scanning from the start.
282+
filters.append(FleetModel.created_at >= prev_created_at)
280283
filters.append(
281284
or_(
282285
FleetModel.created_at > prev_created_at,
@@ -287,6 +290,7 @@ async def list_projects_fleet_models(
287290
if prev_id is None:
288291
filters.append(FleetModel.created_at < prev_created_at)
289292
else:
293+
filters.append(FleetModel.created_at <= prev_created_at)
290294
filters.append(
291295
or_(
292296
FleetModel.created_at < prev_created_at,

‎src/dstack/_internal/server/services/instances.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -796,6 +796,9 @@ async def list_projects_instance_models(
796796
if prev_id is None:
797797
filters.append(InstanceModel.created_at > prev_created_at)
798798
else:
799+
# Redundant with the OR below, but unlike the OR it lets the database
800+
# start the index scan at the cursor instead of scanning from the start.
801+
filters.append(InstanceModel.created_at >= prev_created_at)
799802
filters.append(
800803
or_(
801804
InstanceModel.created_at > prev_created_at,
@@ -809,6 +812,7 @@ async def list_projects_instance_models(
809812
if prev_id is None:
810813
filters.append(InstanceModel.created_at < prev_created_at)
811814
else:
815+
filters.append(InstanceModel.created_at <= prev_created_at)
812816
filters.append(
813817
or_(
814818
InstanceModel.created_at < prev_created_at,

‎src/dstack/_internal/server/services/projects.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,9 @@ async def list_user_accessible_projects(
137137
if prev_id is None:
138138
pagination_filters.append(ProjectModel.created_at > prev_created_at)
139139
else:
140+
# Redundant with the OR below, but unlike the OR it lets the database
141+
# start the index scan at the cursor instead of scanning from the start.
142+
pagination_filters.append(ProjectModel.created_at >= prev_created_at)
140143
pagination_filters.append(
141144
or_(
142145
ProjectModel.created_at > prev_created_at,
@@ -149,6 +152,7 @@ async def list_user_accessible_projects(
149152
if prev_id is None:
150153
pagination_filters.append(ProjectModel.created_at < prev_created_at)
151154
else:
155+
pagination_filters.append(ProjectModel.created_at <= prev_created_at)
152156
pagination_filters.append(
153157
or_(
154158
ProjectModel.created_at < prev_created_at,

‎src/dstack/_internal/server/services/runs/__init__.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -302,6 +302,9 @@ async def list_projects_run_models(
302302
if prev_run_id is None:
303303
filters.append(RunModel.submitted_at > prev_submitted_at)
304304
else:
305+
# Redundant with the OR below, but unlike the OR it lets the database
306+
# start the index scan at the cursor instead of scanning from the start.
307+
filters.append(RunModel.submitted_at >= prev_submitted_at)
305308
filters.append(
306309
or_(
307310
RunModel.submitted_at > prev_submitted_at,
@@ -314,6 +317,7 @@ async def list_projects_run_models(
314317
if prev_run_id is None:
315318
filters.append(RunModel.submitted_at < prev_submitted_at)
316319
else:
320+
filters.append(RunModel.submitted_at <= prev_submitted_at)
317321
filters.append(
318322
or_(
319323
RunModel.submitted_at < prev_submitted_at,

‎src/dstack/_internal/server/services/users.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,9 @@ async def list_all_users(
108108
if prev_id is None:
109109
pagination_filters.append(UserModel.created_at > prev_created_at)
110110
else:
111+
# Redundant with the OR below, but unlike the OR it lets the database
112+
# start the index scan at the cursor instead of scanning from the start.
113+
pagination_filters.append(UserModel.created_at >= prev_created_at)
111114
pagination_filters.append(
112115
or_(
113116
UserModel.created_at > prev_created_at,
@@ -121,6 +124,7 @@ async def list_all_users(
121124
if prev_id is None:
122125
pagination_filters.append(UserModel.created_at < prev_created_at)
123126
else:
127+
pagination_filters.append(UserModel.created_at <= prev_created_at)
124128
pagination_filters.append(
125129
or_(
126130
UserModel.created_at < prev_created_at,

‎src/dstack/_internal/server/services/volumes.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,9 @@ async def list_projects_volume_models(
150150
if prev_id is None:
151151
filters.append(VolumeModel.created_at > prev_created_at)
152152
else:
153+
# Redundant with the OR below, but unlike the OR it lets the database
154+
# start the index scan at the cursor instead of scanning from the start.
155+
filters.append(VolumeModel.created_at >= prev_created_at)
153156
filters.append(
154157
or_(
155158
VolumeModel.created_at > prev_created_at,
@@ -160,6 +163,7 @@ async def list_projects_volume_models(
160163
if prev_id is None:
161164
filters.append(VolumeModel.created_at < prev_created_at)
162165
else:
166+
filters.append(VolumeModel.created_at <= prev_created_at)
163167
filters.append(
164168
or_(
165169
VolumeModel.created_at < prev_created_at,

‎src/tests/_internal/server/routers/test_events.py‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1476,6 +1476,42 @@ async def test_pagination(
14761476
resp.raise_for_status()
14771477
assert len(resp.json()) == 0
14781478

1479+
@pytest.mark.parametrize("ascending", [True, False])
1480+
async def test_pagination_with_same_recorded_at(
1481+
self, session: AsyncSession, client: AsyncClient, ascending: bool
1482+
) -> None:
1483+
users = [await create_user(session=session, name=f"user_{i}") for i in range(3)]
1484+
with time_machine.travel(datetime(2026, 1, 1, 12, 0, 0), tick=False):
1485+
for user in users:
1486+
events.emit(
1487+
session,
1488+
"User created",
1489+
actor=events.UserActor.from_user(user),
1490+
targets=[events.Target.from_model(user)],
1491+
)
1492+
await session.commit()
1493+
1494+
listed = []
1495+
pagination = {}
1496+
for _ in range(len(users) + 1):
1497+
resp = await client.post(
1498+
"/api/events/list",
1499+
json={"limit": 1, "ascending": ascending, **pagination},
1500+
headers=get_auth_headers(users[0].token),
1501+
)
1502+
resp.raise_for_status()
1503+
if not resp.json():
1504+
break
1505+
listed.extend(resp.json())
1506+
pagination = {
1507+
"prev_id": resp.json()[-1]["id"],
1508+
"prev_recorded_at": resp.json()[-1]["recorded_at"],
1509+
}
1510+
ids = [event["id"] for event in listed]
1511+
# Events with the same `recorded_at` are ordered by `id`, descending when ascending.
1512+
assert ids == sorted(ids, reverse=ascending)
1513+
assert len(set(ids)) == len(users)
1514+
14791515
async def test_limits_events_regardless_number_of_targets(
14801516
self, session: AsyncSession, client: AsyncClient
14811517
) -> None:

0 commit comments

Comments
 (0)