🎯 개요
SQL2DB란?
SQL2DB는 Microsoft SQL Server 간의 데이터 이관을 효율적으로 수행하는 Node.js 기반 도구입니다. 대용량 데이터 처리, 실시간 모니터링, 중단 재시작 등 고급 기능을 제공하여 안정적이고 효율적인 데이터 마이그레이션을 지원합니다.
주요 특징
- JSON 매핑 버그 수정 (v0.8.7 신규): JSON 기반 컬럼 오버라이드 매핑이 실제 데이터 값에 따라 올바르게 작동하도록 수정
- 컬럼 오버라이드 로그 개선 (v0.8.6): 2단계 필터링으로 실제 오버라이드된 컬럼만 표시
- 글로벌 타임존 시스템 (v0.8.5): 전 세계 22개 타임존 지원 with ${DATE.TIMEZONE:format}
- 대화형 인터페이스 (v0.8.4): 사용자 친화적인 메뉴 시스템으로 쉬운 작업 수행
- 독립 실행 파일 (v0.8.4): Node.js 설치 없이 즉시 실행 가능
- 진행 상황 모니터링 (v0.8.4): 상세한 이관 작업 이력 및 진행 추적
- 언어 설정 통일 (v0.8.4): 환경 변수 기반 언어 설정 통일
- 보안 강화 (v0.8.3): 로그에서 자동 비밀번호 마스킹
- 대소문자 구분 없는 컬럼 매칭 (v0.8.3): 컬럼명 대소문자 자동 보정
- 대량 데이터 지원 (v0.8.3): SQL Server 2100 파라미터 제한 자동 처리
- 향상된 디버깅 (v0.8.3): 삭제 작업 상세 진단
- 배치 단위 데이터 이관: 대용량 데이터 처리 최적화
- 유연한 설정: XML 또는 JSON 기반 설정
- 컬럼 오버라이드: 이관 시 특정 컬럼값 변경/추가
- 전처리/후처리: 이관 전후 SQL 스크립트 실행
- 동적 변수: 실행 시점 데이터 추출 및 활용
- 중단 재시작: 네트워크 오류 등으로 중단된 마이그레이션을 완료된 지점에서 재시작
🆕 v0.9.1의 새로운 기능
비대화형 CLI
app.js --mode로 메뉴 없이 바로 실행합니다. 모드: validate, test, migrate, help. Node/배포 EXE 모두 지원.
모듈 일관성 및 타입 안정성
모듈 간 일관성 개선과 타입 안정성 향상으로 더 견고한 마이그레이션 실행.
전역 컬럼 오버라이드 선택 적용 강화
실제 사용되는 컬럼만 정확히 적용되도록 선택 로직을 강화했습니다.
대소문자 무시 컬럼 매칭 개선
컬럼명 매칭 시 대소문자 차이로 인한 오류를 줄이도록 매칭 로직을 개선했습니다.
🛠️ 설치 및 설정
시스템 요구사항
독립 실행 파일 사용자용
- Windows 7 이상 (64비트)
- SQL Server 2012 이상 (소스/타겟)
- 적절한 데이터베이스 권한
- Node.js 설치 불필요
Node.js 소스 사용자용 (개발자)
- Node.js 14.0 이상 (18.x 권장)
- npm 6.0 이상
- SQL Server 2012 이상 (소스/타겟)
- 적절한 데이터베이스 권한
설치 방법
옵션 1: 독립 실행 파일 (권장)
# 1. sql2db-v0.9.1-win-x64.zip 다운로드
# 2. 원하는 위치에 압축 해제
# 3. 압축 해제한 폴더로 이동
# 영문 버전 실행
run.bat
# 한글 버전 실행
실행하기.bat
# 또는 환경 변수로 언어 설정하여 직접 실행
set LANGUAGE=en && sql2db.exe
set LANGUAGE=kr && sql2db.exe
옵션 2: Node.js 소스 (개발자용)
# 저장소 클론
git clone https://github.com/happysoft2018/sql2db.git
cd sql2db
# 의존성 설치
npm install
# 실행
npm start # 영문
npm run start:kr # 한글
데이터베이스 설정
config/dbinfo.json 파일을 생성하고 데이터베이스 연결 정보를 설정합니다:
{
"dbs": {
"sourceDB": {
"server": "source-server.com",
"port": 1433,
"database": "source_database",
"user": "username",
"password": "password",
"isWritable": false,
"description": "소스 데이터베이스",
"options": {
"encrypt": true,
"trustServerCertificate": true
}
},
"targetDB": {
"server": "target-server.com",
"port": 1433,
"database": "target_database",
"user": "username",
"password": "password",
"isWritable": true,
"description": "타겟 데이터베이스"
}
}
}
🚀 기본 사용법
대화형 인터페이스 (v0.8.3)
SQL2DB는 사용자 친화적인 메뉴 기반 인터페이스를 제공합니다. 복잡한 명령어를 외울 필요 없이 간단한 메뉴 선택만으로 모든 작업을 수행할 수 있습니다.
실행 방법
# 독립 실행 파일
run.bat # 영문 버전
실행하기.bat # 한글 버전
# 또는 환경 변수로 언어 설정하여 직접 실행
set LANGUAGE=en && sql2db.exe
set LANGUAGE=kr && sql2db.exe
# Node.js 소스
npm start # 영문
npm run start:kr # 한글 (배치 파일 사용 권장)
메뉴 옵션
- 1. 쿼리문정의 파일 Syntax검증: XML/JSON 쿼리 정의 파일의 구문 및 속성 검증
- 2. DB연결 테스트: 데이터베이스 연결 테스트 (연결 가능한 DB 목록 표시)
- 3. 데이터 이관 실행: 실제 데이터 이관 작업 실행
- 4. 이관 진행 상황 조회: 최근 이관 작업의 진행 상황 및 상세 정보 조회
- 5. 도움말 보기: 사용 가능한 명령어 및 기능 설명
- 0. 종료: 프로그램 종료
쿼리 파일 선택
작업 시 쿼리 정의 파일을 선택해야 합니다. 전체 경로를 입력할 필요 없이 표시되는 번호만 입력하면 됩니다:
사용 가능한 쿼리문정의 파일들:
1. migration-queries.xml [XML]
2. test-migration.json [JSON]
파일 번호를 선택하세요 (1-2): 1
선택된 파일: D:\sql2db\queries\migration-queries.xml
진행 상황 모니터링
메뉴 옵션 4를 선택하면 최근 이관 작업의 진행 상황을 조회할 수 있습니다:
- 처음에는 최근 3개 이관 작업만 표시
- 'A' 입력으로 전체 이관 이력 조회 가능
- 번호 선택으로 상세 정보 조회:
- 전체 마이그레이션 상태 (완료/실패/실행중)
- 시작/종료 시간 및 소요 시간
- 쿼리별 진행 상황 (처리된 행 수, 배치 수)
- 오류 정보 (발생 시)
CLI 명령어 기본 사용법
설정 검증
node src/migrate-cli.js validate --query ./queries/migration-queries.xml
데이터베이스 목록 조회
node src/migrate-cli.js list-dbs
데이터 이관 실행
node src/migrate-cli.js migrate --query ./queries/migration-queries.xml
시뮬레이션 실행 (DRY RUN)
node src/migrate-cli.js migrate --query ./queries/migration-queries.xml --dry-run
비대화형 실행 (app.js --mode)
대화형 메뉴 없이 app.js --mode로 바로 실행합니다. Node/배포 EXE 모두에서 동작합니다.
# 설정 검증
node app.js --lang=kr --mode=validate --query=queries/migration-queries.xml
# 연결 테스트
node app.js --lang=kr --mode=test
# 이관 실행
node app.js --lang=kr --mode=migrate --query=queries/migration-queries.xml
# 도움말
node app.js --mode=help
# 독립 실행 파일(EXE)
sql2db.exe --lang=kr --mode=validate --query=queries/migration-queries.xml
sql2db.exe --lang=kr --mode=test
sql2db.exe --lang=kr --mode=migrate --query=queries/migration-queries.xml
중단된 마이그레이션 재시작
node src/migrate-cli.js migrate --query ./queries/migration-queries.xml --resume
XML 설정 파일 구조
<?xml version="1.0" encoding="UTF-8"?>
<migrations>
<!-- 전역 설정 -->
<global>
<batchSize>1000</batchSize>
<timeout>30000</timeout>
<retryCount>3</retryCount>
</global>
<!-- 동적 변수 정의 -->
<dynamicVars>
<dynamicVar name="currentDate">
<![CDATA[
SELECT GETDATE() as CurrentDate
]]>
</dynamicVar>
</dynamicVars>
<!-- 마이그레이션 작업 정의 -->
<migration name="사용자_데이터_이관" use="true">
<source db="sourceDB">
<![CDATA[
SELECT UserID, UserName, Email, CreatedDate
FROM Users
WHERE CreatedDate >= '2024-01-01'
]]>
</source>
<target db="targetDB" table="Users">
<columns>
<column name="UserID" type="int" />
<column name="UserName" type="varchar(100)" />
<column name="Email" type="varchar(255)" />
<column name="CreatedDate" type="datetime" />
<column name="MigratedDate" type="datetime" override="true">${currentDate.CurrentDate}</column>
</columns>
</target>
<!-- 전처리 스크립트 -->
<preProcess db="targetDB">
<![CDATA[
DELETE FROM Users WHERE CreatedDate >= '2024-01-01'
]]>
</preProcess>
<!-- 후처리 스크립트 -->
<postProcess db="targetDB">
<![CDATA[
UPDATE Users SET Status = 'Migrated' WHERE MigratedDate IS NOT NULL
]]>
</postProcess>
</migration>
</migrations>
🎨 고급 기능
동적 변수 시스템
실행 시점에 데이터베이스에서 값을 추출하여 마이그레이션 과정에서 활용합니다.
- 실시간 데이터 추출
- 변수 치환 및 활용
- 복잡한 쿼리 지원
- 디버그 모드 지원
실시간 모니터링
키보드 인터랙티브 모니터링과 차트를 통해 마이그레이션 진행 상황을 실시간으로 추적합니다.
- 실시간 진행률 표시
- 차트 기반 시각화
- 키보드 인터랙션
- 성능 메트릭 표시
중단 재시작 기능
네트워크 오류 등으로 중단된 마이그레이션을 완료된 지점에서 재시작할 수 있습니다.
- 진행 상황 저장
- 자동 재시작 지원
- 데이터 일관성 보장
- 오류 복구 기능
전처리/후처리
마이그레이션 전후에 SQL 스크립트를 실행하여 데이터 정리 및 검증을 수행합니다.
- 데이터 정리 스크립트
- 검증 및 검사
- 인덱스 관리
- 통계 업데이트
컬럼 오버라이드
마이그레이션 시 특정 컬럼의 값을 변경하거나 추가할 수 있습니다.
- 기본값 설정
- 동적 값 할당
- 데이터 변환
- 메타데이터 추가
배치 처리 최적화
대용량 데이터를 효율적으로 처리하기 위한 배치 단위 처리 시스템을 제공합니다.
- 메모리 효율성
- 성능 최적화
- 트랜잭션 관리
- 오류 처리
📋 실용 예제
📊 사용자 데이터 이관
사용자 테이블의 데이터를 소스에서 타겟으로 이관하는 기본 예제입니다.
<migration name="사용자_이관" use="true">
<source db="sourceDB">
<![CDATA[
SELECT UserID, UserName, Email, CreatedDate, Status
FROM Users
WHERE Status = 'Active'
]]>
</source>
<target db="targetDB" table="Users">
<columns>
<column name="UserID" type="int" />
<column name="UserName" type="varchar(100)" />
<column name="Email" type="varchar(255)" />
<column name="CreatedDate" type="datetime" />
<column name="Status" type="varchar(20)" />
<column name="MigratedDate" type="datetime" override="true">${currentDate.CurrentDate}</column>
</columns>
</target>
</migration>
🔄 동적 변수 활용
실행 시점에 데이터를 추출하여 마이그레이션 조건으로 활용하는 예제입니다.
<dynamicVars>
<dynamicVar name="lastSyncDate">
<![CDATA[
SELECT MAX(LastModifiedDate) as LastSyncDate
FROM TargetDB.dbo.Products
]]>
</dynamicVar>
</dynamicVars>
<migration name="제품_이관">
<source db="sourceDB">
<![CDATA[
SELECT ProductID, ProductName, Price, LastModifiedDate
FROM Products
WHERE LastModifiedDate > ${lastSyncDate.LastSyncDate}
]]>
</source>
</migration>
⚙️ 전처리/후처리 활용
마이그레이션 전후에 데이터 정리 및 검증을 수행하는 예제입니다.
<migration name="주문_이관">
<!-- 전처리: 기존 데이터 정리 -->
<preProcess db="targetDB">
<![CDATA[
DELETE FROM Orders WHERE OrderDate >= '2024-01-01'
]]>
</preProcess>
<source db="sourceDB">
<![CDATA[SELECT * FROM Orders WHERE OrderDate >= '2024-01-01']]>
</source>
<target db="targetDB" table="Orders" />
<!-- 후처리: 인덱스 재생성 및 통계 업데이트 -->
<postProcess db="targetDB">
<![CDATA[
CREATE INDEX IX_Orders_OrderDate ON Orders(OrderDate)
UPDATE STATISTICS Orders
]]>
</postProcess>
</migration>
🔧 문제 해결
❌ 연결 오류
문제: 데이터베이스 연결에 실패합니다.
해결:
- config/dbinfo.json 파일의 연결 정보 확인
- SQL Server 서비스가 실행 중인지 확인
- 방화벽 설정 확인
- 사용자 권한 확인
⏱️ 타임아웃 오류
문제: 쿼리 실행 중 타임아웃이 발생합니다.
해결:
- global 설정에서 timeout 값 증가
- 배치 크기(batchSize) 감소
- 쿼리 최적화
- 인덱스 활용
🔄 중단 재시작 문제
문제: 중단된 마이그레이션 재시작이 실패합니다.
해결:
- 진행 상황 파일 확인
- 데이터베이스 상태 점검
- 로그 파일 분석
- --resume 옵션 사용
📊 메모리 부족
문제: 대용량 데이터 처리 시 메모리 부족 오류가 발생합니다.
해결:
- 배치 크기 감소
- 쿼리 최적화
- 인덱스 활용
- 시스템 리소스 확인
❓ 자주 묻는 질문
Q: SQL2DB는 어떤 데이터베이스를 지원하나요?
+A: 현재 Microsoft SQL Server 2012 이상을 지원합니다. 소스와 타겟 모두 SQL Server여야 합니다.
Q: 대용량 데이터 처리 시 성능은 어떻게 되나요?
+A: 배치 처리와 실시간 모니터링을 통해 대용량 데이터도 효율적으로 처리할 수 있습니다. 배치 크기를 조정하여 메모리 사용량을 제어할 수 있습니다.
Q: 마이그레이션 중 오류가 발생하면 어떻게 하나요?
+A: 중단 재시작 기능을 사용하여 완료된 지점에서 마이그레이션을 재개할 수 있습니다. --resume 옵션을 사용하면 됩니다.
Q: 실시간 모니터링은 어떻게 사용하나요?
+A: 마이그레이션 실행 시 자동으로 모니터링 화면이 표시됩니다. 키보드 인터랙션을 통해 진행 상황을 실시간으로 확인할 수 있습니다.
Q: 동적 변수는 어떤 용도로 사용하나요?
+A: 실행 시점에 데이터베이스에서 값을 추출하여 마이그레이션 조건이나 컬럼 값으로 활용할 수 있습니다. 예를 들어, 마지막 동기화 날짜를 기준으로 증분 마이그레이션을 수행할 수 있습니다.