docs: add DB query performance guidelines to CLAUDE.md

[CAFxX]

Summary

• Extend the "Proxy database access" section in CLAUDE.md with database query performance guidelines, tailored to actual Prisma Client Python usage patterns in the litellm codebase
• Guidelines cover: N+1 queries, pushing work to the database (e.g. group_by over distinct), bounding large result sets with cursor-based pagination, using select on wide tables, batching writes with deadlock-safe ordering, preferring update_many/delete_many when return values aren't needed, index coverage considerations, and schema file sync requirements
• Motivated by recurring production issues across multiple PRs:
  • fix: use group_by instead of find_many(distinct) in /tag/list to avoid full table scan #23136 — Prisma distinct causing full table scan on 3M+ rows
  • fix: batch key queries in list_team to eliminate N+1 #23152 — N+1 key queries in team listing
  • fix: add missing indexes for top CPU-consuming queries #23147, add missing indexes on VerificationToken table #20736, add missing indexes on VerificationToken table #20040 — Missing database indexes
  • Optimize date filtering for spend logs queries #17073 — Unoptimized date filtering on spend logs
  • fix: minimize the occurrence of deadlocks #15281, avoid/minimize more deadlocks #16343 — Deadlocks from unordered writes

Test plan

• N/A — documentation only

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Error		Mar 10, 2026 4:47am

[greptile-apps]

Greptile Summary

This documentation-only PR extends the CLAUDE.md "Proxy database access" section with 7 concrete database query performance guidelines, motivated by recurring production incidents (N+1 queries, full-table scans from distinct, missing indexes, deadlocks). The changes fit well with the existing Prisma-centric guidance already in the file.

Key additions:

• N+1 prevention – batch-fetch with {"in": ids} instead of querying inside loops
• Batch writes – prefer create_many/update_many/delete_many; correctly documents that these return counts only and that update_many/delete_many silently no-op on missing rows
• Server-side work – prefer group_by over find_many(distinct=...) for server-side deduplication
• Result-set bounding – paginate large results with cursor/take (preferred) or skip/take; correctly notes skip is O(n)
• Column selection – use select on wide tables; correctly warns that it returns a partial object
• Index guidance – prefer extending existing @@index unless it is a @@unique constraint
• Schema sync – lists all four schema.prisma copies including litellm-js/spend-logs/ and directs migrations to litellm-proxy-extras/

One minor gap remains: create_many(skip_duplicates=True) silently ignores duplicate-key conflicts (analogous to the documented update_many/delete_many silent no-op), but this behavior is not called out in the batch-writes guideline.

Confidence Score: 4/5

• Documentation-only change with no production code impact; safe to merge after addressing the minor create_many(skip_duplicates=True) caveat
• Score of 4 reflects that this is a pure documentation PR with no runtime risk, and the guidelines are technically accurate. The only remaining gap is the undocumented silent-skip behavior of create_many(skip_duplicates=True), which is minor enough not to block the PR but worth fixing before merge to keep the guidance internally consistent.
• No files require special attention — the single changed file (CLAUDE.md) is documentation only.

Important Files Changed

Filename

Overview

CLAUDE.md

Adds 7 database query performance guidelines to the "Proxy database access" section, covering N+1 queries, batch writes, server-side aggregation, result-set bounding, column selection, index coverage, and schema sync. Guidelines are largely accurate after multiple review rounds; one minor omission: create_many(skip_duplicates=True) silent-skip behavior is not documented alongside the analogous update_many/delete_many no-op caveat.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[New DB Operation] --> B{Multiple rows\nor loop?}
    B -->|Loop detected| C[Batch: find_many with 'in'\nor create_many/update_many/delete_many]
    B -->|Single op| D{Need aggregation\nor dedup?}
    C --> E{Return value\nneeded?}
    E -->|Yes| F[update / delete\nRaises RecordNotFoundError]
    E -->|No| G[update_many / delete_many\nSilently no-ops on missing rows]
    D -->|Yes| H[Push to DB: group_by,\naggregate in SQL\nNot find_many with distinct]
    D -->|No| I{Wide table?}
    I -->|Yes| J[Add select to limit columns\nNote: returns partial object]
    I -->|No| K{Large result set?}
    K -->|>~10 MB| L[Paginate with cursor+take\nor skip+take with explicit order]
    K -->|Small / bounded| M[find_many / find_unique directly]
    L --> N{Prefer cursor\npagination}
    N -->|cursor+take| O[Cursor must be unique field]
    N -->|skip+take| P[skip is O skip-value — avoid for large offsets]

Loading

_{Last reviewed commit: 9d2b011}