Scrambling Guide¶

개요¶

Datatrans Scrambling은 Target assignment YAML의 column과 rule_define.yaml에 등록된 Python domain을 연결합니다.

웹 콘솔에서는 작업의 스크램블링에서 YAML·표로 규칙을 편집하고 합성 표본으로 테스트할 수 있습니다. 관리자 전용 규칙 관리는 Python 코드 편집·구문 검사·테스트·버전 관리를 제공합니다. 아래는 CLI와 YAML의 공통 규칙입니다.

1. 원본값을 그대로 반환하지 않는 Python 함수를 작성합니다.
2. 함수를 rule_define.yaml의 domain으로 등록합니다.
3. 실제 Target OWNER.TABLE 기준 assignment를 작성합니다.
4. scrambles=FILE[,FILE...]로 실행합니다.

1. Python plugin 작성¶

Plugin은 신뢰할 수 있는 관리 경로에 보관합니다. 다음 예시는 입력 token을 결과나 오류에 포함하지 않고 완전히 새로운 값을 반환합니다.

# $DATATRANS_HOME/rules/custom_rules.py
import secrets

def synthetic_name(_original_name):
    return f"USER_{secrets.token_hex(8).upper()}"

def synthetic_email(_original_email):
    return f"user_{secrets.token_hex(8)}@example.invalid"

def synthetic_identity(_name, _email):
    token = secrets.token_hex(8).upper()
    return (f"USER_{token}", f"user_{token.lower()}@example.invalid")

Multi-column rule은 columns 수와 정확히 같은 개수의 list 또는 tuple을 반환해야 합니다. 단일 값으로 부족한 column을 원본으로 유지하는 동작은 허용되는 fallback이 아닙니다.

2. Domain 등록¶

현재 문서에서 사용하는 rule_define.yaml의 형식은 다음 domains mapping입니다.

domains:
  SC_NAME:
    file: $DATATRANS_HOME/rules/custom_rules.py
    function: synthetic_name
    description: 합성 이름 생성
  SC_EMAIL:
    file: $DATATRANS_HOME/rules/custom_rules.py
    function: synthetic_email
    description: 합성 이메일 생성
  SC_IDENTITY:
    file: $DATATRANS_HOME/rules/custom_rules.py
    function: synthetic_identity
    description: 합성 이름과 이메일 생성

Assignment의 rules에는 Python 함수명이 아니라 SC_NAME 같은 domain 이름을 씁니다. 위 파일·함수는 예제용이며 기존 기본 규칙을 덮어쓰는 설치 명령이 아닙니다. 현재 registry의 domains 아래에 파일·함수·설명을 등록합니다. UI용 입출력 명세를 제공하면 콘솔에서 인자와 결과 안내를 표시할 수 있습니다.

3. 스크램블링 규칙에 스크램블링 도메인을 적용¶

Assignment 최상위 key는 실제 Target OWNER.TABLE과 일치해야 하며 대소문자를 구분하지 않습니다.

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

TGT_USER.CUSTOMER_PROFILE:
  - columns: DISPLAY_NAME,CONTACT_EMAIL
    rules: SC_IDENTITY
    args: DISPLAY_NAME,CONTACT_EMAIL

필드¶

UNIQUE와 CONSISTENT를 동시에 지정하는 것은 권고 문제가 아니라 INVALID_SET_COMBINATION 오류입니다. 다른 값은 UNKNOWN_SET 오류입니다.

NULL과 함수 인자¶

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

TGT_USER.CUSTOMER_PROFILE:
  - columns: DISPLAY_NAME,CONTACT_EMAIL
    rules: SC_IDENTITY
    args: [DISPLAY_NAME, null]

첫 규칙은 함수에 Python None을 전달합니다. 두 번째 규칙은 현재 DISPLAY_NAME 값과 None을 순서대로 전달합니다. 이 예제는 위에서 등록한 함수와 출력 개수가 일치합니다.

• args를 생략하면 출력 컬럼의 현재 값을 입력으로 읽습니다. args: null은 생략과 다릅니다.
• args: "NULL"은 NULL 리터럴이 아닌 컬럼명입니다.
• 추가 인자도 컬럼에서 읽습니다. args에 문자열 옵션을 쓰면 상수 대신 해당 이름의 컬럼을 찾습니다.
• 여러 규칙을 순서대로 적용하면 각 단계에서 현재 행을 다시 읽습니다. 별도 입력 컬럼을 지정했다면 앞 단계 출력이 자동으로 다음 함수 입력이 되지는 않습니다.

UNIQUE와 CONSISTENT의 보장 범위¶

CONSISTENT의 기준은 args가 아니라 columns의 변환 전 원본 값입니다. Mapping이 있으면 Mapping 후 전송 행의 해당 컬럼 값을 사용합니다. 앞선 스크램블링이 행을 바꿔도 처음의 원본 기준을 유지합니다.

같은 작업·같은 규칙에서는 테이블명·컬럼명이 달라도 같은 원본 값에 같은 결과를 사용합니다. 여러 출력 컬럼은 지정 순서의 값 조합이 기준입니다. 따라서 args: null이어도 원본 A, B, A는 결과 X, Y, X로 연결할 수 있습니다. 원본 자체가 NULL인 행들은 같은 원본으로 취급됩니다.

CONSISTENT는 서로 다른 원본의 출력 중복도 거부합니다. 결과 공간이 작거나 고정값만 생성하는 함수는 충돌 오류가 발생할 수 있습니다. 보장은 해당 작업의 저장소 범위이며 별도 실행 간 공통 결과, Target의 기존 데이터·자료형 변환·제약조건까지 대신 보장하지 않습니다.

4. Target coverage와 routing¶

Scrambling은 CLI에서 선택된 Target과 assignment를 비교합니다.

• 선택된 Target에 assignment가 있으면 해당 rule을 적용합니다.
• 선택됐지만 assignment가 없는 Target은 UNSCRAMBLED_TABLE INFO로 표시되고 평문 그대로 이관됩니다. Warning이나 Error가 아니므로 실행 전에 반드시 확인합니다.
• Assignment에만 있고 이번 작업에서 선택되지 않은 Target은 UNUSED_ASSIGNMENT Warning 후 사용하지 않습니다.
• 여러 파일의 같은 Target 정의는 입력 순서대로 병합되고 MERGED_TARGET INFO로 표시됩니다.
• Mapping 작업에서는 mapping YAML의 target.owner와 target.table_name이 실제 Target입니다.

예를 들어 Source SRC_USER.CUSTOMER가 일반 전송에서 접속 사용자의 TGT_USER.CUSTOMER로 적재된다면 assignment key도 TGT_USER.CUSTOMER여야 합니다.

5. 실행¶

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

여러 assignment 파일은 쉼표로 한 번에 지정합니다.

scrambles=/secure/rules/customer.yaml,/secure/rules/profile.yaml

6. Parsing과 preflight¶

아래는 CLI 도움말과 현재 사전 검증 동작을 기준으로 정리한 parsing·preflight 안내입니다. 설치본의 SCRAMBLING_PREFLIGHT_GUIDE.md에서 안내하는 주요 결과도 함께 설명합니다.

Scrambling Rule Parsing¶

Assignment YAML을 읽고 같은 Target 정의를 입력 순서대로 병합합니다.

SCRAMBLING PREFLIGHT¶

병합된 규칙을 실제 선택 Target과 DB metadata에 비교합니다.

요약 항목¶

Selected tables = Covered tables + Uncovered tables

INFO와 Warning¶

오류 코드¶

7. Runtime 오류와 commit 경계¶

Plugin 실행 또는 output cardinality 오류가 발생하면 다음과 같이 fail closed로 처리합니다.

• 해당 Target table을 중단합니다.
• 실패한 데이터를 스크램블링하지 않은 원본값으로 적재하지 않습니다.
• 같은 Target을 사용하는 다른 Mapping도 함께 중단합니다.
• 다른 Scrambling table과 assignment가 없는 table은 계속 처리합니다.
• 이미 commit된 이전 batch는 유지될 수 있습니다.
• 최종 상태는 COMPLETED_WITH_ERRORS이고 process exit code는 0입니다.
• 로그에는 Target, rule, column과 오류 유형만 표시하며 row 값은 기록하지 않습니다.
• Scrambling 저장소 무결성 오류는 전체 작업을 중단합니다.

따라서 exit code 0만으로 성공을 판단하지 말고 작업 상태와 preflight/runtime 오류를 함께 확인해야 합니다.

8. 운영 체크리스트¶

• Assignment key가 실제 Target OWNER.TABLE과 일치합니다.
• Uncovered tables와 모든 UNSCRAMBLED_TABLE을 검토했습니다.
• UNIQUE|CONSISTENT를 하나만 사용했습니다.
• Multi-column rule이 정확한 개수의 list|tuple을 반환합니다.
• Plugin과 오류 처리에 Source 원문을 반환하거나 기록하는 경로가 없습니다.
• Assignment 파일이 하나라도 잘못되면 전체 실행이 중단됨을 운영 절차에 반영했습니다.
• COMPLETED_WITH_ERRORS와 exit code 0의 조합을 모니터링합니다.