Spanner에서 Avro로 데이터베이스 내보내기

이 페이지에서는 Google Cloud 콘솔을 사용하여 Spanner 데이터베이스를 내보내는 방법을 설명합니다. REST API 또는 gcloud spanner 명령줄 도구를 사용하여 Spanner 데이터베이스를 내보내려면 이 페이지의 시작하기 전에 섹션의 단계를 완료한 후 Dataflow 문서의 Spanner to Cloud Storage Avro에 있는 자세한 안내를 참조하세요. 내보내기 프로세스는 Dataflow를 사용하고 Cloud Storage 버킷의 폴더에 데이터를 작성합니다. 이 폴더에는 여러 개의 Avro 파일 및 JSON 매니페스트 파일이 포함됩니다.

시작하기 전에

Spanner 데이터베이스를 내보내려면 먼저 Spanner, Cloud Storage, Compute Engine, Dataflow API를 사용 설정해야 합니다.

API 사용 설정

또한 충분한 할당량과 필수 IAM 권한이 필요합니다.

할당량 요구사항

내보내기 작업의 할당량 요구사항은 다음과 같습니다.

• Spanner: 데이터베이스를 내보내는 데 컴퓨팅 용량이 추가로 필요하지는 않지만 적당한 시간 안에 작업을 마치려면 컴퓨팅 용량을 더 추가해야 할 수도 있습니다. 자세한 내용은 작업 최적화를 참조하세요.
• Cloud Storage : 내보내려면 내보낸 파일을 위한 버킷을 만들어야 합니다(아직 없는 경우). 이 작업은 Cloud Storage 페이지를 통해서 또는 Spanner 페이지를 통해 내보내기를 만드는 동안 Google Cloud 콘솔에서 수행할 수 있습니다. 버킷의 크기를 설정할 필요는 없습니다.
• Dataflow: 내보내기 작업에는 다른 Cloud Dataflow 작업과 동일한 CPU, 디스크 사용량, IP 주소, Compute Engine 할당량이 적용됩니다.

• Compute Engine: 내보내기 작업을 실행하기 전에 Dataflow가 사용하는 Computer Engine에 초기 할당량을 설정해야 합니다. 이 할당량은 Dataflow가 작업에 사용할 수 있는 최대 리소스 수를 나타냅니다. 권장되는 시작 값은 다음과 같습니다.

  • CPU: 200
  • 사용 중인 IP 주소: 200
  • 표준 영구 디스크: 50TB

  일반적으로 다른 조정은 할 필요가 없습니다. Dataflow는 자동 확장을 지원하므로 내보내기 중에 사용된 실제 리소스에 대해서만 비용을 지불하면 됩니다. 작업에 더 많은 리소스가 사용될 수 있으면 Dataflow UI에 경고 아이콘이 표시됩니다. 경고 아이콘이 표시되더라도 작업은 완료됩니다.

IAM 요구사항

데이터베이스를 내보내려면 내보내기 작업과 관련된 모든 서비스를 사용할 수 있는 충분한 권한이 있는 IAM 역할도 있어야 합니다. 역할과 권한을 부여하는 방법은 IAM 역할 적용을 참조하세요.

데이터베이스를 내보내려면 다음 역할이 필요합니다.

• Google Cloud 프로젝트 수준:
  • Spanner 뷰어(roles/spanner.viewer)
  • Dataflow 관리자(roles/dataflow.admin)
  • 스토리지 관리자(roles/storage.admin)
• Spanner 데이터베이스나 인스턴스 수준 또는 Google Cloud 프로젝트 수준에서:
  • Spanner 데이터베이스 리더(roles/spanner.databaseReader)
  • Spanner 데이터베이스 관리자(roles/spanner.databaseAdmin)

참고: Spanner 데이터베이스 관리자 역할은 가져오기 작업에만 필요합니다.

내보내기 중에 Spanner Data Boost의 독립적인 컴퓨팅 리소스를 사용하려면 spanner.databases.useDataBoost IAM 권한도 필요합니다. 자세한 내용은 Data Boost 개요를 참조하세요.

데이터베이스 내보내기

위에서 설명한 할당량 및 IAM 요구사항을 충족하면 기존 Spanner 데이터베이스를 내보낼 수 있습니다.

참고: 사용 중인 데이터베이스도 안전하게 내보낼 수 있습니다. 하지만 모든 데이터를 같은 데이터베이스 스냅샷에서 내보내므로 Dataflow에서 Cloud Spanner 트랜잭션을 만든 이후의 변경사항은 내보내기에서 캡처되지 않습니다.

Spanner 데이터베이스를 Cloud Storage 버킷으로 내보내려면 다음 단계를 수행합니다.

1. Spanner 인스턴스 페이지로 이동합니다.

   인스턴스 페이지로 이동

2. 데이터베이스가 포함된 인스턴스의 이름을 클릭합니다.

3. 왼쪽 창에서 가져오기/내보내기 메뉴 항목을 클릭한 다음 내보내기 버튼을 클릭합니다.

4. 내보내기 저장 위치 선택에서 찾아보기를 클릭합니다.

5. 내보낸 데이터를 저장할 Cloud Storage 버킷이 아직 없으면 다음을 수행합니다.

   1. 새 버킷()을 클릭합니다.
   2. 버킷 이름을 입력합니다. 버킷 이름은 Cloud Storage 전체에서 고유해야 합니다.
   3. 기본 스토리지 클래스와 위치를 선택한 후 만들기를 클릭합니다.
   4. 버킷을 클릭하여 선택합니다.

   버킷이 이미 있으면 초기 목록에서 버킷을 선택하거나 검색()을 클릭하여 목록을 필터링한 후 버킷을 클릭하여 선택합니다.

6. 선택을 클릭합니다.

7. 내보낼 데이터베이스 선택 드롭다운 메뉴에서 내보낼 데이터베이스를 선택합니다.

8. 선택사항: 이전 시점의 데이터베이스를 내보내려면 체크박스를 선택하고 타임스탬프를 입력합니다.

9. 내보내기 작업의 리전 선택 드롭다운 메뉴에서 리전을 선택합니다.

   참고: 데이터 전송 요금이 부과되지 않도록 인스턴스 구성과 겹치는 리전을 선택하세요. 자세한 내용은 리전 선택을 참조하세요.

10. 선택사항: 고객 관리 암호화 키를 사용하여 Dataflow 파이프라인 상태를 암호화하려면 다음 안내를 따르세요.

    1. 암호화 옵션 표시를 클릭합니다.
    2. 고객 관리 암호화 키(CMEK) 사용을 선택합니다.
    3. 드롭다운 목록에서 키를 선택합니다.

    이 옵션은 대상 Cloud Storage 버킷 수준 암호화에 영향을 주지 않습니다. Cloud Storage 버킷에 CMEK를 사용 설정하려면 Cloud Storage에 CMEK 사용을 참조하세요.

11. 선택사항: Spanner Data Boost를 사용하여 내보내려면 Spanner Data Boost 사용 체크박스를 선택합니다. 자세한 내용은 Data Boost 개요를 참조하세요.

12. 요금 부과 확인에서 체크박스를 선택하여 기존 Spanner 인스턴스에서 발생하는 요금 이외에 청구되는 요금을 확인합니다.

13. 내보내기를 클릭합니다.

    Google Cloud 콘솔은 작업 경과 시간을 포함하여 가져오기/내보내기 작업 목록에 내보내기 작업의 항목을 표시하는 데이터베이스 가져오기/내보내기 페이지를 표시합니다.

    

작업이 완료 또는 종료되면 가져오기/내보내기 목록에서 상태가 업데이트됩니다. 작업이 성공하면 성공 상태가 표시됩니다.

작업이 실패하면 실패 상태가 표시됩니다.

작업에 대한 Dataflow 작업의 세부정보를 보려면 Dataflow 작업 이름 열에 있는 작업 이름을 클릭하세요.

작업이 실패하면 작업의 Dataflow 로그에서 오류 세부정보를 확인하세요.

실패한 내보내기 작업 파일에 Cloud Storage 요금이 부과되지 않도록 하려면 해당 폴더 및 파일을 삭제해야 합니다. 폴더를 찾는 방법은 내보내기 보기를 참조하세요.

생성 열 및 변경 내역 내보내기 참고사항

저장된 생성 열의 값은 내보내지 않습니다. 필드의 커스텀 속성으로 지정된 열 정의를 null 유형의 레코드 필드로 Avro 스키마로 내보냅니다. 새로 추가된 생성 열의 백필 작업이 완료될 때까지 생성 열은 스키마 안에 존재하지 않는 경우 무시됩니다.

Avro 파일로 내보낸 변경 내역에는 데이터 변경 레코드가 아닌 변경 내역의 스키마만 포함됩니다.

시퀀스 내보내기 참고사항

시퀀스(GoogleSQL, PostgreSQL)는 고유한 정수 값을 생성하는 데 사용하는 스키마 객체입니다. Spanner는 각 스키마 객체를 Avro 스키마에 레코드 필드로 내보내고 시퀀스 종류, 건너뛴 범위, 카운터를 필드 속성으로 내보냅니다. 스키마를 가져온 후 시퀀스가 재설정되고 중복 값이 생성되지 않도록 하기 위해 스키마 내보내기 중에 GET_INTERNAL_SEQUENCE_STATE()(GoogleSQL, PostgreSQL) 함수가 시퀀스 카운터를 캡처합니다. Spanner는 카운터에 버퍼 1,000을 추가하고 새 카운터 값을 레코드 필드에 씁니다. 이 방법은 가져오기 후에 발생할 수 있는 중복 값 오류를 방지합니다. 데이터 내보내기 중에 소스 데이터베이스에 쓰기가 더 있으면 ALTER SEQUENCE(GoogleSQL, PostgreSQL) 문을 사용하여 실제 시퀀스 카운터를 조정해야 합니다.

가져올 때 시퀀스는 스키마에서 찾은 카운터 대신 이 새로운 카운터에서 시작됩니다. 또는 ALTER SEQUENCE(GoogleSQL, PostgreSQL) 문을 사용하여 새 카운터로 시퀀스를 업데이트할 수 있습니다.

Cloud Storage에서 내보내기 보기

Google Cloud 콘솔에서 내보낸 데이터베이스가 포함된 폴더를 보려면 Cloud Storage 브라우저로 이동하고 앞에서 선택한 버킷을 선택합니다.

Cloud Storage 브라우저로 이동

이 버킷에는 내보낸 데이터베이스가 들어있는 폴더가 포함되어 있습니다. 폴더 이름은 인스턴스 ID, 데이터베이스 이름, 내보내기 작업의 타임스탬프로 시작됩니다. 이 폴더에는 다음이 포함되어 있습니다.

• spanner-export.json 파일
• 내보낸 데이터베이스에 있는 각 테이블의 TableName-manifest.json 파일

• 하나 이상의 TableName.avro-#####-of-##### 파일. 확장명 .avro-#####-of-#####에서 첫 번째 숫자는 Avro 파일의 색인(0부터 시작)을 나타내고, 두 번째 숫자는 각 테이블에 생성된 Avro 파일 수를 나타냅니다.

  예를 들어 Songs.avro-00001-of-00002는 Songs 테이블의 데이터가 포함된 두 파일 중 두 번째 파일입니다.

• 내보낸 데이터베이스에서 각 변경 내역의 ChangeStreamName-manifest.json 파일.

• 변경 내역당 하나의 ChangeStreamName.avro-00000-of-00001. 이 파일에는 변경 내역의 Avro 스키마만 있는 빈 데이터가 포함되어 있습니다.

가져오기 작업 리전 선택

Cloud Storage 버킷 위치에 따라 다른 리전을 선택할 수 있습니다. 아웃바운드 데이터 전송 요금이 부과되지 않도록 하려면 Cloud Storage 버킷 위치와 일치하는 리전을 선택합니다.

• Cloud Storage 버킷 위치가 리전인 경우 리전을 사용할 수 있으면 가져오기 작업에 동일한 리전을 선택하여 무료 네트워크 사용량을 활용할 수 있습니다.

• Cloud Storage 버킷 위치가 이중 리전인 경우 리전 중 하나를 사용할 수 있으면 가져오기 작업에 이중 리전을 구성하는 두 리전 중 하나를 선택하여 무료 네트워크 사용량을 활용할 수 있습니다.

• 같은 위치에 있는 리전을 가져오기 작업에 사용할 수 없거나 Cloud Storage 버킷 위치가 멀티 리전이면 아웃바운드 데이터 전송 요금이 청구됩니다. Cloud Storage 데이터 전송 가격 책정을 참조하여 데이터 전송 요금이 가장 적은 리전을 선택하세요.

테이블 하위 집합 내보내기

전체 데이터베이스가 아닌 특정 테이블의 데이터만 내보내려면 내보내기 중에 이러한 테이블을 지정하면 됩니다. 이 경우 Spanner는 지정한 테이블 데이터를 포함하여 데이터베이스의 전체 스키마를 내보냅니다. 따라서 내보낸 파일은 비어 있지만 다른 모든 테이블은 그대로 있습니다.

Google Cloud 콘솔의 Dataflow 페이지나 명령줄을 사용하여 내보낼 테이블의 하위 집합을 지정할 수 있습니다. (Spanner 페이지에서는 이 작업을 제공하지 않습니다.)

다른 테이블의 하위 요소인 테이블의 데이터를 내보내는 경우 상위 테이블 데이터도 내보내야 합니다. 상위 항목을 내보내지 않으면 내보내기 작업이 실패합니다.

테이블의 하위 집합을 내보내려면 Dataflow의 Spanner to Cloud Storage Avro 템플릿을 사용하여 내보내기를 시작하고 다음 설명대로 Google Cloud 콘솔의 Dataflow 페이지나 Google Cloud CLI를 사용하여 테이블을 지정합니다.

Google Cloud 콘솔

Google Cloud 콘솔의 Dataflow 페이지를 사용하는 경우 Cloud Spanner 테이블 이름 매개변수는 템플릿에서 작업 만들기 페이지의 선택적 매개변수 섹션에 있습니다. 테이블 여러 개를 쉼표로 구분된 형식으로 지정할 수 있습니다.

gcloud CLI

Google Cloud CLI를 사용하는 경우 tableNames 인수를 사용하여 테이블을 지정합니다. 예를 들면 다음과 같습니다.

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=table1,outputDir=gs://my-gcs-bucket' \
--max-workers=10

gcloud에서 테이블 여러 개를 지정하려면 사전 유형 인수 이스케이프 처리가 필요합니다. 다음 예시에서는 '|'를 이스케이프 문자로 사용합니다.

 gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='^|^instanceId=test-instance|databaseId=example-db|tableNames=table1,table2|outputDir=gs://my-gcs-bucket' \
--max-workers=10

shouldExportRelatedTables 매개변수는 원하는 테이블의 모든 상위 테이블을 자동으로 내보내는 편리한 옵션입니다. 예를 들어 Singers, Albums, Songs 테이블이 있는 이 스키마 계층 구조에서는 Songs만 지정해야 합니다. Songs는 둘 다의 하위 요소이므로 shouldExportRelatedTables 옵션에서도 Singers 및 Albums를 내보냅니다.

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=Songs,shouldExportRelatedTables=true,outputDir=gs://my-gcs-bucket' \
--max-workers=10

Dataflow UI에서 작업 보기 또는 문제 해결

내보내기 작업을 시작한 후에는 Google Cloud 콘솔의 Dataflow 섹션에 로그를 포함한 작업의 세부정보가 표시됩니다.

Dataflow 작업 세부정보 보기

현재 실행 중인 작업을 포함하여 지난주에 실행한 가져오기/내보내기 작업의 세부정보를 확인하려면 다음을 실행합니다.

1. 데이터베이스의 데이터베이스 개요 페이지로 이동합니다.
2. 왼쪽 창에서 가져오기/내보내기 메뉴 항목을 클릭합니다. 데이터베이스의 가져오기/내보내기 페이지에 최근 작업 목록이 표시됩니다.

3. 데이터베이스의 가져오기/내보내기 페이지에서 Dataflow 작업 이름 열에 있는 작업 이름을 클릭합니다.

   

   Google Cloud 콘솔에 Dataflow 작업의 세부정보가 표시됩니다.

일주일 이상 전에 실행한 작업을 보려면 다음을 수행합니다.

1. Google Cloud 콘솔에서 Dataflow 작업 페이지로 이동합니다.

   작업 페이지로 이동

2. 목록에서 작업을 찾은 다음 작업 이름을 클릭합니다.

   Google Cloud 콘솔에 Dataflow 작업의 세부정보가 표시됩니다.

참고: 데이터베이스가 같고 유형이 같은 작업은 이름도 동일합니다. 시작 시간 또는 종료 시간 열에 있는 값으로 작업을 구분할 수 있습니다.

작업의 Dataflow 로그 보기

Dataflow 작업의 로그를 보려면 위에서 설명한대로 작업의 세부정보 페이지로 이동한 다음 작업 이름 오른쪽에 있는 로그를 클릭합니다.

작업이 실패한 경우 로그에서 오류를 찾습니다. 오류가 있으면 오류 개수가 로그 옆에 표시됩니다.

작업 오류를 보려면 다음을 수행합니다.

1. 로그 옆에 있는 오류 개수를 클릭합니다.

   Google Cloud 콘솔에 작업 로그가 표시됩니다. 오류를 보려면 스크롤해야 할 수도 있습니다.

2. 오류 아이콘()이 있는 항목을 찾습니다.

3. 개별 로그 항목을 클릭하여 내용을 펼칩니다.

Dataflow 작업 문제 해결에 대한 자세한 내용은 파이프라인 문제 해결을 참조하세요.

실패한 내보내기 작업 문제 해결

작업 로그에 다음 오류가 표시되는 경우가 있습니다.

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Google Cloud 콘솔에 있는 Spanner 데이터베이스의 모니터링 탭에서 99% 읽기 지연 시간을 확인합니다. 높은 값(수 초)이 표시되면 인스턴스가 과부하되어 읽기 제한 시간이 초과되고 실패했음을 나타냅니다.

지연 시간이 긴 이유 중 하나는 Dataflow 작업에서 너무 많은 작업자를 통해 실행되어 Spanner 인스턴스에 너무 많은 부하가 발생하기 때문입니다.

Google Cloud 콘솔에서 Spanner 데이터베이스의 인스턴스 세부정보 페이지에 있는 가져오기/내보내기 탭을 사용하는 대신 Dataflow 작업자 수를 제한하려면 Dataflow Cloud Storage to Cloud Spanner Avro 템플릿을 사용하여 내보내기를 시작하고 다음 설명대로 최대 작업자 수를 지정해야 합니다

• Dataflow Console을 사용할 경우 최대 작업자 매개변수는 템플릿에서 작업 만들기 페이지의 선택적 매개변수 섹션에 있습니다.

• gcloud를 사용할 경우 max-workers 인수를 지정합니다. 예를 들면 다음과 같습니다.

  gcloud dataflow jobs run my-export-job \
  --gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
  --region=us-central1 \
  --parameters='instanceId=test-instance,databaseId=example-db,outputDir=gs://my-gcs-bucket' \
  --max-workers=10
  

느리게 실행되는 내보내기 작업 최적화

초기 설정의 제안에 따랐다면 일반적으로 다른 조정이 필요 없습니다. 작업이 느리게 실행되는 경우에는 몇 가지 다른 최적화 방법을 시도할 수 있습니다.

• 작업 및 데이터 위치 최적화: Spanner 인스턴스와 Cloud Storage 버킷이 있는 리전과 동일한 리전에서 Dataflow 작업을 실행합니다.

• 충분한 Dataflow 리소스 확보: 관련 Compute Engine 할당량에 따라 Dataflow 작업의 리소스가 제한되는 경우에는 Google Cloud 콘솔에서 작업의 Dataflow 페이지에 경고 아이콘()과 로그 메시지가 표시됩니다.

  

  이 경우 CPU, 사용 중인 IP 주소, 표준 영구 디스크의 할당량을 늘리면 작업 실행 시간이 단축될 수 있지만 Compute Engine 요금이 늘어날 수 있습니다.

• Spanner CPU 사용률 확인: 인스턴스의 CPU 사용률이 65%를 초과하면 인스턴스의 컴퓨팅 용량을 늘리면 됩니다. 용량을 추가하면 Spanner 리소스가 늘어나고 작업 속도가 빨라지지만 Spanner 요금이 더 많이 청구됩니다.

내보내기 작업 성능에 영향을 미치는 요소

내보내기 작업 완료에 걸리는 시간은 몇 가지 요소의 영향을 받습니다.

• Spanner 데이터베이스 크기: 처리하는 데이터가 많을수록 시간과 리소스가 더 많이 소요됩니다.

• 다음을 포함한 Spanner 데이터베이스 스키마:

  • 테이블 수
  • 행 크기
  • 보조 색인 수
  • 외래 키 수
  • 변경 내역 수

• 데이터 위치: 데이터는 Dataflow를 사용하여 Spanner와 Cloud Storage 간에 전송됩니다. 이 세 가지 구성요소가 같은 리전에 위치하는 것이 이상적입니다. 구성요소가 서로 다른 리전에 있으면 다른 리전으로 데이터를 이동하느라 작업 속도가 느려집니다.

• Dataflow 작업자 수: 성능 향상을 위해 최적의 Dataflow 작업자가 필요합니다. 자동 확장을 사용하면 Dataflow는 수행해야 하는 작업량에 따라 작업의 작업자 수를 선택합니다. 하지만 작업자 수는 CPU, 사용 중인 IP 주소, 표준 영구 디스크의 할당량에 따라 제한됩니다. 할당량 한도에 도달하면 Dataflow UI에 경고 아이콘이 표시됩니다. 이러한 경우 진행 속도가 느려지지만 작업은 완료됩니다.

• Spanner의 기존 부하: 일반적으로 내보내기 작업을 수행할 때는 Spanner 인스턴스에서 부하가 약간 늘어납니다. 인스턴스에 이미 상당한 기존 부하가 있다면 작업 실행 속도가 더 느려집니다.

• Spanner 컴퓨팅 용량: 인스턴스의 CPU 사용률이 65%를 초과하면 작업 실행 속도가 더 느려집니다.