📖 목차
🎯 개요
🛠️ 설치 및 설정
🚀 기본 사용법
🎨 고급 기능
📦 배포
📋 예제
🔧 문제 해결
🎯 개요
SQL2Excel이란?
SQL2Excel은 SQL 쿼리 결과를 Excel 파일로 생성하는 Node.js 기반 도구로, 고급 스타일링과 템플릿 지원 기능을 제공합니다.
개발자와 데이터 분석가가 데이터베이스의 정보를 쉽게 Excel 형태로 변환하여 보고서나 분석 자료를 만들 수 있도록 도와줍니다.
주요 특징
- 🗄️ 다중 데이터베이스 지원: ORACLE, PostgreSQL, MSSQL, MySQL, MariaDB, SQLite 지원
- 📊 다중 시트 지원: 하나의 엑셀 파일 내에서 여러 SQL 쿼리 결과를 별도의 시트에 저장
- 🎨 템플릿 스타일 시스템: 일관된 디자인을 위한 사전 정의된 엑셀 스타일링 템플릿 (7가지 내장 스타일)
- 🔗 다중 DB 연결: 각 시트마다 다른 데이터베이스 연결 사용 가능
- 📝 변수 시스템: 동적 쿼리 생성을 위한 변수 사용
- 🔄 향상된 동적 변수: 실시간으로 데이터베이스에서 값을 추출하여 고급 처리
- 🔄 쿼리 재사용: 공통 쿼리를 정의하고 여러 시트에서 재사용
- ⚙️ 파라미터 오버라이드: 각 시트에 대해 쿼리 정의 파라미터를 다른 값으로 재정의
- 📋 자동 목차 생성: 하이퍼링크가 있는 목차 시트 자동 생성
- 📊 집계 기능: 지정된 컬럼 값별 개수 자동 집계 및 표시
- 🚦 쿼리 제한: 대용량 데이터 처리를 위한 행 개수 제한
- 🖥️ CLI 인터페이스: 간단한 명령줄 도구 실행
- 🪟 Windows 배치 파일: Windows 사용자를 위한 대화형 배치 파일
- 📄 XML/JSON 지원: 유연한 구성 파일 형식 지원
- 🎯 시트별 스타일링: 개별 시트에 다른 스타일 적용
- 📦 독립 실행 파일: Node.js 의존성 없이 배포할 수 있는 독립 실행 파일(.exe) 생성
- 🌐 다국어 지원: 한국어 및 영어 릴리스 패키지
- 🔧 릴리스 자동화: 적절한 문서와 함께 자동 릴리스 패키지 생성
- 🕒 생성 타임스탬프: 각 엑셀 시트에 생성 타임스탬프 표시
- ⏰ 향상된 DateTime 변수: 전세계 22개 타임존 지원 및 커스텀 포맷
- 📋 SQL 쿼리 포맷팅: 목차에서 줄바꿈을 포함한 원본 SQL 포맷 유지
- 🔧 입력 유효성 검증: 파일 경로 입력에 대한 자동 공백 제거
🛠️ 설치 및 설정
1. 시스템 요구사항
- Windows 10 이상 (64비트)
- 데이터베이스 서버 (MSSQL/MySQL/MariaDB/PostgreSQL/SQLite/Oracle 중 해당)
- 적절한 데이터베이스 권한
- Node.js 설치 불필요 ✨
2. 다운로드 및 압축 해제
최신 릴리스 패키지를 다운로드하세요:
📦 sql2excel-v2.1.5-win-x64.zip
steps
1. sql2excel-v2.1.5-win-x64.zip 다운로드
2. 원하는 디렉토리에 압축 해제 (예: C:\sql2excel\)
3. config/dbinfo.json 파일을 편집하여 데이터베이스 연결을 설정합니다.
4. queries/ 폴더의 샘플 쿼리 파일을 참조하여 본인의 쿼리 파일을 작성합니다.
5. run.bat (영어) 또는 실행하기.bat (한글)를 실행하면 인터랙티브 메뉴를 사용할 수 있습니다.3. 패키지 구성
sql2excel-v2.1.5-win-x64/
├── sql2excel-v2.1.5.exe # 독립 실행파일
├── run.bat # 영어 인터랙티브 메뉴 (--lang=en)
├── 실행하기.bat # 한글 인터랙티브 메뉴 (--lang=kr)
├── config/
│ └── dbinfo.json # 데이터베이스 설정
├── queries/ # 샘플 쿼리 파일
│ ├── datetime-variables-example.xml
│ ├── queries-sample.xml
│ └── ...
├── templates/ # Excel 스타일 템플릿
│ └── excel-styles.xml
├── user_manual/ # 문서
│ ├── README_KR.md
│ ├── README.md
│ ├── CHANGELOG_KR.md
│ └── CHANGELOG.md
└── RELEASE_INFO.txt # 릴리스 정보4. 데이터베이스 설정
config/dbinfo.json 파일을 편집하여 데이터베이스 연결을 설정합니다:
json
{
"dbs": {
"sampleDB": {
"server": "localhost",
"port": 1433,
"database": "SampleDB",
"user": "sa",
"password": "yourpassword",
"options": {
"encrypt": false,
"trustServerCertificate": true
}
}
}
}🚀 기본 사용법
CLI 명령어 기본 사용법
방법 1: 인터랙티브 메뉴 시스템 (권장)
run.bat (영어) 또는 실행하기.bat (한글)를 더블클릭하여 사용자 친화적인 메뉴 인터페이스 사용
batch
# 영어 메뉴
run.bat
# 한글 메뉴
실행하기.bat방법 2: 직접 명령줄 사용
독립 실행파일을 직접 사용
기본 Excel 생성
sql2excel-v2.1.5.exe export --xml queries/sample-queries.xml템플릿 스타일 사용
sql2excel-v2.1.5.exe export --xml queries/sample-queries.xml --style modern설정 검증 (상세 출력)
sql2excel-v2.1.5.exe validate --xml queries/sample-queries.xml사용 가능한 스타일 목록
sql2excel-v2.1.5.exe list-styles방법 3: 비대화형 CLI (v1.2.10)
--mode를 사용해 메뉴 없이 바로 실행합니다. Node/배포 EXE 모두 지원.
Node.js
# 검증
node app.js --mode=validate --xml=queries/sample-queries.xml
# 또는 JSON
node app.js --mode=validate --query=queries/sample-queries.json
# 연결 테스트
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독립 실행 파일(EXE)
sql2excel-v2.1.5.exe --mode=validate --xml=queries/sample-queries.xml
sql2excel-v2.1.5.exe --mode=test
sql2excel-v2.1.5.exe --mode=export --xml=queries/sample-queries.xml
sql2excel-v2.1.5.exe --mode=helpXML 설정 파일 구조
xml
<?xml version="1.0" encoding="UTF-8"?>
<queries maxRows="10000">
<!-- 엑셀 파일 설정 -->
<excel db="sampleDB" output="output/보고서.xlsx" style="modern">
</excel>
<!-- 변수 정의 -->
<vars>
<var name="year">2024</var>
<var name="month">12</var>
</vars>
<!-- 시트 정의 -->
<sheet name="매출현황" use="true" aggregateColumn="Region">
<![CDATA[
SELECT Region, SUM(Amount) as TotalAmount
FROM Sales
WHERE YEAR(Date) = ${year}
GROUP BY Region
]]>
</sheet>
</queries>JSON 설정 파일 구조
json
{
"excel": {
"db": "sampleDB",
"output": "output/보고서.xlsx",
"style": "modern"
},
"vars": {
"year": "2024",
"month": "12"
},
"sheets": [
{
"name": "매출현황",
"use": true,
"aggregateColumn": "Region",
"query": "SELECT Region, SUM(Amount) as TotalAmount FROM Sales WHERE YEAR(Date) = ${year} GROUP BY Region"
}
]
}📋 실용 예제
📊 매출 보고서 생성
월별 매출 데이터를 분석하여 Excel 보고서로 생성하는 예제입니다.
xml
<sheet name="월별매출_${year}" use="true" style="business">
<![CDATA[
SELECT
MONTH(OrderDate) as Month,
DATENAME(MONTH, OrderDate) as MonthName,
COUNT(*) as OrderCount,
SUM(TotalAmount) as TotalSales
FROM Orders
WHERE YEAR(OrderDate) = ${year}
GROUP BY MONTH(OrderDate), DATENAME(MONTH, OrderDate)
ORDER BY Month
]]>
</sheet>👥 고객 분석 보고서
고객별 구매 패턴을 분석하는 보고서 예제입니다.
json
{
"name": "고객분석",
"use": true,
"style": "premium",
"query": "SELECT c.CustomerName, COUNT(o.OrderID) as OrderCount, SUM(o.TotalAmount) as TotalPurchase FROM Customers c LEFT JOIN Orders o ON c.CustomerID = o.CustomerID GROUP BY c.CustomerID, c.CustomerName ORDER BY TotalPurchase DESC"
}🔄 동적 변수 사용
실시간으로 데이터베이스에서 값을 가져와 쿼리에 사용하는 예제입니다.
xml
<dynamicVars>
<dynamicVar name="activeCustomers">
<![CDATA[
SELECT CustomerID FROM Customers WHERE IsActive = 1
]]>
</dynamicVar>
</dynamicVars>
<sheet name="활성고객주문">
<![CDATA[
SELECT * FROM Orders
WHERE CustomerID IN (${activeCustomers.CustomerID})
]]>
</sheet>🔧 문제 해결
❌ 연결 오류
문제: 데이터베이스 연결에 실패합니다.
해결:
- config/dbinfo.json 파일의 연결 정보 확인
- SQL Server 서비스가 실행 중인지 확인
- 방화벽 설정 확인
- 사용자 권한 확인
⚠️ 한글 파일명 경고
문제: 한글 파일명 사용 시 경고가 표시됩니다.
해결:
- 영문 파일명 사용 권장
- 파일명에 특수문자 사용 금지
- 공백 대신 언더스코어(_) 사용
🔍 변수 치환 오류
문제: 동적 변수가 제대로 치환되지 않습니다.
해결:
- DEBUG_VARIABLES=true 환경변수 설정
- 변수 쿼리 결과 확인
- 변수명과 사용법 확인
- 데이터베이스 권한 확인
📊 대용량 데이터 처리
문제: 대용량 데이터 처리 시 메모리 부족 오류가 발생합니다.
해결:
- maxRows 속성으로 행 수 제한
- 쿼리 최적화
- 인덱스 활용
- 배치 처리 고려
❓ 자주 묻는 질문
Q: SQL2Excel은 어떤 데이터베이스를 지원하나요?
+A: 현재 ORACLE, PostgreSQL, MSSQL, MySQL, MariaDB, SQLite 등 가장 많이 사용되는 주요 RDBMS는 대부분 지원하고 있습니다.
Q: 템플릿 스타일을 커스터마이징할 수 있나요?
+A: 네, templates/excel-styles.xml 파일을 수정하여 새로운 스타일을 추가하거나 기존 스타일을 수정할 수 있습니다.
Q: 대용량 데이터 처리 시 성능은 어떻게 되나요?
+A: maxRows 속성을 사용하여 처리할 행 수를 제한할 수 있으며, 스트리밍 처리로 메모리 효율성을 높였습니다.
Q: 자동화된 보고서 생성이 가능한가요?
+A: 네, Windows 배치 파일이나 스케줄러를 사용하여 정기적인 보고서 생성을 자동화할 수 있습니다.
⏰ 날짜시간 변수
SQL2Excel v1.2.9는 전세계 22개 타임존을 지원하며 유연한 커스텀 날짜/시간 포맷을 제공합니다.
타임존 지정 (권장): ${DATE.<TIMEZONE>:format}
타임존 생략 (로컬 시간): ${DATE:format}
💡 타임존 생략 시 서버의 로컬 시간이 사용됩니다. 글로벌 일관성을 위해 타임존 지정을 권장합니다.
지원 타임존 (22개)
| 타임존 코드 | 설명 | UTC 오프셋 | 지역 |
|---|---|---|---|
| UTC | 협정 세계시 | UTC+0 | 세계 표준 |
| GMT | 그리니치 표준시 | UTC+0 | 영국 |
| KST | 한국 표준시 | UTC+9 | 대한민국 |
| JST | 일본 표준시 | UTC+9 | 일본 |
| CST | 중국 표준시 | UTC+8 | 중국 |
| PHT | 필리핀 표준시 | UTC+8 | 필리핀 |
| ICT | 인도차이나 표준시 | UTC+7 | 태국, 베트남 |
| CET | 중앙 유럽 표준시 | UTC+1 | 독일, 프랑스, 이탈리아, 폴란드 |
| EST | 미국 동부 표준시 | UTC-5 | 미국 동부 |
| AST | 대서양 표준시 | UTC-4 | 캐나다 동부 |
| CST_US | 중부 표준시 | UTC-6 | 미국, 캐나다, 멕시코 중부 |
| PST | 미국 서부 표준시 | UTC-8 | 미국 서부 |
그 외: SGT, AEST, IST, GST, EET, MST, AKST, HST, BRT, ART
일반적인 형식 예시
| 형식 | 출력 예시 | 사용 예 |
|---|---|---|
${DATE.UTC:YYYY-MM-DD} |
2024-10-21 | 표준 날짜 형식 |
${DATE.KST:YYYY년 MM월 DD일} |
2024년 10월 22일 | 한국어 날짜 |
${DATE.EST:YYYY-MM-DD HH:mm:ss} |
2024-10-21 10:30:45 | 미국 동부시간 |
${DATE.UTC:YYYYMMDD_HHmmss} |
20241021_153045 | 파일명용 형식 |
사용 예제
-- XML 쿼리에서
<vars>
<var name="reportDate">${DATE.KST:YYYY년 MM월 DD일}</var>
<var name="currentTime">${DATE.KST:YYYY-MM-DD HH:mm:ss}</var>
</vars>
-- 파일명 지정에서 (타임존 지정)
<excel output="report_${DATE.UTC:YYYYMMDD}_${DATE.UTC:HHmmss}.xlsx">
-- 파일명 지정에서 (로컬 시간)
<excel output="report_${DATE:YYYYMMDD}_${DATE:HHmmss}.xlsx">
-- 글로벌 보고서 (다중 타임존)
SELECT
'서울: ${DATE.KST:YYYY-MM-DD HH:mm:ss}' as Seoul_Time,
'뉴욕: ${DATE.EST:YYYY-MM-DD HH:mm:ss}' as NewYork_Time,
'도쿄: ${DATE.JST:YYYY-MM-DD HH:mm:ss}' as Tokyo_Time