[G1-Sync] Manual knowledge update

10_Wiki/Topics/Coding/DB_Soft_Delete_Patterns.md

@@ -0,0 +1,133 @@
+---
+id: db-soft-delete-patterns
+title: Soft Delete — deleted_at / 일관성 / 인덱스
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [database, soft-delete, vibe-coding]
+tech_stack: { language: "SQL / ORM", applicable_to: ["Backend"] }
+applied_in: []
+aliases: [soft-delete, tombstone, partial index, deleted_at]
+---
+
+# Soft Delete
+
+> 행 자체 삭제 X — `deleted_at` 컬럼에 timestamp. 복구 / audit / FK 안 깨짐. 단 모든 query 에 `WHERE deleted_at IS NULL` 안 붙이면 leak. ORM scope / view / 부분 인덱스로 강제.
+
+## 📖 핵심 개념
+- Hard delete: 행 사라짐 — FK 깨짐, 복구 불가.
+- Soft delete: 보존 — query 마다 필터.
+- Partial index: `deleted_at IS NULL` 만 인덱싱 — 빠름 + 작음.
+- Unique constraint: 유니크 컬럼은 `(email, deleted_at IS NULL)` 처럼 부분 unique.
+
+## 💻 코드 패턴
+
+### 스키마
+```sql
+CREATE TABLE users (
+  id UUID PRIMARY KEY,
+  email TEXT NOT NULL,
+  deleted_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- partial unique: 살아있는 행 사이에서만 유니크
+CREATE UNIQUE INDEX users_email_active ON users(email) WHERE deleted_at IS NULL;
+
+-- partial index: 활성 lookup 빠름
+CREATE INDEX users_active ON users(id) WHERE deleted_at IS NULL;
+```
+
+### Prisma — 자동 필터
+```ts
+// extension 으로 모든 query 에 자동 필터
+const prisma = new PrismaClient().$extends({
+  query: {
+    user: {
+      async findMany({ args, query }) {
+        args.where = { ...args.where, deletedAt: null };
+        return query(args);
+      },
+      async findUnique({ args, query }) {
+        args.where = { ...args.where, deletedAt: null };
+        return query(args);
+      },
+    },
+  },
+});
+```
+
+### Drizzle — 명시적 helper
+```ts
+const activeUsers = () => db.select().from(users).where(isNull(users.deletedAt));
+
+// 삭제
+await db.update(users).set({ deletedAt: new Date() }).where(eq(users.id, id));
+
+// 복구
+await db.update(users).set({ deletedAt: null }).where(eq(users.id, id));
+```
+
+### View 로 강제
+```sql
+CREATE VIEW v_users AS SELECT * FROM users WHERE deleted_at IS NULL;
+-- 앱은 v_users 만 사용, 직접 users 접근 금지
+```
+
+### Cascade soft delete
+```sql
+-- user 삭제 시 그의 posts 도 soft delete
+WITH deleted_user AS (
+  UPDATE users SET deleted_at = NOW() WHERE id = $1 RETURNING id
+)
+UPDATE posts SET deleted_at = NOW()
+WHERE user_id IN (SELECT id FROM deleted_user) AND deleted_at IS NULL;
+```
+
+### 진짜 영구 삭제 (GDPR)
+```sql
+-- 1년 전 soft-deleted 는 hard delete
+DELETE FROM users WHERE deleted_at < NOW() - INTERVAL '1 year';
+```
+
+### Audit log 와 함께
+```sql
+CREATE TABLE user_deletions (
+  user_id UUID,
+  deleted_at TIMESTAMPTZ,
+  deleted_by UUID,
+  reason TEXT
+);
+```
+
+## 🤔 의사결정 기준
+| 상황 | 추천 |
+|---|---|
+| 사용자 / 게시물 (복구 필요) | Soft delete |
+| 일시적 데이터 (세션, 캐시) | Hard delete |
+| GDPR 영구삭제 요청 | Hard delete (또는 anonymize) |
+| 큰 audit / compliance | Soft + audit log |
+| FK 가 자주 끊김 우려 | Soft delete (FK 유지) |
+| 매우 큰 테이블 (10M+) | Hard + 테이블 이력화 |
+
+## ❌ 안티패턴
+- **모든 query 에 필터 누락**: 삭제된 행 노출.
+- **Unique constraint 그대로**: 같은 email 재등록 막힘. partial unique.
+- **인덱스에 deleted 행 포함**: 인덱스 비대.
+- **deleted_at 만 — by 누구 / 왜 모름**: audit 필드 같이.
+- **Cascade 안 함**: 삭제된 user 의 post 가 살아있음.
+- **GDPR 무시**: 영구 삭제 정책 + 일정 시간 후 hard delete.
+- **`is_deleted` boolean**: timestamp 보다 정보 적음.
+
+## 🤖 LLM 활용 힌트
+- `deleted_at` timestamp + partial unique + partial index 3종.
+- ORM extension 또는 view 로 자동 필터.
+- GDPR = soft → 일정 시간 후 hard.
+
+## 🔗 관련 문서
+- [[DB_Audit_Log_Patterns]]
+- [[GDPR_Data_Retention]]
+- [[DB_Migrations_Zero_Downtime]]