PostgreSQL 데이터를 BigQuery에 로드

PostgreSQL에서 BigQuery로 반복 데이터 전송을 예약하려면 전송할 데이터 객체와 데이터 전송을 예약할 빈도를 지정하는 전송 구성을 만들면 됩니다. 전송 구성을 설정하면 BigQuery Data Transfer Service가 지정된 일정에 따라 최신 데이터를 BigQuery 테이블로 전송합니다.

구성 옵션을 비롯한 PostgreSQL 전송에 대한 일반적인 내용은 PostgreSQL 데이터 전송 소개를 참조하세요.

제한사항

PostgreSQL 데이터 전송에는 다음과 같은 제한사항이 적용됩니다.

  • 단일 PostgreSQL 데이터베이스에 대한 최대 동시 전송 실행 수는 PostgreSQL 데이터베이스에서 지원하는 최대 동시 연결 수에 따라 결정됩니다. 동시 전송 작업 수는 PostgreSQL 데이터베이스에서 지원하는 최대 동시 연결 수보다 작은 값으로 제한해야 합니다.

  • 단일 전송 구성은 지정된 시간에 하나의 데이터 전송 실행만 지원할 수 있습니다. 첫 번째 전송이 완료되기 전에 두 번째 데이터 전송이 실행되도록 예약된 경우 첫 번째 데이터 전송만 완료되고 첫 번째 전송과 겹치는 다른 데이터 전송은 건너뜁니다.

    단일 전송 구성 내에서 전송이 건너뛰는 것을 방지하려면 반복 빈도를 구성하여 대규모 데이터 전송 간의 시간을 늘리는 것이 좋습니다.

  • 데이터 전송 중에 PostgreSQL 커넥터는 색인이 생성된 파티션을 나눈 키 열을 식별하여 데이터를 병렬 일괄 처리로 전송합니다. 따라서 테이블에서 기본 키 열을 지정하거나 색인이 생성된 열을 사용하여 데이터 전송의 성능을 개선하고 오류율을 줄이는 것이 좋습니다. 다음 사항을 고려하세요.

    • 색인이 생성된 제약조건 또는 기본 키 제약조건이 있는 경우 병렬 일괄 처리를 만드는 데 다음 열 유형만 지원됩니다.
      • INTEGER
      • TINYINT
      • SMALLINT
      • FLOAT
      • REAL
      • DOUBLE
      • NUMERIC
      • BIGINT
      • DECIMAL
      • DATE
    • 기본 키 또는 색인이 생성된 열을 사용하지 않는 PostgreSQL 데이터 전송은 테이블당 2,000,000개 이상의 레코드를 지원할 수 없습니다.

증분 전송 제한사항

증분 PostgreSQL 전송에는 다음과 같은 제한사항이 적용됩니다.

  • TIMESTAMP 열만 워터마크 열로 선택할 수 있습니다.
  • 증분 수집은 유효한 워터마크 열이 있는 애셋에만 지원됩니다.
  • 워터마크 열의 값은 단조 증가해야 합니다.
  • 증분 전송은 소스 테이블에서 삭제 작업을 동기화할 수 없습니다.
  • 단일 전송 구성은 증분 수집 또는 전체 수집만 지원할 수 있습니다.
  • 첫 번째 증분 수집 실행 후에는 asset 목록에서 객체를 업데이트할 수 없습니다.
  • 첫 번째 증분 수집 실행 후에는 전송 구성에서 쓰기 모드를 변경할 수 없습니다.
  • 첫 번째 증분 수집 실행 후에는 워터마크 열 또는 기본 키를 변경할 수 없습니다.
  • 대상 BigQuery 테이블은 제공된 기본 키를 사용하여 클러스터링되며 클러스터링된 테이블 제한사항이 적용됩니다.

  • 기존 전송 구성을 처음으로 증분 수집 모드로 업데이트하면 업데이트 후 첫 번째 데이터 전송에서 데이터 소스의 사용 가능한 모든 데이터를 전송합니다. 이후의 증분 데이터 전송은 데이터 소스의 신규 및 업데이트된 행만 전송합니다.

  • 워터마크 열에 색인을 만드는 것이 좋습니다. 이 커넥터는 증분 전송의 필터에 워터마크 열을 사용하므로 이러한 열에 색인을 생성하면 성능을 개선할 수 있습니다.

  • 증분 전송을 실행할 때는 업데이트된 데이터 유형 매핑을 사용해야 합니다.

시작하기 전에

필요한 역할

Pub/Sub의 전송 실행 알림을 설정하려면 pubsub.topics.setIamPolicy Identity and Access Management(IAM) 권한이 있어야 합니다. 이메일 알림만 설정한다면 Pub/Sub 권한이 필요하지 않습니다. 자세한 내용은 BigQuery Data Transfer Service 실행 알림을 참조하세요.

BigQuery Data Transfer Service 데이터 전송을 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 BigQuery 관리자 (roles/bigquery.admin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 BigQuery Data Transfer Service 데이터 전송을 만드는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

BigQuery Data Transfer Service 데이터 전송을 만들려면 다음 권한이 필요합니다.

  • BigQuery Data Transfer Service 권한:
    • bigquery.transfers.update
    • bigquery.transfers.get
  • BigQuery 권한:
    • bigquery.datasets.get
    • bigquery.datasets.getIamPolicy
    • bigquery.datasets.update
    • bigquery.datasets.setIamPolicy
    • bigquery.jobs.create

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

자세한 내용은 액세스 권한 부여를 참조하세요.bigquery.admin

네트워크 연결

PostgreSQL 데이터베이스 연결에 공개 IP 주소를 사용할 수 없는 경우 네트워크 연결을 설정해야 합니다 .

필요한 네트워크 설정에 관한 자세한 안내는 다음 문서를 참조하세요.

PostgreSQL 데이터 전송 설정

다음 옵션 중 하나를 사용하여 전송 구성을 설정하여 BigQuery에 PostgreSQL 데이터를 추가합니다.

콘솔

  1. 데이터 전송 페이지로 이동합니다.

    데이터 전송으로 이동

  2. 전송 만들기를 클릭합니다.

  3. 소스 유형 섹션의 소스에 PostgreSQL을 선택합니다.

  4. 데이터 소스 세부정보 섹션에서 다음을 수행합니다.

    • 네트워크 연결의 경우 기존 네트워크 연결을 선택하거나 네트워크 연결 만들기를 클릭합니다. 자세한 내용은 이 문서의 네트워크 연결 섹션을 참조하세요.
    • 호스트에 PostgreSQL 데이터베이스 서버의 호스트 이름 또는 IP 주소를 입력합니다.
    • 포트 번호에 PostgreSQL 데이터베이스 서버의 포트 번호를 입력합니다.
    • 데이터베이스 이름에 PostgreSQL 데이터베이스의 이름을 입력합니다.
    • 사용자 이름에 PostgreSQL 데이터베이스 연결을 시작하는 PostgreSQL 사용자 의 사용자 이름을 입력합니다.
    • 비밀번호에 PostgreSQL 데이터베이스 연결을 시작하는 PostgreSQL 사용자의 비밀번호를 입력합니다.
    • TLS 모드의 메뉴에서 옵션을 선택합니다. TLS 모드에 관한 자세한 내용은 TLS 구성을 참고하세요.
    • 신뢰할 수 있는 PEM 인증서에 데이터베이스 서버의 TLS 인증서를 발급한 인증 기관(CA)의 공개 인증서를 입력합니다. 자세한 내용은 신뢰할 수 있는 서버 인증서 (PEM)를 참고하세요.
    • **레거시 매핑 사용 설정** 에서 레거시 데이터 유형 매핑을 사용하려면 **true**(기본값)를 선택합니다. 업데이트된 데이터 유형 매핑을 사용하려면 false 를 선택합니다. 증분 전송을 실행하는 경우 이 값은 false 여야 합니다. 데이터 유형 매핑 업데이트에 관한 자세한 내용은 2027년 3월 16일 데이터베이스 서버를 참고하세요.
    • 수집 유형에서 전체 또는 증분을 선택합니다.
      • 증분(프리뷰)을 선택한 경우 쓰기 모드에서 추가 또는 삽입/업데이트(upsert)를 선택합니다. 다양한 쓰기 모드에 관한 자세한 내용은 전체 또는 증분 전송을 참고하세요.

    • **전송할 PostgreSQL 객체** 에서 **찾아보기** 를 클릭합니다.

      BigQuery 대상 데이터 세트로 전송할 객체를 선택합니다. 데이터 전송에 포함할 객체를 이 필드에 직접 입력할 수도 있습니다.

      • 증분 쓰기 모드로 추가를 선택한 경우 열을 워터마크 열로 선택해야 합니다.
      • 삽입/업데이트(upsert) 를 증분 쓰기 모드로 선택한 경우 열을 워터마크 열로 선택한 다음 하나 이상의 열을 기본 키로 선택해야 합니다.

  5. 전송 구성 이름 섹션의 표시 이름에 전송 이름을 입력합니다. 전송 이름은 나중에 수정해야 할 경우를 대비해 간편하게 전송을 식별할 수 있는 값이면 됩니다.

  6. 일정 옵션 섹션에서 다음을 수행합니다.

    • 반복 빈도를 선택합니다. 시간, 일 (기본값), 주 또는 월 옵션을 선택하면 빈도도 지정해야 합니다. 커스텀 옵션을 선택하여 더 구체적인 반복 빈도를 만들 수도 있습니다. 주문형 옵션을 선택한 경우 수동으로 전송을 트리거하면 이 데이터 전송만 실행됩니다 .
    • 해당하는 경우 지금 시작 또는 설정 시간에 시작 옵션을 선택하고 시작 날짜와 실행 시간을 입력하세요.

  7. 대상 설정 섹션의 데이터 세트에서 데이터를 저장하기 위해 만든 데이터 세트를 선택하거나 새 데이터 세트 만들기 를 클릭하여 대상 데이터 세트로 사용할 데이터 세트를 만듭니다.

  8. 선택사항: 알림 옵션 섹션에서 다음을 수행합니다.

  9. 저장을 클릭합니다.

bq

bq mk 명령어를 입력하고 전송 생성 플래그 --transfer_config를 지정합니다.

bq mk
    --transfer_config
    --project_id=PROJECT_ID
    --data_source=DATA_SOURCE
    --display_name=DISPLAY_NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

다음을 바꿉니다.

  • PROJECT_ID(선택사항): Google Cloud 프로젝트 ID. 특정 프로젝트를 지정하는 --project_id 플래그가 입력되지 않으면 기본 프로젝트가 사용됩니다.
  • DATA_SOURCE: 데이터 소스(postgresql)
  • DISPLAY_NAME: 데이터 전송 구성의 표시 이름. 전송 이름은 나중에 수정해야 할 경우를 대비해 간편하게 전송을 식별할 수 있는 값이면 됩니다.
  • DATASET. 데이터 전송 구성의 대상 데이터 세트

  • PARAMETERS: JSON 형식으로 생성된 전송 구성의 매개변수. 예를 들면 --params='{"param":"param_value"}'입니다. 다음은 PostgreSQL 전송의 매개변수입니다.

    • connector.networkAttachment(선택사항): PostgreSQL 데이터베이스에 연결할 네트워크 연결의 이름
    • connector.database: PostgreSQL 데이터베이스의 이름
    • connector.endpoint.host: 데이터베이스 서버의 호스트 이름 또는 IP 주소
    • connector.endpoint.port: 데이터베이스의 포트 번호
    • connector.authentication.username: 데이터베이스 사용자의 사용자 이름
    • connector.authentication.password: 데이터베이스 사용자의 비밀번호
    • connector.tls.mode: 이 전송에 사용할 TLS 구성을 지정합니다.
      • ENCRYPT_VERIFY_CA_AND_HOST: 데이터 암호화, CA 및 호스트 이름 확인
      • ENCRYPT_VERIFY_CA: 데이터 암호화, CA만 확인
      • ENCRYPT_VERIFY_NONE: 데이터 암호화만
      • DISABLE: 암호화 또는 확인 없음
    • connector.tls.trustedServerCertificate: (선택사항) 하나 이상의 PEM 인코딩 인증서를 제공합니다. connector.tls.mode이 ENCRYPT_VERIFY_CA_AND_HOST 또는 ENCRYPT_VERIFY_CA인 경우에만 필요합니다.
    • ingestionType: full 또는 incremental을 지정합니다. 증분 전송은 프리뷰에서 지원됩니다. 자세한 내용은 전체 또는 증분 전송을 참조하세요.
    • writeMode: WRITE_MODE_APPEND 또는 WRITE_MODE_UPSERT를 지정합니다.
    • watermarkColumns: 테이블의 열을 워터마크 열로 지정합니다. 이 필드는 증분 전송에 필요합니다.
    • primaryKeys: 테이블의 열을 기본 키로 지정합니다. 이 필드는 증분 전송에 필요합니다.
    • connector.legacyMapping: 레거시 데이터 유형 매핑을 사용하려면 true (기본값)로 설정합니다. 업데이트된 데이터 유형 매핑을 사용하려면 false로 설정합니다. 증분 전송을 실행하는 경우 이 값은 false여야 합니다. 데이터 유형 매핑 업데이트에 관한 자세한 내용은 2027년 3월 16일 을 참고하세요.
    • assets: 전송의 일부로 PostgreSQL 데이터베이스에서 전송할 PostgreSQL 테이블 이름 목록.

예를 들어 다음 명령어는 My Transfer라는 PostgreSQL 전송을 만듭니다.

bq mk
    --transfer_config
    --target_dataset=mydataset
    --data_source=postgresql
    --display_name='My Transfer'
    --params='{"assets":["DB1/PUBLIC/DEPARTMENT","DB1/PUBLIC/EMPLOYEES"],
        "connector.authentication.username": "User1",
        "connector.authentication.password":"ABC12345",
        "connector.database":"DB1",
        "connector.endpoint.host":"192.168.0.1",
        "connector.endpoint.port":5432,
        "ingestionType":"incremental",
        "writeMode":"WRITE_MODE_APPEND",
        "watermarkColumns":["createdAt","createdAt"],
        "primaryKeys":[['dep_id'], ['report_by','report_title']],
        "connector.tls.mode": "ENCRYPT_VERIFY_CA_AND_HOST",
        "connector.tls.trustedServerCertificate": "PEM-encoded certificate"}'

증분 전송 중에 여러 애셋을 지정하면 watermarkColumns 및 primaryKeys 필드의 값은 assets 필드의 값 위치에 해당합니다. 다음 예에서 dep_id는 테이블 DB1/USER1/DEPARTMENT에 해당하고 report_by 및 report_title은 테이블 DB1/USER1/EMPLOYEES에 해당합니다.

      "primaryKeys":[['dep_id'], ['report_by','report_title']],
      "assets":["DB1/USER1/DEPARTMENT","DB1/USER1/EMPLOYEES"],

API

projects.locations.transferConfigs.create 메서드 를 사용하고 TransferConfig 리소스의 인스턴스를 지정합니다.

전송 구성을 저장하면 PostgreSQL 커넥터가 일정 옵션에 따라 전송 실행을 자동으로 트리거합니다. 전송 실행마다 PostgreSQL 커넥터는 PostgreSQL의 사용 가능한 모든 데이터를 BigQuery로 전송합니다.

정기 일정 외에 데이터 전송을 수동으로 실행하려면 백필 실행을 시작하면 됩니다.

문제 해결

데이터 전송을 설정하는 데 문제가 있으면 PostgreSQL 전송 문제를 참조하세요.

메타데이터 전송

PostgreSQL 커넥터를 사용하여 메타데이터를 Knowledge Catalog 로 전송할 수도 있습니다. 자세한 내용은 PostgreSQL 메타데이터를 Knowledge Catalog에 로드를 참조하세요.

다음 단계