Quick Start¶

Datatrans는 CLI와 웹 콘솔(UI) 모두에서 작업할 수 있습니다. 이 문서는 CLI 도움말과 현재 실행 동작을 기준으로 빠른 시작을 정리합니다. 예제의 접속 정보와 대상 범위를 실제 환경에 맞게 바꾸고 사용하세요.

웹 콘솔로 시작하기¶

서버의 설치 루트에서 콘솔을 기동합니다.

DATATRANS_HOME="$PWD" python/bin/python3 -m dashboard --host 0.0.0.0 --port 7501

브라우저에서 http://서버주소:7501에 접속한 뒤 다음 순서로 진행합니다.

최초 관리자를 등록하고 서버 라이선스·DB 연결을 확인합니다.
관리자가 작업용 사용자와 프로젝트를 만들고 생성·수정·실행 권한을 할당합니다.
사용자 계정으로 프로젝트에 작업을 만들고 테이블·매핑·스크램블링·병렬도를 설정합니다.
입력 검사와 DB Preview를 거쳐 실행하고 실행 모니터에서 결과를 확인합니다.
저장된 작업 버전을 재사용하거나 예약합니다. 실행 통제 프로젝트는 관리자 승인 절차를 따릅니다.

관리자는 관리·승인을 담당하고 실제 작업 생성·수정·실행은 사용자 계정으로 진행합니다. 파일 가져오기, 표 편집, 보고서와 예약은 웹 콘솔 가이드에 설명되어 있습니다.

1. 실행 문법¶

일반 실행, parfile 실행, 대화형 실행은 다음과 같습니다.

datatrans KEY=VALUE [KEY=VALUE ...]
python -m datatrans KEY=VALUE [KEY=VALUE ...]
datatrans parfile=/path/to/job.par
datatrans

파라미터 이름은 대소문자를 구분하지 않습니다.
문법은 KEY=VALUE이며 --option 형식은 사용하지 않습니다.
목록은 쉼표로 구분합니다. Y|N 파라미터에는 Y 또는 N만 씁니다.
같은 파라미터를 중복 지정하거나 정의되지 않은 파라미터를 사용하면 오류입니다.
공백이 포함된 값과 SQL은 큰따옴표로 묶는 것이 안전합니다.

datatrans help=Y
datatrans version=Y
datatrans activate=Y

2. 기본 TRANSFER¶

TRANSFER는 기본 모드입니다. source, target과 schemas|tables|mapping_rule 중 하나가 필요합니다. 일반 작업에서는 schemas와 tables 중 하나만 사용합니다.

스키마 전송¶

datatrans \
  source=SRC_USER/password@host:1521/SRCDB \
  target=TGT_USER/password@host:1521/TGTDB \
  schemas=SALES \
  degree=4 \
  jobname=SALES_TRANSFER

degree 기본값은 1, table_action 기본값은 APPEND입니다. Target 데이터 처리 방식은 다음 네 가지입니다.

값	동작
`APPEND`	기존 데이터를 유지하고 새 데이터를 추가합니다. 기본값입니다.
`TRUNCATE`	Target 구조를 유지하고 기존 데이터를 비운 뒤 적재합니다.
`REPLACE`	Source 정의를 기준으로 Target 테이블을 다시 생성하고 적재합니다.
`STRUCTURE`	Target 구조만 생성하고 데이터는 적재하지 않습니다.

특정 테이블과 조건¶

안전한 예제에서는 owner를 명시합니다. query는 WHERE 키워드를 제외한 신뢰된 Oracle SQL 조건식입니다.

datatrans \
  source=SRC_USER/password@host:1521/SRCDB \
  target=TGT_USER/password@host:1521/TGTDB \
  tables=HR.EMPLOYEES \
  query=HR.EMPLOYEES:"DEPARTMENT_ID = 90" \
  table_action=TRUNCATE \
  flashback_timestamp=2026-07-20T09:00:00+09:00 \
  jobname=HR_EMP_90

flashback_timestamp는 timezone을 포함한 ISO 8601 값이어야 하며 flashback_scn과 함께 사용할 수 없습니다. flashback_scn은 CURRENT(기본), INDIVIDUAL, OFF 또는 숫자 SCN을 받습니다.

일반 전송의 remap_schema, remap_tablespace, batcherrors, suffix 계약은 Execution Parameters에서 확인합니다.

3. Mapping 빠른 시작¶

현재 CLI 파라미터 이름은 mapping_rule입니다. YAML 최상위 키인 mappings:는 그대로 유지됩니다.

mappings:
  customer_mapping:
    source:
      owner: SRC_USER
      table_name: CUSTOMER
      condition: STATUS = 'ACTIVE'
    target:
      owner: TGT_USER
      table_name: CUSTOMER_COPY
    columns:
      - source_column: CUSTOMER_ID
        target_column: CUSTOMER_ID
      - conversion_rule: "FIRST_NAME || ' ' || LAST_NAME"
        target_column: FULL_NAME

datatrans \
  source=SRC_USER/password@host:1521/SRCDB \
  target=TGT_USER/password@host:1521/TGTDB \
  mapping_rule="/secure/mapping/*.yaml" \
  table_action=APPEND \
  jobname=CUSTOMER_MAPPING

배타 조건과 Target 조건

mapping_rule은 schemas, tables, query와 함께 사용할 수 없습니다.
Source와 Target routing은 YAML의 owner와 table_name이 직접 결정합니다.
Mapping은 이미 존재하며 호환되는 Target에 APPEND 또는 TRUNCATE로 적재할 때만 지원합니다.
REPLACE와 STRUCTURE는 Target DDL 전에 거부됩니다.

모든 glob pattern은 최소 하나의 일반 파일과 일치해야 합니다. Parsing 가능한 파일에서는 잘못된 entry를 제외하고 정상 entry를 계속 검사하며, metadata preflight를 통과한 mapping만 실행합니다. 자세한 상태·요약·오류 코드는 Data Mapping Guide를 참고하십시오.

4. Scrambling 빠른 시작¶

Assignment의 최상위 key는 실제 Target OWNER.TABLE이어야 합니다.

TGT_USER.CUSTOMER:
  - columns: CUSTOMER_NAME
    rules: SC_NAME
  - columns: EMAIL
    rules: SC_EMAIL
    args: EMAIL
    sets: CONSISTENT

datatrans \
  source=SRC_USER/password@host:1521/SRCDB \
  target=TGT_USER/password@host:1521/TGTDB \
  tables=SRC_USER.CUSTOMER \
  remap_schema=SRC_USER:TGT_USER \
  scrambles=/secure/rules/customer.yaml \
  table_action=APPEND \
  jobname=CUSTOMER_MASKED

columns는 결과를 저장할 Target column, rules는 rule_define.yaml의 domain 이름입니다.
args를 생략하면 columns가 함수 입력으로 사용됩니다.
args: null은 Python None을 전달하며 args: [COLUMN, null]처럼 혼합할 수 있습니다. CONSISTENT의 일관성 기준은 args가 아닌 출력 컬럼의 스크램블링 전 원본 값입니다.
sets는 UNIQUE 또는 CONSISTENT이며 동시에 지정하면 오류입니다.
여러 결과 column을 쓰는 rule은 정확히 같은 개수의 list 또는 tuple을 반환해야 합니다.
선택된 Target에 assignment가 없으면 UNSCRAMBLED_TABLE INFO와 함께 평문 그대로 이관됩니다.
assignment 파일 하나라도 접근·UTF-8·YAML parsing에 실패하면 일부 규칙만 적용하지 않고 전체 작업을 preflight 전에 중단합니다.

Runtime plugin 또는 결과 개수 오류가 발생하면 해당 Target과 같은 Target을 쓰는 다른 Mapping도 중단하며, 실패 row를 원본으로 대신 적재하지 않습니다. 이미 commit된 batch는 남을 수 있고 최종 상태는 COMPLETED_WITH_ERRORS, process exit code는 0입니다. 자세한 내용은 Scrambling Guide를 참고하십시오.

5. PREVIEW 빠른 시작¶

PREVIEW는 Target DML 없이 일부 Source row의 적재 호환성을 검증합니다. 선택적으로 매핑·스크램블링 전 원본의 민감정보 후보를 탐색할 수 있습니다. 전체 DB로 범위를 확대하거나 데이터를 자동 마스킹하지는 않습니다.

datatrans \
  source=SRC_USER/password@host:1521/SRCDB \
  target=TGT_USER/password@host:1521/TGTDB \
  tables=HR.EMPLOYEES \
  mode=PREVIEW \
  jobname=HR_PREVIEW

기존 {JOBNAME}.md 보고서는 계속 생성됩니다. 신규 실행은 Dashboard History에서 table·column별 결과를 확인할 수 있습니다.

원본 민감정보 탐색을 함께 하려면 위 명령에 다음 옵션을 추가합니다.

privacy_check=Y
privacy_entities=RRN,PHONE,EMAIL,ACCOUNT,CARD,PERSON,ADDRESS

privacy_check의 기본값은 N입니다. 유형을 생략하면 지원하는 12개 유형 전체를 검사합니다. CLI는 범위별 기본 100행을 사용하며 preview_rows는 CLI 옵션이 아닙니다. UI/API에서는 1~10,000행을 설정할 수 있습니다.

보고서에 원본 값을 저장하지 않으며, 미탐지가 전체 테이블에 민감정보가 없음을 보장하지 않습니다. 지원 유형·자료형·부분 검사·오류 상태는 Preview 가이드를 확인하세요.

outcome	의미
`PASSED`	조회 sample에서 위반을 발견하지 못했습니다.
`VIOLATIONS`	조회 sample에서 하나 이상의 column 위반을 발견했습니다.
`NOT_EVALUATED`	조회 row가 없어 데이터 검증을 판정하지 못했습니다.
`INCOMPLETE`	Metadata, 조회 또는 변환 오류로 검증이 완전하지 않습니다.

VIOLATIONS와 NOT_EVALUATED 자체는 실행 오류가 아닙니다. 다른 실행 오류가 없으면 작업 상태는 COMPLETED입니다. 원본 민감정보 탐색 오류 등은 최종 작업 상태에 별도로 반영됩니다.

6. TRIGGER 빠른 시작¶

TRIGGER는 모드를 반드시 명시하고 다음 값을 모두 지정합니다.

source, target, repository
working_target_query, completed_target_query
schemas|tables|mapping_rule 중 하나

datatrans \
  source=SRC_USER/password@host:1521/SRCDB \
  target=TGT_USER/password@host:1521/TGTDB \
  schemas=SALES \
  mode=TRIGGER \
  repository=REPO_USER/password@host:1521/REPODB \
  completed_target_query="SELECT OWNER,TABLE_NAME FROM MIG_TARGETS" \
  working_target_query="SELECT OWNER,TABLE_NAME FROM MIG_READY" \
  polling_frequency=3 \
  jobname=SALES_TRIGGER

두 query는 Repository를 변경하지 않는 읽기 전용 조회입니다. 결과는 OWNER, TABLE_NAME 두 column 또는 'OWNER.TABLE' 한 column이어야 합니다. polling_frequency는 양의 정수이고 기본값은 3초입니다. 준비되지 않은 테이블은 임의로 건너뛰거나 timeout 처리하지 않습니다.

7. Parfile¶

# /job/sales.par
source=SRC_USER/password@host:1521/SRCDB
target=TGT_USER/password@host:1521/TGTDB
schemas=SALES
degree=4
table_action=APPEND
batcherrors=Y # 공백 뒤 인라인 주석

datatrans parfile=/job/sales.par jobname=SALES_TRANSFER

우선순위

같은 key가 CLI와 parfile에 모두 있으면 parfile 값이 적용됩니다. 공통 parfile에서 실행마다 달라질 jobname을 빼거나, 작업별 parfile에 정확한 이름을 넣으십시오.

줄 시작 #와 공백 뒤 #부터 줄 끝까지는 주석입니다. -- SQL 주석은 parfile 주석이 아닙니다.
parfile 안의 또 다른 parfile은 재귀적으로 읽지 않습니다.
Trigger SQL처럼 공백이나 =가 있는 값은 한 줄에서 큰따옴표로 묶습니다.
CLI 인자 안이나 parfile 안에서 같은 파라미터를 반복하면 오류입니다. CLI와 parfile에 한 번씩 있는 같은 key에는 위의 parfile 우선 규칙을 적용합니다. 정의되지 않은 파라미터는 어느 위치에서든 오류입니다.

8. 상태 확인과 운영¶

Help에 문서화된 상태 조회는 대화형 모드에서 실행합니다.

$ datatrans
DATATRANS> JOB_LIST
DATATRANS> STATUS=SALES_TRANSFER
DATATRANS> STATUS=SALES_TRANSFER,3
DATATRANS> PROGRESS=SALES_TRANSFER
DATATRANS> CONTINUE_JOB=SALES_TRANSFER
DATATRANS:SALES_TRANSFER> PROGRESS_WATCH,3

STOP_JOB은 일시 정지, 연결된 작업에서의 START_JOB은 재개, KILL_JOB은 강제 종료입니다. START_JOB=JOBNAME은 지원하지 않습니다.

9. 예약¶

schedule은 실제 datetime 또는 cron expression을 받으며 jobname이 필수입니다.

datatrans \
  source=SRC_USER/password@host:1521/SRCDB \
  target=TGT_USER/password@host:1521/TGTDB \
  schemas=SALES \
  schedule="2027-01-15 02:00:00+09:00" \
  jobname=SALES_ONCE

datatrans \
  source=SRC_USER/password@host:1521/SRCDB \
  target=TGT_USER/password@host:1521/TGTDB \
  schemas=SALES \
  schedule="0 2 * * *" \
  jobname=SALES_NIGHTLY

schedule=ONCE 또는 schedule=CRON은 올바른 값이 아닙니다.

일회 날짜는 실제 미래 시각으로 바꾸세요. 예약 기동은 systemd 사용자 timer/service가 담당하며 운영 계정의 사용자 서비스와 linger 설정이 필요합니다. Cron은 5필드 표현식을 사용합니다. 콘솔에서는 저장된 작업 버전, 반복 기준 시간대와 선택적 만료날짜도 지정할 수 있습니다. 준비·조회·기존 예약 이행은 작업 예약을 참고하세요.

10. 첫 실행 체크리스트¶

Source/Target 접속과 실제 owner를 확인했습니다.
schemas|tables|mapping_rule의 배타 조건을 확인했습니다.
기본 APPEND가 맞는지, 또는 TRUNCATE|REPLACE|STRUCTURE가 필요한지 확인했습니다.
Mapping이면 기존 compatible Target과 APPEND|TRUNCATE만 사용했습니다.
Scrambling preflight의 Uncovered tables와 UNSCRAMBLED_TABLE을 확인했습니다.
query, mapping expression, Repository query는 신뢰된 관리자 입력입니다.
실제 접속 정보가 있는 parfile·mapping·scrambling 파일의 권한을 제한했습니다.
로그와 Preview 보고서에 Source row 원문이나 개인정보를 추가로 기록하지 않습니다.