@nine-lab/nine-connector 0.1.10 → 0.1.12

package/README.md

@@ -1,64 +1,66 @@
 cat <<EOF > README.md
 # @nine-lab/nine-connector 🚀
 
-자연어 기반 SQL 생성 엔진(NineQuery)과 실제 데이터베이스 사이를 연결하는 **AI 전용 DB 커넥터 서비스**입니다.
+자연어 기반 SQL 생성 엔진(NineQuery)과 데이터베이스 사이를 연결하는 **AI 전용 DB 커넥터 서비스**입니다.
 
-AI가 생성한 SQL을 안전하게 실행하고, 데이터베이스의 구조(Schema)를 AI에게 전달하기 위한 표준 API 환경을 제공합니다.
+데이터베이스의 구조(Schema)를 분석하여 AI가 최적의 쿼리를 생성할 수 있도록 브릿지 역할을 수행하며, 보안이 검증된 환경에서 데이터를 안전하게 반환합니다.
 
 ---
 
 ## 🌟 주요 기능
 
-*   **Multi-DB 지원**: MySQL, PostgreSQL, MariaDB와 즉시 연결 가능합니다.
-*   **스키마 자동 추출**: AI가 쿼리를 생성할 때 필요한 테이블 및 컬럼 정보를 API로 제공합니다.
-*   **보안 가드**: 오직 \`SELECT\` 쿼리만 실행할 수 있도록 설계되어 데이터 변조를 원천 차단합니다.
-*   **BigInt 대응**: 데이터베이스의 큰 숫자형(\`BigInt\`) 데이터를 JSON으로 안전하게 변환하여 반환합니다.
+* **자동 초기화**: \`nine-connector init\` 명령으로 \`.env\` 설정과 AI 프롬프트 템플릿을 즉시 구축합니다.
+* **Multi-DB 지원**: MySQL, PostgreSQL, MariaDB, Oracle 등 다양한 엔터프라이즈 DB 환경에 대응합니다.
+* **비즈니스 로직 최적화**: 프롬프트 파일 수정을 통해 특정 테이블 조회 금지, 필터링 조건 강제 등 고객사별 맞춤 규칙을 적용할 수 있습니다.
+* **보안 가드**: 내부적으로 오직 \`SELECT\` 쿼리만 허용하여 데이터 변조 및 유출을 원천 차단합니다.
+* **운영 안정성**: BigInt 직렬화 및 DB별 결과 포맷 정규화를 통해 데이터 일관성을 보장합니다.
 
 ---
 
-## 🛠 설치 및 실행 방법
-
-### 1. 전역(Global) 설치
-어느 경로에서나 명령어로 즉시 기동할 수 있도록 전역 설치를 권장합니다.
+## 🛠 설치 및 사용 방법
 
+### 1. 패키지 설치
 \`\`\`bash
 npm install -g @nine-lab/nine-connector
 \`\`\`
 
-### 2. 환경 변수 설정 (\`.env\`)
-서버 실행 전, 데이터베이스 접속 정보를 설정해야 합니다. 실행할 경로에 \`.env\` 파일을 생성하거나 시스템 환경 변수를 설정하세요.
-
-\`\`\`env
-# 서버 포트 (기본값: 3000)
-SERVER_PORT=3000
-
-# 데이터베이스 설정
-DB_TYPE=mysql
-DB_HOST=127.0.0.1
-DB_PORT=3306
-DB_USER=your_user
-DB_PASS=your_password
-DB_NAME=your_database
-\`\`\`
-
-### 3. 서버 기동
-설정이 완료되었다면 터미널에서 아래 명령어를 입력합니다.
-
+### 2. 프로젝트 초기화 (최초 1회)
+서버 실행 전 DB 접속 정보 및 프롬프트 환경 구성을 위해 실행합니다.
 \`\`\`bash
-nine-connector
+nine-connector init
 \`\`\`
 
+### 3. 서버 실행 및 관리 (PM2 권장)
+서버의 안정적인 기동과 로그 관리를 위해 프로세스 이름을 패키지명과 동일한 **nine-connector**로 관리하는 것을 권장합니다.
+
+* **서버 시작**:
+  \`\`\`bash
+  pm2 start nine-connector --name "nine-connector"
+  \`\`\`
+* **상태 확인**:
+  \`\`\`bash
+  pm2 status
+  \`\`\`
+* **로그 확인**:
+  \`\`\`bash
+  pm2 logs nine-connector
+  \`\`\`
+* **서버 중지/재시작**:
+  \`\`\`bash
+  pm2 stop nine-connector
+  pm2 restart nine-connector
+  \`\`\`
+
 ---
 
-## 🔌 API 명세
+## 📂 프로젝트 구조 및 커스터마이징
 
-### 1. 데이터베이스 스키마 조회
-AI 모델이 현재 DB 구조를 학습할 수 있도록 메타데이터를 반환합니다.
-*   **Endpoint:** \`GET /api/schema\`
+기본적으로 \`nine-query\` 컴포넌트와 연동되어 동작하며, 아래 파일들을 통해 세부 동작을 제어할 수 있습니다.
 
-### 2. SQL 쿼리 실행
-AI가 생성한 SQL을 실행합니다. 보안을 위해 **SELECT 문**만 허용됩니다.
-*   **Endpoint:** \`POST /api/query\`
+* **.env**: DB 접속 정보 및 AI 모델(Gemini) 설정값
+* **prompts/table-filter.md**: 질문에 적합한 테이블을 찾아내는 AI의 판단 로직
+* **prompts/query-generator.md**: 실제 SQL을 생성하는 AI의 페르소나 및 규칙
+    * **💡 Tip**: 이 파일의 \`[고객사 전용 비즈니스 로직 및 보안 규칙]\` 섹션에 "특정 민감 테이블 조회 금지"나 "기본 정렬/필터링 기준"을 명시하여 AI의 답변을 통제할 수 있습니다.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nine-lab/nine-connector",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "NineQuery AI Connector for Database",
   "main": "src/index.js",
   "type": "module",

package/prompts/query-generator.md

@@ -1,5 +1,5 @@
 ### SQL_GENERATE_PROMPT
-당신은 SQL 생성기입니다. 제공된 테이블의 컬럼 정보를 바탕으로 사용자의 질문에 답하는 최적의 SQL 쿼리를 작성하세요.
+당신은 SQL 생성기입니다. 제공된 테이블 정보를 바탕으로 사용자의 질문에 답하는 최적의 SQL 쿼리를 작성하세요.
 
 [선택된 테이블 정보]
 {detailed_schema}
@@ -10,12 +10,15 @@
 [데이터베이스 타입]
 {db_type}
 
-[응답 규칙]
+[기본 응답 규칙]
 1. 반드시 JSON 형식으로만 응답하세요.
 2. SQL은 {db_type} 문법에 완벽하게 맞아야 하며, 즉시 실행 가능해야 합니다.
-3. 쿼리문 안에 마크다운 코드 블록(```sql)을 포함하지 마세요. 오직 순수 문자열로만 작성하세요.
-4. 사용자가 이해하기 쉽도록 쿼리에 대한 설명(explanation)을 친절하게 작성하세요.
-5. 존재하지 않는 컬럼이나 테이블은 절대 사용하지 마세요.
+3. 쿼리문 안에 마크다운 코드 블록(```sql)을 포함하지 마세요.
+
+[고객사 전용 비즈니스 로직 및 보안 규칙]
+- 
+-
+(여기에 "특정 테이블 조회 금지"나 "기본 정렬 기준" 등 커스텀 규칙을 작성하세요.)
 
 [응답 포맷]
 {{