본문으로 건너뛰기

PostgreSQL 데이터 소스 설정

최근 업데이트 2026. 11. 03.

PostgreSQL 데이터 소스는 오프라인 동기화를 통해 PostgreSQL 테이블 또는 쿼리 결과를 플랫폼의 기본 스토리지로 읽거나 기본 스토리지의 워크스페이스 테이블을 PostgreSQL에 쓰는 데 사용됩니다. 이 문서에서는 연결 설정, 소스 및 목적지 설정, 필드 매핑, 지원하는 필드 타입, 동기화 검증과 워크플로우 스케줄을 설명합니다.

사용 제한 및 사전 준비​

설정을 시작하기 전에 다음 사항을 확인하십시오.

  • PostgreSQL → 기본 스토리지 및 기본 스토리지 → PostgreSQL을 지원하며, 이 계획을 통한 PostgreSQL과 다른 외부 데이터 소스 간의 직접 동기화는 지원하지 않습니다.
  • PostgreSQL 서버 주소, 포트, 데이터베이스 이름과 연동에 사용할 사용자 이름 및 비밀번호를 준비합니다. 플랫폼 실행 환경에서 해당 주소에 접근할 수 있어야 하며, 데이터베이스 연결 접근 제어와 네트워크 허용 목록에서 플랫폼 서버의 연결을 허용해야 합니다.
  • 읽기 계정에는 데이터베이스에 연결하고 해당 schema에 접근하며 선택한 테이블, 뷰 또는 쿼리에 포함된 데이터를 읽을 수 있는 권한이 있어야 합니다. 쓰기 계정에는 선택한 쓰기 모드에 해당하는 타겟 테이블 권한도 필요합니다. 데이터베이스 관리자가 실제 작업 범위에 맞게 권한을 부여해야 합니다. PostgreSQL 권한 설명을 참조하십시오.
  • 타겟 테이블을 미리 준비하고 필드 타입, NOT NULL 제약 조건 및 기본 키를 확인합니다. 기본 스토리지로 읽어 오는 경우 생성 방법은 워크스페이스 테이블 생성 및 관리를 참조하십시오. PostgreSQL에 쓰는 경우에는 타겟 데이터베이스와 schema가 이미 존재하는지도 확인해야 합니다.
환경 설정 방식설정 요구 사항
환경 구분 없음개발 환경과 운영 환경에서 데이터베이스 및 자격 증명 설정 한 세트를 공유
독립 환경 설정개발 환경과 운영 환경을 각각 설정. 두 설정 모두 계획에서 선택한 데이터베이스, schema 및 테이블에 접근할 수 있어야 함

데이터 미리보기에는 개발 환경 설정을 사용하고 수동 실행에는 운영 환경 설정을 사용합니다. 두 설정의 데이터베이스, 테이블 권한 및 네트워크 접근을 각각 확인하십시오.

비밀번호는 안전한 방법으로 전달하고 스크린샷, 로그 또는 공개 문서에 자격 증명이 노출되지 않도록 하십시오. 자격 증명을 교체하거나 권한을 조정한 후에는 데이터 소스 연결 및 동기화 계획을 다시 검증해야 합니다.

PostgreSQL 데이터 소스 생성​

  1. 데이터 개발 플랫폼 > 통합 > 데이터 소스로 이동하여 + 데이터 소스를 클릭합니다.
  2. PostgreSQL을 선택하고 다음 단계를 클릭한 후 데이터 소스 이름과 비고를 입력합니다.
  3. 환경 구분 없음 또는 독립 환경 설정을 선택합니다. 독립 환경 설정에서는 개발 환경과 운영 환경의 정보를 각각 입력해야 합니다.
  4. 다음 연결 파라미터를 입력합니다. 연결 테스트에서 테스트를 클릭하고 테스트를 통과했는지 확인한 후 완료를 클릭합니다.
PostgreSQL 연결 문자열, 데이터베이스 및 접근 자격 증명 설정
구성 항목설명
연결 문자열PostgreSQL JDBC 연결 주소. 형식 예시는 jdbc:postgresql://<host>:<port>/<database>입니다. 자리 표시자를 실제 주소, 포트 및 데이터베이스로 바꾸십시오. 연결 파라미터 설명은 pgJDBC 연결 설정을 참조하십시오
데이터베이스연결 테스트에 사용할 PostgreSQL 데이터베이스 이름. 연결 주소 및 계정 권한과 일치해야 하며, schema가 아닌 데이터베이스를 입력해야 함
사용자 이름데이터베이스 및 관련 테이블에 접근할 권한이 있는 계정
비밀번호사용자 이름에 해당하는 비밀번호
고급 설정필요에 따라 JSON 형식의 확장 연결 파라미터를 입력. 추가 설정이 필요하지 않으면 비워 둘 수 있음

PostgreSQL의 데이터베이스와 schema는 서로 다른 계층입니다. 동기화 계획을 설정할 때 먼저 데이터베이스를 선택한 후 데이터 테이블이 속한 schema를 확인하여 다른 schema에 있는 같은 이름의 테이블을 선택하지 않도록 하십시오.

연결 테스트를 통과한 후에도 동기화 계획에서 테이블을 로드하고 데이터를 미리 본 후 실행하여 검증해야 합니다. 테이블 권한과 실제 읽기 및 쓰기 결과를 확인하십시오.

PostgreSQL 소스 설정​

  1. 데이터 개발 플랫폼 > 통합 > 오프라인 동기화로 이동하여 + 통합 방안을 클릭합니다.
  2. 데이터 소스에서 PostgreSQL과 생성한 데이터 소스를 선택합니다.
  3. 데이터 가져오기 방식을 선택하고 다음 설명에 따라 읽기 범위를 설정합니다.
  4. 데이터 미리보기를 클릭하여 필드, 실제 값 및 읽기 범위를 확인합니다.
  5. 배치별로 처리할 데이터 양을 조정하려면 고급 설정을 펼쳐 일괄 건수를 설정합니다.
기존 계획 설정의 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을 데이터 소스로 사용할 때 다음 필드 타입을 지원합니다. 표에서는 필드 분석 결과의 타입 이름을 사용합니다.

타입 분류지원하는 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가 지원 범위에 포함되어도 모든 바이너리 요소나 배열 구조가 검증되었다는 의미는 아닙니다.
  • 소스 또는 타겟 테이블의 구조가 변경되면 필드를 다시 분석하고 필드 대응 관계를 확인하십시오. 데이터 미리보기에 필드가 표시되어도 해당 필드 타입의 동기화가 지원된다는 의미는 아닙니다.

저장, 검증 및 워크플로우 스케줄​

동기화 결과 저장 및 검증​

  1. 소스 테이블 또는 SQL, 필터 조건, 타겟 테이블과 파티션, 쓰기 모드 및 필드 매핑을 확인합니다. PostgreSQL에 쓰는 경우 schema, 기본 키 및 테이블 제약 조건을 다시 확인합니다.
  2. 데이터 미리보기를 사용하여 소스 필드와 예시 값을 확인한 후 필드 매핑, 타겟 타입 및 타겟 테이블 제약 조건을 항목별로 확인합니다.
  3. 계획 이름, 담당자 및 비고를 입력하고 저장을 클릭합니다.
  4. 수동 실행을 클릭하고 대화 상자의 요구 사항에 따라 실행 모드를 선택한 후 이번 실행의 파라미터 값을 확인하고 실행을 시작합니다. 수동 실행에는 운영 환경 설정을 사용하며 실행 모드로 개발 환경과 운영 환경을 전환할 수는 없습니다.
  5. 수동 실행 기록에서 실행 상태와 로그를 확인합니다. 작업이 성공하면 타겟 테이블에서 데이터 건수, 필드 대응 관계 및 숫자, 시간, 배열, NULL 등의 예시 값을 확인합니다.

독립 환경 설정에서 개발 단계에 데이터를 정상적으로 로드하거나 미리 볼 수 있다고 해서 운영 환경의 자격 증명과 읽기 및 쓰기 권한도 갖추어진 것은 아닙니다. 최초 실행 전에 두 설정과 타겟 환경의 데이터베이스 및 테이블, 파티션, 파라미터를 각각 확인하십시오.

작업 플로우에 연결​

수동 검증을 통과한 후 계획을 작업 플로우에 연결하여 스케줄링 주기에 따라 실행할 수 있습니다.

  1. 저장된 계획을 열고 워크플로우에 연결을 클릭하여 타겟 작업 플로우를 선택합니다. 아직 생성하지 않은 경우 작업 플로우 생성을 참조하십시오.
  2. 노드 이름, 실행 모드, 담당자 등의 정보를 입력하고 노드 생성 및 연결을 클릭합니다.
  3. 작업 플로우로 이동을 클릭하여 노드와 상위·하위 의존성을 확인하고 스케줄링에 사용할 데이터베이스 및 테이블, 필터 조건 및 워크스페이스 파라미터를 확인합니다.
  4. 작업 플로우 스케줄 설정을 완료하고 저장한 후 작업 플로우를 배포합니다. 연결에 성공했다고 해서 노드가 이미 배포되어 운영 중인 것은 아닙니다.

계획을 작업 플로우에 연결한 후에는 계획 상세 페이지에서 더 이상 수동 실행하지 않습니다. 작업 플로우에서 해당 노드를 실행하고 검증하십시오.

자주 묻는 질문​

증상확인 항목
연결 테스트 실패연결 문자열, 데이터베이스, 사용자 이름 및 비밀번호, 플랫폼 서버의 네트워크 접근 및 데이터베이스 연결 접근 제어를 확인
연결은 가능하지만 테이블을 찾을 수 없거나 미리 볼 수 없음선택한 데이터베이스, schema, 테이블 이름 및 계정의 읽기 권한을 확인. 사용자 정의 쿼리에서는 SQL과 참조 객체도 확인해야 함
뷰에서 샤딩 키를 선택할 수 없음뷰에서는 샤딩 키 설정을 지원하지 않으므로 실제 뷰 또는 쿼리 범위에 따라 읽어야 함
미리보기는 정상이지만 실행 실패운영 환경의 자격 증명, 읽기 및 쓰기 권한, 타겟 schema, 테이블 제약 조건, 쓰기 모드, 파티션 및 파라미터를 확인하고 이번 실행 로그를 확인
이 문서가 도움이 되었나요?