데이터 가져오기 및 내보내기

이 문서에서는 Avro 및 CSV 형식을 사용하여 Spanner Omni에서 데이터를 이전, 백업, 전송하는 방법을 설명합니다. Spanner Omni CLI를 사용하여 Spanner Omni와 Cloud Storage, Amazon Simple Storage Service (Amazon S3), S3 호환 로컬 스토리지, 로컬 파일 시스템 (NFS)과 같은 스토리지 솔루션 간에 데이터베이스 콘텐츠를 이동합니다. Spanner Omni의 가져오기 및 내보내기 데이터 흐름은 모델, 지역 그룹, 배치를 지원하지 않습니다.

가져오기 및 내보내기 작업은 Spanner Omni 서버에서 실행되며 사용 가능한 시스템 리소스를 공유합니다. 가져오기는 리소스 집약적이며 RAM, CPU, 디스크 사용량이 많아 활성 워크로드에 영향을 미칠 수 있습니다. 이러한 작업은 일반적으로 일반 트래픽보다 낮은 우선순위로 실행되지만 배포에서 잠재적인 성능 영향을 모니터링해야 합니다.

파일 형식 비교

다음 표에서는 Spanner 데이터를 가져오고 내보낼 때 Avro 파일 형식과 CSV 파일 형식의 기능을 비교합니다.

기능	Avro	CSV
전체 데이터베이스 가져오기 또는 내보내기	예	아니요
이전에 내보낸 테이블 가져오기	예	예
이전 타임스탬프에서 내보내기	예	예
Spanner를 사용하여 가져오기 또는 내보내기	예	예
다른 데이터베이스에서 데이터 가져오기	아니요	예

Avro 및 CSV 형식 모두 데이터베이스의 모든 테이블을 내보냅니다. Avro 형식은 스키마도 내보내므로 다시 가져올 수 있습니다. CSV 형식은 스키마를 내보내지 않습니다.

시작하기 전에

가져오기 또는 내보내기 작업을 시작하기 전에 권한을 확인하고 데이터 스토리지 위치에 대한 액세스를 구성합니다.

권한

시작하기 전에 다음 권한이 있는지 확인합니다.

spanner.databases.import
spanner.databases.export

Spanner Omni의 Identity and Access Management (IAM)에 대한 자세한 내용은 IAM 개요를 참조하세요. 사용자의 역할을 업데이트하는 방법을 알아보려면 사용자 업데이트를 참조하세요.

데이터 소스 및 대상

Amazon Simple Storage Service (Amazon S3) 버킷, Cloud Storage 버킷, Amazon S3 호환 로컬 스토리지 (예: MinIO) 또는 로컬 파일 시스템 (NFS)에 데이터를 저장할 수 있습니다. 로컬 파일 시스템을 사용하는 경우 배포의 모든 서버에서 동일한 경로로 데이터를 사용할 수 있는지 확인합니다.

다음 두 가지 방법으로 데이터 스토어에 대한 액세스 권한을 제공할 수 있습니다.

배포에 외부 스토리지 추가: 버킷을 재사용하려는 경우 이 방법을 사용하는 것이 좋습니다.
일회성 사용자 인증 정보 만들기: 이러한 사용자 인증 정보가 가져오기 또는 내보내기 작업 기간 (예: 48시간)보다 오래 지속되도록 합니다.

사용자 인증 정보는 가져오기를 위해 버킷에서 객체를 나열하고 읽을 수 있는 권한을 제공해야 합니다. Amazon S3로 내보내려면 다음과 같은 추가 Amazon S3 권한이 필요합니다.

s3:PutObject
s3:AbortMultipartUpload
s3:ListBucketMultipartUploads

자세한 내용은 IAM 권한을 참조하세요.

Spanner Avro 파일 가져오기

이전에 다른 Spanner 데이터베이스 (Spanner 또는 Spanner Omni)에서 Avro 형식으로 내보낸 데이터를 가져오려면 다음 단계를 따르세요.

Avro 가져오기 기본 요건

Avro 가져오기를 시작하기 전에 환경이 다음 요구사항을 충족하는지 확인합니다.

대상 데이터베이스를 만들었습니다.
가져오려는 스키마 객체가 데이터베이스에 아직 없습니다. Avro 가져오기 프로세스는 데이터를 가져오기 전에 이러한 테이블을 만듭니다.

Avro 가져오기 안내

내보낸 데이터가 포함된 폴더의 경로를 식별합니다. 폴더에는 다음이 포함됩니다.

spanner-export.json 파일
내보낸 각 항목 (예: 테이블, 시퀀스, 스키마)의 ENTITY_NAME-manifest.json 파일
매니페스트 파일에 나열된 모든 Avro 파일

데이터 스토어를 외부 스토리지로 이미 추가한 경우 경로에 사용자 인증 정보를 포함할 필요가 없습니다. 경로를 직접 제공할 수 있습니다. 일회성 사용자 인증 정보를 사용하는 경우 다음 URL 형식을 사용합니다.

Cloud Storage: gs://BUCKET_NAME/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY]. HMAC 사용자 인증 정보를 사용합니다. 자세한 내용은 HMAC 키를 참조하세요.
Amazon S3: s3://S3_BUCKET/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY[&sessiontoken=SESSION_TOKEN]]
로컬 파일 폴더*: file:///PATH_TO_DIR

가져오기를 시작하려면 다음 명령어를 실행하세요.

spanner databases import DATABASE_ID --url="URL" --format=avro [--avro-skip-wait-for-index-creation]

기타 참고사항

Avro 파일을 가져올 때 다음 정보를 고려하세요.

Spanner 문서의 생성 열 및 변경 내역 가져오기 참고사항
Spanner 문서의 시퀀스 가져오기 참고사항
Spanner 문서의 인터리브 처리된 테이블 및 외래 키 가져오기 참고사항
특정 항목 가져오기를 건너뛰려면 spanner-export.json 파일에서 삭제합니다.
대규모 데이터 세트의 경우 색인을 만드는 데 상당한 시간이 걸릴 수 있습니다. 색인 생성을 기다리지 않으려면 선택사항인 --avro-skip-wait-for-index-creation 플래그를 사용하세요.

가져오기 작업이 성공적으로 시작되면 장기 실행 작업 ID가 반환됩니다. 이 ID를 사용하여 작업 상태를 추적합니다.

CSV 파일 가져오기

다른 데이터베이스에서 내보낸 텍스트 데이터를 가져오려면 다음 단계를 따르세요.

CSV 가져오기 기본 요건

CSV 가져오기를 시작하기 전에 다음을 수행해야 합니다.

테이블이 지원되는 데이터 유형 중 하나인지 확인합니다. BOOL, INT64, FLOAT64, NUMERIC, STRING, DATE, TIMESTAMP, BYTES, JSON
대상 데이터베이스를 만듭니다.
데이터를 가져오려는 모든 테이블을 만듭니다. CSV 가져오기 프로세스는 테이블을 만들지 않습니다.
CSV 파일에 헤더 행이 포함되어 있지 않은지 확인합니다.

CSV 가져오기 안내

CSV 파일을 가져오려면 가져올 데이터를 설명하는 매니페스트 파일을 만듭니다. 매니페스트 파일은 여기에 프로토콜 버퍼 형식으로 정의된 다음 구조를 사용합니다.

message ImportManifest {
  // The per-table import manifest.
  message TableManifest {
    // Required. The name of the destination table.
    string table_name = 1;
    // Required. The CSV files to import. This value can be either a path or a glob pattern.
    repeated string file_patterns = 2;
    // The schema for a table column.
    message Column {
      // Required for each column that you specify. The name of the column in the
      // destination table.
      string column_name = 1;
      // Required for each column that you specify. The type of the column.
      string type_name = 2;
    }
    // Optional. The schema for the table columns.
    repeated Column columns = 3;
  }
  // Required. The TableManifest of the tables to be imported.
  repeated TableManifest tables = 1;

  enum ProtoDialect {
    GOOGLE_STANDARD_SQL = 0;
    POSTGRESQL = 1;
  }
  // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
  ProtoDialect dialect = 2;
}

다음은 매니페스트의 예시입니다.

{
  "tables": [
    {
      "table_name": "Albums",
      "file_patterns": [
        "gs://bucket1/Albums_1.csv",
        "gs://bucket1/Albums_2.csv"
      ]
    },
    {
      "table_name": "Singers",
      "file_patterns": [
        "gs://bucket1/Singers*.csv"
      ],
      "columns": [
        {"column_name": "SingerId", "type_name": "INT64"},
        {"column_name": "FirstName", "type_name": "STRING"},
        {"column_name": "LastName", "type_name": "STRING"}
      ]
    }
  ]
}

다음 CSV 파일에 헤더 행이 포함되어 있지 않습니다.가져오기 명령어의 URL은 예시 매니페스트에 설명된 대로 JSON 형식의 매니페스트 파일이 포함된 폴더를 가리켜야 합니다. 예시 매니페스트 이 파일은 Avro 가져오기 안내에 설명된 것과 동일한 사용자 인증 정보 URL 형식을 사용하여 Cloud Storage, Amazon S3 또는 로컬 파일 폴더에 있을 수 있습니다. 가져오기를 시작하려면 다음 명령어를 실행하세요.

spanner databases import DATABASE_ID --url="URL" --format=csv

CSV 가져오기 옵션

다음 플래그를 사용하여 Spanner Omni에서 텍스트 파일을 처리하는 방식을 맞춤설정합니다.

--csv-date-format: 날짜 열의 형식을 재정의합니다. 기본값은 %Y-%m-%d입니다. 예: %d/%m/%Y
--csv-timestamp-format: 타임스탬프 열의 형식을 재정의합니다. Spanner Omni에서 CSV의 형식을 지원하지 않는 경우에만 이 옵션을 사용합니다. 예: %d/%m/%Y %H:%M:%S%Ez
--csv-delimiter: 구분 기호 문자를 재정의합니다. 기본값은 쉼표입니다.
--csv-quote-char: 따옴표 문자를 재정의합니다. 기본값은 큰따옴표입니다.
--csv-escape-char: 이스케이프 문자를 재정의합니다. 기본값은 큰따옴표입니다.
--csv-null-string: NULL 값을 나타내는 문자열을 재정의합니다. 기본값은 \N입니다.
--csv-has-trailing-delimiters: CSV 파일에 후행 구분 기호가 있는지 지정합니다. 기본값은 false입니다.

Avro 파일로 내보내기

데이터를 Avro 파일로 내보내려면 Avro 가져오기 안내의 URL 형식 안내를 따르세요.

배포의 모든 서버는 제공된 데이터 스토어에 데이터를 쓸 수 있습니다. 로컬 파일 폴더를 대상으로 사용하는 경우 모든 서버가 동일한 경로에 액세스할 수 있고 병렬로 쓸 수 있는지 확인합니다.

시스템은 데이터베이스의 모든 테이블과 항목을 내보냅니다. 내보낸 데이터의 새 빈 폴더 경로를 제공해야 합니다.

내보내기를 시작하려면 다음 명령어를 실행하세요.

spanner databases export DATABASE_ID --url="URL" --format=avro

CSV 내보내기는 테이블만 지원하며 데이터베이스 스키마를 내보내지 않습니다.

CSV 파일로 내보내기

CSV 내보내기는 데이터베이스 스키마를 내보내지 않으며 테이블만 지원합니다. 데이터를 CSV 파일로 내보내려면 다음 명령어를 실행하세요.

spanner databases export DATABASE_ID --url="URL" --format=csv

문제 해결

가져오기에 실패하면 스키마 업데이트 및 가져온 데이터가 자동으로 되돌아가지 않습니다. 작업을 다시 시도하기 전에 데이터베이스를 수동으로 정리합니다.

가져오기 작업의 속도는 폴더의 파일 수, 배포에서 사용 가능한 컴퓨팅 리소스, 디스크 속도 등 여러 요인에 따라 달라집니다. 사용 가능한 리소스가 충분하면 시스템은 파일을 병렬로 가져옵니다.

데이터 가져오기 및 내보내기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.