이 페이지는 Cloud Translation API를 통해 번역되었습니다.

CSV 파일 내보내기

이 페이지에서는 PostgreSQL용 AlloyDB 클러스터에서 다른 도구와 환경에서 사용할 수 있는 CSV 형식으로 Cloud Storage 버킷으로 데이터를 내보내는 방법을 설명합니다.

지원되는 데이터베이스 서버에서 새 AlloyDB 인스턴스로 전체 데이터베이스를 마이그레이션하는 방법에 관한 자세한 내용은 Database Migration Service를 사용하여 데이터베이스를 AlloyDB로 마이그레이션을 참고하세요. 내보낸 파일에서 새 인스턴스를 만들기 위해 내보내려는 경우 저장된 백업에서 클러스터를 복원하는 것이 좋습니다.

PostgreSQL용 AlloyDB 클러스터에서 데이터 내보내기를 취소할 수 있습니다. 자세한 내용은 데이터 내보내기 취소를 참고하세요.

시작하기 전에

내보내기 작업을 시작하기 전에 내보내기 작업은 데이터베이스 리소스를 사용하지만 인스턴스가 프로비저닝되지 않는 한 표준 데이터베이스 작업에 지장을 주지 않는다는 점에 유의하세요.
SELECT_QUERY에는 주석이나 선행 및 후행 공백이 포함될 수 있습니다. 내보내기 쿼리를 실행하기 전에 주석은 무시되고 공백은 잘립니다.
대상 버킷이 소스 클러스터와 다른 리전에 있는 경우 리전 간 데이터 전송 요금이 적용됩니다. 자세한 내용은 PostgreSQL용 AlloyDB 가격 책정을 참고하세요.
여러 내보내기 작업을 동시에 실행할 수 있습니다.
객체 이름이 .gz 확장자로 끝나는 경우 압축이 사용 설정됩니다. 그런 다음 객체가 .gz 형식으로 Cloud Storage로 내보내집니다.
field_delimiter, quote_character, escape_character과 같은 CSV 옵션의 문자 값에는 16진수 코드의 ASCII 문자 (0x 접두사 유무와 관계없음)만 허용됩니다.

AlloyDB에서 내보내기에 필요한 역할 및 권한

AlloyDB에서 Cloud Storage로 데이터를 내보내려면 내보내기를 시작하는 사용자에게 다음 Identity and Access Management (IAM) 역할 중 하나가 있어야 합니다.

Cloud AlloyDB 관리자(roles/alloydb.admin) 역할
다음 권한이 포함된 맞춤 역할:
- alloydb.clusters.get
- alloydb.clusters.export

또한 AlloyDB 클러스터의 서비스 계정에는 다음 역할 중 하나가 있어야 합니다.

storage.objectAdmin IAM 역할
다음 권한이 포함된 맞춤 역할:
- storage.objects.create

IAM 역할에 대한 도움말은 Identity and Access Management를 참고하세요.

CSV 파일로 데이터 내보내기

CSV 내보내기 도중에 내보낼 스키마를 지정할 수 있습니다. 데이터베이스 수준의 모든 스키마는 내보낼 수 있습니다.

gcloud CLI 또는 REST API를 사용하여 CSV 파일 형식을 맞춤설정할 수 있습니다.

gcloud

Cloud Storage 버킷 생성
서비스 계정에 내보내기 작업을 위한 Cloud Storage 버킷에 대한 권한을 부여합니다. 서비스 계정 형식을 사용하여 내보내는 프로젝트의 서비스 계정을 식별합니다. 서비스 계정의 형식은 다음과 같습니다.
```
service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
gcloud storage buckets add-iam-policy-binding을 사용하여 서비스 계정에 storage.objectAdmin IAM 역할을 부여합니다. IAM 권한 설정에 대한 도움말은 IAM 권한 사용을 참고하세요.

참고: 기존 객체의 이름이 Cloud Storage 버킷으로 내보내는 객체의 이름과 동일한 경우 서비스 계정에 objectAdmin 역할을 부여하면 이전 객체가 대체됩니다. 이를 방지하려면 서비스 계정에 기존 객체를 대체할 수 없는 권한이 낮은 storage.objectCreator 권한을 부여하면 됩니다.
데이터베이스를 Cloud Storage 버킷으로 내보냅니다.

CSV 내보내기 명령어(TODOgcloud alloydb clusters export)를 실행합니다.

다음 표에는 CSV 형식으로 데이터를 내보내는 옵션이 나와 있습니다.
- --select-query (필수): 데이터를 추출하는 데 사용된 선택 쿼리입니다.
참고: 전송 중에 대상 인스턴스의 위치가 아닌 중간 위치에서 쿼리가 처리될 수 있습니다.
- --async (선택사항): 진행 중인 작업이 완료되기를 기다리지 않고 즉시 반환합니다.
- --field-delimiter (선택사항): 파일의 각 행 (줄)에서 열을 구분하는 문자를 지정합니다. 기본값은 쉼표입니다. 이 인수 값은 16진수 ASCII 코드의 문자여야 합니다.
- --quote-character (선택사항): 데이터 값을 따옴표로 묶을 때 사용할 따옴표 문자를 지정합니다. 기본값은 큰따옴표입니다. 이 인수 값은 16진수 ASCII 코드의 문자여야 합니다.
- --escape-character (선택사항): 이스케이프 처리해야 하는 데이터 문자 앞에 표시되어야 하는 문자를 지정합니다. 기본값은 --quote-character과 동일합니다. 이 인수 값은 16진수 ASCII 코드의 문자여야 합니다.
이러한 기능을 사용하려면 gcloud CLI 명령어에 이러한 옵션을 포함하세요.

그렇지 않으면 다음 명령어에서 이러한 매개변수를 삭제합니다.
```
gcloud alloydb clusters export CLUSTER_NAME
  --region=REGION
  --database=DATABASE_NAME
  --gcs-uri="gs://BUCKET_NAME/OBJECT_NAME"
  --select-query=SELECT_QUERY
  --field-delimiter=FIELD_DELIMITER
  --quote-character=QUOTE_CHARACTER
  --escape-character=ESCAPE_CHARACTER
  --csv
```
이전에 설정한 IAM 역할을 유지할 필요가 없으면 지금 취소합니다.

REST v1

내보내기에 사용할 버킷을 만듭니다.

gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_NAME>

서비스 계정 형식을 사용하여 내보내는 프로젝트의 서비스 계정을 식별합니다.

서비스 계정의 형식은 다음과 같습니다.
```
 service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
내보내기 작업을 위해 Cloud Storage 버킷에 권한을 부여해야 합니다.
gcloud storage buckets add-iam-policy-binding을 사용하여 서비스 계정에 storage.objectAdmin IAM 역할을 부여합니다. IAM 권한 설정에 대한 도움말은 IAM 권한 사용을 참고하세요.

참고: Cloud Storage 버킷에 내보내는 객체와 이름이 같은 객체가 이미 있는 경우 서비스 계정에 objectAdmin 역할을 부여하면 이전 객체가 대체됩니다. 이를 방지하려면 이미 존재하는 객체를 대체할 수 없는 권한이 낮은 storage.objectCreator 권한을 서비스 계정에 부여하면 됩니다.
데이터베이스를 내보냅니다.

다음 HTTP 메서드와 URL을 사용합니다.
```
POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export
```
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: 프로젝트 ID입니다.
- REGION: AlloyDB 클러스터가 배포되는 리전입니다.
- CLUSTER_ID: 클러스터 ID입니다.
- BUCKET_NAME: Cloud Storage 버킷 이름입니다.
- PATH_TO_CSV_FILE: CSV 파일의 경로입니다.
- DATABASE_NAME: AlloyDB 클러스터 내 데이터베이스의 이름입니다.
- SELECT_QUERY: 내보내기를 위한 SQL 쿼리입니다.
  
  참고: 전송 중에 대상 인스턴스의 위치가 아닌 중간 위치에서 쿼리가 처리될 수 있습니다.
- ESCAPE_CHARACTER (선택사항): 이스케이프 처리되어야 하는 데이터 문자 앞에 표시되어야 하는 문자입니다. 이 인수 값은 16진수 ASCII 코드의 문자여야 합니다. 예를 들어 22는 큰따옴표를 나타냅니다.
- QUOTE_CHARACTER (선택사항): 문자열 데이터 유형이 있는 열의 값을 묶는 문자입니다. 이 인수 값은 16진수 ASCII 코드의 문자여야 합니다. 예를 들어 22는 큰따옴표를 나타냅니다.
- FIELD_DELIMITER (선택사항): 열 값을 분할하는 문자입니다. 이 인수 값은 16진수 ASCII 코드의 문자여야 합니다. 예를 들어 2C는 쉼표를 나타냅니다.
JSON 요청 본문:
```
{
  "gcs_destination": {
    "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE"
  },
  "database": "DATABASE_NAME",
  "csv_export_options": {
    "select_query": "SELECT_QUERY",
    "escape_character": "ESCAPE_CHARACTER",
    "quote_character": "QUOTE_CHARACTER",
    "field_delimiter": "FIELD_DELIMITER"
  }
}
```
요청을 보내려면 다음 옵션 중 하나를 사용하세요.

cURL(Linux, macOS, Cloud Shell)

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

       curl -X POST \
             -H "Authorization: Bearer $(gcloud auth print-access-token)" \
             -H "Content-Type: application/json; charset=utf-8" \
             -d @request.json \
             "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export"

PowerShell(Windows)

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
      -Method POST `
      -Headers $headers `
      -ContentType: "application/json; charset=utf-8" `
      -InFile request.json `
      -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export"| Select-Object -Expand Content

다음과 유사한 JSON 응답이 표시됩니다.

응답

    {
     "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
     "metadata": {
      "@type": "type.googleapis.com/google.cloud.alloydb.v1.OperationMetadata",
      "createTime": "2024-09-17T06:05:31.244428646Z",
      "target": "projects/PROJECT_ID/locations/REGION/clusters/TARGET_CLUSTER",
      "verb": "export",
      "requestedCancellation": false,
      "apiVersion": "v1"
     },
     "done": false
    }

이전에 설정한 IAM 권한을 유지할 필요가 없으면 지금 삭제합니다.

이 요청에서 사용 가능한 매개변수의 전체 목록은 clusters:export를 참고하세요.

CSV 내보내기 파일 형식 맞춤설정

gcloud CLI 또는 REST API를 사용하여 CSV 파일 형식을 맞춤설정할 수 있습니다. 내보내기를 수행할 때 다음 형식 지정 옵션을 지정할 수 있습니다.

CSV 옵션	기본값	gcloud 플래그	REST API 속성	설명
이스케이프	기본값은 `QUOTE` 값과 동일합니다.	`--escape-character`	`escape_character`	이스케이프 처리해야 하는 데이터 문자 앞에 표시되는 문자입니다.
견적	`"22"` 큰따옴표의 ASCII 16진수 코드입니다.	`--quote-character`	`quote_character`	데이터 값을 따옴표로 묶을 때 사용할 따옴표 문자를 지정합니다.
필드 구분 기호	`"2C"` 쉼표의 ASCII 16진수 코드입니다.	`--field-delimiter`	`field_delimiter`	열 값을 분할하는 문자입니다.

예를 들어 이러한 인수를 모두 사용하는 gcloud CLI 명령어는 다음과 비슷하게 표시될 수 있습니다.

gcloud alloydb clusters export CLUSTER_NAME \
--region=REGION \
--database=DATABASE_NAME \
--gcs-uri='gs://BUCKET_NAME/PATH_TO_CSV_FILE' \
--select-query=SELECT_QUERY \
--field-delimiter='2C' \
--quote-character='22' \
--escape-character='5C'
--csv

이에 상응하는 REST API 요청 본문은 다음과 유사합니다.

{
 "exportContext":
   {
      "gcs_destination": {
        "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE",
      },
      "database": "DATABASE_NAME",
      "csv_export_options":
       {
           "select_query": "SELECT_QUERY",
           "escape_character": "5C",
           "quote_character": "22",
           "field_delimiter": "2C",
       }
   }
}

기본적으로 CSV 내보내기는 표준 CSV 출력을 만듭니다. AlloyDB에서 제공하는 것보다 더 많은 옵션이 필요한 경우 psql 클라이언트에서 다음 문을 사용할 수 있습니다.

     \copy `TABLE_NAME` TO `CSV_FILE_NAME.csv' WITH
          (FORMAT csv, ESCAPE 'ESCAPE_CHARACTER', QUOTE 'QUOTE_CHARACTER',
          DELIMITER 'DELIMITER_CHARACTER', ENCODING 'UTF8', NULL 'NULL_MARKER_STRING');

다음 단계

SQL 덤프 파일을 내보내는 방법을 알아보세요.
내보내기 작업 취소