컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

일괄 SQL 변환기를 사용하여 코드 마이그레이션

이 문서에서는 BigQuery의 일괄 SQL 변환기를 사용하여 다른 SQL 언어로 작성된 스크립트를 Google 표준 SQL 쿼리로 변환하는 방법을 설명합니다. 이 문서는 Google Cloud 콘솔에 익숙한 사용자를 대상으로 합니다.

일괄 SQL 변환기는 BigQuery Migration Service의 일부입니다. 일괄 SQL 변환기는 다음 SQL 언어를 Google 표준 SQL로 변환할 수 있습니다.

  • Amazon Redshift SQL
  • SPL을 제외한 Teradata SQL

또한 미리보기에서 다음 SQL 언어 변환이 지원됩니다.

  • Apache HiveQL
  • Apache Spark SQL
  • Azure Synapse T-SQL
  • BTEQ(Basic Teradata Query)
  • IBM Netezza SQL/NZPLSQL
  • MySQL SQL
  • Oracle SQL, PL/SQL, Exadata
  • Presto SQL
  • PostgreSQL SQL
  • Snowflake SQL
  • SQL Server T-SQL
  • Teradata SPL
  • Vertica SQL

필수 권한

BigQuery Migration Service를 사용 설정하려면 프로젝트에 대해 다음 권한이 있어야 합니다.

  • resourcemanager.projects.get
  • serviceusage.services.enable
  • serviceusage.services.get

BigQuery Migration Service를 액세스하고 사용하려면 프로젝트에 대해 다음 권한이 필요합니다.

  • bigquerymigration.workflows.create
  • bigquerymigration.workflows.get
  • bigquerymigration.workflows.list
  • bigquerymigration.workflows.delete
  • bigquerymigration.subtasks.get
  • bigquerymigration.subtasks.list

    또는 다음 역할을 사용하여 동일한 권한을 얻을 수 있습니다.

    • bigquerymigration.viewer - 읽기 전용 액세스
    • bigquerymigration.editor - 읽기/쓰기 액세스

입력 및 출력 파일에 대해 Cloud Storage 버킷에 액세스하려면 다음 권한이 있어야 합니다.

  • 소스 Cloud Storage 버킷에서 storage.objects.get
  • 소스 Cloud Storage 버킷에서 storage.objects.list
  • 대상 Cloud Storage 버킷에서 storage.objects.create

다음 역할에서 위에 표시된 모든 필요한 Cloud Storage 권한을 지정할 수 있습니다.

  • roles/storage.objectAdmin
  • roles/storage.admin

시작하기 전에

변환 작업을 제출하기 전에 다음 단계를 완료하세요.

  1. BigQuery Migration API를 사용 설정합니다.
  2. 변환할 SQL 스크립트와 쿼리가 포함된 소스 파일을 수집합니다.
  3. (선택사항) 메타데이터 파일을 만들어 변환의 정확도를 높입니다.
  4. (선택사항) 소스 파일의 SQL 객체 이름을 BigQuery의 새 이름으로 매핑해야 하는지 결정합니다. 필요한 경우 사용할 이름 매핑 규칙을 결정합니다.
  5. 변환 작업을 제출하는 데 사용할 메서드를 결정합니다.
  6. Cloud Storage에 소스 파일 업로드

BigQuery Migration API 사용 설정

Google Cloud CLI 프로젝트가 2022년 2월 15일 이전에 생성된 경우 다음과 같이 BigQuery Migration API를 사용 설정합니다.

  1. Google Cloud 콘솔에서 BigQuery Migration API 페이지로 이동합니다.

    BigQuery Migration API로 이동

  2. 사용 설정을 클릭합니다.

소스 파일 수집

소스 파일은 소스 언어에 유효한 SQL이 포함된 텍스트 파일이어야 합니다. 소스 파일에는 주석이 포함될 수도 있습니다. 사용 가능한 모든 방법을 사용하여 SQL이 유효한지 확인합니다.

메타데이터 파일 만들기

서비스에서 보다 정확한 변환 결과를 생성할 수 있도록 메타데이터 파일을 제공하는 것이 좋습니다. 그러나 필수는 아닙니다.

dwh-migration-dumper 명령줄 도구를 사용하여 메타데이터 정보를 생성하거나 사용자 고유의 메타데이터 파일을 제공하면 됩니다. 메타데이터 파일이 준비되면 변환 소스 폴더에 소스 파일과 함께 포함할 수 있습니다. 변환기는 자동으로 메타데이터를 감지하고 소스 파일을 변환하는 데 활용하므로 이를 사용 설정하기 위해 추가 설정을 구성할 필요가 없습니다.

dwh-migration-dumper 도구를 사용하여 메타데이터 정보를 생성하려면 변환용 메타데이터 생성을 참조하세요.

자체 메타데이터를 제공하려면 소스 시스템의 SQL 객체에 대한 데이터 정의 언어(DDL) 문을 별도의 텍스트 파일로 수집합니다.

SQL 객체 이름 매핑

일괄 변환 중에 출력 이름 매핑을 선택적으로 수행할 수 있습니다. 출력 이름 매핑을 사용할 때 소스 시스템의 SQL 객체 이름을 BigQuery의 새 이름으로 변경하는 이름 매핑 규칙을 지정합니다. 예를 들어 소스 시스템에 schema1.table1 객체가 있고 BigQuery에서 이 객체 이름을 project1.dataset1.table1로 지정할 수 있습니다. 출력 이름 매핑을 사용하는 경우 일괄 변환 작업을 시작하기 전에 이름 매핑 규칙을 정의해야 합니다. 작업을 구성할 때 이러한 규칙을 수동으로 입력하거나 대신 이름 매핑 규칙이 포함된 JSON 파일을 만들어 업로드할 수 있습니다.

변환 작업 제출 방법 결정

일괄 변환 작업을 제출하는 방법은 3가지입니다.

  • 일괄 변환 클라이언트: 구성 파일에서 설정을 변경하여 작업을 구성하고 명령줄을 사용하여 작업을 제출합니다. 이 방식에서는 소스 파일을 수동으로 Cloud Storage에 업로드할 필요가 없습니다. 클라이언트는 변환 작업을 처리하는 동안 여전히 Cloud Storage를 사용하여 파일을 저장합니다.

    일괄 변환 클라이언트는 오픈소스 Python 클라이언트이며 이를 사용하면 로컬 머신에 있는 소스 파일을 변환하고 변환된 파일을 로컬 디렉터리로 출력할 수 있습니다. 구성 파일에서 몇 가지 설정을 변경하여 클라이언트를 기본 용도로 구성합니다. 원하는 경우 클라이언트에서 매크로 대체, 변환 입력과 출력의 사전 및 사후 처리와 같은 더욱 복잡한 태스크를 처리하도록 구성할 수도 있습니다. 자세한 내용은 일괄 변환 클라이언트 리드미를 참조하세요.

  • Google Cloud Console: 사용자 인터페이스를 사용하여 작업을 구성하고 제출합니다. 이 방식을 사용하려면 소스 파일을 Cloud Storage에 업로드해야 합니다.

  • BigQuery Migration API: 프로그래매틱 방식으로 작업을 구성하고 제출합니다. 이 방식을 사용하려면 소스 파일을 Cloud Storage에 업로드해야 합니다.

Cloud Storage에 입력 파일 업로드

Google Cloud 콘솔 또는 BigQuery Migration API를 사용하여 변환 작업을 수행하려면 Cloud Storage로 변환할 쿼리와 스크립트가 포함된 소스 파일을 업로드해야 합니다. 또한 만들 메타데이터 파일도 업로드해야 합니다. 버킷을 만들고 파일을 Cloud Storage에 업로드하는 방법은 스토리지 버킷 만들기객체 업로드를 참조하세요.

변환 작업 제출

변환 작업을 시작하고, 진행 상황을 확인하고, 결과를 확인하려면 다음 단계를 따르세요.

일괄 변환 클라이언트

  1. 일괄 변환 클라이언트 및 Google Cloud CLI를 설치합니다.

  2. gcloud CLI 사용자 인증 정보 파일을 생성합니다.

  3. 일괄 변환 클라이언트 설치 디렉터리에서 원하는 텍스트 편집기를 사용하여 config.yaml 파일을 열고 다음 설정을 수정합니다.

    • project_number: 일괄 변환 작업에 사용할 프로젝트의 프로젝트 번호를 입력합니다. 프로젝트의 Google Cloud 콘솔 대시보드에 있는 프로젝트 정보 창에서 찾을 수 있습니다.
    • gcs_bucket: 일괄 변환 클라이언트가 변환 작업 처리 중에 파일을 저장하는 데 사용할 Cloud Storage 버킷의 이름을 입력합니다.
    • input_directory: 소스 파일과 모든 메타데이터 파일이 있는 디렉터리의 절대 또는 상대 경로를 입력합니다.
    • output_directory: 변환된 파일의 대상 디렉터리에 대한 절대 또는 상대 경로를 입력합니다.
  4. 변경사항을 저장하고 config.yaml 파일을 닫습니다.

  5. 소스 파일과 메타데이터 파일을 입력 디렉터리에 저장합니다.

  6. 다음 명령어를 사용하여 일괄 변환 클라이언트를 실행합니다.

    bin/dwh-migration-client
    

    변환 작업이 생성되면 Google Cloud 콘솔의 변환 작업 목록에서 상태를 확인할 수 있습니다.

  7. (선택사항) 변환 작업이 완료되면 스토리지 비용이 방지되도록 작업이 지정한 Cloud Storage 버킷에 만든 파일을 삭제합니다.

Console

이러한 단계에서는 소스 파일이 Cloud Storage 버킷에 이미 업로드되었다고 가정합니다.

  1. Google Cloud Console에서 BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 탐색 패널의 마이그레이션 섹션에서 SQL 변환을 클릭합니다.

  3. 변환 시작을 클릭합니다.

  4. 변환 구성 대화상자를 입력합니다.

    1. 표시 이름에 변환 작업 이름을 입력합니다. 이름에는 문자, 숫자 또는 밑줄을 사용할 수 있습니다.
    2. 처리 위치에서 변환 작업을 실행할 위치를 선택합니다. 예를 들어 개발자가 유럽에 있고 데이터가 위치 경계를 넘어가지 않게 하려면 eu 리전을 선택합니다. 변환 작업은 소스 파일 버킷과 동일한 위치를 선택할 때 최고의 성능을 발휘합니다.
    3. 소스 언어에서 변환할 SQL 언어를 선택합니다.
    4. 대상 언어에서 BigQuery를 선택합니다.
  5. 다음을 클릭합니다.

  6. 소스 위치에 변환할 파일이 포함된 Cloud Storage 폴더의 경로를 지정합니다. 경로를 bucket_name/folder_name/ 형식으로 입력하거나 찾아보기 옵션을 사용할 수 있습니다.

  7. 다음을 클릭합니다.

  8. 대상 위치에서 변환된 파일의 대상 Cloud Storage 폴더 경로를 지정합니다. 경로를 bucket_name/folder_name/ 형식으로 입력하거나 찾아보기 옵션을 사용할 수 있습니다.

  9. 기본 객체 이름이나 소스-대상 이름 매핑을 지정할 필요가 없는 변환을 수행하는 경우 11단계로 건너뜁니다. 그렇지 않으면 다음을 클릭합니다.

  10. 필요한 설정(선택사항)을 입력합니다.

    1. (선택사항) 기본 데이터베이스에 소스 파일에서 사용할 기본 데이터베이스 이름을 입력합니다. 변환기는 이 기본 데이터베이스 이름을 사용하여 데이터베이스 이름이 누락된 SQL 객체의 정규화된 이름을 확인합니다.

    2. (선택사항) 스키마 검색 경로의 경우, 변환기가 스키마 이름이 누락된 소스 파일에서 SQL 객체의 정규화된 이름을 확인해야 하는 경우에 검색할 스키마를 지정합니다. 소스 파일에서 여러 스키마 이름을 사용하는 경우 스키마 이름 추가를 클릭하고 참조될 수 있는 각 스키마의 값을 추가합니다.

      변환기는 제공된 메타데이터 파일을 검색하여 스키마 이름으로 테이블의 유효성을 검사합니다. 메타데이터에서 명확한 옵션을 결정할 수 없으면 입력한 첫 번째 스키마 이름이 기본값으로 사용됩니다. 기본 스키마 이름이 사용되는 방법에 대한 자세한 내용은 기본 스키마를 참조하세요.

    3. (선택사항) 변환 중에 소스 시스템과 BigQuery 간에 SQL 객체 이름을 변경하도록 이름 매핑 규칙을 지정하려면 이름 매핑 쌍이 있는 JSON 파일을 제공하거나 Google Cloud 콘솔을 사용하여 매핑할 값을 지정하면 됩니다.

      JSON 파일을 사용하려면 다음 안내를 따르세요.

      1. 이름 매핑용 JSON 파일 업로드를 클릭합니다.
      2. 적절한 형식으로 된 이름 매핑 파일의 위치를 찾아 선택하고 열기를 클릭합니다.

        파일 크기는 5MB 미만이어야 합니다.

      Google Cloud 콘솔을 사용하려면 다음 안내를 따르세요.

      1. 이름 매핑 쌍 추가를 클릭합니다.
      2. 소스 열의 데이터베이스, 스키마, 관계, 속성 필드에 소스 객체 이름의 적절한 부분을 추가합니다.
      3. 대상 열의 필드에 BigQuery의 대상 객체 이름 부분을 추가합니다.
      4. 유형에 매핑하려는 객체를 설명하는 객체 유형을 선택합니다.
      5. 필요한 이름 매핑 쌍을 모두 지정할 때까지 1~4단계를 반복합니다. Google Cloud 콘솔을 사용할 때 이름 매핑 쌍을 최대 25개까지만 지정할 수 있습니다.
  11. 만들기를 클릭하여 변환 작업을 시작합니다.

변환 작업이 생성되면 번역 작업 목록에서 상태를 확인할 수 있습니다.

API

이러한 단계에서는 소스 파일이 Cloud Storage 버킷에 이미 업로드되었다고 가정합니다.

  1. 정의된 워크플로를 사용해서 create 메서드를 호출합니다.
  2. 그런 다음 start 메서드를 호출하여 변환 워크플로를 시작합니다.

Go, 자바, Python용 BigQuery Migration API 클라이언트 라이브러리를 사용하면 프로그래매틱 방식으로 일괄 변환 작업을 더 쉽게 구성하고 제출할 수 있습니다.

변환 출력 살펴보기

변환 작업을 실행하면 Google Cloud 콘솔에서 작업에 대한 정보를 확인할 수 있습니다. Google Cloud 콘솔 또는 BigQuery Migration API를 사용하여 작업을 실행한 경우 지정한 대상 Cloud Storage 버킷에서 작업 결과를 확인할 수 있습니다. 일괄 변환 클라이언트를 사용하여 작업을 실행한 경우 지정한 출력 디렉터리에서 작업 결과를 확인할 수 있습니다. 일괄 SQL 변환기는 다음 파일을 지정된 대상으로 출력합니다.

  • 변환된 파일
  • CSV 형식의 변환 요약 보고서
  • JSON 형식의 사용된 출력 이름 매핑

Google Cloud 콘솔 출력

변환 작업 세부정보를 보려면 다음 단계를 따르세요.

  1. Google Cloud Console에서 BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 탐색 패널의 마이그레이션 섹션에서 SQL 변환을 클릭합니다.

  3. 변환 작업 목록에서 원하는 작업을 찾고 변환 작업 이름을 클릭합니다.

  4. 결과 섹션에서는 전체 변환 성공률, 처리된 문 수, 작업 기간을 확인할 수 있습니다.

  5. 작업 탭을 선택하여 변환 문제와 발생 빈도를 확인합니다. 나열된 각 작업에는 문제 카테고리, 특정 문제 메시지, 문제가 발생한 파일에 대한 링크가 표시된 하위 행이 있습니다.

  6. 변환 구성 탭을 선택하여 변환 작업 구성 세부정보를 확인합니다.

요약 보고서

요약 보고서는 변환 작업 중에 발생한 모든 경고 및 오류 메시지 테이블을 포함하는 CSV 파일입니다.

Google Cloud 콘솔에서 요약 파일을 보려면 다음 단계를 따르세요.

  1. Google Cloud Console에서 BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 탐색 패널의 마이그레이션 섹션에서 SQL 변환을 클릭합니다.

  3. 변환 작업 목록에서 원하는 작업을 찾고 상태 열에서 세부정보 표시를 클릭합니다.

  4. 변환 보고서 섹션에서 batch_translation_report.csv를 클릭합니다.

  5. 객체 세부정보 페이지에서 인증된 URL 행의 값을 클릭하여 브라우저에서 파일을 확인합니다.

다음 테이블에서는 요약 파일 열을 설명합니다.

설명
타임스탬프 문제가 발생한 타임스탬프입니다.
FilePath 문제와 연결된 소스 파일의 경로입니다.
파일 이름 문제와 연결된 소스 파일의 이름입니다.
ScriptLine 문제가 발생한 줄 번호입니다.
ScriptColumn 문제가 발생한 열 번호입니다.
TranspilerComponent 경고나 오류가 발생한 변환 엔진 내부 구성요소입니다. 이 열은 비어 있을 수 있습니다.
환경 경고 또는 오류와 관련된 변환 언어 환경입니다. 이 열은 비어 있을 수 있습니다.
ObjectName 경고 또는 오류와 관련된 소스 파일의 SQL 객체입니다. 이 열은 비어 있을 수 있습니다.
심각도 문제 심각도로, 경고나 오류입니다.
카테고리 변환 문제 카테고리입니다.
메시지 변환 문제 경고 또는 오류 메시지입니다.
ScriptContext 문제와 연결된 소스 파일의 SQL 스니펫입니다.
작업 문제를 해결하기 위한 권장한 조치입니다.

소비된 출력 이름 매핑 파일

이 JSON 파일에는 변환 작업에 사용된 출력 이름 매핑 규칙이 포함되어 있습니다. 이 파일의 규칙은 이름 매핑 규칙 충돌이나 변환 중에 식별된 SQL 객체에 대한 이름 매핑 규칙 부족으로 인해 변환 작업에 지정한 출력 이름 매핑 규칙과 다를 수 있습니다. 이 파일을 검토하여 이름 매핑 규칙을 수정해야 하는지 여부를 결정합니다. 수정한 경우 식별된 모든 문제를 해결하는 새로운 출력 이름 매핑 규칙을 만들고 새 변환 작업을 실행합니다.

변환된 파일

각 소스 파일에 대해 해당 출력 파일이 대상 경로에 생성됩니다. 출력 파일에는 변환된 쿼리가 포함됩니다.

제한사항

변환기는 SQL 이외의 언어에서 사용자 정의 함수(UDF)를 변환할 수 없습니다. 입력 및 출력 데이터 유형을 결정하기 위해 파싱할 수 없기 때문입니다. 이렇게 하면 이러한 UDF를 참조하는 SQL 문 변환이 부정확해질 수 있습니다. 변환 중에 SQL이 아닌 UDF를 올바르게 참조하게 하려면 유효한 SQL을 사용하여 동일한 서명으로 자리표시자 UDF를 만듭니다.

예를 들어 C로 작성된 UDF가 두 정수의 합을 계산한다고 가정해 보겠습니다. 이 UDF를 참조하는 SQL 문이 올바르게 변환되게 하려면 다음 예시와 같이 C UDF와 동일한 서명을 공유하는 자리표시자 SQL UDF를 만듭니다.

CREATE FUNCTION Test.MySum (a INT, b INT)
  RETURNS INT
  LANGUAGE SQL
  RETURN a + b;

이 자리표시자 UDF를 텍스트 파일로 저장하고 해당 파일을 변환 작업의 소스 파일 중 하나로 포함합니다. 이렇게 하면 변환기가 UDF 정의를 학습하고 예상 입력 및 출력 데이터 유형을 식별할 수 있습니다.

할당량 및 한도

  • BigQuery Migration API 할당량이 적용됩니다.
  • 프로젝트마다 활성 변환 태스크를 최대 10개까지 있을 수 있습니다.
  • 소스 파일과 메타데이터 파일의 총 수에는 엄격한 제한이 없지만 우수한 성능을 위해 파일 수를 1000개 미만으로 유지하는 것이 좋습니다.

다음 단계

데이터 웨어하우스 마이그레이션의 다음 단계를 자세히 알아보세요.