@kood/claude-code 0.2.0 → 0.2.2

package/templates/hono/docs/library/drizzle/index.md

@@ -0,0 +1,259 @@
+# Drizzle ORM - Database ORM
+
+> Type-safe, lightweight TypeScript ORM
+
+@config.md
+@cloudflare-d1.md
+
+---
+
+## 설치
+
+```bash
+npm install drizzle-orm pg
+npm install -D drizzle-kit @types/pg
+```
+
+---
+
+## 스키마 정의
+
+### 폴더 구조
+
+```
+src/
+├── db/
+│   ├── index.ts       # Drizzle client
+│   └── schema/
+│       ├── index.ts   # export all
+│       ├── user.ts    # User 테이블
+│       └── post.ts    # Post 테이블
+```
+
+### user.ts
+
+```typescript
+import { pgTable, serial, text, timestamp, boolean } from 'drizzle-orm/pg-core'
+
+// 사용자 테이블
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  email: text('email').notNull().unique(),  // 로그인 이메일
+  name: text('name'),                        // 표시 이름
+  verified: boolean('verified').notNull().default(false),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow(),
+})
+
+// 타입 추론
+export type User = typeof users.$inferSelect
+export type NewUser = typeof users.$inferInsert
+```
+
+---
+
+## Drizzle Client
+
+```typescript
+// src/db/index.ts
+import { drizzle } from 'drizzle-orm/node-postgres'
+import * as schema from './schema'
+
+export const db = drizzle(process.env.DATABASE_URL!, { schema })
+```
+
+---
+
+## CRUD
+
+### Create
+
+```typescript
+import { db } from '@/db'
+import { users } from '@/db/schema'
+
+const user = await db.insert(users).values({
+  email: 'user@example.com',
+  name: 'John',
+}).returning()
+
+// Batch insert
+await db.insert(users).values([
+  { email: 'user1@example.com', name: 'User 1' },
+  { email: 'user2@example.com', name: 'User 2' },
+])
+```
+
+### Read
+
+```typescript
+import { eq, and, or, gt, like, desc, asc } from 'drizzle-orm'
+
+// 전체 조회
+const allUsers = await db.select().from(users)
+
+// 조건 조회
+const user = await db.select().from(users).where(eq(users.id, 1))
+
+// 복합 조건
+const filtered = await db.select().from(users).where(
+  and(
+    eq(users.verified, true),
+    gt(users.createdAt, new Date('2024-01-01'))
+  )
+)
+
+// 정렬 + 페이지네이션
+const paginated = await db.select().from(users)
+  .orderBy(desc(users.createdAt))
+  .limit(10)
+  .offset(0)
+
+// 특정 필드만 선택
+const emails = await db.select({ email: users.email }).from(users)
+```
+
+### Update
+
+```typescript
+await db.update(users)
+  .set({ name: 'Updated Name' })
+  .where(eq(users.id, 1))
+
+// Upsert
+await db.insert(users)
+  .values({ email: 'user@example.com', name: 'John' })
+  .onConflictDoUpdate({
+    target: users.email,
+    set: { name: 'John Updated' },
+  })
+```
+
+### Delete
+
+```typescript
+await db.delete(users).where(eq(users.id, 1))
+await db.delete(users).where(eq(users.verified, false))
+```
+
+---
+
+## 필터링 연산자
+
+```typescript
+import { eq, ne, gt, gte, lt, lte, like, ilike, inArray, isNull, between, and, or, not } from 'drizzle-orm'
+
+// 비교
+where(eq(users.id, 1))           // =
+where(ne(users.id, 1))           // !=
+where(gt(users.age, 18))         // >
+where(gte(users.age, 18))        // >=
+where(lt(users.age, 65))         // <
+where(lte(users.age, 65))        // <=
+
+// 문자열
+where(like(users.name, '%John%'))
+where(ilike(users.name, '%john%'))  // 대소문자 무시
+
+// 배열
+where(inArray(users.id, [1, 2, 3]))
+
+// NULL
+where(isNull(users.deletedAt))
+
+// 범위
+where(between(users.age, 18, 65))
+
+// 논리
+where(and(eq(users.role, 'admin'), eq(users.verified, true)))
+where(or(eq(users.role, 'admin'), eq(users.role, 'moderator')))
+where(not(eq(users.role, 'guest')))
+```
+
+---
+
+## 트랜잭션
+
+```typescript
+const result = await db.transaction(async (tx) => {
+  const [user] = await tx.insert(users)
+    .values({ email: 'user@example.com' })
+    .returning()
+
+  await tx.insert(posts).values({ title: 'First Post', authorId: user.id })
+
+  return user
+})
+
+// 롤백
+await db.transaction(async (tx) => {
+  const [account] = await tx.select().from(accounts).where(eq(accounts.id, 1))
+  if (account.balance < 100) {
+    tx.rollback()  // 예외 발생, 트랜잭션 롤백
+  }
+  await tx.update(accounts).set({ balance: account.balance - 100 }).where(eq(accounts.id, 1))
+})
+```
+
+---
+
+## Hono와 함께 사용
+
+```typescript
+import { Hono } from 'hono'
+import { zValidator } from '@hono/zod-validator'
+import { z } from 'zod'
+import { HTTPException } from 'hono/http-exception'
+import { eq } from 'drizzle-orm'
+import { db } from '@/db'
+import { users } from '@/db/schema'
+
+const app = new Hono()
+
+app.post('/users',
+  zValidator('json', z.object({ email: z.email(), name: z.string().optional() })),
+  async (c) => {
+    const data = c.req.valid('json')
+
+    const existing = await db.select().from(users).where(eq(users.email, data.email))
+    if (existing.length > 0) {
+      throw new HTTPException(409, { message: 'Email already exists' })
+    }
+
+    const [user] = await db.insert(users).values(data).returning()
+    return c.json({ user }, 201)
+  }
+)
+
+app.get('/users/:id', async (c) => {
+  const id = Number(c.req.param('id'))
+  const [user] = await db.select().from(users).where(eq(users.id, id))
+
+  if (!user) {
+    throw new HTTPException(404, { message: 'User not found' })
+  }
+
+  return c.json({ user })
+})
+
+export default app
+```
+
+---
+
+## CLI 명령어
+
+```bash
+npx drizzle-kit generate    # 마이그레이션 생성
+npx drizzle-kit migrate     # 마이그레이션 실행
+npx drizzle-kit push        # 스키마 동기화 (개발용)
+npx drizzle-kit pull        # DB에서 스키마 가져오기
+npx drizzle-kit studio      # GUI 실행
+```
+
+---
+
+## 관련 문서
+
+- [Config 파일](./config.md) - drizzle.config.ts 설정
+- [Cloudflare D1](./cloudflare-d1.md)

package/templates/tanstack-start/docs/library/drizzle/cloudflare-d1.md

@@ -0,0 +1,146 @@
+# Drizzle - Cloudflare D1
+
+SQLite 기반 서버리스 DB. 일반 Drizzle 마이그레이션과 다른 워크플로우.
+
+트랜잭션 미지원 | drizzle-kit migrate 불가 - wrangler 사용
+
+## 설정
+
+### 스키마 (SQLite)
+
+```typescript
+// src/db/schema.ts
+import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core'
+
+export const users = sqliteTable('users', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  email: text('email').notNull().unique(),
+  name: text('name'),
+})
+
+export type User = typeof users.$inferSelect
+export type NewUser = typeof users.$inferInsert
+```
+
+### drizzle.config.ts
+
+```typescript
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  dialect: 'sqlite',
+  schema: './src/db/schema.ts',
+  out: './drizzle/migrations',
+  driver: 'd1-http',
+  dbCredentials: {
+    accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
+    databaseId: process.env.CLOUDFLARE_DATABASE_ID!,
+    token: process.env.CLOUDFLARE_D1_TOKEN!,
+  },
+})
+```
+
+### wrangler.jsonc
+
+```jsonc
+{
+  "d1_databases": [{
+    "binding": "DB",
+    "database_name": "my-db",
+    "database_id": "YOUR_DATABASE_ID",
+    "migrations_dir": "drizzle/migrations"
+  }]
+}
+```
+
+## 사용법
+
+```typescript
+import { drizzle } from 'drizzle-orm/d1'
+import * as schema from './db/schema'
+
+export interface Env {
+  DB: D1Database
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const db = drizzle(env.DB, { schema })
+    const users = await db.select().from(schema.users)
+    return new Response(JSON.stringify(users))
+  },
+}
+```
+
+## TanStack Start + D1
+
+```typescript
+// app/services/user.ts
+import { createServerFn } from '@tanstack/react-start'
+import { drizzle } from 'drizzle-orm/d1'
+import { eq } from 'drizzle-orm'
+import * as schema from '@/db/schema'
+
+// D1 바인딩 접근 (Cloudflare Pages/Workers)
+const getDb = () => {
+  const env = (globalThis as any).__env__
+  return drizzle(env.DB, { schema })
+}
+
+export const getUsers = createServerFn({ method: 'GET' })
+  .handler(async () => {
+    const db = getDb()
+    return db.select().from(schema.users)
+  })
+
+export const createUser = createServerFn({ method: 'POST' })
+  .validator((data: { email: string; name?: string }) => data)
+  .handler(async ({ data }) => {
+    const db = getDb()
+    const [user] = await db.insert(schema.users).values(data).returning()
+    return user
+  })
+```
+
+## 마이그레이션 워크플로우
+
+```bash
+# 1. D1 생성
+npx wrangler d1 create my-database
+
+# 2. 마이그레이션 생성
+npx drizzle-kit generate
+
+# 3. 로컬 적용
+npx wrangler d1 migrations apply my-database --local
+
+# 4. 원격 적용
+npx wrangler d1 migrations apply my-database --remote
+```
+
+## 로컬 개발
+
+```bash
+# Worker 실행
+npx wrangler dev
+
+# D1 조회
+npx wrangler d1 execute my-database --local \
+  --command "SELECT * FROM users;"
+```
+
+## 배포
+
+```bash
+npx drizzle-kit generate
+npx wrangler d1 migrations apply my-database --remote
+npx wrangler deploy
+```
+
+## 제한사항
+
+| 항목 | 일반 SQLite | D1 |
+|------|-------------|-----|
+| 마이그레이션 | drizzle-kit migrate | wrangler d1 |
+| 트랜잭션 | 지원 | 미지원 |
+| 접속 | 직접 | HTTP (D1 binding) |

package/templates/tanstack-start/docs/library/drizzle/config.md

@@ -0,0 +1,118 @@
+# Drizzle - Config 파일
+
+drizzle.config.ts 설정.
+
+## 기본 설정
+
+```typescript
+// drizzle.config.ts
+import 'dotenv/config'
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './src/db/schema/index.ts',
+  out: './drizzle/migrations',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+})
+```
+
+## 폴더 구조
+
+```
+프로젝트/
+├── drizzle.config.ts
+├── drizzle/
+│   └── migrations/
+│       ├── 0000_init.sql
+│       └── meta/
+├── src/
+│   └── db/
+│       └── schema/
+│           ├── index.ts
+│           └── user.ts
+```
+
+## PostgreSQL
+
+```typescript
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './src/db/schema/index.ts',
+  out: './drizzle/migrations',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+})
+```
+
+## MySQL
+
+```typescript
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  dialect: 'mysql',
+  schema: './src/db/schema/index.ts',
+  out: './drizzle/migrations',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+})
+```
+
+## SQLite
+
+```typescript
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  dialect: 'sqlite',
+  schema: './src/db/schema/index.ts',
+  out: './drizzle/migrations',
+  dbCredentials: {
+    url: './sqlite.db',
+  },
+})
+```
+
+## 설정 옵션
+
+| 옵션 | 설명 |
+|------|------|
+| `dialect` | DB 종류 (postgresql, mysql, sqlite) |
+| `schema` | 스키마 파일 경로 (glob 패턴 지원) |
+| `out` | 마이그레이션 출력 폴더 |
+| `dbCredentials` | DB 연결 정보 |
+| `driver` | 드라이버 (d1-http 등) |
+| `verbose` | 상세 로그 출력 |
+| `strict` | 엄격 모드 |
+
+## 다중 스키마 파일
+
+```typescript
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './src/db/schema/*.ts',  // glob 패턴
+  out: './drizzle/migrations',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+})
+```
+
+## 마이그레이션 명령어
+
+```bash
+npx drizzle-kit generate    # 마이그레이션 파일 생성
+npx drizzle-kit migrate     # 마이그레이션 실행
+npx drizzle-kit push        # 스키마 직접 동기화 (개발용)
+npx drizzle-kit pull        # DB에서 스키마 가져오기
+npx drizzle-kit studio      # GUI 실행
+```

package/templates/tanstack-start/docs/library/drizzle/crud.md

@@ -0,0 +1,205 @@
+# Drizzle - CRUD 작업
+
+## Create
+
+```typescript
+import { db } from '@/lib/db'
+import { users } from '@/db/schema'
+
+// 단일
+const [user] = await db.insert(users)
+  .values({ email: 'alice@example.com', name: 'Alice' })
+  .returning()
+
+// Batch insert
+await db.insert(users).values([
+  { email: 'alice@example.com', name: 'Alice' },
+  { email: 'bob@example.com', name: 'Bob' },
+])
+
+// returning 없이
+await db.insert(users).values({ email: 'alice@example.com' })
+```
+
+## Read
+
+```typescript
+import { eq, and, or, gt, like, desc, asc, count, sql } from 'drizzle-orm'
+
+// 전체
+const allUsers = await db.select().from(users)
+
+// 조건
+const [user] = await db.select().from(users).where(eq(users.id, 1))
+
+// 복합 조건
+const filtered = await db.select().from(users).where(
+  and(
+    eq(users.role, 'ADMIN'),
+    gt(users.createdAt, new Date('2024-01-01'))
+  )
+)
+
+// 특정 필드만
+const emails = await db.select({ email: users.email }).from(users)
+
+// 정렬
+const sorted = await db.select().from(users).orderBy(desc(users.createdAt))
+
+// 페이지네이션
+const paginated = await db.select().from(users)
+  .orderBy(asc(users.id))
+  .limit(10)
+  .offset(0)
+
+// 카운트
+const [{ count: total }] = await db.select({ count: count() }).from(users)
+```
+
+## Relational Query (관계 포함)
+
+```typescript
+// with 사용
+const userWithPosts = await db.query.users.findFirst({
+  where: eq(users.id, 1),
+  with: {
+    posts: true,
+  },
+})
+
+// 중첩 관계
+const userWithAll = await db.query.users.findFirst({
+  where: eq(users.id, 1),
+  with: {
+    posts: {
+      with: {
+        comments: true,
+      },
+    },
+  },
+})
+
+// 조건 + 정렬
+const result = await db.query.users.findMany({
+  where: eq(users.verified, true),
+  with: {
+    posts: {
+      where: eq(posts.published, true),
+      orderBy: desc(posts.createdAt),
+      limit: 5,
+    },
+  },
+  orderBy: asc(users.id),
+  limit: 10,
+})
+```
+
+## Update
+
+```typescript
+// 단일
+const [updated] = await db.update(users)
+  .set({ name: 'Updated Name' })
+  .where(eq(users.id, 1))
+  .returning()
+
+// 다중
+await db.update(users)
+  .set({ verified: true })
+  .where(eq(users.role, 'ADMIN'))
+
+// Upsert (PostgreSQL)
+await db.insert(users)
+  .values({ email: 'alice@example.com', name: 'Alice' })
+  .onConflictDoUpdate({
+    target: users.email,
+    set: { name: 'Alice Updated' },
+  })
+
+// Upsert - 아무것도 안 함
+await db.insert(users)
+  .values({ email: 'alice@example.com', name: 'Alice' })
+  .onConflictDoNothing({ target: users.email })
+```
+
+## Delete
+
+```typescript
+// 단일
+await db.delete(users).where(eq(users.id, 1))
+
+// 조건부
+await db.delete(users).where(eq(users.verified, false))
+
+// 전체 (주의!)
+await db.delete(users)
+```
+
+## 필터 연산자
+
+```typescript
+import {
+  eq,        // =
+  ne,        // !=
+  gt,        // >
+  gte,       // >=
+  lt,        // <
+  lte,       // <=
+  like,      // LIKE
+  ilike,     // ILIKE (대소문자 무시)
+  inArray,   // IN
+  notInArray,// NOT IN
+  isNull,    // IS NULL
+  isNotNull, // IS NOT NULL
+  between,   // BETWEEN
+  and,       // AND
+  or,        // OR
+  not,       // NOT
+} from 'drizzle-orm'
+
+// 문자열
+where(like(users.name, '%John%'))
+where(ilike(users.name, '%john%'))
+
+// 숫자
+where(gt(users.age, 18))
+where(between(users.age, 18, 65))
+
+// 배열
+where(inArray(users.id, [1, 2, 3]))
+
+// NULL
+where(isNull(users.deletedAt))
+
+// 논리
+where(and(eq(users.role, 'admin'), eq(users.verified, true)))
+where(or(eq(users.role, 'admin'), eq(users.role, 'moderator')))
+```
+
+## Join
+
+```typescript
+// Inner join
+const result = await db.select({
+  userId: users.id,
+  userName: users.name,
+  postTitle: posts.title,
+})
+.from(users)
+.innerJoin(posts, eq(users.id, posts.authorId))
+
+// Left join
+const result = await db.select()
+.from(users)
+.leftJoin(posts, eq(users.id, posts.authorId))
+
+// Aggregation
+const result = await db.select({
+  userId: users.id,
+  userName: users.name,
+  postCount: count(posts.id),
+})
+.from(users)
+.leftJoin(posts, eq(users.id, posts.authorId))
+.groupBy(users.id)
+```