PostgreSQL to BigQuery 템플릿은 PostgreSQL 테이블의 데이터를 기존 BigQuery 테이블에 복사하는 일괄 파이프라인입니다. 이 파이프라인은 JDBC를 사용하여 PostgreSQL에 연결합니다. 보안 강화를 위해 Cloud KMS 키로 암호화된 Base64 인코딩 사용자 이름, 비밀번호 및 연결 문자열 매개변수와 함께 Cloud KMS 키를 전달할 수도 있습니다. 사용자 이름, 비밀번호, 연결 문자열 매개변수 암호화에 대한 자세한 내용은 Cloud KMS API 암호화 엔드포인트를 참조하세요.
파이프라인 요구사항
- 파이프라인을 실행하기 전에 BigQuery 테이블이 있어야 합니다.
- BigQuery 테이블에 호환 가능한 스키마가 있어야 합니다.
- 관계형 데이터베이스는 Dataflow가 실행되는 서브넷에서 액세스할 수 있어야 합니다.
템플릿 매개변수
필수 매개변수
- driverJars: 쉼표로 구분된 드라이버 JAR 파일 목록입니다. 예를 들면
gs://your-bucket/driver_jar1.jar,gs://your-bucket/driver_jar2.jar
입니다. - driverClassName: JDBC 드라이버 클래스 이름입니다. 예를 들면
com.mysql.jdbc.Driver
입니다. - connectionURL: JDBC 연결 URL 문자열입니다. 예를 들면
jdbc:mysql://some-host:3306/sampledb
입니다. 이 값을 Cloud KMS 키로 암호화된 Base64 인코딩 문자열로 전달할 수 있습니다. Base64로 인코딩된 문자열에서 공백 문자를 삭제하세요. Oracle RAC가 아닌 데이터베이스 연결 문자열(jdbc:oracle:thin:@some-host:<port>:<sid>
)과 Oracle RAC 데이터베이스 연결 문자열(jdbc:oracle:thin:@//some-host[:<port>]/<service_name>
)의 차이점에 유의하세요(예:jdbc:mysql://some-host:3306/sampledb
). - outputTable: BigQuery 출력 테이블 위치입니다. 예를 들면
<PROJECT_ID>:<DATASET_NAME>.<TABLE_NAME>
입니다. - bigQueryLoadingTemporaryDirectory: BigQuery 로드 프로세스를 위한 임시 디렉터리입니다. 예를 들면
gs://your-bucket/your-files/temp_dir
입니다.
선택적 매개변수
- connectionProperties: JDBC 연결에 사용할 속성 문자열입니다. 문자열 형식은
[propertyName=property;]*
여야 합니다. 자세한 내용은 MySQL 문서의 구성 속성(https://dev.mysql.com/doc/connector-j/8.1/en/connector-j-reference-configuration-properties.html)을 참조하세요. 예를 들면unicode=true;characterEncoding=UTF-8
입니다. - username: JDBC 연결에 사용할 사용자 이름입니다. 이 값을 Cloud KMS 키로 암호화된 Base64 인코딩 문자열로 전달할 수 있습니다. Base64로 인코딩된 문자열에서 공백 문자를 삭제하세요.
- password: JDBC 연결에 사용할 비밀번호입니다. 이 값을 Cloud KMS 키로 암호화된 Base64 인코딩 문자열로 전달할 수 있습니다. Base64로 인코딩된 문자열에서 공백 문자를 삭제하세요.
- query: 데이터를 추출하기 위해 소스에서 실행할 쿼리입니다. 일부 JDBC SQL 및 BigQuery 유형은 이름이 동일하지만 몇 가지 차이점이 있습니다. 유의해야 할 몇 가지 중요한 SQL -> BigQuery 유형 매핑은
DATETIME --> TIMESTAMP
입니다. 스키마가 일치하지 않으면 유형 변환이 필요할 수 있습니다. 예를 들면select * from sampledb.sample_table
입니다. - KMSEncryptionKey: 사용자 이름, 비밀번호, 연결 문자열을 복호화하는 데 사용할 Cloud KMS 암호화 키입니다. Cloud KMS 키를 전달할 때 사용자 이름, 비밀번호, 연결 문자열도 암호화해야 합니다. 예를 들면
projects/your-project/locations/global/keyRings/your-keyring/cryptoKeys/your-key
입니다. - useColumnAlias:
true
로 설정하면 파이프라인은 열 이름 대신 열 별칭 (AS
)을 사용하여 행을 BigQuery에 매핑합니다. 기본값은false
입니다. - isTruncate:
true
로 설정하면 BigQuery에 데이터를 로드하기 전에 파이프라인이 잘립니다. 기본값은false
이며, 이 경우 파이프라인이 데이터를 추가합니다. - partitionColumn: 이 매개변수가 선택적 매개변수로 정의된
table
이름과 함께 제공되는 경우, JdbcIO는 범위를 사용해서 동일한 테이블 (서브 쿼리)의 쿼리 인스턴스 여러 개를 실행하여 테이블을 병렬로 읽습니다. 현재Long
파티션 열만 지원됩니다. - table: 파티션을 사용할 때 읽을 테이블입니다. 이 매개변수는 괄호로 묶인 서브 쿼리도 허용합니다. 예를 들면
(select id, name from Person) as subq
입니다. - numPartitions: 파티션 수입니다. 이 값은 하한 및 상한과 함께 파티션 열을 균등하게 분할하는 데 사용되는 생성된
WHERE
절 표현식에 대한 파티션 스트라이드를 형성합니다. 입력이1
보다 작으면 숫자가1
로 설정됩니다. - lowerBound: 파티션 스키마에서 사용할 하한값입니다. 제공하지 않으면 이 값은 지원되는 유형에 대해 Apache Beam에서 자동으로 추론됩니다.
- upperBound: 파티션 스키마에서 사용할 상한값입니다. 제공하지 않으면 이 값은 지원되는 유형에 대해 Apache Beam에서 자동으로 추론됩니다.
- fetchSize: 데이터베이스에서 한 번에 가져올 행 수입니다. 파티션을 나눈 읽기에는 사용되지 않습니다. 기본값은 50000입니다.
- createDisposition: 사용할 BigQuery CreateDisposition입니다. 예를 들면
CREATE_IF_NEEDED
또는CREATE_NEVER
입니다. 기본값은 CREATE_NEVER입니다. - bigQuerySchemaPath: BigQuery JSON 스키마의 Cloud Storage 경로입니다.
createDisposition
가CREATE_IF_NEEDED
로 설정된 경우 이 매개변수를 지정해야 합니다. 예를 들면gs://your-bucket/your-schema.json
입니다. - disabledAlgorithms: 사용 중지할 쉼표로 구분된 알고리즘입니다. 이 값을
none
로 설정하면 알고리즘이 중지되지 않습니다. 기본적으로 중지된 알고리즘은 취약점 또는 성능 문제를 일으킬 수 있으므로 이 매개변수를 사용할 때는 주의해야 합니다. 예를 들면SSLv3, RC4
입니다. - extraFilesToStage: 작업자에 스테이징할 파일의 쉼표로 구분된 Cloud Storage 경로 또는 Secret Manager 보안 비밀입니다. 이러한 파일은 각 작업자의 /extra_files 디렉터리에 저장됩니다. 예를 들면
gs://<BUCKET_NAME>/file.txt,projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<VERSION_ID>
입니다. - useStorageWriteApi:
true
인 경우 파이프라인은 BigQuery Storage Write API (https://cloud.google.com/bigquery/docs/write-api)를 사용합니다. 기본값은false
입니다. 자세한 내용은 Storage Write API(https://beam.apache.org/documentation/io/built-in/google-bigquery/#storage-write-api) 사용을 참조하세요. - useStorageWriteApiAtLeastOnce: Storage Write API를 사용할 때 쓰기 시맨틱스를 지정합니다. 1회 이상 실행되는 시맨틱스(https://beam.apache.org/documentation/io/built-in/google-bigquery/#at-least-once-semantics)로 설정)를 사용하려면, 이 매개변수를
true
로 설정합니다. 1회만 실행되는 시맨틱스를 사용하려면 매개변수를false
로 설정합니다. 이 매개변수는useStorageWriteApi
가true
인 경우에만 적용됩니다. 기본값은false
입니다.
템플릿 실행
콘솔
- Dataflow 템플릿에서 작업 만들기 페이지로 이동합니다. 템플릿에서 작업 만들기로 이동
- 작업 이름 필드에 고유한 작업 이름을 입력합니다.
- (선택사항): 리전 엔드포인트의 드롭다운 메뉴에서 값을 선택합니다. 기본 리전은
us-central1
입니다.Dataflow 작업을 실행할 수 있는 리전 목록은 Dataflow 위치를 참조하세요.
- Dataflow 템플릿 드롭다운 메뉴에서 the PostgreSQL to BigQuery template을 선택합니다.
- 제공된 매개변수 필드에 매개변수 값을 입력합니다.
- 작업 실행을 클릭합니다.
gcloud
셸 또는 터미널에서 템플릿을 실행합니다.
gcloud dataflow flex-template run JOB_NAME \ --project=PROJECT_ID \ --region=REGION_NAME \ --template-file-gcs-location=gs://dataflow-templates-REGION_NAME/VERSION/flex/PostgreSQL_to_BigQuery \ --parameters \ connectionURL=JDBC_CONNECTION_URL,\ query=SOURCE_SQL_QUERY,\ outputTable=PROJECT_ID:DATASET.TABLE_NAME, bigQueryLoadingTemporaryDirectory=PATH_TO_TEMP_DIR_ON_GCS,\ connectionProperties=CONNECTION_PROPERTIES,\ username=CONNECTION_USERNAME,\ password=CONNECTION_PASSWORD,\ KMSEncryptionKey=KMS_ENCRYPTION_KEY
다음을 바꿉니다.
JOB_NAME
: 선택한 고유한 작업 이름VERSION
: 사용할 템플릿 버전다음 값을 사용할 수 있습니다.
latest
: 버킷의 날짜가 지정되지 않은 상위 폴더(gs://dataflow-templates-REGION_NAME/latest/)에서 사용할 수 있는 최신 버전의 템플릿을 사용합니다.- 버전 이름(예:
2023-09-12-00_RC00
): 버킷의 날짜가 지정된 해당 상위 폴더(gs://dataflow-templates-REGION_NAME/)에 중첩되어 있는 특정 버전의 템플릿을 사용합니다.
REGION_NAME
: Dataflow 작업을 배포할 리전(예:us-central1
)JDBC_CONNECTION_URL
: JDBC 연결 URLSOURCE_SQL_QUERY
: 소스 데이터베이스에서 실행할 SQL 쿼리DATASET
: BigQuery 데이터 세트TABLE_NAME
: BigQuery 테이블 이름PATH_TO_TEMP_DIR_ON_GCS
: 임시 디렉터리의 Cloud Storage 경로CONNECTION_PROPERTIES
: JDBC 연결 속성(필요한 경우)CONNECTION_USERNAME
: JDBC 연결 사용자 이름CONNECTION_PASSWORD
: JDBC 연결 비밀번호KMS_ENCRYPTION_KEY
: Cloud KMS 암호화 키
API
REST API를 사용하여 템플릿을 실행하려면 HTTP POST 요청을 전송합니다. API 및 승인 범위에 대한 자세한 내용은 projects.templates.launch
를 참조하세요.
POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch { "launchParameter": { "jobName": "JOB_NAME", "containerSpecGcsPath": "gs://dataflow-templates-LOCATION/VERSION/flex/PostgreSQL_to_BigQuery" "parameters": { "connectionURL": "JDBC_CONNECTION_URL", "query": "SOURCE_SQL_QUERY", "outputTable": "PROJECT_ID:DATASET.TABLE_NAME", "bigQueryLoadingTemporaryDirectory": "PATH_TO_TEMP_DIR_ON_GCS", "connectionProperties": "CONNECTION_PROPERTIES", "username": "CONNECTION_USERNAME", "password": "CONNECTION_PASSWORD", "KMSEncryptionKey":"KMS_ENCRYPTION_KEY" }, "environment": { "zone": "us-central1-f" } } }
다음을 바꿉니다.
PROJECT_ID
: Dataflow 작업을 실행하려는 Google Cloud 프로젝트 IDJOB_NAME
: 선택한 고유한 작업 이름VERSION
: 사용할 템플릿 버전다음 값을 사용할 수 있습니다.
latest
: 버킷의 날짜가 지정되지 않은 상위 폴더(gs://dataflow-templates-REGION_NAME/latest/)에서 사용할 수 있는 최신 버전의 템플릿을 사용합니다.- 버전 이름(예:
2023-09-12-00_RC00
): 버킷의 날짜가 지정된 해당 상위 폴더(gs://dataflow-templates-REGION_NAME/)에 중첩되어 있는 특정 버전의 템플릿을 사용합니다.
LOCATION
: Dataflow 작업을 배포할 리전(예:us-central1
)JDBC_CONNECTION_URL
: JDBC 연결 URLSOURCE_SQL_QUERY
: 소스 데이터베이스에서 실행할 SQL 쿼리DATASET
: BigQuery 데이터 세트TABLE_NAME
: BigQuery 테이블 이름PATH_TO_TEMP_DIR_ON_GCS
: 임시 디렉터리의 Cloud Storage 경로CONNECTION_PROPERTIES
: JDBC 연결 속성(필요한 경우)CONNECTION_USERNAME
: JDBC 연결 사용자 이름CONNECTION_PASSWORD
: JDBC 연결 비밀번호KMS_ENCRYPTION_KEY
: Cloud KMS 암호화 키
다음 단계
- Dataflow 템플릿 알아보기
- Google 제공 템플릿 목록 참조