Runbook

Common Issues

"Model or operation not supported"

Symptoms: HTTP 400/500 error with this message.

Diagnosis:

1. Check model name matches schema.prisma (case-sensitive)
2. Verify prisma generate has run

Resolution:

# Regenerate Prisma client
pnpm --filter @repo/crm-db db:core:generate

# Verify model exists
grep "^model" packages/crm/db/schema.prisma

Slow Queries

Symptoms: findMany operations taking > 500ms.

Diagnosis:

1. Check crud_operation_duration histogram
2. Check for missing indexes
3. Verify query filters are indexed

Resolution:

-- Check indexes on a table
SELECT indexname, indexdef 
FROM pg_indexes 
WHERE tablename = 'contact';

-- Add index for common filter
CREATE INDEX idx_contact_org ON contact(org_id);

Hooks Not Executing

Symptoms: Side-effects (emails, webhooks) not triggering.

Diagnosis:

1. Check hook registration in hooks.ts
2. Verify model/op matchers
3. Check hook handler errors

Resolution:

// Debug hook execution
import { crudHooks } from "./hooks";

console.log("Registered hooks:", crudHooks.getRegistered());

Maintenance

Adding a New Model

1. Define model in packages/crm/db/schema.prisma
2. Generate client: pnpm --filter @repo/crm-db db:core:generate
3. Create Zod schemas in crm/server/features/crud/schemas/
4. Register routes using createCrudRoutes:

   import { createCrudRoutes } from "@/features/crud/crud.routes";
   
   export const myModelRoutes = createCrudRoutes({
     model: "myModel",
     schemas: { ... },
   });

5. Add to router in crm/server/routes/index.ts

Modifying Operation Pipeline

Warning: The shared pipeline in features/shared/operation-pipeline.ts affects all database operations.

Changes here require:

1. Full regression testing
2. Review by another engineer
3. Deploy during maintenance window

Database Commands

# Push schema
pnpm --filter @repo/crm-db db:core:push

# Studio
pnpm --filter @repo/crm-db db:core:studio

# Generate migrations
pnpm --filter @repo/crm-db db:core:gen-migration

# Deploy migrations
pnpm --filter @repo/crm-db db:core:migrate