BigQuery 및 Iceberg 데이터를 AlloyDB에 동기화

이 페이지에서는 PostgreSQL용 AlloyDB의 Lakehouse Federation을 사용하여 BigQuery 기본 테이블, 구체화된 뷰, BigQuery 뷰, BigLake 외부 테이블 (예: Apache Iceberg 관리 테이블), 표준 외부 테이블의 데이터를 동기화하는 방법을 설명합니다. Iceberg는 데이터를 관리하고 교환하기 위한 개방형 테이블 형식입니다.

이 페이지에서는 AlloyDB 클러스터 및 기본 인스턴스가 있고 BigQuery 데이터 세트와 테이블이 있다고 가정합니다. 자세한 내용은 데이터 세트 만들기 및 테이블 만들기 및 사용을 참조하세요.

시작하기 전에

  1. AlloyDB 인스턴스에서 bigquery_fdw.enabled 플래그가 구성되어 있는지 확인합니다.
  2. 지원되는 BigQuery 데이터 유형 및 열 매핑에 대해 알아봅니다.
  3. Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

    10.

  10. PostgreSQL용 AlloyDB를 만들고 여기에 연결하는 데 필요한 Cloud API를 사용 설정합니다.

    API 사용 설정

  11. 프로젝트 확인 단계에서 다음을 클릭하여 변경할 프로젝트의 이름을 확인합니다.

  12. API 사용 설정 단계에서 사용 설정을 클릭하여 다음을 사용 설정합니다.

    • AlloyDB API
    • Compute Engine API
    • Cloud Resource Manager API
    • Service Networking API
    • BigQuery Storage API

    AlloyDB와 동일한 Google Cloud 프로젝트에 있는 VPC 네트워크를 사용하여 AlloyDB에 대한 네트워크 연결을 구성하려면 Service Networking API가 필요합니다.

    다른 Google Cloud 프로젝트에 있는 VPC 네트워크를 사용하여 AlloyDB에 대한 네트워크 연결을 구성하려면 Compute Engine API와 Cloud Resource Manager API가 필요합니다.

필요한 역할

AlloyDB 클러스터 서비스 계정에 BigQuery 데이터 세트에 대한 읽기 액세스 권한을 부여하려면 다음 권한이 필요합니다.

  • BigQuery 데이터 뷰어(roles/bigquery.dataViewer) 또는 bigquery.tables.get 및 bigquery.tables.getData 권한아 있는 커스텀 역할. 테이블 또는 뷰에 부여되면 이 역할은 테이블 또는 뷰에서 데이터와 메타데이터를 읽을 수 있는 권한을 제공합니다.
  • BigQuery 읽기 세션 사용자(roles/bigquery.readSessionUser) 또는 bigquery.readsessions.create 및 bigquery.readsessions.getData 권한이 있는 커스텀 역할. 읽기 세션을 만들고 사용할 수 있는 기능을 제공합니다.

BigQuery 데이터 세트에 AlloyDB 액세스 권한 부여

AlloyDB 클러스터에서 레이크하우스 제휴 기능이 사용 설정된 후 AlloyDB 클러스터 서비스 계정에 BigQuery 데이터 세트에 대한 액세스 권한을 부여합니다.

gcloud CLI를 사용하려면 Google Cloud CLI를 설치 및 초기화하거나 Cloud Shell을 사용합니다.

  1. gcloud CLI를 엽니다. gcloud CLI가 설치되어 있지 않으면 gcloud CLI를 설치 및 초기화하거나 Cloud Shell을 사용합니다.

  2. gcloud beta alloydb clusters describe 명령어를 실행합니다.

    gcloud beta alloydb clusters describe CLUSTER --region=REGION

    다음을 바꿉니다.

    • CLUSTER: AlloyDB 클러스터 ID
    • REGION: AlloyDB 클러스터의 위치(예: asia-east1, us-east1). 인스턴스 위치 관리에서 전체 리전 목록을 확인합니다.

    출력에는 이 클러스터의 서비스 계정인 serviceAccountEmail 필드가 포함됩니다. 클러스터 세부정보 페이지에서도 서비스 계정을 확인할 수 있습니다.

  3. 필수 권한 부여 자세한 내용은 IAM으로 리소스 액세스 제어를 참조하세요.

    클러스터 서비스 계정에 필요한 권한이 없으면 BigQuery 테이블에 대해 쿼리를 실행할 때 다음 오류가 표시됩니다.

    • The user does not have bigquery.readsessions.create permissions
    • Permission bigquery.tables.get denied on table
    • Permission bigquery.tables.getData denied on table

확장 프로그램 구성

  1. 확장 프로그램을 만듭니다.

    1. 인스턴스에 psql 클라이언트 연결의 안내에 따라 psql 클라이언트를 사용하여 AlloyDB 인스턴스에 연결합니다. 또는 AlloyDB Studio를 사용할 수 있습니다. 자세한 내용은 Google Cloud 콘솔을 사용하여 데이터 관리를 참고하세요.

    2. 다음 명령어를 실행합니다.

      CREATE EXTENSION bigquery_fdw;

  2. 원격 BigQuery 데이터 세트의 연결 파라미터를 정의하는 외부 서버를 만듭니다.

    CREATE SERVER BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw;

    다음을 바꿉니다.

    • BIGQUERY_SERVER_NAME: 외부 서버의 고유 식별자. 지정된 데이터베이스에서 한 번 정의합니다. BIGQUERY_SERVER_NAME을 서버 이름으로 바꿀 수 있습니다.

  3. CREATE USER MAPPING 명령어를 실행하여 사용자 매핑을 만듭니다. 이 명령어는 외부 서버에 연결할 때 사용할 사용자 인증 정보를 지정합니다.

    CREATE USER MAPPING FOR USERNAME SERVER BIGQUERY_SERVER_NAME ;

    다음을 바꿉니다.

    • USERNAME: 외부 테이블에 액세스하는 데이터베이스 사용자 이름 또는 IAM 사용자
    • BIGQUERY_SERVER_NAME: 생성한 외부 서버의 고유 식별자

  4. CREATE FOREIGN TABLE 명령어를 사용하여 BigQuery에서 액세스하려는 테이블에 해당하는 외부 테이블을 정의합니다. 이 명령어를 사용하면 원격 테이블의 구조를 정의할 수 있습니다. 외부 테이블에는 BigQuery의 소스 테이블에 있는 열이 전부 또는 일부 포함될 수 있습니다.

    CREATE FOREIGN TABLE TABLENAME (
COLUMNX_NAME DATA_TYPE,
COLUMNX_NAME DATA_TYPE,
...
) SERVER  BIGQUERY_SERVER_NAME OPTIONS (project BIGQUERY_PROJECT_ID, dataset  BIGQUERY_DATASET_NAME, table  BIGQUERY_TABLE_NAME [, mode EXECUTION_MODE]);

    다음을 바꿉니다.

    • TABLENAME: 로컬 데이터베이스의 외부 테이블 이름
    • COLUMNX_NAME: AlloyDB 열 이름입니다. 열 이름은 BigQuery 소스 테이블의 해당 열 이름과 정확히 일치해야 합니다. X는 테이블을 여러 열로 만들 수 있음을 나타냅니다. 이름은 BigQuery 열의 정확한 대소문자와도 일치해야 합니다. BigQuery 열 이름에 대문자가 포함된 경우(예: employeeID) 혼합 또는 대문자를 유지하려면 AlloyDB 식별자를 큰따옴표로 묶어야 합니다(예: "employeeID").
    • DATA_TYPE: 열의 데이터 유형입니다.
    • BIGQUERY_SERVER_NAME: 생성한 외부 서버의 고유 식별자
    • BIGQUERY_PROJECT_ID: BigQuery 데이터 세트가 있는 프로젝트의 ID
    • BIGQUERY_DATASET_NAME: 테이블의 BigQuery 데이터 세트 이름
    • BIGQUERY_TABLE_NAME: BigQuery 테이블의 이름

    • EXECUTION_MODE: 선택사항. mode 옵션은 다음 설정을 지원합니다.

      • query: 복잡한 쿼리에 BigQuery API를 사용합니다.
      • storage: 빠른 대량 읽기를 위해 BigQuery Storage API를 사용합니다.
      • auto: 모드를 자동으로 선택합니다. 기본값입니다.

      자세한 내용은 BigQuery 외부 데이터 래퍼 실행 모드를 참고하세요.

    외부 테이블이 생성된 후에는 AlloyDB의 테이블을 쿼리하는 것과 같은 방식으로 이 테이블을 쿼리할 수 있습니다.

데이터 동기화

BigQuery 데이터 또는 BigLake Iceberg 데이터를 AlloyDB에 동기화하려면 다음 단계를 따르세요.

  1. 기존 데이터 소스를 식별하거나 기본 BigQuery 테이블 또는 새 Iceberg 관리형 테이블을 만듭니다.

  2. psql을 사용하여 다음 명령어를 실행하여 local_table을 만듭니다.

    CREATE TABLE local_table AS (SELECT * from foreign_table);

    이 명령어는 BigQuery 테이블의 복사본을 로컬 네이티브 AlloyDB 테이블에 만듭니다.
    애플리케이션 워크플로에 따라 PostgreSQL pg_cron 확장 프로그램을 구성하여 주기적으로 AlloyDB 테이블을 새로고침할 수 있습니다.

AlloyDB로 데이터를 동기화하는 일정 설정

BigQuery 데이터 또는 BigLake Iceberg 데이터를 AlloyDB에 동기화하는 일정을 설정하려면 다음 단계를 따르세요.

  1. bigquery_fdw 확장 프로그램을 구성합니다.
  2. AlloyDB 인스턴스에서 pg_cron 확장 프로그램을 사용 설정합니다. 자세한 내용은 지원되는 데이터베이스 확장 프로그램을 참고하세요.
    1. alloydb.enable_pg_cron 플래그를 on으로 설정합니다. 자세한 내용은 alloydb.enable_pg_cron을 참고하세요.
    2. cron.database_name 플래그를 bigquery_fdw 확장 프로그램을 설치하고 동기화를 위한 SQL 쿼리를 실행할 데이터베이스 이름으로 설정합니다. 자세한 내용은 지원되는 데이터베이스 플래그를 참고하세요.

  3. 외부 테이블의 로컬 사본을 주기적으로 새로고침하려면 bigquery_fdw 확장 프로그램을 설치한 데이터베이스에서 다음 명령어를 실행합니다.

    CREATE EXTENSION pg_cron;
SELECT cron.schedule(JOB_NAME, SCHEDULE, 'CREATE TABLE IF NOT EXISTS local_table_copy AS (SELECT * FROM foreign_table); DROP TABLE IF EXISTS local_table; ALTER TABLE local_table_copy RENAME TO local_table;');

    다음을 바꿉니다.

    • JOB_NAME: 작업의 이름
    • SCHEDULE: 작업의 일정

    자세한 내용은 pg_cron이란 무엇인가요?를 참고하세요.

다음 단계