@girardmedia/bootspring 1.2.0 → 2.0.3

package/skills/patterns/database/pooling.md

@@ -1,357 +0,0 @@
-# Database Connection Pooling Patterns
-
-Patterns for managing database connections efficiently.
-
-## Prisma Connection Pooling
-
-```typescript
-// lib/db.ts
-import { PrismaClient } from '@prisma/client'
-
-const globalForPrisma = globalThis as unknown as {
-  prisma: PrismaClient | undefined
-}
-
-export const prisma =
-  globalForPrisma.prisma ??
-  new PrismaClient({
-    log: process.env.NODE_ENV === 'development'
-      ? ['query', 'error', 'warn']
-      : ['error'],
-    datasources: {
-      db: {
-        url: process.env.DATABASE_URL
-      }
-    }
-  })
-
-if (process.env.NODE_ENV !== 'production') {
-  globalForPrisma.prisma = prisma
-}
-```
-
-## Connection URL with Pool Settings
-
-```bash
-# .env
-# PostgreSQL connection with pool settings
-DATABASE_URL="postgresql://user:password@localhost:5432/mydb?connection_limit=20&pool_timeout=30"
-
-# Using PgBouncer (recommended for serverless)
-DATABASE_URL="postgresql://user:password@pgbouncer:6432/mydb?pgbouncer=true"
-
-# Direct URL for migrations (bypasses PgBouncer)
-DIRECT_URL="postgresql://user:password@localhost:5432/mydb"
-```
-
-```prisma
-// prisma/schema.prisma
-datasource db {
-  provider  = "postgresql"
-  url       = env("DATABASE_URL")
-  directUrl = env("DIRECT_URL")
-}
-```
-
-## Serverless Connection Handling
-
-```typescript
-// lib/db/serverless.ts
-import { PrismaClient } from '@prisma/client'
-import { Pool } from '@neondatabase/serverless'
-
-// For Neon serverless driver
-const pool = new Pool({ connectionString: process.env.DATABASE_URL })
-
-// For edge functions
-export async function queryWithServerlessPool<T>(
-  query: string,
-  params?: any[]
-): Promise<T[]> {
-  const client = await pool.connect()
-  try {
-    const result = await client.query(query, params)
-    return result.rows as T[]
-  } finally {
-    client.release()
-  }
-}
-
-// Prisma with connection limit for serverless
-const prisma = new PrismaClient({
-  datasources: {
-    db: {
-      url: `${process.env.DATABASE_URL}?connection_limit=1`
-    }
-  }
-})
-
-export { prisma }
-```
-
-## PgBouncer Configuration
-
-```ini
-# pgbouncer.ini
-[databases]
-mydb = host=localhost port=5432 dbname=mydb
-
-[pgbouncer]
-listen_addr = 0.0.0.0
-listen_port = 6432
-auth_type = md5
-auth_file = /etc/pgbouncer/userlist.txt
-
-# Pool settings
-pool_mode = transaction
-max_client_conn = 1000
-default_pool_size = 25
-min_pool_size = 5
-reserve_pool_size = 5
-
-# Timeouts
-server_connect_timeout = 15
-server_idle_timeout = 600
-server_lifetime = 3600
-```
-
-## Connection Lifecycle Management
-
-```typescript
-// lib/db/lifecycle.ts
-import { PrismaClient } from '@prisma/client'
-
-class DatabaseManager {
-  private static instance: PrismaClient | null = null
-  private static connectionCount = 0
-
-  static async getClient(): Promise<PrismaClient> {
-    if (!this.instance) {
-      this.instance = new PrismaClient({
-        log: ['error', 'warn']
-      })
-      await this.instance.$connect()
-      console.log('Database connected')
-    }
-    this.connectionCount++
-    return this.instance
-  }
-
-  static async releaseClient(): Promise<void> {
-    this.connectionCount--
-    if (this.connectionCount <= 0 && this.instance) {
-      // Optionally disconnect when no clients are using it
-      // await this.instance.$disconnect()
-      // this.instance = null
-    }
-  }
-
-  static async disconnect(): Promise<void> {
-    if (this.instance) {
-      await this.instance.$disconnect()
-      this.instance = null
-      this.connectionCount = 0
-      console.log('Database disconnected')
-    }
-  }
-
-  static async healthCheck(): Promise<boolean> {
-    try {
-      const client = await this.getClient()
-      await client.$queryRaw`SELECT 1`
-      return true
-    } catch {
-      return false
-    }
-  }
-}
-
-// Graceful shutdown
-process.on('SIGINT', async () => {
-  await DatabaseManager.disconnect()
-  process.exit(0)
-})
-
-process.on('SIGTERM', async () => {
-  await DatabaseManager.disconnect()
-  process.exit(0)
-})
-
-export { DatabaseManager }
-```
-
-## Request-scoped Connections
-
-```typescript
-// lib/db/request-scoped.ts
-import { PrismaClient } from '@prisma/client'
-import { AsyncLocalStorage } from 'async_hooks'
-
-const asyncLocalStorage = new AsyncLocalStorage<{ prisma: PrismaClient }>()
-
-const globalPrisma = new PrismaClient()
-
-export function withDatabase<T>(fn: () => Promise<T>): Promise<T> {
-  return asyncLocalStorage.run({ prisma: globalPrisma }, fn)
-}
-
-export function getDatabase(): PrismaClient {
-  const store = asyncLocalStorage.getStore()
-  if (!store) {
-    throw new Error('Database not available in current context')
-  }
-  return store.prisma
-}
-
-// Middleware usage
-import { NextRequest, NextResponse } from 'next/server'
-
-export async function middleware(request: NextRequest) {
-  return withDatabase(async () => {
-    // Database available in this context
-    return NextResponse.next()
-  })
-}
-```
-
-## Connection Pool Monitoring
-
-```typescript
-// lib/db/monitoring.ts
-import { PrismaClient } from '@prisma/client'
-
-interface PoolMetrics {
-  activeConnections: number
-  idleConnections: number
-  waitingRequests: number
-  totalQueries: number
-}
-
-class MonitoredPrismaClient extends PrismaClient {
-  private metrics: PoolMetrics = {
-    activeConnections: 0,
-    idleConnections: 0,
-    waitingRequests: 0,
-    totalQueries: 0
-  }
-
-  constructor() {
-    super({
-      log: [
-        { level: 'query', emit: 'event' },
-        { level: 'error', emit: 'event' }
-      ]
-    })
-
-    // Track queries
-    this.$on('query' as never, (e: any) => {
-      this.metrics.totalQueries++
-      console.log(`Query: ${e.query} - Duration: ${e.duration}ms`)
-    })
-
-    this.$on('error' as never, (e: any) => {
-      console.error('Database error:', e)
-    })
-  }
-
-  getMetrics(): PoolMetrics {
-    return { ...this.metrics }
-  }
-
-  async getPoolStatus(): Promise<object> {
-    const result = await this.$queryRaw<any[]>`
-      SELECT
-        count(*) FILTER (WHERE state = 'active') as active,
-        count(*) FILTER (WHERE state = 'idle') as idle,
-        count(*) as total
-      FROM pg_stat_activity
-      WHERE datname = current_database()
-    `
-    return result[0]
-  }
-}
-
-export const monitoredPrisma = new MonitoredPrismaClient()
-
-// API endpoint for monitoring
-// app/api/health/db/route.ts
-import { NextResponse } from 'next/server'
-import { monitoredPrisma } from '@/lib/db/monitoring'
-
-export async function GET() {
-  try {
-    const status = await monitoredPrisma.getPoolStatus()
-    const metrics = monitoredPrisma.getMetrics()
-
-    return NextResponse.json({
-      healthy: true,
-      poolStatus: status,
-      metrics
-    })
-  } catch (error) {
-    return NextResponse.json(
-      { healthy: false, error: 'Database connection failed' },
-      { status: 503 }
-    )
-  }
-}
-```
-
-## Retry Logic with Backoff
-
-```typescript
-// lib/db/retry.ts
-import { PrismaClient, Prisma } from '@prisma/client'
-
-interface RetryOptions {
-  maxRetries?: number
-  baseDelay?: number
-  maxDelay?: number
-}
-
-export async function withRetry<T>(
-  operation: () => Promise<T>,
-  options: RetryOptions = {}
-): Promise<T> {
-  const { maxRetries = 3, baseDelay = 100, maxDelay = 5000 } = options
-
-  let lastError: Error | null = null
-
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      return await operation()
-    } catch (error) {
-      lastError = error as Error
-
-      // Check if error is retryable
-      if (error instanceof Prisma.PrismaClientKnownRequestError) {
-        // Connection errors
-        if (['P1001', 'P1002', 'P1008', 'P1017'].includes(error.code)) {
-          const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay)
-          console.log(`Retrying after ${delay}ms (attempt ${attempt + 1}/${maxRetries})`)
-          await new Promise(resolve => setTimeout(resolve, delay))
-          continue
-        }
-      }
-
-      // Non-retryable error
-      throw error
-    }
-  }
-
-  throw lastError
-}
-
-// Usage
-const users = await withRetry(() => prisma.user.findMany(), {
-  maxRetries: 3,
-  baseDelay: 100
-})
-```
-
-## When to Use
-
-- High-traffic applications
-- Serverless deployments
-- Multi-tenant systems
-- Connection-limited databases

package/skills/patterns/database/prisma.md

@@ -1,180 +0,0 @@
-# Prisma ORM Patterns
-
-Battle-tested patterns for Prisma with Next.js.
-
-## Client Singleton (Prevents Connection Exhaustion)
-
-```typescript
-// lib/db.ts
-import { PrismaClient } from '@prisma/client'
-
-const globalForPrisma = globalThis as unknown as {
-  prisma: PrismaClient | undefined
-}
-
-export const prisma = globalForPrisma.prisma ?? new PrismaClient({
-  log: process.env.NODE_ENV === 'development'
-    ? ['query', 'error', 'warn']
-    : ['error'],
-})
-
-if (process.env.NODE_ENV !== 'production') {
-  globalForPrisma.prisma = prisma
-}
-```
-
-## Common Query Patterns
-
-```typescript
-// Create with relations
-const user = await prisma.user.create({
-  data: {
-    email: 'john@example.com',
-    name: 'John Doe',
-    profile: {
-      create: { bio: 'Hello world' }
-    }
-  },
-  include: { profile: true }
-})
-
-// Read with filters and pagination
-const posts = await prisma.post.findMany({
-  where: {
-    published: true,
-    author: { email: { contains: '@example.com' } }
-  },
-  include: { author: { select: { name: true } } },
-  orderBy: { createdAt: 'desc' },
-  skip: (page - 1) * pageSize,
-  take: pageSize
-})
-
-// Update
-const updated = await prisma.user.update({
-  where: { id: userId },
-  data: { name: 'Updated Name' }
-})
-
-// Upsert (create or update)
-const result = await prisma.user.upsert({
-  where: { email: 'user@example.com' },
-  update: { name: 'Updated' },
-  create: { email: 'user@example.com', name: 'New User' }
-})
-
-// Soft delete pattern
-const deleted = await prisma.user.update({
-  where: { id: userId },
-  data: { deletedAt: new Date() }
-})
-```
-
-## Transactions
-
-```typescript
-// Sequential transaction (atomic)
-const [user, post] = await prisma.$transaction([
-  prisma.user.create({ data: userData }),
-  prisma.post.create({ data: postData })
-])
-
-// Interactive transaction (with logic)
-await prisma.$transaction(async (tx) => {
-  const user = await tx.user.findUnique({ where: { id: userId } })
-  if (!user) throw new Error('User not found')
-  if (user.credits < 10) throw new Error('Insufficient credits')
-
-  await tx.user.update({
-    where: { id: userId },
-    data: { credits: { decrement: 10 } }
-  })
-
-  await tx.transaction.create({
-    data: { userId, amount: -10, type: 'PURCHASE' }
-  })
-})
-```
-
-## Server Action Pattern
-
-```typescript
-// actions/user.ts
-'use server'
-import { prisma } from '@/lib/db'
-import { revalidatePath } from 'next/cache'
-import { z } from 'zod'
-
-const UpdateProfileSchema = z.object({
-  name: z.string().min(1).max(100),
-  bio: z.string().max(500).optional()
-})
-
-export async function updateProfile(userId: string, formData: FormData) {
-  const validated = UpdateProfileSchema.parse({
-    name: formData.get('name'),
-    bio: formData.get('bio')
-  })
-
-  await prisma.user.update({
-    where: { id: userId },
-    data: validated
-  })
-
-  revalidatePath('/profile')
-  return { success: true }
-}
-```
-
-## Migration Commands
-
-```bash
-# Development: create and apply migration
-npx prisma migrate dev --name add_posts_table
-
-# Production: apply pending migrations
-npx prisma migrate deploy
-
-# Regenerate client after schema changes
-npx prisma generate
-
-# Visual database browser
-npx prisma studio
-
-# Reset database (WARNING: destroys data)
-npx prisma migrate reset
-```
-
-## Schema Example
-
-```prisma
-// prisma/schema.prisma
-model User {
-  id        String   @id @default(cuid())
-  email     String   @unique
-  name      String?
-  credits   Int      @default(0)
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-  deletedAt DateTime?
-
-  posts    Post[]
-  profile  Profile?
-
-  @@index([email])
-  @@map("users")
-}
-
-model Post {
-  id        String   @id @default(cuid())
-  title     String
-  content   String?
-  published Boolean  @default(false)
-  authorId  String
-  author    User     @relation(fields: [authorId], references: [id])
-  createdAt DateTime @default(now())
-
-  @@index([authorId])
-  @@map("posts")
-}
-```

package/skills/patterns/database/relations.md

@@ -1,187 +0,0 @@
-# Database Relations Patterns
-
-Patterns for modeling and querying relationships in Prisma.
-
-## One-to-One
-
-```prisma
-// schema.prisma
-model User {
-  id      String   @id @default(cuid())
-  email   String   @unique
-  profile Profile?
-}
-
-model Profile {
-  id     String @id @default(cuid())
-  bio    String?
-  avatar String?
-  userId String @unique
-  user   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
-}
-```
-
-```typescript
-// Query with relation
-const userWithProfile = await prisma.user.findUnique({
-  where: { id },
-  include: { profile: true }
-})
-```
-
-## One-to-Many
-
-```prisma
-// schema.prisma
-model User {
-  id    String @id @default(cuid())
-  posts Post[]
-}
-
-model Post {
-  id       String @id @default(cuid())
-  title    String
-  authorId String
-  author   User   @relation(fields: [authorId], references: [id])
-
-  @@index([authorId])
-}
-```
-
-```typescript
-// Query user's posts
-const userWithPosts = await prisma.user.findUnique({
-  where: { id },
-  include: {
-    posts: {
-      orderBy: { createdAt: 'desc' },
-      take: 10
-    }
-  }
-})
-
-// Create post with user
-const post = await prisma.post.create({
-  data: {
-    title: 'My Post',
-    author: { connect: { id: userId } }
-  }
-})
-```
-
-## Many-to-Many (Implicit)
-
-```prisma
-// schema.prisma
-model Post {
-  id         String     @id @default(cuid())
-  title      String
-  categories Category[]
-}
-
-model Category {
-  id    String @id @default(cuid())
-  name  String @unique
-  posts Post[]
-}
-```
-
-```typescript
-// Add categories to post
-await prisma.post.update({
-  where: { id: postId },
-  data: {
-    categories: {
-      connect: [{ id: cat1 }, { id: cat2 }]
-    }
-  }
-})
-
-// Query with categories
-const post = await prisma.post.findUnique({
-  where: { id },
-  include: { categories: true }
-})
-```
-
-## Many-to-Many (Explicit with Extra Fields)
-
-```prisma
-// schema.prisma
-model User {
-  id    String       @id @default(cuid())
-  teams TeamMember[]
-}
-
-model Team {
-  id      String       @id @default(cuid())
-  name    String
-  members TeamMember[]
-}
-
-model TeamMember {
-  id       String   @id @default(cuid())
-  userId   String
-  teamId   String
-  role     String   @default("MEMBER")
-  joinedAt DateTime @default(now())
-
-  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
-  team Team @relation(fields: [teamId], references: [id], onDelete: Cascade)
-
-  @@unique([userId, teamId])
-}
-```
-
-```typescript
-// Add user to team with role
-await prisma.teamMember.create({
-  data: {
-    user: { connect: { id: userId } },
-    team: { connect: { id: teamId } },
-    role: 'ADMIN'
-  }
-})
-
-// Query team with members
-const team = await prisma.team.findUnique({
-  where: { id },
-  include: {
-    members: {
-      include: { user: true }
-    }
-  }
-})
-```
-
-## Self-Relation
-
-```prisma
-// schema.prisma
-model Comment {
-  id       String    @id @default(cuid())
-  content  String
-  parentId String?
-  parent   Comment?  @relation("CommentReplies", fields: [parentId], references: [id])
-  replies  Comment[] @relation("CommentReplies")
-}
-```
-
-```typescript
-// Get comments with nested replies
-const comments = await prisma.comment.findMany({
-  where: { parentId: null },
-  include: {
-    replies: {
-      include: { replies: true }
-    }
-  }
-})
-```
-
-## When to Use
-
-- User profiles (1:1)
-- Posts and comments (1:N)
-- Tags and categories (M:N)
-- Team memberships (M:N with data)