SQL2Excel - SQL 쿼리 결과로 엑셀 파일 생성

SQL 쿼리 결과를 엑셀 파일로 생성하는 Node.js 기반 도구입니다.

v2.1.5 하이라이트

동적 변수 DB 라우팅
- XML의 dynamicVar에서 db(= database 별칭) 속성 지원.
- 각 동적 변수는 지정한 DB 어댑터에서 실행되며, 미지정 시 기본 DB 사용.
XML 검증 업데이트
- XML 스키마 검증에서 queryDef의 db 속성을 허용. 주의: 현재 실행 DB는 시트의 db 또는 전역 기본 DB가 사용되며, queryDef.db는 향후 문서/확장용.

v2.1.4 하이라이트

어댑터별 DB 연결 테스트 쿼리 도입
- 모든 DB 어댑터에 getTestQuery() 추가
  - MSSQL/MySQL/MariaDB: SELECT 1 as test, PostgreSQL/SQLite: SELECT 1, Oracle: SELECT 1 FROM dual
- excel-cli.js가 어댑터의 테스트 쿼리를 사용하여 연결 검증 수행 (Oracle 검증 이슈 해결)
샘플 스키마 정합성(Orders)
- PostgreSQL/MySQL: SubTotal, PaymentMethod, PaymentStatus, EmployeeID 추가
- 샘플 데이터와 컬럼 일치, MSSQL 스키마와의 정합성 향상

v2.1.3-beta (v1.3.3) 하이라이트

문서 동기화(KR/EN) 및 소규모 정리
패키지 버전을 1.3.3으로 업데이트

주요 기능

🗄️ 다중 데이터베이스 지원: ORACLE, PostgreSQL, MSSQL, MySQL, MariaDB를 통합 인터페이스로 지원
📊 다중 시트 지원: 하나의 엑셀 파일 내에서 여러 SQL 쿼리 결과를 별도의 시트에 저장
🎨 템플릿 스타일 시스템: 일관된 디자인을 위한 사전 정의된 엑셀 스타일링 템플릿 (7가지 내장 스타일)
🔗 다중 DB 연결: 각 시트마다 다른 데이터베이스 연결 사용 가능
📝 변수 시스템: 동적 쿼리 생성을 위한 변수 사용
🔄 향상된 동적 변수: 실시간으로 데이터베이스에서 값을 추출하여 고급 처리
🔄 쿼리 재사용: 공통 쿼리를 정의하고 여러 시트에서 재사용
⚙️ 파라미터 오버라이드: 각 시트에 대해 쿼리 정의 파라미터를 다른 값으로 재정의
📋 자동 목차 생성: 하이퍼링크가 있는 목차 시트 자동 생성
📊 집계 기능: 지정된 컬럼 값별 개수 자동 집계 및 표시
🚦 쿼리 제한: 대용량 데이터 처리를 위한 행 개수 제한
🖥️ CLI 인터페이스: 간단한 명령줄 도구 실행
🪟 Windows 배치 파일: Windows 사용자를 위한 대화형 배치 파일
📄 XML/JSON 지원: 유연한 구성 파일 형식 지원
🎯 시트별 스타일링: 개별 시트에 다른 스타일 적용
📦 독립 실행 파일: Node.js 의존성 없이 배포할 수 있는 독립 실행 파일(.exe) 생성
🌐 다국어 지원: 한국어 및 영어 릴리스 패키지
🔧 릴리스 자동화: 적절한 문서와 함께 자동 릴리스 패키지 생성
🕒 생성 타임스탬프: 각 엑셀 시트에 생성 타임스탬프 표시
⏰ 커스텀 DateTime 변수: 전세계 22개 타임존 지원 및 커스텀 포맷 (${DATE.UTC:YYYY-MM-DD}, ${DATE.KST:YYYY년 MM월 DD일}, ${DATE.EST:YYYY-MM-DD HH:mm} 등) 또는 로컬 시간 사용 (${DATE:YYYY-MM-DD})
📋 SQL 쿼리 포맷팅: 목차에서 줄바꿈을 포함한 원본 SQL 포맷 유지
🔧 입력 유효성 검증: 파일 경로 입력에 대한 자동 공백 제거
🗂️ 파일명 변수: excel.output에서 ${DATE:...}, ${DATE.TZ:...}, ${DB_NAME} 사용 가능 (커스텀 $(DB_NAME}도 지원)

🔗 다중 데이터베이스 사용

지원 드라이버: MSSQL(mssql), MySQL(mysql2), MariaDB(mysql2), PostgreSQL(pg), SQLite(better-sqlite3), Oracle(oracledb)
설정 파일: config/dbinfo.json에 DB 키별 접속 정보와 type 지정 (MSSQL은 생략 시 기본값)
런타임 DB 선택 우선순위
- 기본 DB 키: --db(CLI) > excel.db(XML/JSON)
- 시트: sheet.db > 기본 DB
- 동적 변수: dynamicVar.database 또는 dynamicVar.db > 기본 DB
연결 테스트
- 개발: npm run list-dbs
- EXE: sql2excel.exe list-dbs

v2.1.2(v1.3.2) 하이라이트

시트별 내보내기 디렉토리 명명 단순화
- 디렉토리는 이제 <출력파일베이스> (확장자 접미사 제거)
- 예: output="d:/temp/report.csv" → 디렉토리 d:/temp/report/
CSV/TXT 필드 포맷팅 변경
- CSV 인용/이스케이프는 .csv일 때만 적용
- 비-CSV(예: .txt, .sql)는 인용 없이 그대로 기록
- 필드 내부 줄바꿈(\r/\n)은 CSV/TXT 모두 공백으로 정규화
- 레코드 구분 개행은 CRLF 유지, 헤더 포함
- 날짜 값은 CSV/TXT 및 SQL 리터럴에서 yyyy-MM-dd HH:mm:ss(24시간) 형식으로 직렬화

v2.1.1-beta (v1.3.1) 하이라이트

출력 경로에서 파일명 변수 지원 강화
- ${DB_NAME} 지원 (현재 기본 DB 키). 커스텀 문법 $(DB_NAME}는 자동으로 ${DB_NAME}로 정규화
- ${DATE:...}(로컬 시간), ${DATE.TZ:...}(타임존 명시) 파일명에서 사용 가능
- 소문자 날짜 토큰 지원: yyyy, yy, dd, d, hh, h, sss
- 자동 _yyyymmddhhmmss 접미사 제거 → DATE 변수로 직접 제어

v2.1.0-beta (v1.3.0) 하이라이트

확장자 기반 시트별 내보내기 라우팅
- .xlsx / .xls → 단일 엑셀 통합문서 생성 (기존 동작)
- .csv → 시트별 CSV 파일 생성
- 그 외 모든 확장자(예: .txt, .log, .data, .sql 등) → 시트별 TXT 파일 생성 (탭 구분)
시트별 내보내기 디렉토리/파일명 규칙
- 출력 디렉토리( v1.3.2에서 업데이트): <출력파일베이스>
  - 예: output="d:/temp/report.csv" → d:/temp/report/
- 각 시트는 originalName(원본 시트명)으로 파일 생성
- CSV/TXT는 31자 제한 없음(엑셀 전용 제한). 파일명은 안전화 및 최대 100자 제한
포맷 기본값
- CSV: 콤마, UTF-8 BOM, 헤더, CRLF; 인용은 .csv에서만; 내부 줄바꿈 정규화
- TXT: 탭, UTF-8 BOM, 헤더, CRLF; 인용 없음; 내부 줄바꿈 정규화
- 날짜: yyyy-MM-dd HH:mm:ss (24시간)

이전 버전(v1.2.11)

시트명 31자 초과 경고 처리 및 엑셀에서 잘릴 수 있음 안내
TOC: "Original Name" 컬럼 추가, Note(툴팁) 제거

이전 버전(v1.2.10)

비대화식 CLI: 메뉴 없이 app.js --mode로 직접 실행
- 모드: validate, test, export, help
- Node 실행 및 배포 EXE 모두 지원

비대화형 CLI (신규)

Node.js

# 쿼리정의 검증
node app.js --mode=validate --xml=./queries/sample-queries.xml
# 또는 JSON
node app.js --mode=validate --query=./queries/sample-queries.json

# DB 연결 테스트
node app.js --mode=test

# 엑셀 생성
node app.js --mode=export --xml=./queries/sample-queries.xml
# 또는 JSON
node app.js --mode=export --query=./queries/sample-queries.json

# 도움말
node app.js --mode=help

참고:

dynamicVar에서 지원하는 속성: name, description, type, db, database (db는 별칭). 둘 다 있으면 database가 우선합니다.
queryDef는 검증 목적상 db를 허용합니다. 실제 실행 DB는 시트의 db 혹은 전역 기본 DB가 사용됩니다.

독립 실행 파일(EXE)

sql2excel.exe --mode=validate --xml=./queries/sample-queries.xml
sql2excel.exe --mode=test
sql2excel.exe --mode=export --xml=./queries/sample-queries.xml
sql2excel.exe --mode=help

🚀 빠른 시작

🛠️ 설치 및 설정

1. 시스템 요구사항

개발/소스 코드 사용 시

Node.js 16.0 이상
데이터베이스 서버 (MSSQL 2012+, MySQL 5.7+, 또는 MariaDB 10.2+)
적절한 데이터베이스 권한

독립 실행 파일 사용 시

Windows 10 이상 (64비트)
데이터베이스 서버 (MSSQL 2012+, MySQL 5.7+, 또는 MariaDB 10.2+)
적절한 데이터베이스 권한
Node.js 설치 불필요

2. 설치 옵션

옵션 A: 개발 설치

# 소스 코드 복제 또는 다운로드
npm install

# 독립 실행 파일 빌드 (선택사항)
npm run build

옵션 B: 독립 실행 파일

릴리스 섹션에서 릴리스 패키지 다운로드
원하는 디렉토리에 압축 해제
대화형 메뉴 실행:
- 영어: run.bat 실행
- 한글: 실행하기.bat 실행
또는 sql2excel-v{version}.exe를 직접 사용

3. 데이터베이스 연결 설정

config/dbinfo.json 파일을 생성하세요:

{
  "sampleDB": {
    "type": "mssql",
    "server": "localhost",
    "port": 1433,
    "database": "SampleDB",
    "user": "sa",
    "password": "yourpassword",
    "options": {
      "encrypt": false,
      "trustServerCertificate": true
    }
  },
  "mysqlDB": {
    "type": "mysql",
    "server": "localhost",
    "port": 3306,
    "database": "mydb",
    "user": "root",
    "password": "password",
    "options": {
      "connectionTimeout": 30000
    }
  },
  "mariaDB": {
    "type": "mariadb",
    "server": "localhost",
    "port": 3306,
    "database": "mydb",
    "user": "root",
    "password": "password",
    "options": {
      "connectionTimeout": 30000
    }
  }
}

참고:

type 필드는 선택사항입니다. 지정하지 않으면 하위 호환성을 위해 기본값 mssql을 사용합니다.
지원 타입: mssql, mysql, mariadb

🚀 기본 사용법

언어 설정

도구는 환경 변수를 통해 한국어와 영어를 지원합니다:

개발 환경

영어: run.bat 실행 (자동으로 LANGUAGE=en 설정)
한글: 실행하기.bat 실행 (자동으로 LANGUAGE=kr 설정)

배포 환경 (Release Package)

영어: run.bat 실행
한글: 실행하기.bat 실행

💡 참고: 환경 변수 LANGUAGE를 사용하여 언어를 제어합니다. 기본값은 영어(en)입니다.

방법 1: 대화형 배치 파일 (Windows 사용자 권장)

개발 환경

# 영어 버전
run.bat

# 한글 버전
실행하기.bat

배포 환경 (Release Package)

# 영어 버전
run.bat

# 한글 버전
실행하기.bat

대화형 메뉴 제공 항목:

쿼리 정의 파일 유효성 검사 - XML/JSON 파일의 오류 확인
데이터베이스 연결 테스트 - 데이터베이스 연결 확인
엑셀 파일 생성 (XML 파일) - XML 쿼리 정의를 사용하여 내보내기
엑셀 파일 생성 (JSON 파일) - JSON 쿼리 정의를 사용하여 내보내기
도움말 표시 - 자세한 도움말 정보 표시

방법 2: 직접 CLI 명령 실행

개발 환경 (Node.js)

# XML 쿼리 파일 사용
node src/excel-cli.js export --xml ./queries/sample-queries.xml

# JSON 쿼리 파일 사용
node src/excel-cli.js export --query ./queries/sample-queries.json

# 변수와 함께 실행
node src/excel-cli.js export --xml ./queries/sample-queries.xml --var "year=2024" --var "dept=IT"

# 템플릿 스타일 사용
node src/excel-cli.js export --xml ./queries/sample-queries.xml --style modern

독립 실행 파일

# XML 쿼리 파일 사용
sql2excel.exe export --xml ./queries/sample-queries.xml

# JSON 쿼리 파일 사용
sql2excel.exe export --query ./queries/sample-queries.json

# 변수와 함께 실행
sql2excel.exe export --xml ./queries/sample-queries.xml --var "year=2024" --var "dept=IT"

# 템플릿 스타일 사용
sql2excel.exe export --xml ./queries/sample-queries.xml --style modern

방법 3: NPM 스크립트 (개발 전용)

# 엑셀로 내보내기
npm run export -- --xml ./queries/sample-queries.xml

# 구성 유효성 검사
npm run validate -- --xml ./queries/sample-queries.xml

# 데이터베이스 연결 테스트
npm run list-dbs

# 독립 실행 파일 빌드
npm run build

# 릴리스 패키지 생성
npm run release

일반 명령어

쿼리 파일 유효성 검사

# 개발 환경
node src/excel-cli.js validate --xml ./queries/sample-queries.xml

# 독립 실행 파일
sql2excel.exe validate --xml ./queries/sample-queries.xml

데이터베이스 연결 테스트

# 개발 환경
node src/excel-cli.js list-dbs

# 독립 실행 파일
sql2excel.exe list-dbs

사용 가능한 템플릿 스타일 목록

# 개발 환경
node src/excel-cli.js list-styles

# 독립 실행 파일
sql2excel.exe list-styles

📚 문서

자세한 사용법 및 고급 기능은 다음 문서를 참조하세요:

📖 사용자 매뉴얼 - 전체 사용 가이드
📋 변경 이력 - 버전별 변경사항

💡 사용 예제

XML 구성 파일 예제 (동적 변수 포함)

<queries>
  <excel db="sampleDB" output="output/SalesReport.xlsx">
    <header>
      <font name="Arial" size="12" color="FFFFFF" bold="true"/>
      <fill color="4F81BD"/>
    </header>
  </excel>
  
  <!-- 일반 변수 -->
  <vars>
    <var name="startDate">2024-01-01</var>
    <var name="endDate">2024-12-31</var>
  </vars>
  
  <!-- 동적 변수 -->
  <dynamicVars>
    <dynamicVar name="activeCustomers" description="활성 고객 목록">
      <![CDATA[
        SELECT CustomerID, CustomerName, Region
        FROM Customers WHERE IsActive = 1
      ]]>
    </dynamicVar>
  </dynamicVars>
  
  <sheet name="MonthlySales" use="true" aggregateColumn="Month">
    <![CDATA[
      SELECT MONTH(OrderDate) as Month, SUM(TotalAmount) as Sales
      FROM Orders 
      WHERE YEAR(OrderDate) = 2024
        AND CustomerID IN (${activeCustomers.CustomerID})
      GROUP BY MONTH(OrderDate)
    ]]>
  </sheet>
</queries>

변수 사용 예제

node src/excel-cli.js export --xml ./queries/sales-report.xml \
  --var "startDate=2024-01-01" \
  --var "endDate=2024-06-30"

동적 변수

이 도구는 런타임에 데이터를 추출하여 쿼리에서 사용할 수 있는 동적 변수를 지원합니다:

변수 유형

유형	설명	액세스 패턴	기본값
`column_identified`	모든 컬럼을 컬럼명으로 키가 지정된 배열로 추출	`${varName.columnName}`	✅ 예
`key_value_pairs`	처음 두 컬럼을 키-값 쌍으로 추출	`${varName.key}`	아니오

사용 예제

<!-- column_identified 사용 (기본값) -->
<dynamicVar name="customerData" description="고객 정보" db="sampleDB">
  <![CDATA[
    SELECT CustomerID, CustomerName, Region FROM Customers
  ]]>
  <!-- type 생략 - column_identified가 기본값 -->
</dynamicVar>

<!-- key_value_pairs 사용 -->
<dynamicVar name="statusMapping" description="상태 매핑" database="mariaDB">
  <![CDATA[
    SELECT StatusCode, StatusName FROM StatusCodes
  ]]>
  <type>key_value_pairs</type>
</dynamicVar>

-- 시트 쿼리에서 사용
SELECT * FROM Orders 
WHERE CustomerID IN (${customerData.CustomerID})
  AND Status IN (${statusMapping.StatusCode})

🔧 환경 요구사항

Node.js 16.0 이상
SQL Server 2012 이상
적절한 데이터베이스 권한

📞 지원

웹사이트: www.sql2excel.com
이메일: sql2excel.nodejs@gmail.com

FilesExpand file tree

README_KR.md

Latest commit

History

README_KR.md

File metadata and controls

SQL2Excel - SQL 쿼리 결과로 엑셀 파일 생성

v2.1.5 하이라이트

v2.1.4 하이라이트

v2.1.3-beta (v1.3.3) 하이라이트

주요 기능

🔗 다중 데이터베이스 사용

v2.1.2(v1.3.2) 하이라이트

v2.1.1-beta (v1.3.1) 하이라이트

v2.1.0-beta (v1.3.0) 하이라이트

이전 버전(v1.2.11)

이전 버전(v1.2.10)

비대화형 CLI (신규)

Node.js

독립 실행 파일(EXE)

🚀 빠른 시작

🛠️ 설치 및 설정

1. 시스템 요구사항

개발/소스 코드 사용 시

독립 실행 파일 사용 시

2. 설치 옵션

옵션 A: 개발 설치

옵션 B: 독립 실행 파일

3. 데이터베이스 연결 설정

🚀 기본 사용법

언어 설정

개발 환경

배포 환경 (Release Package)

방법 1: 대화형 배치 파일 (Windows 사용자 권장)

개발 환경

배포 환경 (Release Package)

방법 2: 직접 CLI 명령 실행

개발 환경 (Node.js)

독립 실행 파일

방법 3: NPM 스크립트 (개발 전용)

일반 명령어

쿼리 파일 유효성 검사

데이터베이스 연결 테스트

사용 가능한 템플릿 스타일 목록

📚 문서

💡 사용 예제

XML 구성 파일 예제 (동적 변수 포함)

변수 사용 예제

동적 변수

변수 유형

사용 예제

🔧 환경 요구사항

📞 지원