@kood/claude-code 0.2.0 → 0.2.2

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

@@ -0,0 +1,79 @@
+# Drizzle ORM
+
+> **Version**: 0.38.x | Node.js/TypeScript ORM
+
+@setup.md
+@config.md
+@schema.md
+@crud.md
+@relations.md
+@transactions.md
+@cloudflare-d1.md
+
+---
+
+## Quick Reference
+
+```typescript
+import { db } from '@/lib/db'
+import { users } from '@/db/schema'
+import { eq } from 'drizzle-orm'
+
+// CRUD
+const allUsers = await db.select().from(users)
+const [user] = await db.insert(users).values({ email, name }).returning()
+const [updated] = await db.update(users).set({ name }).where(eq(users.id, id)).returning()
+await db.delete(users).where(eq(users.id, id))
+
+// 관계 포함 (Relational Query)
+const userWithPosts = await db.query.users.findFirst({
+  where: eq(users.id, id),
+  with: { posts: true },
+})
+```
+
+### drizzle.config.ts
+
+```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!,
+  },
+})
+```
+
+### Claude Code 금지
+
+| 금지 사항 |
+|----------|
+| drizzle-kit push 자동 실행 |
+| drizzle-kit migrate 자동 실행 |
+| drizzle-kit generate 자동 실행 |
+| 스키마 임의 변경 |
+
+---
+
+## Drizzle Client 설정
+
+```typescript
+// lib/db.ts
+import { drizzle } from 'drizzle-orm/node-postgres'
+import * as schema from '@/db/schema'
+
+export const db = drizzle(process.env.DATABASE_URL!, { schema })
+```
+
+## CLI 명령어
+
+```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/relations.md

@@ -0,0 +1,202 @@
+# Drizzle - 관계 정의
+
+## 관계 유형
+
+### 1:N (One-to-Many)
+
+```typescript
+import { pgTable, serial, text, integer } from 'drizzle-orm/pg-core'
+import { relations } from 'drizzle-orm'
+
+// 사용자
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  name: text('name').notNull(),
+})
+
+// 사용자 관계
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+}))
+
+// 게시글
+export const posts = pgTable('posts', {
+  id: serial('id').primaryKey(),
+  title: text('title').notNull(),
+  authorId: integer('author_id').references(() => users.id),
+})
+
+// 게시글 관계
+export const postsRelations = relations(posts, ({ one }) => ({
+  author: one(users, {
+    fields: [posts.authorId],
+    references: [users.id],
+  }),
+}))
+```
+
+### 1:1 (One-to-One)
+
+```typescript
+// 사용자
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  name: text('name').notNull(),
+})
+
+export const usersRelations = relations(users, ({ one }) => ({
+  profile: one(profiles),
+}))
+
+// 프로필
+export const profiles = pgTable('profiles', {
+  id: serial('id').primaryKey(),
+  bio: text('bio'),
+  userId: integer('user_id').unique().references(() => users.id),
+})
+
+export const profilesRelations = relations(profiles, ({ one }) => ({
+  user: one(users, {
+    fields: [profiles.userId],
+    references: [users.id],
+  }),
+}))
+```
+
+### M:N (Many-to-Many)
+
+```typescript
+// 사용자
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  name: text('name').notNull(),
+})
+
+export const usersRelations = relations(users, ({ many }) => ({
+  usersToGroups: many(usersToGroups),
+}))
+
+// 그룹
+export const groups = pgTable('groups', {
+  id: serial('id').primaryKey(),
+  name: text('name').notNull(),
+})
+
+export const groupsRelations = relations(groups, ({ many }) => ({
+  usersToGroups: many(usersToGroups),
+}))
+
+// 조인 테이블
+export const usersToGroups = pgTable('users_to_groups', {
+  userId: integer('user_id').notNull().references(() => users.id),
+  groupId: integer('group_id').notNull().references(() => groups.id),
+}, (table) => [
+  primaryKey({ columns: [table.userId, table.groupId] }),
+])
+
+export const usersToGroupsRelations = relations(usersToGroups, ({ one }) => ({
+  user: one(users, {
+    fields: [usersToGroups.userId],
+    references: [users.id],
+  }),
+  group: one(groups, {
+    fields: [usersToGroups.groupId],
+    references: [groups.id],
+  }),
+}))
+```
+
+## 관계 포함 조회
+
+```typescript
+// 1:N 관계 포함
+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.findFirst({
+  with: {
+    posts: {
+      where: eq(posts.published, true),
+      orderBy: desc(posts.createdAt),
+      limit: 5,
+    },
+  },
+})
+
+// M:N 관계
+const userWithGroups = await db.query.users.findFirst({
+  where: eq(users.id, 1),
+  with: {
+    usersToGroups: {
+      with: {
+        group: true,
+      },
+    },
+  },
+})
+```
+
+## SQL 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))
+.where(eq(users.id, 1))
+
+// Left join + count
+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)
+```
+
+## 자기 참조 관계
+
+```typescript
+import { type AnyPgColumn, pgTable, serial, text, integer } from 'drizzle-orm/pg-core'
+
+// 사용자 (초대 관계)
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  name: text('name').notNull(),
+  invitedBy: integer('invited_by').references((): AnyPgColumn => users.id),
+})
+
+export const usersRelations = relations(users, ({ one, many }) => ({
+  inviter: one(users, {
+    fields: [users.invitedBy],
+    references: [users.id],
+    relationName: 'inviter',
+  }),
+  invitees: many(users, {
+    relationName: 'inviter',
+  }),
+}))
+```

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

@@ -0,0 +1,154 @@
+# Drizzle - 스키마 정의
+
+## 필수 규칙
+
+1. **파일별 분리** 구조 사용
+2. **모든 요소에 한글 주석** (파일, 테이블, 컬럼)
+
+## 구조
+
+```
+src/db/schema/
+├── index.ts     # export all
+├── user.ts      # User 테이블
+├── post.ts      # Post 테이블
+└── enums.ts     # Enum 정의
+```
+
+## 예시
+
+### index.ts
+
+```typescript
+// 모든 스키마 export
+export * from './user'
+export * from './post'
+export * from './enums'
+```
+
+### enums.ts
+
+```typescript
+import { pgEnum } from 'drizzle-orm/pg-core'
+
+// 사용자 역할
+export const roleEnum = pgEnum('role', ['USER', 'ADMIN'])
+```
+
+### user.ts
+
+```typescript
+import { pgTable, serial, text, boolean, timestamp } from 'drizzle-orm/pg-core'
+import { relations } from 'drizzle-orm'
+import { roleEnum } from './enums'
+import { posts } from './post'
+
+// 사용자 테이블
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  email: text('email').notNull().unique(),  // 로그인 이메일
+  name: text('name'),                        // 표시 이름
+  role: roleEnum('role').default('USER'),    // 사용자 역할
+  verified: boolean('verified').notNull().default(false),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow(),
+})
+
+// 사용자 관계
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),  // 작성 게시글 (1:N)
+}))
+
+// 타입 추론
+export type User = typeof users.$inferSelect
+export type NewUser = typeof users.$inferInsert
+```
+
+### post.ts
+
+```typescript
+import { pgTable, serial, text, integer, boolean, timestamp } from 'drizzle-orm/pg-core'
+import { relations } from 'drizzle-orm'
+import { users } from './user'
+
+// 게시글 테이블
+export const posts = pgTable('posts', {
+  id: serial('id').primaryKey(),
+  title: text('title').notNull(),           // 제목
+  content: text('content'),                  // 본문
+  published: boolean('published').notNull().default(false),
+  authorId: integer('author_id').references(() => users.id),  // 작성자
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow(),
+})
+
+// 게시글 관계
+export const postsRelations = relations(posts, ({ one }) => ({
+  author: one(users, {
+    fields: [posts.authorId],
+    references: [users.id],
+  }),
+}))
+
+export type Post = typeof posts.$inferSelect
+export type NewPost = typeof posts.$inferInsert
+```
+
+## 컬럼 타입 (PostgreSQL)
+
+```typescript
+import {
+  serial,        // auto-increment
+  integer,       // 정수
+  bigint,        // 큰 정수
+  text,          // 문자열
+  varchar,       // 길이 제한 문자열
+  boolean,       // 불린
+  timestamp,     // 날짜/시간
+  date,          // 날짜
+  numeric,       // 소수점
+  json,          // JSON
+  jsonb,         // JSONB
+  uuid,          // UUID
+} from 'drizzle-orm/pg-core'
+```
+
+## 인덱스
+
+```typescript
+import { pgTable, serial, text, index, uniqueIndex } from 'drizzle-orm/pg-core'
+
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  name: text('name'),
+  email: text('email').notNull(),
+}, (table) => [
+  index('name_idx').on(table.name),
+  uniqueIndex('email_idx').on(table.email),
+])
+```
+
+## 복합 키
+
+```typescript
+import { pgTable, integer, primaryKey } from 'drizzle-orm/pg-core'
+
+export const usersToGroups = pgTable('users_to_groups', {
+  userId: integer('user_id').notNull(),
+  groupId: integer('group_id').notNull(),
+}, (table) => [
+  primaryKey({ columns: [table.userId, table.groupId] }),
+])
+```
+
+## 테이블 매핑
+
+```typescript
+// snake_case 컬럼명 사용
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  firstName: text('first_name'),  // DB: first_name, JS: firstName
+  lastName: text('last_name'),
+  createdAt: timestamp('created_at').defaultNow(),
+})
+```

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

@@ -0,0 +1,95 @@
+# Drizzle - 설치 및 설정
+
+## 설치
+
+### PostgreSQL
+
+```bash
+npm install drizzle-orm pg
+npm install -D drizzle-kit @types/pg
+```
+
+### MySQL
+
+```bash
+npm install drizzle-orm mysql2
+npm install -D drizzle-kit
+```
+
+### SQLite
+
+```bash
+npm install drizzle-orm better-sqlite3
+npm install -D drizzle-kit @types/better-sqlite3
+```
+
+---
+
+## 폴더 구조
+
+```
+프로젝트/
+├── drizzle.config.ts
+├── drizzle/
+│   └── migrations/
+├── src/
+│   ├── db/
+│   │   └── schema/
+│   │       ├── index.ts    # export all
+│   │       ├── user.ts
+│   │       └── post.ts
+│   └── lib/
+│       └── db.ts           # Drizzle client
+```
+
+---
+
+## Drizzle Client
+
+```typescript
+// src/lib/db.ts
+import { drizzle } from 'drizzle-orm/node-postgres'
+import * as schema from '@/db/schema'
+
+export const db = drizzle(process.env.DATABASE_URL!, { schema })
+```
+
+---
+
+## TanStack Start 연동
+
+```typescript
+// app/services/user.ts
+import { createServerFn } from '@tanstack/react-start'
+import { db } from '@/lib/db'
+import { users } from '@/db/schema'
+import { eq } from 'drizzle-orm'
+
+export const getUsers = createServerFn({ method: 'GET' })
+  .handler(async () => {
+    return db.select().from(users)
+  })
+
+export const getUserById = createServerFn({ method: 'GET' })
+  .validator((id: number) => id)
+  .handler(async ({ data: id }) => {
+    const [user] = await db.select().from(users).where(eq(users.id, id))
+    return user
+  })
+
+export const createUser = createServerFn({ method: 'POST' })
+  .validator((data: { email: string; name: string }) => data)
+  .handler(async ({ data }) => {
+    const [user] = await db.insert(users).values(data).returning()
+    return user
+  })
+```
+
+---
+
+## 환경 변수
+
+```bash
+# .env
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
+```

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

@@ -0,0 +1,127 @@
+# Drizzle - 트랜잭션
+
+## 기본 트랜잭션
+
+하나라도 실패하면 모두 롤백.
+
+```typescript
+import { db } from '@/lib/db'
+import { users, accounts } from '@/db/schema'
+import { eq, sql } from 'drizzle-orm'
+
+await db.transaction(async (tx) => {
+  await tx.update(accounts)
+    .set({ balance: sql`${accounts.balance} - 100` })
+    .where(eq(accounts.userId, senderId))
+
+  await tx.update(accounts)
+    .set({ balance: sql`${accounts.balance} + 100` })
+    .where(eq(accounts.userId, recipientId))
+})
+```
+
+## 반환값 사용
+
+```typescript
+const newBalance = await db.transaction(async (tx) => {
+  await tx.update(accounts)
+    .set({ balance: sql`${accounts.balance} - 100` })
+    .where(eq(accounts.userId, senderId))
+
+  await tx.update(accounts)
+    .set({ balance: sql`${accounts.balance} + 100` })
+    .where(eq(accounts.userId, recipientId))
+
+  const [account] = await tx.select({ balance: accounts.balance })
+    .from(accounts)
+    .where(eq(accounts.userId, senderId))
+
+  return account.balance
+})
+```
+
+## 조건부 롤백
+
+```typescript
+await db.transaction(async (tx) => {
+  const [account] = await tx.select({ balance: accounts.balance })
+    .from(accounts)
+    .where(eq(accounts.userId, senderId))
+
+  if (account.balance < 100) {
+    tx.rollback()  // 예외 발생, 트랜잭션 롤백
+  }
+
+  await tx.update(accounts)
+    .set({ balance: sql`${accounts.balance} - 100` })
+    .where(eq(accounts.userId, senderId))
+
+  await tx.update(accounts)
+    .set({ balance: sql`${accounts.balance} + 100` })
+    .where(eq(accounts.userId, recipientId))
+})
+```
+
+## 에러 처리
+
+```typescript
+try {
+  await db.transaction(async (tx) => {
+    const [user] = await tx.insert(users)
+      .values({ email: 'user@example.com' })
+      .returning()
+
+    if (someCondition) {
+      throw new Error('Rollback')
+    }
+
+    await tx.insert(posts)
+      .values({ title: 'Post', authorId: user.id })
+  })
+} catch (error) {
+  // 전체 롤백됨
+  console.error('Transaction failed:', error)
+}
+```
+
+## 중첩 트랜잭션 (PostgreSQL)
+
+```typescript
+await db.transaction(async (tx) => {
+  await tx.insert(users).values({ email: 'user1@example.com' })
+
+  await tx.transaction(async (tx2) => {
+    await tx2.insert(users).values({ email: 'user2@example.com' })
+    // 여기서 에러 발생해도 외부 트랜잭션은 영향 없음 (savepoint)
+  })
+})
+```
+
+## 복잡한 예시
+
+```typescript
+import { db } from '@/lib/db'
+import { users, posts, comments } from '@/db/schema'
+import { eq } from 'drizzle-orm'
+
+const createUserWithPost = async (userData: NewUser, postData: NewPost) => {
+  return db.transaction(async (tx) => {
+    // 사용자 생성
+    const [user] = await tx.insert(users).values(userData).returning()
+
+    // 게시글 생성
+    const [post] = await tx.insert(posts)
+      .values({ ...postData, authorId: user.id })
+      .returning()
+
+    // 사용자 + 게시글 반환
+    return { user, post }
+  })
+}
+
+// 사용
+const result = await createUserWithPost(
+  { email: 'user@example.com', name: 'John' },
+  { title: 'First Post', content: 'Hello World' }
+)
+```