prisma-sql 1.16.0 → 1.18.0

package/readme.md

@@ -2,17 +2,24 @@
 
 Speed up Prisma reads **2-7x** by executing queries via postgres.js or better-sqlite3 instead of Prisma's query engine.
 
+**Same API. Same types. Just faster.**
+
 ```typescript
-import { convertDMMFToModels } from 'prisma-sql'
-import { Prisma } from '@prisma/client'
+import { PrismaClient, Prisma } from '@prisma/client'
+import { speedExtension, convertDMMFToModels } from 'prisma-sql'
+import postgres from 'postgres'
 
 const models = convertDMMFToModels(Prisma.dmmf.datamodel)
-const sql = postgres(DATABASE_URL)
+const sql = postgres(process.env.DATABASE_URL)
 const prisma = new PrismaClient().$extends(
   speedExtension({ postgres: sql, models }),
 )
 
-const users = await prisma.user.findMany({ where: { status: 'ACTIVE' } })
+// Just use Prisma normally - queries are automatically faster
+const users = await prisma.user.findMany({
+  where: { status: 'ACTIVE' },
+  include: { posts: true },
+})
 ```
 
 ## Why?
@@ -44,81 +51,6 @@ npm install prisma-sql better-sqlite3
 
 ## Quick Start
 
-You can use prisma-sql in two ways:
-
-### 1. Generator Mode (Recommended - Fastest)
-
-Prebake SQL queries at build time for maximum performance.
-
-**Add generator to schema:**
-
-```prisma
-// schema.prisma
-datasource db {
-  provider = "postgresql"
-  url      = env("DATABASE_URL")
-}
-
-generator client {
-  provider = "prisma-client-js"
-}
-
-generator sql {
-  provider = "prisma-sql-generator"
-  // Dialect auto-detected from datasource.provider
-}
-
-model User {
-  id     Int     @id @default(autoincrement())
-  email  String  @unique
-  status String
-  posts  Post[]
-
-  /// @sql.findMany({ where: { status: "ACTIVE" } })
-  /// @sql.findMany({ where: { status: "PENDING" } })
-  /// @sql.count({ where: { status: "ACTIVE" } })
-}
-
-model Post {
-  id        Int     @id @default(autoincrement())
-  title     String
-  published Boolean
-  authorId  Int
-  author    User    @relation(fields: [authorId], references: [id])
-
-  /// @sql.findMany({ where: { published: true }, include: { author: true } })
-}
-```
-
-**Generate and use:**
-
-```bash
-npx prisma generate
-```
-
-```typescript
-import { PrismaClient } from '@prisma/client'
-import { createExtension } from '.prisma/client/sql'
-import postgres from 'postgres'
-
-const sql = postgres(process.env.DATABASE_URL)
-const prisma = new PrismaClient().$extends(createExtension({ postgres: sql }))
-
-// ⚡ PREBAKED - Uses pre-generated SQL (instant)
-const activeUsers = await prisma.user.findMany({
-  where: { status: 'ACTIVE' },
-})
-
-// 🔨 RUNTIME - Generates SQL on-the-fly (still fast)
-const searchUsers = await prisma.user.findMany({
-  where: { email: { contains: '@example.com' } },
-})
-```
-
-### 2. Runtime Mode (Simpler, No Build Step)
-
-Generate SQL on-the-fly without code generation.
-
 **PostgreSQL:**
 
 ```typescript
@@ -128,10 +60,12 @@ import postgres from 'postgres'
 
 const models = convertDMMFToModels(Prisma.dmmf.datamodel)
 const sql = postgres(process.env.DATABASE_URL)
+
 const prisma = new PrismaClient().$extends(
   speedExtension({ postgres: sql, models }),
 )
 
+// Use Prisma exactly as before - it's just faster now
 const users = await prisma.user.findMany({
   where: { status: 'ACTIVE' },
   include: { posts: true },
@@ -147,6 +81,7 @@ import Database from 'better-sqlite3'
 
 const models = convertDMMFToModels(Prisma.dmmf.datamodel)
 const db = new Database('./data.db')
+
 const prisma = new PrismaClient().$extends(
   speedExtension({ sqlite: db, models }),
 )
@@ -154,192 +89,40 @@ const prisma = new PrismaClient().$extends(
 const users = await prisma.user.findMany({ where: { status: 'ACTIVE' } })
 ```
 
-## Generator Mode vs Runtime Mode
-
-### Generator Mode (Recommended)
-
-**Pros:**
-
-- ⚡ **Fastest** - SQL pre-generated at build time
-- 🎯 **Zero overhead** for known queries
-- 🔨 **Auto-fallback** to runtime for unknown queries
-- 📊 **Track performance** with `prebaked` flag
-
-**Cons:**
-
-- Requires `npx prisma generate` step
-- Need to define common queries upfront
-
-**When to use:**
-
-- ✅ Production applications
-- ✅ Known query patterns (dashboards, APIs)
-- ✅ Want maximum performance
-- ✅ Build step is acceptable
-
-### Runtime Mode
-
-**Pros:**
-
-- 🚀 **Simple** - no build step
-- 🔧 **Flexible** - handles any query
-- 📝 **Easy prototyping**
-
-**Cons:**
-
-- Small overhead (~0.2ms) for SQL generation
-- Still 2-7x faster than Prisma
-
-**When to use:**
-
-- ✅ Rapid prototyping
-- ✅ Fully dynamic queries
-- ✅ No build step desired
-- ✅ Query patterns unknown
-
-## Generator Mode Details
-
-### How It Works
-
-```
-Build Time:
-  schema.prisma
-       ↓
-  /// @sql.findMany({ where: { status: "ACTIVE" } })
-       ↓
-  npx prisma generate
-       ↓
-  .prisma/client/sql/index.ts
-       ↓
-  QUERIES = {
-    User: {
-      '{"where":{"status":"ACTIVE"}}': {
-        sql: 'SELECT * FROM users WHERE status = $1',
-        params: ['ACTIVE'],
-        dynamicKeys: []
-      }
-    }
-  }
-
-Runtime:
-  prisma.user.findMany({ where: { status: 'ACTIVE' } })
-       ↓
-  Normalize query → '{"where":{"status":"ACTIVE"}}'
-       ↓
-  QUERIES.User[query] found?
-       ↓
-  YES → ⚡ Use prebaked SQL (0.03ms overhead)
-       ↓
-  NO → 🔨 Generate SQL runtime (0.2ms overhead)
-       ↓
-  Execute via postgres.js/better-sqlite3
-```
-
-### Generator Configuration
-
-```prisma
-generator sql {
-  provider = "prisma-sql-generator"
-
-  // Optional: Override auto-detected dialect (rarely needed)
-  // dialect = "postgres"  // or "sqlite"
-
-  // Optional: Output directory (default: ../node_modules/.prisma/client/sql)
-  // output = "./generated/sql"
-
-  // Optional: Skip invalid directives instead of failing (default: false)
-  // skipInvalid = "true"
-}
-```
-
-### Supported Directive Patterns
-
-```prisma
-model User {
-  // Simple queries
-  /// @sql.findMany({ where: { status: "ACTIVE" } })
-  /// @sql.findFirst({ where: { email: "test@example.com" } })
-  /// @sql.findUnique({ where: { id: 1 } })
-
-  // With relations
-  /// @sql.findMany({ include: { posts: true } })
-  /// @sql.findMany({ include: { posts: { where: { published: true } } } })
-
-  // With pagination
-  /// @sql.findMany({ take: 10, skip: 20, orderBy: { createdAt: "desc" } })
-
-  // Aggregations
-  /// @sql.count({ where: { status: "ACTIVE" } })
-  /// @sql.aggregate({ _count: { _all: true }, _avg: { age: true } })
-  /// @sql.groupBy({ by: ["status"], _count: { _all: true } })
-
-  // Dynamic parameters
-  /// @sql.findMany({ where: { status: { $param: "status" } } })
-  /// @sql.findMany({ where: { age: { gte: { $param: "minAge" } } } })
-}
-```
-
-### Dynamic Parameters
-
-Use `$param` for runtime values:
-
-```prisma
-model User {
-  /// @sql.findMany({ where: { status: { $param: "status" } } })
-  /// @sql.findMany({ where: { age: { gte: { $param: "minAge" } } } })
-}
-```
-
-```typescript
-// Prebaked SQL with runtime parameters
-const users = await prisma.user.findMany({
-  where: { status: 'ACTIVE' }, // Matches directive with $param
-})
-
-// SQL: SELECT * FROM users WHERE status = $1
-// Params: ['ACTIVE']
-```
-
-### Performance Tracking
-
-```typescript
-const prisma = new PrismaClient().$extends(
-  createExtension({
-    postgres: sql,
-    debug: true,
-    onQuery: (info) => {
-      console.log(`${info.model}.${info.method}: ${info.duration}ms`)
-      console.log(info.prebaked ? '⚡ PREBAKED' : '🔨 RUNTIME')
-    },
-  }),
-)
-```
+That's it! All your read queries are now 2-7x faster with zero code changes.
 
-## What Gets Faster
+## Performance
 
-**Accelerated (via raw SQL):**
+Benchmarks from 137 E2E tests comparing identical queries:
 
-- `findMany`, `findFirst`, `findUnique`
-- `count`
-- `aggregate` (\_count, \_sum, \_avg, \_min, \_max)
-- `groupBy` with having clauses
+### PostgreSQL Results (Highlights)
 
-**Unchanged (still uses Prisma):**
+| Query Type          | Prisma v6 | Prisma v7 | This Extension | Speedup vs v7 |
+| ------------------- | --------- | --------- | -------------- | ------------- |
+| Simple where        | 0.40ms    | 0.34ms    | 0.17ms         | **2.0x** ⚡   |
+| Complex conditions  | 13.10ms   | 6.90ms    | 2.37ms         | **2.9x** ⚡   |
+| With relations      | 0.83ms    | 0.72ms    | 0.41ms         | **1.8x** ⚡   |
+| Nested relations    | 28.35ms   | 14.34ms   | 4.81ms         | **3.0x** ⚡   |
+| Aggregations        | 0.42ms    | 0.44ms    | 0.24ms         | **1.8x** ⚡   |
+| Multi-field orderBy | 3.97ms    | 2.38ms    | 1.09ms         | **2.2x** ⚡   |
 
-- `create`, `update`, `delete`, `upsert`
-- `createMany`, `updateMany`, `deleteMany`
-- Transactions (`$transaction`)
-- Middleware
+**Overall:** 2.10x faster than Prisma v7, 2.39x faster than v6
 
----
+### SQLite Results (Highlights)
 
-## Performance
+| Query Type         | Prisma v6 | Prisma v7 | This Extension | Speedup vs v7 |
+| ------------------ | --------- | --------- | -------------- | ------------- |
+| Simple where       | 0.45ms    | 0.23ms    | 0.03ms         | **7.7x** ⚡   |
+| Complex conditions | 10.32ms   | 3.87ms    | 0.93ms         | **4.2x** ⚡   |
+| Relation filters   | 166.62ms  | 128.44ms  | 2.40ms         | **53.5x** ⚡  |
+| Count queries      | 0.17ms    | 0.07ms    | 0.01ms         | **7.0x** ⚡   |
 
-Benchmarks from 137 E2E tests comparing identical queries against Prisma v6, Prisma v7, and Drizzle:
+**Overall:** 5.48x faster than Prisma v7, 7.51x faster than v6
 
-### BENCHMARK RESULTS - Prisma v6 vs v7 vs Generated SQL
+<details>
+<summary><b>View Full Benchmark Results (137 queries)</b></summary>
 
-## POSTGRES Results:
+### POSTGRES - Complete Results
 
 | Test                     | Prisma v6 | Prisma v7 | Generated | Drizzle | v6 Speedup | v7 Speedup |
 | ------------------------ | --------- | --------- | --------- | ------- | ---------- | ---------- |
@@ -403,17 +186,7 @@ Benchmarks from 137 E2E tests comparing identical queries against Prisma v6, Pri
 | ILIKE special chars      | 0.22ms    | 0.26ms    | 0.14ms    | N/A     | 1.54x      | 1.76x      |
 | LIKE case sensitive      | 0.19ms    | 0.22ms    | 0.12ms    | N/A     | 1.62x      | 1.85x      |
 
-##### Summary:
-
-- Generated SQL vs Prisma v6: **2.39x faster**
-- Generated SQL vs Prisma v7: **2.10x faster**
-- Generated SQL vs Drizzle: **1.53x faster**
-
----
-
-#### SQLITE:
-
----
+### SQLITE - Complete Results
 
 | Test                     | Prisma v6 | Prisma v7 | Generated | Drizzle | v6 Speedup | v7 Speedup |
 | ------------------------ | --------- | --------- | --------- | ------- | ---------- | ---------- |
@@ -474,48 +247,27 @@ Benchmarks from 137 E2E tests comparing identical queries against Prisma v6, Pri
 | \_count relation         | 0.62ms    | 0.46ms    | 0.32ms    | N/A     | 1.93x      | 1.44x      |
 | \_count multi-relation   | 0.14ms    | 0.17ms    | 0.04ms    | N/A     | 3.22x      | 4.09x      |
 
-##### Summary:
-
-- Generated SQL vs Prisma v6: **7.51x faster**
-- Generated SQL vs Prisma v7: **5.48x faster**
-- Generated SQL vs Drizzle: **2.61x faster**
-
-> **Note on Prisma v7:** Prisma v7 introduced significant performance improvements (39% faster than v6 on PostgreSQL, 24% faster on SQLite), but this extension still provides 2-7x additional speedup over v7.
-
-> **Benchmarks:** These are representative results from our test suite running on a MacBook Pro M1 with PostgreSQL 15 and SQLite 3.43. Your mileage may vary based on:
->
-> - Database configuration and indexes
-> - Query complexity and data volume
-> - Hardware and network latency
-> - Concurrent load
->
-> Run benchmarks with your own schema and data for accurate measurements. See [Benchmarking](#benchmarking) section below.
+</details>
 
----
-
-## Configuration
-
-### Basic Configuration
+> **Note:** Benchmarks run on MacBook Pro M1 with PostgreSQL 15 and SQLite 3.43. Results vary based on database config, indexes, query complexity, and hardware. Run your own benchmarks for accurate measurements.
 
-```typescript
-import { Prisma } from '@prisma/client'
-import { convertDMMFToModels } from 'prisma-sql'
+## What Gets Faster
 
-const models = convertDMMFToModels(Prisma.dmmf.datamodel)
+**Accelerated (via raw SQL):**
 
-speedExtension({
-  postgres: sql,
-  models,
+- ✅ `findMany`, `findFirst`, `findUnique`
+- ✅ `count`
+- ✅ `aggregate` (\_count, \_sum, \_avg, \_min, \_max)
+- ✅ `groupBy` with having clauses
 
-  debug: true,
+**Unchanged (still uses Prisma):**
 
-  allowedModels: ['User', 'Post'],
+- `create`, `update`, `delete`, `upsert`
+- `createMany`, `updateMany`, `deleteMany`
+- Transactions (`$transaction`)
+- Middleware
 
-  onQuery: (info) => {
-    console.log(`${info.model}.${info.method}: ${info.duration}ms`)
-  },
-})
-```
+## Configuration
 
 ### Debug Mode
 
@@ -527,25 +279,13 @@ import { Prisma } from '@prisma/client'
 
 const models = convertDMMFToModels(Prisma.dmmf.datamodel)
 
-speedExtension({
-  postgres: sql,
-  models,
-  debug: true,
-})
-```
-
-### Selective Models
-
-Only accelerate specific models:
-
-```typescript
-const models = convertDMMFToModels(Prisma.dmmf.datamodel)
-
-speedExtension({
-  postgres: sql,
-  models,
-  allowedModels: ['User', 'Post'],
-})
+const prisma = new PrismaClient().$extends(
+  speedExtension({
+    postgres: sql,
+    models,
+    debug: true, // Logs SQL for every query
+  }),
+)
 ```
 
 ### Performance Monitoring
@@ -555,162 +295,76 @@ Track query performance:
 ```typescript
 const models = convertDMMFToModels(Prisma.dmmf.datamodel)
 
-speedExtension({
-  postgres: sql,
-  models,
-  onQuery: (info) => {
-    console.log(`${info.model}.${info.method} completed in ${info.duration}ms`)
+const prisma = new PrismaClient().$extends(
+  speedExtension({
+    postgres: sql,
+    models,
+    onQuery: (info) => {
+      console.log(`${info.model}.${info.method}: ${info.duration}ms`)
 
-    if (info.duration > 100) {
-      logger.warn('Slow query detected', {
-        model: info.model,
-        method: info.method,
-        sql: info.sql,
-      })
-    }
-  },
-})
+      if (info.duration > 100) {
+        logger.warn('Slow query', {
+          model: info.model,
+          method: info.method,
+          sql: info.sql,
+        })
+      }
+    },
+  }),
+)
 ```
 
-## Advanced Usage
-
-### Read Replicas
-
-Send writes to primary, reads to replica:
+The `onQuery` callback receives:
 
 ```typescript
-import { convertDMMFToModels } from 'prisma-sql'
-import { Prisma } from '@prisma/client'
-
-const models = convertDMMFToModels(Prisma.dmmf.datamodel)
-
-const primary = new PrismaClient()
-
-const replica = postgres(process.env.REPLICA_URL)
-const fastPrisma = new PrismaClient().$extends(
-  speedExtension({ postgres: replica, models })
-)
-
-await primary.user.create({ data: { ... } })
-const users = await fastPrisma.user.findMany()
+interface QueryInfo {
+  model: string // "User"
+  method: string // "findMany"
+  sql: string // The executed SQL
+  params: unknown[] // SQL parameters
+  duration: number // Query duration in ms
+  prebaked: boolean // true if using generated SQL (see Advanced Usage)
+}
 ```
 
-### Connection Pooling
+### Selective Models
 
-Configure postgres.js connection pool:
+Only accelerate specific models:
 
 ```typescript
 const models = convertDMMFToModels(Prisma.dmmf.datamodel)
 
-const sql = postgres(process.env.DATABASE_URL, {
-  max: 20,
-  idle_timeout: 20,
-  connect_timeout: 10,
-  ssl: 'require',
-})
-
 const prisma = new PrismaClient().$extends(
-  speedExtension({ postgres: sql, models }),
+  speedExtension({
+    postgres: sql,
+    models,
+    allowedModels: ['User', 'Post'], // Only speed up these models
+  }),
 )
 ```
 
-### Gradual Rollout
+## Supported Queries
 
-Feature-flag the extension for safe rollout:
-
-```typescript
-const models = convertDMMFToModels(Prisma.dmmf.datamodel)
-const USE_FAST_READS = process.env.FAST_READS === 'true'
-
-const sql = postgres(DATABASE_URL)
-const prisma = new PrismaClient()
-
-const db = USE_FAST_READS
-  ? prisma.$extends(speedExtension({ postgres: sql, models }))
-  : prisma
-```
-
-### Access Original Prisma
-
-```typescript
-const models = convertDMMFToModels(Prisma.dmmf.datamodel)
-const prisma = new PrismaClient().$extends(
-  speedExtension({ postgres: sql, models }),
-)
-
-const fast = await prisma.user.findMany()
-
-const slow = await prisma.$original.user.findMany()
-```
-
-## Edge Runtime
-
-### Vercel Edge Functions
-
-```typescript
-import { PrismaClient, Prisma } from '@prisma/client'
-import { speedExtension, convertDMMFToModels } from 'prisma-sql'
-import postgres from 'postgres'
-
-const models = convertDMMFToModels(Prisma.dmmf.datamodel)
-const sql = postgres(process.env.DATABASE_URL)
-const prisma = new PrismaClient().$extends(
-  speedExtension({ postgres: sql, models }),
-)
-
-export const config = { runtime: 'edge' }
-
-export default async function handler(req: Request) {
-  const users = await prisma.user.findMany()
-  return Response.json(users)
-}
-```
-
-### Cloudflare Workers
-
-For Cloudflare Workers, use the standalone SQL generation API instead of the extension:
-
-```typescript
-import { createToSQL, convertDMMFToModels } from 'prisma-sql'
-import { Prisma } from '@prisma/client'
-
-const models = convertDMMFToModels(Prisma.dmmf.datamodel)
-const toSQL = createToSQL(models, 'sqlite')
-
-export default {
-  async fetch(request: Request, env: Env) {
-    const { sql, params } = toSQL('User', 'findMany', {
-      where: { status: 'ACTIVE' },
-    })
-
-    const result = await env.DB.prepare(sql)
-      .bind(...params)
-      .all()
-    return Response.json(result.results)
-  },
-}
-```
-
-> **Note:** The Prisma Client extension is not recommended for Cloudflare Workers due to cold start overhead. Use the `createToSQL` API for edge deployments.
-
-## Supported Queries
-
-### Filters
+### Filters
 
 ```typescript
+// Comparisons
 { age: { gt: 18, lte: 65 } }
 { status: { in: ['ACTIVE', 'PENDING'] } }
 { status: { notIn: ['DELETED'] } }
 
+// String operations
 { email: { contains: '@example.com' } }
 { email: { startsWith: 'user' } }
 { email: { endsWith: '.com' } }
 { email: { contains: 'EXAMPLE', mode: 'insensitive' } }
 
+// Boolean logic
 { AND: [{ status: 'ACTIVE' }, { verified: true }] }
 { OR: [{ role: 'ADMIN' }, { role: 'MODERATOR' }] }
 { NOT: { status: 'DELETED' } }
 
+// Null checks
 { deletedAt: null }
 { deletedAt: { not: null } }
 ```
@@ -718,6 +372,7 @@ export default {
 ### Relations
 
 ```typescript
+// Include relations
 {
   include: {
     posts: true,
@@ -725,6 +380,7 @@ export default {
   }
 }
 
+// Nested includes with filters
 {
   include: {
     posts: {
@@ -736,27 +392,22 @@ export default {
   }
 }
 
+// Relation filters
 {
   where: {
-    posts: {
-      some: { published: true }
-    }
+    posts: { some: { published: true } }
   }
 }
 
 {
   where: {
-    posts: {
-      every: { published: true }
-    }
+    posts: { every: { published: true } }
   }
 }
 
 {
   where: {
-    posts: {
-      none: { published: false }
-    }
+    posts: { none: { published: false } }
   }
 }
 ```
@@ -764,12 +415,14 @@ export default {
 ### Pagination & Ordering
 
 ```typescript
+// Basic pagination
 {
   take: 10,
   skip: 20,
   orderBy: { createdAt: 'desc' }
 }
 
+// Cursor-based pagination
 {
   cursor: { id: 100 },
   take: 10,
@@ -777,6 +430,7 @@ export default {
   orderBy: { id: 'asc' }
 }
 
+// Multi-field ordering
 {
   orderBy: [
     { status: 'asc' },
@@ -784,22 +438,15 @@ export default {
     { createdAt: 'desc' }
   ]
 }
-
-{
-  orderBy: {
-    name: {
-      sort: 'asc',
-      nulls: 'last'
-    }
-  }
-}
 ```
 
 ### Aggregations
 
 ```typescript
+// Count
 await prisma.user.count({ where: { status: 'ACTIVE' } })
 
+// Aggregate
 await prisma.task.aggregate({
   where: { status: 'DONE' },
   _count: { _all: true },
@@ -809,6 +456,7 @@ await prisma.task.aggregate({
   _max: { completedAt: true },
 })
 
+// Group by
 await prisma.task.groupBy({
   by: ['status', 'priority'],
   _count: { _all: true },
@@ -821,73 +469,311 @@ await prisma.task.groupBy({
 })
 ```
 
-### Distinct
+## Advanced Usage
+
+### Generator Mode - Prebaked SQL Queries
 
-```typescript
-{
-  distinct: ['status'],
-  orderBy: { status: 'asc' }
+For maximum performance, prebake your most common queries at build time. This reduces overhead from ~0.2ms (runtime) to ~0.03ms.
+
+**1. Add generator to your schema:**
+
+```prisma
+// schema.prisma
+generator sql {
+  provider = "prisma-sql-generator"
 }
+```
 
-{
-  distinct: ['status', 'priority'],
-  orderBy: [
-    { status: 'asc' },
-    { priority: 'asc' }
-  ]
+**2. Add optimize directives to your models:**
+
+```prisma
+/// @optimize {
+///   "method": "findMany",
+///   "query": {
+///     "skip": "$skip",
+///     "take": "$take",
+///     "orderBy": { "createdAt": "desc" },
+///     "where": { "status": "ACTIVE" }
+///   }
+/// }
+/// @optimize { "method": "count", "query": {} }
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique
+  status    String
+  createdAt DateTime @default(now())
+  posts     Post[]
 }
 ```
 
-## Migration Guide
+**3. Generate:**
 
-### From Prisma Client
+```bash
+npx prisma generate
+```
 
-**Before:**
+**4. Use the generated extension:**
 
 ```typescript
-const prisma = new PrismaClient()
-const users = await prisma.user.findMany()
+import { PrismaClient } from '@prisma/client'
+import { createExtension } from '../path/to/generated/sql'
+import postgres from 'postgres'
+
+const sql = postgres(process.env.DATABASE_URL)
+const prisma = new PrismaClient().$extends(createExtension({ postgres: sql }))
+
+// ⚡ PREBAKED - Uses pre-generated SQL (~0.03ms overhead)
+const activeUsers = await prisma.user.findMany({
+  where: { status: 'ACTIVE' },
+  skip: 0,
+  take: 10,
+  orderBy: { createdAt: 'desc' },
+})
+
+// 🔨 RUNTIME - Generates SQL on-the-fly (~0.2ms overhead, still fast!)
+const searchUsers = await prisma.user.findMany({
+  where: { email: { contains: '@example.com' } },
+})
 ```
 
-**After (Generator Mode):**
+The extension automatically:
+
+- Uses prebaked SQL for matching queries (instant)
+- Falls back to runtime generation for non-matching queries (still fast)
+- Tracks which queries are prebaked via `onQuery` callback
+
+**Dynamic Parameters:**
+
+Use `$paramName` syntax for runtime values:
+
+```prisma
+/// @optimize {
+///   "method": "findMany",
+///   "query": {
+///     "where": { "status": "$status" },
+///     "skip": "$skip",
+///     "take": "$take"
+///   }
+/// }
+model User {
+  id     Int    @id
+  status String
+}
+```
+
+**Generator Configuration:**
 
 ```prisma
-// schema.prisma
 generator sql {
   provider = "prisma-sql-generator"
-}
 
-model User {
-  /// @sql.findMany({ where: { status: "ACTIVE" } })
+  // Optional: Override auto-detected dialect
+  // dialect = "postgres"  // or "sqlite"
+
+  // Optional: Custom output directory
+  // output = "./generated/sql"
+
+  // Optional: Skip invalid directives instead of failing
+  // skipInvalid = "true"
 }
 ```
 
+### Access Original Prisma
+
 ```typescript
-import { createExtension } from '.prisma/client/sql'
-import postgres from 'postgres'
+const models = convertDMMFToModels(Prisma.dmmf.datamodel)
+const prisma = new PrismaClient().$extends(
+  speedExtension({ postgres: sql, models }),
+)
 
-const sql = postgres(DATABASE_URL)
-const prisma = new PrismaClient().$extends(createExtension({ postgres: sql }))
+// Fast (via raw SQL)
+const fast = await prisma.user.findMany()
 
-const users = await prisma.user.findMany({ where: { status: 'ACTIVE' } })
+// Slow (via Prisma engine)
+const slow = await prisma.$original.user.findMany()
 ```
 
-**After (Runtime Mode):**
+### Edge Runtime
+
+**Vercel Edge Functions:**
 
 ```typescript
-import postgres from 'postgres'
+import { PrismaClient, Prisma } from '@prisma/client'
 import { speedExtension, convertDMMFToModels } from 'prisma-sql'
-import { Prisma } from '@prisma/client'
+import postgres from 'postgres'
 
 const models = convertDMMFToModels(Prisma.dmmf.datamodel)
-const sql = postgres(DATABASE_URL)
+const sql = postgres(process.env.DATABASE_URL)
 const prisma = new PrismaClient().$extends(
   speedExtension({ postgres: sql, models }),
 )
 
+export const config = { runtime: 'edge' }
+
+export default async function handler(req: Request) {
+  const users = await prisma.user.findMany()
+  return Response.json(users)
+}
+```
+
+**Cloudflare Workers:**
+
+For Cloudflare Workers, use the standalone SQL generation API:
+
+```typescript
+import { createToSQL, convertDMMFToModels } from 'prisma-sql'
+import { Prisma } from '@prisma/client'
+
+const models = convertDMMFToModels(Prisma.dmmf.datamodel)
+const toSQL = createToSQL(models, 'sqlite')
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const { sql, params } = toSQL('User', 'findMany', {
+      where: { status: 'ACTIVE' },
+    })
+
+    const result = await env.DB.prepare(sql)
+      .bind(...params)
+      .all()
+    return Response.json(result.results)
+  },
+}
+```
+
+## Generator Mode Details
+
+### How It Works
+
+```
+Build Time:
+  schema.prisma
+       ↓
+  /// @optimize { "method": "findMany", "query": { "where": { "status": "ACTIVE" } } }
+       ↓
+  npx prisma generate
+       ↓
+  generated/sql/index.ts
+       ↓
+  QUERIES = {
+    User: {
+      findMany: {
+        '{"where":{"status":"ACTIVE"}}': {
+          sql: 'SELECT * FROM users WHERE status = $1',
+          params: ['ACTIVE'],
+          dynamicKeys: []
+        }
+      }
+    }
+  }
+
+Runtime:
+  prisma.user.findMany({ where: { status: 'ACTIVE' } })
+       ↓
+  Normalize query → '{"where":{"status":"ACTIVE"}}'
+       ↓
+  QUERIES.User.findMany[query] found?
+       ↓
+  YES → ⚡ Use prebaked SQL (0.03ms overhead)
+       ↓
+  NO → 🔨 Generate SQL runtime (0.2ms overhead)
+       ↓
+  Execute via postgres.js/better-sqlite3
+```
+
+### Optimize Directive Examples
+
+**Basic query:**
+
+```prisma
+/// @optimize {
+///   "method": "findMany",
+///   "query": {
+///     "where": { "status": "ACTIVE" }
+///   }
+/// }
+model User {
+  id     Int    @id
+  status String
+}
+```
+
+**With pagination:**
+
+```prisma
+/// @optimize {
+///   "method": "findMany",
+///   "query": {
+///     "skip": "$skip",
+///     "take": "$take",
+///     "orderBy": { "createdAt": "desc" }
+///   }
+/// }
+```
+
+**With relations:**
+
+```prisma
+/// @optimize {
+///   "method": "findMany",
+///   "query": {
+///     "include": {
+///       "posts": {
+///         "where": { "published": true },
+///         "orderBy": { "createdAt": "desc" },
+///         "take": 5
+///       }
+///     }
+///   }
+/// }
+```
+
+**Complex query:**
+
+```prisma
+/// @optimize {
+///   "method": "findMany",
+///   "query": {
+///     "skip": "$skip",
+///     "take": "$take",
+///     "orderBy": { "createdAt": "desc" },
+///     "include": {
+///       "company": {
+///         "where": { "deletedAt": null },
+///         "select": { "id": true, "name": true }
+///       }
+///     }
+///   }
+/// }
+```
+
+## Migration Guide
+
+### From Prisma Client
+
+**Before:**
+
+```typescript
+const prisma = new PrismaClient()
 const users = await prisma.user.findMany()
 ```
 
+**After:**
+
+```typescript
+import { PrismaClient, Prisma } from '@prisma/client'
+import { speedExtension, convertDMMFToModels } from 'prisma-sql'
+import postgres from 'postgres'
+
+const models = convertDMMFToModels(Prisma.dmmf.datamodel)
+const sql = postgres(process.env.DATABASE_URL)
+const prisma = new PrismaClient().$extends(
+  speedExtension({ postgres: sql, models }),
+)
+
+const users = await prisma.user.findMany() // Same API, just faster
+```
+
 ### From Drizzle
 
 **Before:**
@@ -908,8 +794,9 @@ const users = await db
 **After:**
 
 ```typescript
+import { PrismaClient, Prisma } from '@prisma/client'
 import { speedExtension, convertDMMFToModels } from 'prisma-sql'
-import { Prisma } from '@prisma/client'
+import postgres from 'postgres'
 
 const models = convertDMMFToModels(Prisma.dmmf.datamodel)
 const sql = postgres(DATABASE_URL)
@@ -922,67 +809,25 @@ const users = await prisma.user.findMany({
 })
 ```
 
-## Local Development
-
-### Testing the Generator Locally
-
-**1. Build the package:**
-
-```bash
-cd prisma-sql
-npm install
-npm run build
-```
-
-**2. Link globally:**
-
-```bash
-npm link
-```
-
-**3. Use in your project:**
-
-```bash
-cd your-project
-npm link prisma-sql
-npx prisma generate
-```
-
-**Alternative: Use file path directly in schema:**
-
-```prisma
-generator sql {
-  provider = "node ../path/to/prisma-sql/dist/generator.cjs"
-}
-```
-
-**Unlink when done:**
-
-```bash
-npm unlink prisma-sql  # In your project
-cd prisma-sql
-npm unlink              # In prisma-sql directory
-```
-
 ## Limitations
 
 ### Partially Supported
 
 These features work but have limitations:
 
-- ⚠️ **Array operations**: Basic operations (`has`, `hasSome`, `hasEvery`, `isEmpty`) work. Advanced filtering like `array_contains(array_field, [1,2,3])` not yet supported.
-- ⚠️ **JSON operations**: Path-based filtering works (`json.path(['field'], { equals: 'value' })`). Advanced JSON functions not yet supported.
+- ⚠️ **Array operations**: Basic operations (`has`, `hasSome`, `hasEvery`, `isEmpty`) work. Advanced filtering not yet supported.
+- ⚠️ **JSON operations**: Path-based filtering works. Advanced JSON functions not yet supported.
 
 ### Not Yet Supported
 
-These Prisma features are not supported and will fall back to Prisma Client:
+These Prisma features will fall back to Prisma Client:
 
 - ❌ Full-text search (`search` operator)
 - ❌ Composite types (MongoDB-style embedded documents)
 - ❌ Raw database features (PostGIS, pg_trgm, etc.)
-- ❌ Some advanced aggregations in `groupBy` (nested aggregations)
+- ❌ Some advanced aggregations in `groupBy`
 
-If you encounter unsupported queries, enable `debug: true` to see which queries are being converted and which fall back to Prisma.
+Enable `debug: true` to see which queries are accelerated vs fallback.
 
 ### Database Support
 
@@ -1013,23 +858,9 @@ const prisma = new PrismaClient().$extends(
 )
 ```
 
-### "Generator: Cannot find module"
-
-The package hasn't been built or linked:
-
-```bash
-# In prisma-sql directory
-npm run build
-npm link
-
-# In your project
-npm link prisma-sql
-npx prisma generate
-```
-
 ### "Results don't match Prisma Client"
 
-Enable debug mode to inspect generated SQL:
+Enable debug mode and compare SQL:
 
 ```typescript
 const models = convertDMMFToModels(Prisma.dmmf.datamodel)
@@ -1037,7 +868,7 @@ const models = convertDMMFToModels(Prisma.dmmf.datamodel)
 speedExtension({
   postgres: sql,
   models,
-  debug: true,
+  debug: true, // Shows generated SQL
 })
 ```
 
@@ -1055,19 +886,10 @@ Increase postgres.js pool size:
 
 ```typescript
 const sql = postgres(DATABASE_URL, {
-  max: 50,
+  max: 50, // Default is 10
 })
 ```
 
-### "Type errors after extending"
-
-Ensure `@prisma/client` is up to date:
-
-```bash
-npm update @prisma/client
-npx prisma generate
-```
-
 ### "Performance not improving"
 
 Some queries won't see dramatic improvements:
@@ -1090,6 +912,48 @@ speedExtension({
 })
 ```
 
+## Local Development
+
+### Testing the Generator Locally
+
+**1. Build the package:**
+
+```bash
+cd prisma-sql
+npm install
+npm run build
+```
+
+**2. Link globally:**
+
+```bash
+npm link
+```
+
+**3. Use in your project:**
+
+```bash
+cd your-project
+npm link prisma-sql
+npx prisma generate
+```
+
+**Alternative: Use file path directly in schema:**
+
+```prisma
+generator sql {
+  provider = "node ../path/to/prisma-sql/dist/generator.cjs"
+}
+```
+
+**Unlink when done:**
+
+```bash
+npm unlink prisma-sql  # In your project
+cd prisma-sql
+npm unlink              # In prisma-sql directory
+```
+
 ## FAQ
 
 **Q: Do I need to keep using Prisma Client?**  
@@ -1099,7 +963,7 @@ A: Yes. You need Prisma for schema management, migrations, types, and write oper
 A: Yes. No schema changes required. It works with your existing Prisma schema and generated client.
 
 **Q: What about writes (create, update, delete)?**  
-A: Writes still use Prisma Client. This extension only accelerates reads. For write-heavy workloads, this provides less benefit.
+A: Writes still use Prisma Client. This extension only accelerates reads.
 
 **Q: Is it production ready?**  
 A: Yes. 137 E2E tests verify exact parity with Prisma Client across both Prisma v6 and v7. Used in production.
@@ -1108,29 +972,22 @@ A: Yes. 137 E2E tests verify exact parity with Prisma Client across both Prisma
 A: Yes. Works with any PostgreSQL-compatible database. Just pass the connection string to postgres.js.
 
 **Q: Does it support Prisma middlewares?**  
-A: The extension runs after middlewares. If you need middleware to see the actual SQL, use Prisma's query logging.
+A: The extension runs after middlewares. For middleware to see actual SQL, use Prisma's query logging.
 
 **Q: Can I still use `$queryRaw` and `$executeRaw`?**  
-A: Yes. Those methods are unaffected. You also still have direct access to the postgres.js client.
+A: Yes. Those methods are unaffected.
 
 **Q: What's the overhead of SQL generation?**  
-A: Generator mode: ~0.03ms (prebaked queries). Runtime mode: ~0.2ms. Even with this overhead, total time is 2-7x faster than Prisma.
-
-**Q: How do I benchmark my own queries?**  
-A: Use the `onQuery` callback to measure each query, or see the [Benchmarking](#benchmarking) section below.
-
-**Q: How does performance compare to Prisma v7?**  
-A: Prisma v7 introduced significant improvements (~39% faster than v6 on PostgreSQL, ~24% on SQLite), but this extension still provides 2-7x additional speedup over v7 depending on query complexity.
+A: Runtime mode: ~0.2ms per query. Generator mode: ~0.03ms for prebaked queries. Still 2-7x faster than Prisma overall.
 
 **Q: Should I use generator mode or runtime mode?**  
-A: Generator mode is recommended for production (faster). Runtime mode is better for prototyping or fully dynamic queries.
+A: Start with runtime mode (simpler). Add generator mode for your hottest queries later if needed.
 
 ## Examples
 
 - [Generator Mode Example](./examples/generator-mode) - Complete working example
 - [PostgreSQL E2E Tests](./tests/e2e/postgres.test.ts) - Comprehensive query examples
 - [SQLite E2E Tests](./tests/e2e/sqlite.e2e.test.ts) - SQLite-specific queries
-- [Runtime API Tests](./tests/e2e/runtime-api.test.ts) - All three APIs
 
 To run examples locally:
 
@@ -1171,22 +1028,6 @@ await prisma.post.findMany({ include: { author: true } })
 console.table(queries)
 ```
 
-Or run the full test suite benchmarks:
-
-```bash
-git clone https://github.com/multipliedtwice/prisma-sql
-cd prisma-sql
-npm install
-
-npx prisma db push
-
-DATABASE_URL="postgresql://..." npm run test:e2e:postgres
-
-npm run test:e2e:sqlite
-```
-
-Results include timing for Prisma vs Extension vs Drizzle (where applicable).
-
 ## Contributing
 
 PRs welcome! Priority areas: