🎯 개요
SQL2Excel이란?
SQL2Excel은 SQL 쿼리 결과를 Excel 파일로 생성하는 Node.js 기반 도구로, 고급 스타일링과 템플릿 지원 기능을 제공합니다.
개발자와 데이터 분석가가 데이터베이스의 정보를 쉽게 Excel 형태로 변환하여 보고서나 분석 자료를 만들 수 있도록 도와줍니다.
주요 특징
- 멀티 시트 지원: 하나의 Excel 파일에 여러 SQL 쿼리 결과를 별도 시트로 저장
- 템플릿 스타일 시스템: 일관된 디자인을 위한 사전 정의된 Excel 스타일링 템플릿
- 다중 DB 연결: 각 시트마다 다른 데이터베이스 연결 사용
- 향상된 동적 변수: 실시간 데이터베이스에서 값을 추출하여 고급 처리
- 독립 실행파일: Node.js 의존성 없는 .exe 파일 생성
- 날짜시간 변수: 20개 이상의 자동 날짜시간 함수
- 다국어 지원: 한국어 및 영어 릴리스 패키지
🆕 v1.2.7의 새로운 기능
최적화된 검증 및 인코딩
쿼리 파일 검증 시 실제로 사용하는 데이터베이스만 표시하도록 개선. 배포판 배치 파일의 문자 인코딩 문제를 해결했습니다.
국제화된 샘플 파일
모든 쿼리 샘플 파일을 영문으로 변환하여 전 세계 사용자의 접근성과 크로스 플랫폼 호환성을 향상시켰습니다.
파일명 제한 제거
파일명의 한글 문자 검증을 제거하여 더 유연한 파일 이름 사용이 가능합니다.
🔄 v1.2.6의 주요 기능
인터랙티브 다국어 메뉴
sql2db 스타일의 사용자 친화적 인터랙티브 메뉴 시스템과 완전한 다국어 지원을 제공합니다.
향상된 검증 시스템
시트 목록 전체 출력, 개별 검증 결과 표시, 데이터베이스 상세 정보 출력 기능을 제공합니다.
pkg 빌드 최적화
네이티브 모듈 호환성 개선, 압축을 통한 파일 크기 최적화, pkg 환경에서의 안정적인 동작을 보장합니다.
🔄 v1.2.5의 주요 기능
개선된 배치 인터페이스
번호 선택 방식으로 변경하여 더욱 직관적이고 사용하기 쉬운 파일 선택 시스템을 제공합니다.
향상된 입력 유효성 검증
파일 선택 번호에 대한 유효성 검증을 추가하여 잘못된 입력을 방지합니다.
자동 파일 유형 감지
XML 및 JSON 파일을 자동으로 감지하고 선택 메뉴에서 분리하여 표시합니다.
🔄 v1.2.4의 주요 기능
독립 실행파일
Node.js 설치가 필요 없는 버전별 독립 실행파일(sql2excel-v1.2.5.exe)을 생성합니다.
향상된 날짜시간 변수
UTC, KST, 한국어 현지화 형식, 압축 형식을 포함한 20개 이상의 자동 날짜시간 변수를 제공합니다.
생성 타임스탬프
각 Excel 시트에 한국어 로케일 형식의 생성 타임스탬프를 자동으로 표시합니다.
다국어 패키지
현지화된 인터페이스로 한국어 및 영어 릴리스 패키지를 자동 생성합니다.
SQL 쿼리 형식
가독성 향상을 위해 목차에서 원본 SQL 형식을 줄바꿈과 함께 보존합니다.
🛠️ 설치 및 설정
시스템 요구사항
- Windows 10 이상 (64비트)
- SQL Server 2012 이상
- 적절한 데이터베이스 권한
- Node.js 설치 불필요 ✨
다운로드 및 압축 해제
최신 릴리스 패키지를 다운로드하세요:
1. sql2excel-v1.2.7-win-x64.zip 다운로드
2. 원하는 디렉토리에 압축 해제 (예: C:\sql2excel\)
3. config/dbinfo.json 파일을 편집하여 데이터베이스 연결을 설정합니다.
4. queries/ 폴더의 샘플 쿼리 파일을 참조하여 본인의 쿼리 파일을 작성합니다.
5. run.bat (영어) 또는 실행하기.bat (한글)를 실행하면 인터랙티브 메뉴를 사용할 수 있습니다.패키지 구성
sql2excel-v1.2.7-win-x64/
├── sql2excel-v1.2.7.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 # 릴리스 정보데이터베이스 설정
config/dbinfo.json 파일을 편집하여 데이터베이스 연결을 설정합니다:
{
"dbs": {
"sampleDB": {
"server": "localhost",
"port": 1433,
"database": "SampleDB",
"user": "sa",
"password": "yourpassword",
"options": {
"encrypt": false,
"trustServerCertificate": true
}
}
}
}🚀 기본 사용법
CLI 명령어 기본 사용법
방법 1: 인터랙티브 메뉴 시스템 (권장)
run.bat (영어) 또는 실행하기.bat (한글)를 더블클릭하여 사용자 친화적인 메뉴 인터페이스 사용
# 영어 메뉴
run.bat
# 한글 메뉴
실행하기.bat방법 2: 직접 명령줄 사용
독립 실행파일을 직접 사용
기본 Excel 생성
sql2excel-v1.2.6.exe export --xml queries/sample-queries.xml템플릿 스타일 사용
sql2excel-v1.2.6.exe export --xml queries/sample-queries.xml --style modern설정 검증 (상세 출력)
sql2excel-v1.2.6.exe validate --xml queries/sample-queries.xml사용 가능한 스타일 목록
sql2excel-v1.2.6.exe list-stylesXML 설정 파일 구조
<?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 설정 파일 구조
{
"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"
}
]
}🎨 고급 기능
템플릿 스타일 시스템
7가지 사전 정의된 스타일로 일관된 디자인을 제공합니다.
향상된 동적 변수
실시간 데이터베이스에서 값을 추출하여 고급 처리를 지원합니다.
- column_identified 타입
- key_value_pairs 타입
- 실행 전 변수 처리
- 디버그 모드 지원
목차 시트 생성
목차 시트 생성하여 보고서 관리 효율성을 향상시킵니다.
- 시트별 데이터 건수 표시 (템플릿 사용 가능)
- 시트별 적용 SQL쿼리문 표시
📋 실용 예제
📊 매출 보고서 생성
월별 매출 데이터를 분석하여 Excel 보고서로 생성하는 예제입니다.
<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>👥 고객 분석 보고서
고객별 구매 패턴을 분석하는 보고서 예제입니다.
{
"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"
}🔄 동적 변수 사용
실시간으로 데이터베이스에서 값을 가져와 쿼리에 사용하는 예제입니다.
<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: 현재 SQL Server 2012 이상을 지원합니다. 향후 MySQL, PostgreSQL 등 다른 데이터베이스 지원을 계획하고 있습니다.
Q: 템플릿 스타일을 커스터마이징할 수 있나요?
+A: 네, templates/excel-styles.xml 파일을 수정하여 새로운 스타일을 추가하거나 기존 스타일을 수정할 수 있습니다.
Q: 대용량 데이터 처리 시 성능은 어떻게 되나요?
+A: maxRows 속성을 사용하여 처리할 행 수를 제한할 수 있으며, 스트리밍 처리로 메모리 효율성을 높였습니다.
Q: 자동화된 보고서 생성이 가능한가요?
+A: 네, Windows 배치 파일이나 스케줄러를 사용하여 정기적인 보고서 생성을 자동화할 수 있습니다.
⏰ 날짜시간 변수
SQL2Excel v1.2.4는 다양한 형식의 실시간 타임스탬프 생성을 위한 20개 이상의 자동 날짜시간 변수를 제공합니다.
기본 날짜시간 함수
| 변수 | 설명 | 출력 예시 |
|---|---|---|
${CURRENT_TIMESTAMP} |
현재 UTC 타임스탬프 | 2024-10-05 15:30:45 |
${KST_NOW} |
한국 표준시 | 2024-10-06 00:30:45 |
${KOREAN_DATE} |
한국어 날짜 형식 | 2024년 10월 6일 |
${DATE_YYYYMMDD} |
압축 날짜 형식 | 20241006 |
사용 예제
-- XML 쿼리에서
<vars>
<var name="reportDate">${KOREAN_DATE}</var>
<var name="currentTime">${KST_NOW}</var>
</vars>
-- 파일명 지정에서
<excel output="report_${DATE_YYYYMMDD}_${DATETIME_YYYYMMDD_HHMMSS}.xlsx">🕒 생성 타임스탬프
📦 독립 실행파일
Node.js 의존성 없이 배포 가능한 버전별 독립 실행파일을 생성합니다.
실행파일 빌드
# 버전별 실행파일 빌드
npm run build
# 생성됨: dist/sql2excel-v1.2.6.exe특징
- 자체 완결형: 모든 Node.js 의존성이 번들됨
- 버전별 파일명: sql2excel-v1.2.6.exe 형식
- 에셋 번들링: 템플릿과 스타일이 포함됨
- 설치 불필요: 모든 Windows 시스템에서 직접 실행 가능
- 최적화: GZip 압축으로 파일 크기 최적화
- 네이티브 모듈: mssql, tedious 등 네이티브 모듈 정상 작동
🌐 다국어 지원
현지화된 인터페이스로 한국어 및 영어 릴리스 패키지를 자동 생성합니다.
통합 릴리스 패키지
📦 sql2excel-v1.2.6-win-x64
- run.bat (영어) / 실행하기.bat (한글) 인터랙티브 메뉴
- 언어별 배치 파일에서 --lang 옵션 자동 적용
- 한국어/영어 문서 모두 포함
- RELEASE_INFO.txt (배포 정보)
릴리스 패키지 생성
# 릴리스 패키지 생성
npm run release
# 생성됨:
# release/sql2excel-v1.2.6-win-x64/
# release/sql2excel-v1.2.6-win-x64.zip다국어 지원 특징
- 인터랙티브 메뉴: app.js 기반의 다국어 메뉴 시스템
- 명령줄 옵션: --lang=en (영어), --lang=kr (한글)
- 자동 선택: run.bat과 실행하기.bat에서 언어 자동 설정
- 완전 현지화: 모든 메뉴, 메시지, 에러가 선택된 언어로 표시