@nine-lab/nine-connector 0.1.9 → 0.1.11

package/README.md

@@ -1,67 +1,60 @@
 cat <<EOF > README.md
 # @nine-lab/nine-connector 🚀
 
-자연어 기반 SQL 생성 엔진(NineQuery)과 실제 데이터베이스 사이를 연결하는 **AI 전용 DB 커넥터 서비스**입니다.
+자연어 기반 SQL 생성 엔진(NineQuery)과 데이터베이스 사이를 연결하는 **AI 전용 DB 커넥터 서비스**입니다.
 
-AI가 생성한 SQL을 안전하게 실행하고, 데이터베이스의 구조(Schema)를 AI에게 전달하기 위한 표준 API 환경을 제공합니다.
+사용자의 질문을 분석하여 최적의 테이블을 필터링하고, 안전한 SQL을 생성하여 즉시 실행 결과를 반환하는 통합 환경을 제공합니다.
 
 ---
 
 ## 🌟 주요 기능
 
-*   **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\` 등 JSON 변환이 까다로운 타입을 포함하여 모든 데이터를 안전하게 반환합니다.
 
 ---
 
-## 🛠 설치 및 실행 방법
-
-### 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
+### 2. 프로젝트 초기화
+접속 정보 설정 및 프롬프트 템플릿 생성을 위해 실행합니다.
+\`\`\`bash
+nine-connector init
 \`\`\`
 
-### 3. 서버 기동
-설정이 완료되었다면 터미널에서 아래 명령어를 입력합니다.
-
+### 3. 서버 실행
 \`\`\`bash
 nine-connector
 \`\`\`
 
 ---
 
-## 🔌 API 명세
+## 🔌 API 명세 (Public API)
+
+### 1. 자연어 질의 처리 (Main)
+사용자의 질문을 받아 **테이블 선정 -> SQL 생성 -> 데이터 조회**를 한 번에 수행합니다.
+* **Endpoint:** \`POST /api/ask\`
+* **Body:** \`{ "question": "올해 매출이 가장 높은 카테고리 알려줘" }\`
+* **Response:** SQL문, AI의 설명, 그리고 조회된 결과 데이터를 포함합니다.
 
-### 1. 데이터베이스 스키마 조회
-AI 모델이 현재 DB 구조를 학습할 수 있도록 메타데이터를 반환합니다.
-*   **Endpoint:** \`GET /api/schema\`
+---
 
-### 2. SQL 쿼리 실행
-AI가 생성한 SQL을 실행합니다. 보안을 위해 **SELECT 문**만 허용됩니다.
-*   **Endpoint:** \`POST /api/query\`
+## 📂 프로젝트 구조 및 커스터마이징
+* **.env**: DB 접속 및 AI 모델 설정값
+* **prompts/table-filter.md**: 질문에 필요한 테이블을 고르는 AI 로직
+* **prompts/query-generator.md**: 실제 SQL을 생성하는 AI 페르소나
+    * **Tip**: 파일 내 \`[고객사 전용 비즈니스 로직 및 보안 규칙]\` 섹션에 "특정 테이블 조회 금지"나 "기본 정렬 기준" 등을 작성하여 AI의 동작을 제어할 수 있습니다.
 
 ---
 
 ## 📄 라이선스
 MIT © **nine-lab**
-EOF
+EOF

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nine-lab/nine-connector",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "NineQuery AI Connector for Database",
   "main": "src/index.js",
   "type": "module",
@@ -22,6 +22,7 @@
     "express": "^4.22.1",
     "mariadb": "^3.5.2",
     "mysql2": "^3.9.7",
+    "oracledb": "^6.10.0",
     "pg": "^8.11.5"
   },
   "publishConfig": {

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)을 포함하지 마세요.
+
+[고객사 전용 비즈니스 로직 및 보안 규칙]
+- 
+-
+(여기에 "특정 테이블 조회 금지"나 "기본 정렬 기준" 등 커스텀 규칙을 작성하세요.)
 
 [응답 포맷]
 {{

package/src/ai/AIProcessor.js

@@ -24,6 +24,7 @@ export class AIProcessor {
 
     async filterTables(question, schemaSummary) {
         if (!this.#chains['table-filter']) throw new Error("table-filter 체인 미등록");
+
         return await this.#chains['table-filter'].invoke({
             question,
             schema_summary: JSON.stringify(schemaSummary, null, 2)

package/src/ai/AIService.js

@@ -13,14 +13,19 @@ export class AIService {
 
         // 2) AI: 필요한 테이블 필터링
         // AI 결과가 문자열일 경우를 대비해 파싱 로직이 AIProcessor에 없다면 여기서 보완 가능
-        const { tables } = await this.ai.filterTables(question, schemaSummary);
+        //const { selected_tables } = await this.ai.filterTables(question, schemaSummary);
+        const { selected_tables } = await this.ai.filterTables(question, schemaSummary);
 
-        if (!tables || tables.length === 0) {
+        console.log(selected_tables);
+
+        if (!selected_tables || selected_tables.length === 0) {
             throw new Error("질문과 관련된 테이블을 찾을 수 없습니다.");
         }
 
+        console.log(schemaSummary);
+
         // 3) 상세 스키마 필터링 및 SQL 생성
-        const detailedSchema = schemaSummary.filter(t => tables.includes(t.tableName));
+        const detailedSchema = schemaSummary.filter(t => selected_tables.includes(t.tableName));
         const { sql, explanation } = await this.ai.generateSql(
             question,
             detailedSchema,

package/src/core/init.js

@@ -18,7 +18,7 @@ async function createEnvFile(rl) {
         { key: 'SERVER_PORT', label: '1. 커넥터 서버 포트', default: '3000' },
         { key: 'GEMINI_API_KEY', label: '2. Gemini API Key', default: '' },
         { key: 'GEMINI_MODEL', label: '3. 사용할 모델', default: 'gemini-2.5-flash' },
-        { key: 'DB_TYPE', label: '4. DB 종류 (mysql, pg, mariadb)', default: 'mysql' },
+        { key: 'DB_TYPE', label: '4. DB 종류 (mysql, mariadb, postgres, oracle)', default: 'mysql' },
         { key: 'DB_HOST', label: '5. DB 호스트', default: '127.0.0.1' },
         { key: 'DB_PORT', label: '6. DB 포트', default: '3306' },
         { key: 'DB_USER', label: '7. DB 사용자 계정', default: 'root' },

package/src/database/core/DatabaseManager.js

@@ -16,13 +16,14 @@ class DatabaseManager {
     /**
      * DatabaseFactory의 init() 역할을 수행합니다.
      */
+    // DatabaseManager.js 내부
     async connect() {
         try {
-            // Pool 생성은 전적으로 PoolManager에게 맡깁니다.
-            this.pool = PoolManager.createPool(this.config);
+            // 이제 createPool이 async이므로 await를 붙입니다.
+            this.pool = await PoolManager.createPool(this.config);
 
-            // 단순 연결 확인 쿼리
-            await this.query('SELECT 1');
+            // 연결 확인
+            await this.query(this.dialect.testQuery || 'SELECT 1');
             console.log(`[${this.type}] Database connection successful.`);
         } catch (error) {
             console.error(`[${this.type}] Connection failed:`, error.message);
@@ -39,6 +40,7 @@ class DatabaseManager {
 
         const result = await this.pool.query(sql, params);
 
+        /**
         if (this.type === 'postgres') {
             return result.rows;
         } else {
@@ -47,7 +49,20 @@ class DatabaseManager {
             return (Array.isArray(result) && Array.isArray(result[0]))
                 ? result[0]
                 : result;
+        } */
+        if (this.type === 'postgres' || this.type === 'postgresql') {
+            return result.rows;
+        }
+
+        // MariaDB/MySQL 대응:
+        // DDL(INSERT/UPDATE) 결과와 DQL(SELECT) 결과를 구분해야 함
+        if (Array.isArray(result)) {
+            // mysql2 대응: rows가 0번에 담겨오는 경우
+            if (Array.isArray(result[0])) return result[0];
+            return result;
         }
+
+        return result;
     }
 
     /**
@@ -63,18 +78,18 @@ class DatabaseManager {
     async getTableSchema() {
         const rows = await this.query(this.dialect.schemaQuery);
 
-        return rows.reduce((acc, row) => {
+        // 1. 우선 객체 형태로 그룹화 (중복 방지 및 효율적 정리를 위해)
+        const grouped = rows.reduce((acc, row) => {
             const { table_name, table_comment, column_name, data_type } = row;
 
-            // 테이블이 처음 등장하면 초기화
             if (!acc[table_name]) {
                 acc[table_name] = {
-                    description: table_comment || "", // 테이블 설명 추가
+                    tableName: table_name, // 배열로 변환 시 식별을 위해 추가
+                    description: table_comment || "",
                     columns: []
                 };
             }
 
-            // 컬럼 정보 push
             acc[table_name].columns.push({
                 column: column_name,
                 type: data_type
@@ -82,6 +97,9 @@ class DatabaseManager {
 
             return acc;
         }, {});
+
+        // 2. 최종적으로 객체의 값들만 뽑아서 배열로 변환
+        return Object.values(grouped);
     }
 }
 

package/src/database/core/Dialects.js

@@ -1,6 +1,7 @@
 const Dialects = {
     // MySQL 추가 (MariaDB와 동일)
     mysql: {
+        testQuery: 'SELECT 1',
         schemaQuery: `
             SELECT
                 c.TABLE_NAME as table_name,
@@ -15,6 +16,7 @@ const Dialects = {
             ORDER BY c.TABLE_NAME, c.ORDINAL_POSITION`
     },
     mariadb: {
+        testQuery: 'SELECT 1',
         schemaQuery: `
             SELECT
                 c.TABLE_NAME as table_name,
@@ -29,19 +31,24 @@ const Dialects = {
             ORDER BY c.TABLE_NAME, c.ORDINAL_POSITION`
     },
     postgres: {
+        testQuery: 'SELECT 1',
         schemaQuery: `
             SELECT
                 t.table_name,
-                obj_description(pgc.oid, 'pg_class') AS table_comment,
+                (SELECT obj_description(pgc.oid, 'pg_class')
+                 FROM pg_class pgc
+                 WHERE pgc.relname = t.table_name
+                   AND pgc.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = t.table_schema)
+                ) AS table_comment,
                 c.column_name,
                 c.data_type
             FROM information_schema.tables t
-                     JOIN information_schema.columns c ON t.table_name = c.table_name
-                     JOIN pg_class pgc ON t.table_name = pgc.relname
-            WHERE t.table_schema = 'public'
+                     JOIN information_schema.columns c ON t.table_name = c.table_name AND t.table_schema = c.table_schema
+            WHERE t.table_schema = CURRENT_SCHEMA() -- 현재 스키마 자동 대응
             ORDER BY t.table_name, c.ordinal_position`
     },
     oracle: {
+        testQuery: 'SELECT 1 FROM DUAL',
         schemaQuery: `
             SELECT 
                 t.TABLE_NAME as table_name, 

package/src/database/core/PoolManager.js

@@ -1,5 +1,6 @@
 import * as mariadb from 'mariadb';
 import pg from 'pg';
+//import oracledb from 'oracledb';
 
 class PoolManager {
     /**
@@ -15,11 +16,49 @@ class PoolManager {
             case 'postgres':
             case 'postgresql':
                 return this.#createPostgresPool(config);
+            case 'oracle':
+                return this.#createOraclePool(config); // 추가
             default:
                 throw new Error(`[PoolManager] Unsupported DB_TYPE: ${type}`);
         }
     }
 
+    static async #createOraclePool(config) {
+        try {
+            const { default: oracledb } = await import('oracledb');
+
+            oracledb.outFormat = oracledb.OUT_FORMAT_OBJECT;
+            oracledb.autoCommit = true;
+
+            const pool = await oracledb.createPool({
+                user: config.user,
+                password: config.password,
+                connectString: `${config.host}:${config.port}/${config.database}`,
+                poolMax: 10,
+                poolMin: 2,
+                poolIncrement: 1
+            });
+
+            // 다른 DB들과 사용법을 맞추기 위해 래핑(Wrapping)
+            return {
+                query: async (sql, params = []) => {
+                    let conn;
+                    try {
+                        conn = await pool.getConnection();
+                        const result = await conn.execute(sql, params);
+                        return result.rows; // 객체 배열 반환
+                    } finally {
+                        if (conn) await conn.close();
+                    }
+                },
+                close: () => pool.close()
+            };
+        } catch (err) {
+            console.error("Oracle Pool 생성 실패:", err.message);
+            throw err;
+        }
+    }
+
     static #createMariaDBPool(config) {
         return mariadb.createPool({
             host: config.host,

package/src/index.js

@@ -69,6 +69,9 @@ async function bootstrap() {
 
     // [API] 자연어 질의 엔드포인트
     app.post('/api/ask', async (req, res) => {
+
+
+
         const { question } = req.body;
         if (!question) return res.status(400).json({ success: false, error: "질문을 입력해주세요." });