@kiyeonjeon21/datacontext 0.3.2 → 0.4.0

package/docs/KNOWLEDGE_TYPES.md

@@ -0,0 +1,261 @@
+# Knowledge Types Guide
+
+> DataContext의 지식 유형 정리 및 사용 가이드
+
+## Overview
+
+DataContext는 4가지 유형의 지식을 관리합니다:
+
+| 유형 | 목적 | 자동 적용 | AI 참조 |
+|------|------|:--------:|:-------:|
+| **Table Description** | 테이블/컬럼 설명 | ❌ | ✅ |
+| **Business Glossary** | 용어 → SQL 번역 | ❌ | ✅ |
+| **Business Rule** | 자동 적용 필터 | ✅ | ✅ |
+| **Query Example** | 검증된 SQL 패턴 | ❌ | ✅ |
+
+---
+
+## 1. Table Description (테이블 설명)
+
+**목적:** 테이블과 컬럼의 비즈니스 의미 설명
+
+**사용 시점:** AI가 스키마를 이해할 때
+
+**예시:**
+```yaml
+table: users
+description: "고객 계정 정보를 저장하는 테이블"
+columns:
+  - name: status
+    description: "계정 상태 (0=비활성, 1=활성, 2=정지)"
+  - name: created_at
+    description: "계정 생성 일시"
+```
+
+**관리 방법:**
+- `datacontext harvest` - DB 코멘트에서 자동 수집
+- `datacontext describe` - 수동 추가/수정
+
+---
+
+## 2. Business Glossary (용어 사전) ⭐
+
+**목적:** 도메인 용어를 SQL 조건으로 번역
+
+**사용 시점:** AI가 자연어 쿼리를 SQL로 변환할 때
+
+**핵심 특징:**
+- **선택적 적용** - AI가 컨텍스트에 맞게 판단
+- **번역 도우미** - "활성 사용자"라고 하면 AI가 `status = 1` 사용
+- **동의어 지원** - "active user", "활성화된 사용자" 모두 같은 의미
+
+**예시:**
+```yaml
+term: "활성 사용자"
+synonyms: ["active user", "활성화된 사용자"]
+definition: "status 컬럼이 1인 사용자"
+sqlExpression: "status = 1"
+appliesTo:
+  tables: ["users"]
+category: status
+```
+
+**사용 시나리오:**
+```
+사용자: "활성 사용자 목록 보여줘"
+AI: SELECT * FROM users WHERE status = 1;  -- Glossary 참조
+```
+
+**관리 방법:**
+- `datacontext glossary add "활성 사용자" "status가 1인 사용자" --sql "status = 1"`
+- `datacontext glossary generate "활성=status 1, VIP=주문 10건 이상"`
+
+---
+
+## 3. Business Rule (비즈니스 룰) ⚠️
+
+**목적:** 모든 쿼리에 자동으로 적용되는 필터/제약
+
+**사용 시점:** 쿼리 실행 전 시스템이 자동 적용
+
+**핵심 특징:**
+- **강제 적용** - 사용자가 명시하지 않아도 항상 추가
+- **보안/무결성** - Soft delete, Tenant isolation 등
+- **우선순위** - 여러 룰이 있으면 priority 순으로 적용
+
+**예시:**
+```yaml
+name: "soft_delete_filter"
+description: "삭제된 레코드 제외 (deleted_at IS NULL)"
+condition: "deleted_at IS NULL"
+appliesTo:
+  tables: ["users", "orders", "products"]
+isActive: true
+priority: 100
+```
+
+**사용 시나리오:**
+```
+사용자: "SELECT * FROM users"
+시스템 적용 후: "SELECT * FROM users WHERE deleted_at IS NULL"
+```
+
+**관리 방법:**
+- VS Code: `DataContext: Add Business Rule`
+- CLI: 현재 미구현 (향후 추가)
+
+---
+
+## 4. Query Example (쿼리 예시)
+
+**목적:** 검증된 SQL 패턴 저장
+
+**사용 시점:** AI가 유사한 쿼리 생성 시 참조
+
+**예시:**
+```yaml
+intent: "최근 30일 주문 총액 조회"
+sql: |
+  SELECT 
+    user_id,
+    SUM(total_amount) as total_spent
+  FROM orders
+  WHERE created_at >= CURRENT_DATE - INTERVAL '30 days'
+  GROUP BY user_id
+tables: ["orders"]
+isVerified: true
+```
+
+**관리 방법:**
+- VS Code: `DataContext: Add Query Example`
+- 피드백에서 자동 생성 (성공한 쿼리)
+
+---
+
+## Glossary vs Rule: 언제 무엇을 사용?
+
+### Glossary 사용 (용어 번역)
+
+✅ 도메인 특화 용어가 있을 때
+✅ 사용자가 자연어로 요청할 때
+✅ 같은 개념에 여러 표현이 있을 때
+
+**예시:**
+- "활성 사용자", "VIP 고객", "최근 주문"
+- 마케팅 용어, 비즈니스 지표
+
+### Rule 사용 (자동 적용 필터)
+
+✅ 항상 적용해야 하는 조건
+✅ 보안/무결성 관련
+✅ 사용자가 잊어버려도 적용되어야 함
+
+**예시:**
+- Soft delete 필터 (`deleted_at IS NULL`)
+- Tenant isolation (`tenant_id = ?`)
+- 권한 기반 필터 (`is_public = true OR owner_id = ?`)
+
+---
+
+## 스케일 대응 전략
+
+### 테이블이 많아질 때
+
+1. **태그로 그룹화**
+   ```yaml
+   table: user_preferences
+   tags: ["user", "settings"]
+   ```
+
+2. **스키마별 분리**
+   ```
+   knowledge/
+   ├── public/     # public schema
+   ├── analytics/  # analytics schema
+   └── admin/      # admin schema
+   ```
+
+### DB가 여러 개일 때
+
+1. **DB별 Knowledge 분리**
+   ```
+   .datacontext/
+   ├── users-db/
+   │   └── knowledge.json
+   ├── orders-db/
+   │   └── knowledge.json
+   └── analytics-db/
+       └── knowledge.json
+   ```
+
+2. **Cross-DB Glossary**
+   ```yaml
+   term: "고객"
+   appliesTo:
+     databases:
+       - name: users-db
+         tables: ["users"]
+       - name: orders-db
+         tables: ["customers"]
+   ```
+
+### 용어가 많아질 때
+
+1. **카테고리 활용**
+   - `status`: 상태 관련 (활성, 비활성, 정지)
+   - `time`: 시간 관련 (최근, 이번달, 지난주)
+   - `money`: 금액 관련 (매출, 비용, 이익)
+   - `entity`: 엔티티 타입 (고객, 상품, 주문)
+   - `metric`: 지표 (전환율, 이탈률)
+
+2. **검색 및 자동완성**
+   ```bash
+   datacontext glossary search "사용자"
+   # → 활성 사용자, 신규 사용자, VIP 사용자, ...
+   ```
+
+---
+
+## 권장 워크플로우
+
+### 1단계: 기본 설정 (처음 연결 시)
+
+```bash
+# DB 메타데이터 수집
+datacontext harvest
+
+# 기본 Soft Delete 룰 추가 (해당되는 경우)
+# VS Code: DataContext: Add Business Rule
+```
+
+### 2단계: 도메인 용어 추가 (점진적)
+
+```bash
+# 자주 사용하는 용어부터
+datacontext glossary add "활성 사용자" "status가 1인 사용자" --sql "status = 1"
+datacontext glossary add "최근 주문" "30일 이내 주문" --sql "created_at > now() - interval '30 days'"
+
+# 또는 AI로 일괄 생성
+datacontext glossary generate "활성=status 1, VIP=order 10건 이상, 신규=created_at 7일 이내"
+```
+
+### 3단계: 사용하면서 개선
+
+```bash
+# 쿼리 피드백 기록 (자동)
+# 자주 수정되는 패턴 → Rule 또는 Glossary 추가
+
+# 성공한 쿼리 → Query Example로 저장
+```
+
+---
+
+## 요약
+
+| 질문 | 답 |
+|------|-----|
+| "AI가 용어를 이해하게 하고 싶다" | → **Glossary** |
+| "모든 쿼리에 조건을 자동 추가하고 싶다" | → **Rule** |
+| "테이블 의미를 설명하고 싶다" | → **Table Description** |
+| "좋은 쿼리 패턴을 저장하고 싶다" | → **Query Example** |
+

package/docs/MULTI_DB_ARCHITECTURE.md

@@ -0,0 +1,319 @@
+# Multi-Database Architecture
+
+> DataContext의 다중 데이터베이스 지원 아키텍처 설계
+
+## 현재 상태
+
+현재 DataContext는 **단일 연결 기반** 으로 동작합니다:
+
+```
+┌─────────────────────────────────────────┐
+│           VS Code Extension             │
+├─────────────────────────────────────────┤
+│  ⭐ Active Connection                   │
+│     └── REST API (localhost:3000)       │
+│         └── PostgreSQL (users-db)       │
+│                                         │
+│  Connection 2                           │
+│     └── REST API (localhost:3001)       │
+│         └── MySQL (orders-db)           │
+└─────────────────────────────────────────┘
+```
+
+- 각 연결은 독립적인 REST API 서버
+- Knowledge는 DB별로 분리 저장 (`~/.datacontext/{db-id}/`)
+- 한 번에 하나의 Active Connection만 사용
+
+---
+
+## 다중 DB 지원 전략
+
+### Level 1: Multi-Connection UI (현재 완료 ✅)
+
+여러 연결을 저장하고 전환하는 기능:
+
+```
+Features:
+✅ 여러 연결 저장
+✅ Active Connection 표시 (⭐)
+✅ 클릭으로 연결 전환
+✅ 연결 삭제/정리
+```
+
+**한계:** 한 번에 하나의 DB만 조회 가능
+
+---
+
+### Level 2: Unified Knowledge Layer (다음 단계)
+
+여러 DB의 Knowledge를 통합하여 관리:
+
+```
+┌─────────────────────────────────────────┐
+│        Unified Knowledge Layer          │
+├─────────────────────────────────────────┤
+│                                         │
+│  Business Glossary                      │
+│  ├── "고객" → users-db.users            │
+│  │           orders-db.customers        │
+│  │                                      │
+│  ├── "VIP" → orders-db.customers        │
+│  │           WHERE total_orders >= 10   │
+│  │                                      │
+│  └── "매출" → orders-db.orders          │
+│               SUM(total_amount)         │
+│                                         │
+│  Cross-DB Mappings                      │
+│  └── users-db.users.id                  │
+│      = orders-db.customers.user_id      │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**구현 방법:**
+
+1. **Global Knowledge Store**
+   ```typescript
+   interface GlobalKnowledge {
+     databases: DatabaseKnowledge[];
+     crossDbMappings: CrossDbMapping[];
+     globalGlossary: BusinessTerm[];
+   }
+   
+   interface CrossDbMapping {
+     source: { db: string; table: string; column: string };
+     target: { db: string; table: string; column: string };
+     relationship: 'equals' | 'foreign_key';
+   }
+   ```
+
+2. **Term Scope 확장**
+   ```typescript
+   interface BusinessTerm {
+     term: string;
+     definition: string;
+     appliesTo: {
+       databases?: string[];  // 추가
+       tables?: string[];
+       columns?: string[];
+     };
+   }
+   ```
+
+3. **AI Context 확장**
+   ```typescript
+   // 현재: 단일 DB 컨텍스트
+   buildContext(query, tables)
+   
+   // 미래: 다중 DB 컨텍스트
+   buildCrossDbContext(query, {
+     databases: ['users-db', 'orders-db'],
+     tables: ['users', 'orders', 'customers']
+   })
+   ```
+
+---
+
+### Level 3: Federated Query (고급)
+
+여러 DB를 하나의 쿼리로 조회:
+
+```sql
+-- 사용자가 원하는 것
+SELECT u.name, SUM(o.total_amount) as revenue
+FROM users u
+JOIN orders o ON u.id = o.user_id
+GROUP BY u.name
+
+-- 실제 실행 (DB가 다를 때)
+-- Step 1: users-db에서 사용자 조회
+-- Step 2: orders-db에서 주문 조회
+-- Step 3: 결과 조인 (클라이언트)
+```
+
+**구현 복잡도:** 매우 높음
+
+**필요 기능:**
+- Query Planner (DB별 쿼리 분리)
+- Result Merger (클라이언트 조인)
+- Type Mapping (DB간 타입 호환)
+- Performance Optimization (병렬 실행)
+
+**대안:** 
+- ETL + Data Warehouse (Snowflake, BigQuery)
+- Trino/Presto (분산 쿼리 엔진)
+- dbt (데이터 변환)
+
+---
+
+## 권장 구현 순서
+
+### Phase 1: Multi-Connection 개선 (현재)
+
+```
+✅ 연결 저장/전환
+✅ Active Connection UI
+⏳ 연결 그룹화 (개발/스테이징/프로덕션)
+⏳ 연결 복사/공유
+```
+
+### Phase 2: Unified Knowledge (다음)
+
+```
+⏳ Cross-DB Term 지원
+⏳ Global Glossary
+⏳ DB 간 테이블 매핑
+⏳ 통합 검색
+```
+
+### Phase 3: Enhanced Query (미래)
+
+```
+⏳ Multi-DB 컨텍스트 인식
+⏳ 자동 DB 선택 (용어 기반)
+⏳ 기본 Cross-DB 조인 제안
+```
+
+### Phase 4: Federation (선택적)
+
+```
+⏳ 간단한 Cross-DB 쿼리
+⏳ 결과 병합
+⏳ Trino/Presto 통합 (외부)
+```
+
+---
+
+## Knowledge 저장 구조
+
+### 현재 (DB별 분리)
+
+```
+~/.datacontext/
+├── localhost_users_db/
+│   └── knowledge.json
+├── localhost_orders_db/
+│   └── knowledge.json
+└── localhost_analytics_db/
+    └── knowledge.json
+```
+
+### 제안 (계층적 구조)
+
+```
+~/.datacontext/
+├── global/
+│   ├── settings.json
+│   ├── glossary.json       # 전역 용어
+│   └── mappings.json       # DB 간 매핑
+├── workspaces/
+│   └── my-project/
+│       ├── workspace.json  # 프로젝트 설정
+│       └── connections.json # 연결 목록
+└── databases/
+    ├── users-db/
+    │   └── knowledge.json
+    ├── orders-db/
+    │   └── knowledge.json
+    └── analytics-db/
+        └── knowledge.json
+```
+
+---
+
+## Glossary 스케일 대응
+
+### 문제: 용어가 많아지면?
+
+```
+현재: 50개 용어 → 검색 O
+미래: 500개 용어 → 검색 어려움
+     5000개 용어 → 관리 불가
+```
+
+### 해결책
+
+1. **카테고리 필터링**
+   ```
+   ┌─ Business Glossary ──────────────┐
+   │ [Filter: 상태 ▼] [Search: ___]  │
+   │                                  │
+   │ 📁 상태 (12)                     │
+   │   ├── 활성 사용자                │
+   │   ├── 휴면 계정                  │
+   │   └── 정지 계정                  │
+   │                                  │
+   │ 📁 시간 (8)                      │
+   │   ├── 최근 주문                  │
+   │   └── 이번달 가입                │
+   └──────────────────────────────────┘
+   ```
+
+2. **Table 연결 기반 필터**
+   ```
+   현재 쿼리: SELECT * FROM users WHERE ...
+   
+   관련 용어만 표시:
+   ├── 활성 사용자 (users.status = 1)
+   ├── VIP 고객 (users.tier = 'vip')
+   └── 신규 가입자 (users.created_at > ...)
+   ```
+
+3. **AI 기반 용어 추천**
+   ```
+   쿼리: "이번달 매출 높은 고객"
+   
+   추천 용어:
+   ✓ 이번달 (created_at >= month_start)
+   ✓ 매출 (SUM(total_amount))
+   ✓ 고객 (users JOIN orders)
+   ```
+
+4. **버전 관리**
+   ```yaml
+   # glossary.yaml
+   version: 2
+   updated_at: 2025-01-01
+   terms:
+     - term: "활성 사용자"
+       version: 3
+       history:
+         - v1: status = 'active'
+         - v2: status = 1
+         - v3: status = 1 AND last_login > now() - interval '30 days'
+   ```
+
+---
+
+## 결론
+
+### 현재 우선순위
+
+1. **Phase 1 완료** ✅
+   - Multi-Connection UI
+   - SQLite/MySQL/PostgreSQL 테스트
+
+2. **Phase 2 준비**
+   - Global Glossary 설계
+   - Cross-DB Mapping 정의
+   - 카테고리 필터 UI
+
+3. **Phase 3+ 유보**
+   - Federated Query는 복잡도가 높음
+   - 사용자 피드백 후 결정
+
+### 핵심 원칙
+
+1. **점진적 복잡도 증가**
+   - 단순한 것부터 시작
+   - 사용자 요구에 따라 확장
+
+2. **독립성 유지**
+   - 각 DB의 Knowledge는 독립적
+   - 전역 레이어는 옵션
+
+3. **AI 활용**
+   - 용어 추천/자동완성
+   - 컨텍스트 기반 필터링
+   - Cross-DB 관계 추론
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kiyeonjeon21/datacontext",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "AI-native database context layer - Make AI understand your data better",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/create-sqlite-testdb.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# Create SQLite test database with sample data
+
+set -e
+
+DB_PATH="${1:-./test-sqlite.db}"
+
+echo "Creating SQLite test database at: $DB_PATH"
+
+# Remove existing
+rm -f "$DB_PATH"
+
+# Create database and tables
+sqlite3 "$DB_PATH" << 'EOF'
+-- Users table
+CREATE TABLE users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    email TEXT UNIQUE NOT NULL,
+    status INTEGER DEFAULT 1,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    deleted_at DATETIME
+);
+
+-- Products table
+CREATE TABLE products (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    price REAL NOT NULL,
+    inventory INTEGER DEFAULT 0,
+    category TEXT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Orders table
+CREATE TABLE orders (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER REFERENCES users(id),
+    product_id INTEGER REFERENCES products(id),
+    quantity INTEGER NOT NULL,
+    total_amount REAL NOT NULL,
+    status TEXT DEFAULT 'pending',
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Insert sample data
+INSERT INTO users (name, email, status) VALUES
+    ('Alice', 'alice@example.com', 1),
+    ('Bob', 'bob@example.com', 1),
+    ('Charlie', 'charlie@example.com', 0),
+    ('Diana', 'diana@example.com', 2);
+
+INSERT INTO products (name, price, inventory, category) VALUES
+    ('Laptop', 999.99, 50, 'electronics'),
+    ('Mouse', 29.99, 200, 'electronics'),
+    ('Keyboard', 79.99, 100, 'electronics'),
+    ('Desk Chair', 299.99, 30, 'furniture');
+
+INSERT INTO orders (user_id, product_id, quantity, total_amount, status) VALUES
+    (1, 1, 1, 999.99, 'delivered'),
+    (1, 2, 2, 59.98, 'delivered'),
+    (2, 3, 1, 79.99, 'shipped'),
+    (2, 4, 1, 299.99, 'pending');
+
+SELECT 'SQLite test database created!' as result;
+.tables
+EOF
+
+echo ""
+echo "Database created: $DB_PATH"
+echo ""
+echo "To start DataContext server:"
+echo "  npx @kiyeonjeon21/datacontext serve sqlite:$DB_PATH --port 3000"
+echo ""
+