PostgreSQL 데이터 소스 설정
PostgreSQL 데이터 소스는 오프라인 동기화를 통해 PostgreSQL 테이블 또는 쿼리 결과를 플랫폼의 기본 스토리지로 읽거나 기본 스토리지의 워크스페이스 테이블을 PostgreSQL에 쓰는 데 사용됩니다. 이 문서에서는 연결 설정, 소스 및 목적지 설정, 필드 매핑, 지원하는 필드 타입, 동기화 검증과 워크플로우 스케줄을 설명합니다.
사용 제한 및 사전 준비
설정을 시작하기 전에 다음 사항을 확인하십시오.
- PostgreSQL → 기본 스토리지 및 기본 스토리지 → PostgreSQL을 지원하며, 이 계획을 통한 PostgreSQL과 다른 외부 데이터 소스 간의 직접 동기화는 지원하지 않습니다.
- PostgreSQL 서버 주소, 포트, 데이터베이스 이름과 연동에 사용할 사용자 이름 및 비밀번호를 준비합니다. 플랫폼 실행 환경에서 해당 주소에 접근할 수 있어야 하며, 데이터베이스 연결 접근 제어와 네트워크 허용 목록에서 플랫폼 서버의 연결을 허용해야 합니다.
- 읽기 계정에는 데이터베이스에 연결하고 해당 schema에 접근하며 선택한 테이블, 뷰 또는 쿼리에 포함된 데이터를 읽을 수 있는 권한이 있어야 합니다. 쓰기 계정에는 선택한 쓰기 모드에 해당하는 타겟 테이블 권한도 필요합니다. 데이터베이스 관리자가 실제 작업 범위에 맞게 권한을 부여해야 합니다. PostgreSQL 권한 설명을 참조하십시오.
- 타겟 테이블을 미리 준비하고 필드 타입, NOT NULL 제약 조건 및 기본 키를 확인합니다. 기본 스토리지로 읽어 오는 경우 생성 방법은 워크스페이스 테이블 생성 및 관리를 참조하십시오. PostgreSQL에 쓰는 경우에는 타겟 데이터베이스와 schema가 이미 존재하는지도 확인해야 합니다.
| 환경 설정 방식 | 설정 요구 사항 |
|---|---|
| 환경 구분 없음 | 개발 환경과 운영 환경에서 데이터베이스 및 자격 증명 설정 한 세트를 공유 |
| 독립 환경 설정 | 개발 환경과 운영 환경을 각각 설정. 두 설정 모두 계획에서 선택한 데이터베이스, schema 및 테이블에 접근할 수 있어야 함 |
데이터 미리보기에는 개발 환경 설정을 사용하고 수동 실행에는 운영 환경 설정을 사용합니다. 두 설정의 데이터베이스, 테이블 권한 및 네트워크 접근을 각각 확인하십시오.
비밀번호는 안전한 방법으로 전달하고 스크린샷, 로그 또는 공개 문서에 자격 증명이 노출되지 않도록 하십시오. 자격 증명을 교체하거나 권한을 조정한 후에는 데이터 소스 연결 및 동기화 계획을 다시 검증해야 합니다.
PostgreSQL 데이터 소스 생성
- 데이터 개발 플랫폼 > 통합 > 데이터 소스로 이동하여 + 데이터 소스를 클릭합니다.
- PostgreSQL을 선택하고 다음 단계를 클릭한 후 데이터 소스 이름과 비고를 입력합니다.
- 환경 구분 없음 또는 독립 환경 설정을 선택합니다. 독립 환경 설정에서는 개발 환경과 운영 환경의 정보를 각각 입력해야 합니다.
- 다음 연결 파라미터를 입력합니다. 연결 테스트에서 테스트를 클릭하고 테스트를 통과했는지 확인한 후 완료를 클릭합니다.
| 구성 항목 | 설명 |
|---|---|
| 연결 문자열 | PostgreSQL JDBC 연결 주소. 형식 예시는 jdbc:postgresql://<host>:<port>/<database>입니다. 자리 표시자를 실제 주소, 포트 및 데이터베이스로 바꾸십시오. 연결 파라미터 설명은 pgJDBC 연결 설정을 참조하십시오 |
| 데이터베이스 | 연결 테스트에 사용할 PostgreSQL 데이터베이스 이름. 연결 주소 및 계정 권한과 일치해야 하며, schema가 아닌 데이터베이스를 입력해야 함 |
| 사용자 이름 | 데이터베이스 및 관련 테이블에 접근할 권한이 있는 계정 |
| 비밀번호 | 사용자 이름에 해당하는 비밀번호 |
| 고급 설정 | 필요에 따라 JSON 형식의 확장 연결 파라미터를 입력. 추가 설정이 필요하지 않으면 비워 둘 수 있음 |
PostgreSQL의 데이터베이스와 schema는 서로 다른 계층입니다. 동기화 계획을 설정할 때 먼저 데이터베이스를 선택한 후 데이터 테이블이 속한 schema를 확인하여 다른 schema에 있는 같은 이름의 테이블을 선택하지 않도록 하십시오.
연결 테스트를 통과한 후에도 동기화 계획에서 테이블을 로드하고 데이터를 미리 본 후 실행하여 검증해야 합니다. 테이블 권한과 실제 읽기 및 쓰기 결과를 확인하십시오.
PostgreSQL 소스 설정
- 데이터 개발 플랫폼 > 통합 > 오프라인 동기화로 이동하여 + 통합 방안을 클릭합니다.
- 데이터 소스에서 PostgreSQL과 생성한 데이터 소스를 선택합니다.
- 데이터 가져오기 방식을 선택하고 다음 설명에 따라 읽기 범위를 설정합니다.
- 데이터 미리보기를 클릭하여 필드, 실제 값 및 읽기 범위를 확인합니다.
- 배치별로 처리할 데이터 양을 조정하려면 고급 설정을 펼쳐 일괄 건수를 설정합니다.
그림은 기존 계획의 설정 예시이며 현재 연결 및 데이터 읽기 검증을 대신하지 않습니다. 설정을 완료한 후 데이터 미리보기를 사용하여 실제 결과를 확인하십시오.
| 데이터 가져오기 방식 | 설정 요구 사항 |
|---|---|
| 전체 테이블 | 데이터베이스와 데이터 테이블을 선택하고 테이블이 속한 schema를 확인. 필요에 따라 샤딩 키를 선택하거나 데이터 필터링을 켜고 WHERE로 시작하는 필터 조건을 입력할 수 있음 |
| 사용자 정의 쿼리 | 데이터베이스를 선택하고 데이터를 읽을 SQL을 입력. 필드 표현이나 읽기 범위를 처리해야 하는 경우 쿼리에 명시해야 함. SQL이 참조하는 schema, 테이블 및 결과 필드 이름을 확인하고 데이터를 수정하는 문장은 실행하지 않아야 함 |
| 구성 항목 | 설명 |
|---|---|
| 데이터 소스 이름 | 현재 워크스페이스에 생성된 PostgreSQL 데이터 소스 |
| 데이터베이스 및 데이터 테이블 | 전체 테이블 방식에서는 읽을 데이터베이스와 테이블을 선택. 사용자 정의 쿼리 방식에서는 데이터베이스를 선택하고 SQL을 입력 |
| 샤딩 키 | 전체 테이블 방식의 선택 항목. 선택 가능한 필드 타입은 int2, int4, int8이며 뷰에서는 샤딩 키 설정을 지원하지 않음 |
| 데이터 필터링 | 전체 테이블 방식에서 필요에 따라 켜고 WHERE 조건으로 읽기 범위를 제한. 끄면 이 필터 조건은 적용되지 않음 |
| 일괄 건수 | 고급 설정 항목. 화면 기본값은 1000이며 설정 가능한 범위는 1000–50000 |
데이터 소스, 데이터베이스, 소스 테이블 또는 쿼리를 변경한 후에는 읽기 범위, 샤딩 키, 미리보기 결과 및 필드 매핑을 다시 확인하십시오. 소스 테이블의 필드를 추가, 삭제 또는 수정한 후에도 필드를 다시 분석하고 매핑을 확인해야 합니다. 계획에서 워크스페이스 파라미터를 사용하는 경우 파라미터 관리를 참조하고 실행 시 실제 파라미터 값을 확인하십시오.
데이터 목적지 설정
PostgreSQL에서 기본 스토리지로 읽기
데이터 목적지에서 플랫폼의 기본 스토리지를 선택한 후 타겟 워크스페이스 테이블을 선택합니다. 타겟 테이블이 아직 없으면 먼저 테이블로 이동하여 필요한 필드 및 파티션 정의에 따라 생성하십시오. 워크스페이스 테이블 생성 및 관리를 참조하십시오.
| 구성 항목 | 설명 |
|---|---|
| 타겟 테이블 | 이번 PostgreSQL 데이터를 받을 기본 스토리지의 워크스페이스 테이블 |
| 파티션 정보 | 타겟이 파티션 테이블이면 타겟 테이블 요구 사항에 맞게 파티션 값을 설정 |
| 쓰기 모드 | 새 데이터 삽입 또는 덮어쓰기를 선택. 화면 기본 선택은 덮어쓰기이며 타겟 데이터의 보존 요구 사항에 따라 조정하십시오 |
실행 전에 타겟 테이블, 타겟 파티션 및 쓰기 모드를 다시 확인하여 보존해야 할 데이터를 덮어쓰지 않도록 하십시오.
기본 스토리지에서 PostgreSQL로 쓰기
데이터 소스에서 읽을 기본 스토리지의 워크스페이스 테이블을 선택합니다. 데이터 목적지에서 PostgreSQL과 생성한 데이터 소스를 선택한 후 타겟 데이터베이스 및 데이터 테이블을 선택합니다. 타겟 테이블이 속한 schema를 확인하십시오. schema를 지정하지 않으면 public을 사용하며 누락된 schema는 자동으로 생성되지 않습니다.
| 구성 항목 | 설명 |
|---|---|
| 쓰기 테이블 | 데이터를 받을 PostgreSQL 데이터베이스 및 데이터 테이블. 전체 schema와 테이블 이름을 확인해야 함 |
| 쓰기 모드 | 다음 표의 세 가지 모드를 지원하며 화면 기본 선택은 덮어쓰기임 |
| 일괄 건수 | 고급 설정 항목. 화면 기본값은 1000이며 설정 가능한 범위는 1000–10000 |
| 쓰기 모드 | 동작 및 설정 요구 사항 |
|---|---|
| 새 데이터 삽입 | 이번 데이터를 타겟 테이블에 추가. 기존 기본 키 또는 UNIQUE 제약 조건과 충돌하지 않는지 확인하십시오 |
| 덮어쓰기 | 타겟 테이블의 기존 데이터를 먼저 비운 후 이번 데이터를 씀. 실행 전에 비울 범위와 백업 요구 사항을 확인하고, 중간에 실패하면 기존 데이터가 자동으로 복원된다고 가정하지 않아야 함 |
| 업데이트 삽입 | 타겟 테이블의 실제 기본 키로 일치하는 레코드를 찾아 기존 레코드를 업데이트하고 새 레코드를 삽입. 타겟 테이블에는 일치 여부를 판단할 기본 키가 있어야 하며 기본 키 필드를 모두 매핑해야 함 |
소스 테이블과 타겟 테이블의 필드 이름은 서로 달라도 되지만 필드 매핑을 통해 대응 관계를 명확히 설정해야 합니다. PostgreSQL에 쓰기 전에는 타겟 필드의 길이, 정밀도, NOT NULL 및 기타 테이블 제약 조건도 확인해야 합니다.
필드 매핑 및 지원하는 필드 타입
소스와 목적지 설정을 완료한 후 필드 매핑에서 소스 필드와 타겟 필드의 대응 관계를 설정합니다. 필드를 개별적으로 선택하거나 동일 이름 매핑 또는 동일 행 매핑을 사용한 후 항목별로 확인할 수 있습니다. 하나의 타겟 필드는 하나의 소스 필드에만 대응할 수 있습니다.
그림은 기존 계획의 필드 대응 관계를 보여 주며, 현재 연결 및 실제 동기화 결과의 검증을 대신할 수 없습니다.
읽기를 지원하는 필드 타입
PostgreSQL을 데이터 소스로 사용할 때 다음 필드 타입을 지원합니다. 표에서는 필드 분석 결과의 타입 이름을 사용합니다.
| 타입 분류 | 지원하는 PostgreSQL 필드 타입 |
|---|---|
| 불리언 | bool |
| 정수 | int2, smallserial, int4, serial, int8, bigserial |
| 부동 소수점 및 고정 소수점 | float4, float8, numeric |
| 문자열 | bpchar, character, varchar, text |
| JSON, UUID 및 공간 타입 | json, jsonb, uuid, geometry, geography |
| 날짜 및 시간 | date, timestamp, timestamptz |
| 배열 | _bool, _bytea, _int2, _int4, _int8, _float4, _float8, _bpchar, _character, _varchar, _text |
bytea, time, timetz 및 기타 인식되지 않는 타입은 지원하지 않습니다. 배열은 위 표에 나열된 타입만 지원하며 _numeric, _date, _timestamp, _jsonb 등은 지원 범위에 포함되지 않습니다.
쓰기를 지원하는 필드 타입
PostgreSQL을 데이터 목적지로 사용할 때 지원하는 PostgreSQL 필드 타입은 위 표와 동일합니다. bytea, time, timetz, 목록에 없는 배열 타입 및 기타 인식되지 않는 타입은 지원하지 않습니다.
쓰기 전에 선택한 PostgreSQL 테이블의 필드 정의, 기본 키, NOT NULL 및 기타 제약 조건을 확인하십시오. 필드 타입이 지원되어도 JSON, UUID, 공간 타입 또는 배열 필드에 임의의 내용을 쓸 수 있다는 의미는 아닙니다.
필드 타입 사용 제한
- PostgreSQL 필드 분석 결과에 메타데이터 이름이 사용될 수 있습니다. 예를 들어
int2,int4,int8은 각각 일반적인smallint,integer,bigint에 해당하며,float4,float8은 각각real,double precision에 해당합니다. 실제 분석된 이름을 기준으로 하십시오. - 길이, 정밀도 또는 소수 자릿수가 있는 필드는 전체 정의를 확인해야 합니다. 시간 필드는 시간대와 정밀도 요구 사항도 확인해야 합니다.
- 배열은 요소 타입, 차원 및 NULL 요소에 대한 요구 사항을 확인해야 합니다.
_bytea가 지원 범위에 포함되어도 모든 바이너리 요소나 배열 구조가 검증되었다는 의미는 아닙니다. - 소스 또는 타겟 테이블의 구조가 변경되면 필드를 다시 분석하고 필드 대응 관계를 확인하십시오. 데이터 미리보기에 필드가 표시되어도 해당 필드 타입의 동기화가 지원된다는 의미는 아닙니다.
저장, 검증 및 워크플로우 스케줄
동기화 결과 저장 및 검증
- 소스 테이블 또는 SQL, 필터 조건, 타겟 테이블과 파티션, 쓰기 모드 및 필드 매핑을 확인합니다. PostgreSQL에 쓰는 경우 schema, 기본 키 및 테이블 제약 조건을 다시 확인합니다.
- 데이터 미리보기를 사용하여 소스 필드와 예시 값을 확인한 후 필드 매핑, 타겟 타입 및 타겟 테이블 제약 조건을 항목별로 확인합니다.
- 계획 이름, 담당자 및 비고를 입력하고 저장을 클릭합니다.
- 수동 실행을 클릭하고 대화 상자의 요구 사항에 따라 실행 모드를 선택한 후 이번 실행의 파라미터 값을 확인하고 실행을 시작합니다. 수동 실행에는 운영 환경 설정을 사용하며 실행 모드로 개발 환경과 운영 환경을 전환할 수는 없습니다.
- 수동 실행 기록에서 실행 상태와 로그를 확인합니다. 작업이 성공하면 타겟 테이블에서 데이터 건수, 필드 대응 관계 및 숫자, 시간, 배열, NULL 등의 예시 값을 확인합니다.
독립 환경 설정에서 개발 단계에 데이터를 정상적으로 로드하거나 미리 볼 수 있다고 해서 운영 환경의 자격 증명과 읽기 및 쓰기 권한도 갖추어진 것은 아닙니다. 최초 실행 전에 두 설정과 타겟 환경의 데이터베이스 및 테이블, 파티션, 파라미터를 각각 확인하십시오.
작업 플로우에 연결
수동 검증을 통과한 후 계획을 작업 플로우에 연결하여 스케줄링 주기에 따라 실행할 수 있습니다.
- 저장된 계획을 열고 워크플로우에 연결을 클릭하여 타겟 작업 플로우를 선택합니다. 아직 생성하지 않은 경우 작업 플로우 생성을 참조하십시오.
- 노드 이름, 실행 모드, 담당자 등의 정보를 입력하고 노드 생성 및 연결을 클릭합니다.
- 작업 플로우로 이동을 클릭하여 노드와 상위·하위 의존성을 확인하고 스케줄링에 사용할 데이터베이스 및 테이블, 필터 조건 및 워크스페이스 파라미터를 확인합니다.
- 작업 플로우 스케줄 설정을 완료하고 저장한 후 작업 플로우를 배포합니다. 연결에 성공했다고 해서 노드가 이미 배포되어 운영 중인 것은 아닙니다.
계획을 작업 플로우에 연결한 후에는 계획 상세 페이지에서 더 이상 수동 실행하지 않습니다. 작업 플로우에서 해당 노드를 실행하고 검증하십시오.
자주 묻는 질문
| 증상 | 확인 항목 |
|---|---|
| 연결 테스트 실패 | 연결 문자열, 데이터베이스, 사용자 이름 및 비밀번호, 플랫폼 서버의 네트워크 접근 및 데이터베이스 연결 접근 제어를 확인 |
| 연결은 가능하지만 테이블을 찾을 수 없거나 미리 볼 수 없음 | 선택한 데이터베이스, schema, 테이블 이름 및 계정의 읽기 권한을 확인. 사용자 정의 쿼리에서는 SQL과 참조 객체도 확인해야 함 |
| 뷰에서 샤딩 키를 선택할 수 없음 | 뷰에서는 샤딩 키 설정을 지원하지 않으므로 실제 뷰 또는 쿼리 범위에 따라 읽어야 함 |
| 미리보기는 정상이지만 실행 실패 | 운영 환경의 자격 증명, 읽기 및 쓰기 권한, 타겟 schema, 테이블 제약 조건, 쓰기 모드, 파티션 및 파라미터를 확인하고 이번 실행 로그를 확인 |

