📖 사용자 매뉴얼

SQL2DB 사용자 매뉴얼

설치부터 고급 기능까지 SQL2DB의 모든 기능을 상세히 다루는 완전한 가이드

🎯 개요

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의 새로운 기능

🧱

모듈 일관성 및 타입 안정성

모듈 간 일관성 개선과 타입 안정성 향상으로 더 견고한 마이그레이션 실행.

🎛️

전역 컬럼 오버라이드 선택 적용 강화

실제 사용되는 컬럼만 정확히 적용되도록 선택 로직을 강화했습니다.

🔠

대소문자 무시 컬럼 매칭 개선

컬럼명 매칭 시 대소문자 차이로 인한 오류를 줄이도록 매칭 로직을 개선했습니다.

📊
소스 DB
⚙️
SQL2DB
🎯
타겟 DB

🛠️ 설치 및 설정

1

시스템 요구사항

독립 실행 파일 사용자용

  • Windows 7 이상 (64비트)
  • SQL Server 2012 이상 (소스/타겟)
  • 적절한 데이터베이스 권한
  • Node.js 설치 불필요

Node.js 소스 사용자용 (개발자)

  • Node.js 14.0 이상 (18.x 권장)
  • npm 6.0 이상
  • SQL Server 2012 이상 (소스/타겟)
  • 적절한 데이터베이스 권한
2

설치 방법

옵션 1: 독립 실행 파일 (권장)

bash
# 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 소스 (개발자용)

bash
# 저장소 클론
git clone https://github.com/happysoft2018/sql2db.git
cd sql2db

# 의존성 설치
npm install

# 실행
npm start              # 영문
npm run start:kr       # 한글
3

데이터베이스 설정

config/dbinfo.json 파일을 생성하고 데이터베이스 연결 정보를 설정합니다:

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 명령어 기본 사용법

설정 검증

bash
node src/migrate-cli.js validate --query ./queries/migration-queries.xml

데이터베이스 목록 조회

bash
node src/migrate-cli.js list-dbs

데이터 이관 실행

bash
node src/migrate-cli.js migrate --query ./queries/migration-queries.xml

시뮬레이션 실행 (DRY RUN)

bash
node src/migrate-cli.js migrate --query ./queries/migration-queries.xml --dry-run

비대화형 실행 (app.js --mode)

대화형 메뉴 없이 app.js --mode로 바로 실행합니다. Node/배포 EXE 모두에서 동작합니다.

bash
# 설정 검증
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

중단된 마이그레이션 재시작

bash
node src/migrate-cli.js migrate --query ./queries/migration-queries.xml --resume

XML 설정 파일 구조

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 스크립트를 실행하여 데이터 정리 및 검증을 수행합니다.

  • 데이터 정리 스크립트
  • 검증 및 검사
  • 인덱스 관리
  • 통계 업데이트
🎯

컬럼 오버라이드

마이그레이션 시 특정 컬럼의 값을 변경하거나 추가할 수 있습니다.

  • 기본값 설정
  • 동적 값 할당
  • 데이터 변환
  • 메타데이터 추가
📈

배치 처리 최적화

대용량 데이터를 효율적으로 처리하기 위한 배치 단위 처리 시스템을 제공합니다.

  • 메모리 효율성
  • 성능 최적화
  • 트랜잭션 관리
  • 오류 처리

📋 실용 예제

📊 사용자 데이터 이관

사용자 테이블의 데이터를 소스에서 타겟으로 이관하는 기본 예제입니다.

xml
<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>

🔄 동적 변수 활용

실행 시점에 데이터를 추출하여 마이그레이션 조건으로 활용하는 예제입니다.

xml
<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>

⚙️ 전처리/후처리 활용

마이그레이션 전후에 데이터 정리 및 검증을 수행하는 예제입니다.

xml
<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: 실행 시점에 데이터베이스에서 값을 추출하여 마이그레이션 조건이나 컬럼 값으로 활용할 수 있습니다. 예를 들어, 마지막 동기화 날짜를 기준으로 증분 마이그레이션을 수행할 수 있습니다.

📞 지원 및 문의

📧

이메일 지원

기술적인 문제나 문의사항이 있으시면 이메일로 연락해주세요.

이메일 보내기
🐛

이슈 리포트

버그 발견이나 기능 요청은 GitHub 이슈를 통해 알려주세요.

이슈 등록
📚

문서 및 예제

더 자세한 정보와 예제는 GitHub 저장소에서 확인하세요.

GitHub 방문