Troubleshooting & limits

Debug logging

const prisma = basePrisma.$extends(
  speedExtension({ postgres: sql, debug: true }),
)

Performance hook

speedExtension({
  postgres: sql,
  onQuery: (info) => {
    console.log(info.model + '.' + info.method + ': ' + info.duration + 'ms')
    console.log('prebaked=' + info.prebaked)
  },
})

// info: { model, method, sql, params, duration, prebaked }

Common problems

speedExtension requires postgres or sqlite client

Pass a database-native client to the generated extension:

const prisma = new PrismaClient().$extends(speedExtension({ postgres: sql }))

Generated dialect mismatch

If generated code targets PostgreSQL, do not pass SQLite, and vice versa. Override the dialect in the generator block if needed.

Results differ from Prisma

Turn on debug logging and compare generated SQL with Prisma query logs, or better, use prisma-sql-verify. If behavior differs, open an issue with schema excerpt, query, generated SQL, expected and actual result.

Performance worse on a relation-heavy query

  • missing foreign-key indexes
  • missing MODEL_STATS (planner stats not collected)
  • stale PostgreSQL catalog stats — refresh with PRISMA_SQL_ANALYZE=1 npx prisma generate
  • high-fanout relation trees without bounds
  • unstable or missing orderBy
  • unrelated heavy branches that should be split into $batch

Large include still uses the wrong strategy

  • planner.generated.ts has empty MODEL_STATS or the model is known: false
  • largeChildTableRows set too high or smallParentCountThreshold set too low
  • check debug logs for where-in segmented loading on the relation

SQLite tuple-IN error

Composite foreign-key where-in requires SQLite 3.15+. Upgrade SQLite if row-value tuple IN fails.

Connection pool exhaustion

const sql = postgres(process.env.DATABASE_URL!, { max: 50 })

Edge runtimes

Vercel Edge

The extension works like on Node: pass a postgres.js client and export config = { runtime: 'edge' }.

Cloudflare Workers

Workers can use the standalone SQL generation API instead of the full extension:

import { createToSQL } from 'prisma-sql'
import { MODELS } from './generated/sql'

const toSQL = createToSQL(MODELS, 'sqlite')

const { sql, params } = toSQL('User', 'findMany', {
  where: { status: 'ACTIVE' },
})

Current limitations

Partially supported

  • basic array operators
  • basic JSON path filtering
  • composite foreign-key includes through tuple-IN in the where-in path

Not yet supported (fall back to Prisma)

  • writes
  • full-text search
  • composite/document-style embedded types
  • vendor-specific extensions not modeled by the SQL builder
  • some advanced groupBy edge cases

Streaming

findManyStream cannot stream queries that require segmented where-in include loading. Use regular findMany for those, or select scalar columns only.

$batch

PostgreSQL only, not transactional.