0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00

perf(factory): index run binding lookups by thread (#29594)

**─────── TLDR ───────**
> Finding a Factory run binding by thread now uses an index instead of
the status index or a full scan. Postgres index DDL with an operator
class and a sort order is now valid.

In the Factory, `findActiveRunBindingByThread` and
`findRunBindingByThread` filter on org, thread, resource and session.
The only index with those columns starts with `factory_project_id`, so
they fell back to the status index or a full scan.

### Behavior changed

a run binding looked up by thread, on Postgres or LibSQL
  ├─ **was** — status index plus a filter, or a full scan for
any status
  └─ **now** — `factory_run_bindings_org_thread_idx` on org,
thread, resource, session

a Postgres index with an operator class and `DESC` or `ASC`
  ├─ **was** — `createIndex` put the operator class after
`DESC`, which Postgres rejects; `exportSchemas` dropped the operator
class entirely
  └─ **now** — both put it right after the column, ahead of
`DESC` or `ASC`

### Decisions

- **no default GIN index on thread metadata** — only Factory and
mastracode features filter threads by metadata, so every other Postgres
user would pay the write cost, the disk and a slower first init for
nothing. Deployments that need it can add it themselves
- **kept `factory_run_bindings_session_idx`** — `findActiveRunBinding`
and `findRunBindingBySession` still filter on `factory_project_id`

### Tradeoff

Local Postgres 16, `EXPLAIN ANALYZE` on 100k seeded bindings:

> active binding by thread: was `0.7–1.5 ms`, now `0.06 ms`
> any-status binding by thread: was `5.8 ms` (full scan), now `0.006 ms`

The index is 6.6 MB per 100k rows. It's built without `CONCURRENTLY`,
like every other Factory index, so a big `factory_run_bindings` blocks
writes while it builds (144 ms per 100k rows here).

### Not verified

- [ ] real deployment row counts. The numbers above come from seeded
local tables

---

> ██████████████████ **tests** `+188` (87% of the additions)
> ██ **source** `+19 −27`
> █ **changeset** `+10`


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

## ELI5
This PR helps the database find run records faster when it searches by
thread details. It also fixes PostgreSQL index statements that combine
sort order with an operator class.

## Changes
- Added a `factory_run_bindings` index on `(org_id, thread_id,
resource_id, session_id)`. The existing project-scoped session index
remains.
- Added LibSQL and optional PostgreSQL tests for active and historical
thread lookups and their index usage.
- Updated PostgreSQL index SQL generation to place the operator class
before sort direction. Both generated schema SQL and runtime index
creation use the shared formatter.
- Added PostgreSQL integration tests for a descending column with
`text_pattern_ops`, including index creation during store
initialization.
- Added patch changesets for `@mastra/factory` and `@mastra/pg`.

## Checks
Test and CI results: not available.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Damien Schneider <damienschneider@damiens-MacBook-Pro.local>
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
This commit is contained in:
Damien Schneider 2026-11-09 10:44:58 -08:00 • committed by GitHub
commit 6bc7614a8f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 247 additions and 27 deletions