# Aurora DSQL로 데이터 로드
기존 데이터베이스에서 마이그레이션하든, Amazon Simple Storage Service에서 파일을 가져오든, 로컬 시스템에서 데이터를 로드하든, Aurora DSQL은 데이터를 가져올 수 있는 여러 접근 방식을 제공합니다. 이 섹션에서는 기가바이트에서 수백 테라바이트에 이르는 모든 규모의 데이터 로드에 권장되는 도구와 기술을 다룹니다.
## 로드 접근 방식 선택
Aurora DSQL은 표준 PostgreSQL 데이터 로드 명령을 지원하지만 대규모로 데이터를 효율적으로 로드하려면 병렬화, 연결 관리 및 오류 복구를 처리해야 합니다. 다음 표에는 사용 가능한 여러 가지 옵션이 요약되어 있습니다.
| 접근 방식 | 최적의 용도 | 고려 사항 |
| --- | --- | --- |
| Aurora DSQL 로더 - Aurora DSQL을 사용할 때 삽입을 쉽게 병렬화할 수 있는 오픈 소스 유틸리티 | 대부분의 데이터 로드 시나리오, 특히 마이그레이션 및 대량 가져오기 | 병렬화, 연결 풀링, 충돌 해결 및 IAM 인증을 자동으로 처리합니다. 소스 코드 또는 바이너리로 사용할 수 있습니다. |
| PostgreSQL \\copy - 클라이언트 측 psql 메타 명령 | psql을 통해 이미 연결된 경우의 간단한 로드 | 클라이언트에서 파일을 읽고 연결을 통해 데이터를 스트리밍합니다. 사용자가 직접 병렬화를 관리합니다. |
| INSERT 트랜잭션 - 표준 SQL DML | 소규모 데이터세트 또는 애플리케이션 기반 삽입 | 가장 간단한 접근 방식이지만 대량 데이터의 경우 가장 느림 |
대부분의 데이터 로드 작업에서 Aurora DSQL 로더를 사용하세요. 이는 여러 연결에 걸친 병렬 실행과 실패한 작업의 자동 재시도를 포함하여 분산 데이터베이스에 데이터를 로드하는 데 따른 운영상의 복잡성을 처리합니다.
## Aurora DSQL 로더
[Aurora DSQL 로더](https://github.com/aws-samples/aurora-dsql-loader)는 Aurora DSQL 클러스터에 데이터를 효율적으로 로드하도록 설계된 오픈 소스 명령줄 유틸리티입니다. 연결 풀링을 관리하고, 여러 워커 간의 데이터 전송을 병렬화하고, 충돌을 자동으로 처리하고 재시도합니다.
### 주요 기능
Aurora DSQL 로더는 다음 기능을 제공합니다.
**병렬 로드**
구성 가능한 워커 스레드를 통해 여러 연결에서 동시에 데이터를 로드하여 성능을 향상시킬 수 있습니다.
**연결 풀링**
IAM 인증 및 연결 수명 주기를 자동으로 처리하며 Aurora DSQL 클러스터에 대한 연결 풀을 관리합니다.
**다중 파일 형식 지원**
CSV(쉼표로 구분된 값), TSV(탭으로 구분된 값) 및 Apache Parquet 열 기반 형식을 지원합니다. 이 로더는 소스 URI 확장명을 기반으로 파일 형식을 자동으로 감지합니다.
**자동 스키마 추론**
`--if-not-exists` 플래그와 함께 사용할 경우 로더가 데이터에 따라 적절한 열 유형으로 테이블을 자동으로 생성할 수 있습니다.
**충돌 처리**
대상 테이블에 고유한 제약 조건이 있는 경우 `--on-conflict` 옵션을 사용하여 로더가 충돌을 처리하는 방법(중복 건너뛰기, 레코드 업서트 또는 오류 반환)을 구성합니다.
**내결함성**
자동 재시도 및 작업 재개 기능을 사용하면 중단된 로드가 처음부터 다시 시작되지 않고 중단된 지점부터 계속되도록 할 수 있습니다.
**로컬 및 S3 소스**
로컬 파일 시스템 경로에서 데이터를 로드하거나 S3 URI를 사용하여 Amazon S3 버킷에서 직접 데이터를 로드할 수 있습니다.
### 사전 조건
Aurora DSQL 로더를 사용하기 전에 다음을 갖추었는지 확인하세요.
+ 유효한 엔드포인트가 있는 활성 Aurora DSQL 클러스터.
+ AWS CLI(**aws configure**), AWS Single Sign-On(**aws sso login**) 또는 IAM 역할을 통해 구성된 AWS 자격 증명.
+ IAM 권한: Aurora DSQL 클러스터에 대한 `dsql:DbConnectAdmin` 또는 `dsql:DbConnect`.
+ S3 소스의 경우 소스 버킷에서 읽을 수 있는 적절한 권한.
### 설치
[GitHub 릴리스 페이지](https://github.com/aws-samples/aurora-dsql-loader/releases/latest)에서 최신 릴리스를 다운로드합니다. 일반적인 플랫폼용으로 미리 빌드된 바이너리가 제공됩니다. 소스에서 빌드하는 방법에 대한 지침은 [Aurora DSQL 로더 리포지토리](https://github.com/aws-samples/aurora-dsql-loader)를 참조하세요.
### 사용 예제
다음 예시에서는 Aurora DSQL 로더의 일반적인 사용 사례를 보여줍니다.
**Example 로컬 CSV 파일 로드**
이 예시에서는 로컬 파일 시스템에서 기존 테이블로 CSV 파일을 로드합니다.
```
aurora-dsql-loader load \
--endpoint {{cluster-id}}.dsql.{{region}}.on.aws \
--source-uri {{data.csv}} \
--table {{my_table}}
```
**Example Amazon S3에서 데이터 로드**
이 예시에서는 Amazon S3 버킷에서 Parquet 파일을 로드합니다.
```
aurora-dsql-loader load \
--endpoint {{cluster-id}}.dsql.{{region}}.on.aws \
--source-uri s3://{{my-bucket}}/{{data.parquet}} \
--table {{my_table}}
```
**Example 자동 테이블 생성**
이 예시에서는 데이터 스키마를 기반으로 새 테이블을 자동으로 생성합니다.
```
aurora-dsql-loader load \
--endpoint {{cluster-id}}.dsql.{{region}}.on.aws \
--source-uri {{data.csv}} \
--table {{my_table}} \
--if-not-exists
```
**Example 로드 전 검증**
이 예시에서는 데이터를 실제로 로드하지 않고 구성을 검증합니다.
```
aurora-dsql-loader load \
--endpoint {{cluster-id}}.dsql.{{region}}.on.aws \
--source-uri {{data.csv}} \
--table {{my_table}} \
--dry-run
```
**Example 중단된 로드 재개**
로드 작업이 중단되면 이전 실행의 작업 ID를 사용하여 재개할 수 있습니다.
```
aurora-dsql-loader load \
--endpoint {{cluster-id}}.dsql.{{region}}.on.aws \
--source-uri {{data.csv}} \
--table {{my_table}} \
--resume-job-id {{job-id}} \
--manifest-dir {{./loader-state}}
```
재개 시 로더는 이미 완료된 대부분의 작업을 건너뛰지만 일부 레코드를 다시 시도할 수 있습니다. 대상 테이블에 고유한 제약 조건이 있는 경우 `--on-conflict` 옵션을 사용하여 중복을 처리합니다(예: 중복을 건너뛰려면 `DO NOTHING`, upsert를 수행하려면 `DO UPDATE`).
### 명령줄 옵션
Aurora DSQL 로더는 다음 명령줄 옵션을 지원합니다.
`--endpoint`
(필수) Aurora DSQL 클러스터 엔드포인트입니다. 예시: `{{cluster-id}}.dsql.{{region}}.on.aws`
`--source-uri`
(필수) 데이터 파일의 경로입니다. 로컬 파일 경로 또는 S3 URI(예: `s3://{{bucket-name}}/{{file.parquet}}`)일 수 있습니다.
`--table`
(필수) Aurora DSQL 데이터베이스의 대상 테이블 이름입니다.
`--if-not-exists`
(선택 사항) 대상 테이블이 없는 경우 자동으로 생성됩니다. 로더는 데이터에서 스키마를 유추합니다.
`--dry-run`
(선택 사항) 실제로 데이터베이스에 로드하지 않고 구성 및 데이터를 검증합니다.
`--resume-job-id`
(선택 사항) 지정된 작업 ID를 사용하여 이전에 중단된 로드 작업을 재개합니다.
`--manifest-dir`
(선택 사항) 작업 재개에 사용되는 작업 상태 및 매니페스트를 저장하기 위한 디렉터리입니다.
`--on-conflict`
(선택 사항) 대상 테이블에서 고유한 제약 조건을 위반하는 행을 삽입할 때 충돌을 처리하는 방법을 지정합니다. 유효한 값은 `error`(오류 반환), `do-nothing`(중복된 행 건너뛰기) 또는 `do-update`(기존 행을 새 값으로 업데이트)입니다.
옵션 및 추가 구성 파라미터의 전체 목록을 보려면 다음을 실행합니다.
```
aurora-dsql-loader load --help
```
### 모범 사례
+ **검증을 위해 모의 실행 사용** - 데이터를 프로덕션 테이블에 로드하기 전에 항상 `--dry-run`을 사용하여 로드 구성을 테스트합니다.
+ **재개를 위한 고유 제약 조건 정의** - 중단된 로드를 재개해야 하는 경우 대상 테이블에 고유한 제약 조건을 정의하고 `--on-conflict` 옵션을 사용하여 이미 로드된 레코드를 처리합니다.
+ **대규모 데이터세트에 Parquet 사용** - Parquet의 열 형식은 일반적으로 CSV 또는 TSV에 비해 대규모 데이터세트에서 더 나은 압축과 더 빠른 로드를 제공합니다.
+ **매니페스트 디렉터리 보존** - 로드가 성공적으로 완료되었음을 확인할 때까지 로드 작업에 대한 매니페스트 디렉터리를 유지하여 필요한 경우 재개할 수 있도록 합니다.
+ **가능한 경우 테이블 사전 생성** - 데이터를 로드하기 전에 열 데이터 유형 및 프라이머리 키를 명시적으로 지정하여 대상 테이블을 정의합니다. 사전 생성된 스키마를 사용하면 유형 정밀도와 인덱싱을 제어할 수 있기 때문에 일반적으로 자동 추론된 스키마에 비해 쿼리 성능이 향상됩니다.
### 문제 해결
인증 오류
AWS 자격 증명이 올바르게 구성되어 있고 IAM ID에 대상 클러스터에 대해 필요한 `dsql:DbConnect` 또는 `dsql:DbConnectAdmin` 권한이 있는지 확인합니다.
S3 액세스 오류
IAM ID에 소스 버킷 및 객체에 대한 적절한 S3 읽기 권한이 있는지 확인합니다.
스키마 추론 오류
`--if-not-exists`를 사용할 때는 데이터 파일의 열 유형이 일관적인지 확인합니다. 열의 유형이 혼합되면 스키마 추론이 실패할 수 있습니다.
재개 시 중복 키 오류
로드를 재개할 때 중복 키 오류가 발생할 경우 로더가 `ON CONFLICT DO NOTHING`을 사용하여 이미 로드된 레코드를 건너뛸 수 있도록 대상 테이블에 고유한 제약 조건을 추가합니다.
추가 문제 해결 정보는 [Aurora DSQL 로더 GitHub 리포지토리](https://github.com/aws-samples/aurora-dsql-loader)를 참조하세요.
## 마이그레이션 경로
다음 섹션에서는 일반적인 소스 시스템에서 Aurora DSQL로 데이터를 마이그레이션하는 방법을 설명합니다.
### PostgreSQL에서 마이그레이션
기존 PostgreSQL 데이터베이스에서 Aurora DSQL로 데이터를 마이그레이션하는 방법:
1. PostgreSQL에서 CSV 또는 Parquet 형식으로 데이터를 내보냅니다. PostgreSQL `COPY` 명령을 사용하여 각 테이블을 내보낼 수 있습니다.
```
COPY {{my_table}} TO '{{/path/to/my_table.csv}}' WITH (FORMAT csv, HEADER true);
```
1. Aurora DSQL에서 대상 테이블을 생성합니다. 스키마를 수동으로 생성하거나 로더의 `--if-not-exists` 플래그를 사용하여 데이터에서 스키마를 유추할 수 있습니다.
1. Aurora DSQL 로더를 사용하여 내보낸 데이터를 로드합니다.
```
aurora-dsql-loader load \
--endpoint {{cluster-id}}.dsql.{{region}}.on.aws \
--source-uri {{/path/to/my_table.csv}} \
--table {{my_table}}
```
**작은 정보**
대규모 마이그레이션의 경우 더 나은 압축과 더 빠른 로드를 위해 Parquet 형식으로 내보내는 것이 좋습니다. DuckDB와 같은 도구는 CSV 파일을 Parquet으로 효율적으로 변환할 수 있습니다.
### MySQL에서 마이그레이션
MySQL에서 Aurora DSQL로 데이터를 마이그레이션하는 방법:
1. `SELECT INTO OUTFILE`을 사용하거나 **mysqldump**와 같은 도구를 `--tab` 옵션과 함께 사용하여 MySQL에서 CSV 형식으로 데이터를 내보냅니다.
```
SELECT * FROM {{my_table}}
INTO OUTFILE '{{/path/to/my_table.csv}}'
FIELDS TERMINATED BY ','
ENCLOSED BY '"'
LINES TERMINATED BY '\n';
```
1. 적절한 PostgreSQL 호환 데이터 유형을 사용하여 Aurora DSQL에서 대상 테이블을 생성합니다.
1. Aurora DSQL 로더를 사용하여 내보낸 데이터를 로드합니다.
```
aurora-dsql-loader load \
--endpoint {{cluster-id}}.dsql.{{region}}.on.aws \
--source-uri {{/path/to/my_table.csv}} \
--table {{my_table}}
```
**참고**
MySQL과 PostgreSQL은 데이터 유형 시스템이 다릅니다. Aurora DSQL에서 테이블을 생성할 때 스키마를 검토하고 필요에 따라 데이터 유형을 조정합니다.
### Amazon S3에서 로드
데이터가 이미 Amazon S3에 있는 경우 로컬 시스템에 다운로드하지 않고도 직접 로드할 수 있습니다. Aurora DSQL 로더는 S3 URI를 기본적으로 지원합니다.
```
aurora-dsql-loader load \
--endpoint {{cluster-id}}.dsql.{{region}}.on.aws \
--source-uri s3://{{my-bucket}}/{{path/to/data.parquet}} \
--table {{my_table}}
```
IAM ID에 소스 객체에 대한 `s3:GetObject` 권한이 있는지 확인합니다.
## PostgreSQL \\copy 사용
IAM 인증을 처리하는 `psql` 세션을 통해 이미 Aurora DSQL에 연결되어 있는 경우 클라이언트 측 `\copy` 메타 명령을 사용하여 로컬 파일 시스템에서 데이터를 로드할 수 있습니다. 서버 측 `COPY` 문과 달리 `\copy`는 클라이언트 시스템에서 파일을 읽고 기존 연결을 통해 데이터를 스트리밍하므로 서버 측 파일 액세스가 필요하지 않습니다. 이 접근 방식은 간단한 단일 스레드 로드에 적합합니다.
**Example \\copy를 사용하여 CSV 파일 로드**
```
\copy {{my_table}} FROM '{{/path/to/data.csv}}' WITH (FORMAT csv, HEADER true);
```
`\copy`를 직접 사용할 경우 사용자에게 다음과 같은 책임이 있습니다.
+ 여러 파일 또는 대용량 데이터세트를 로드하는 경우 병렬화 관리
+ 연결 관리 및 인증 토큰 새로 고침 처리
+ 실패한 작업에 대한 재시도 로직 구현
### INSERT 트랜잭션 모범 사례
`INSERT` 문을 사용하여 Aurora DSQL에 데이터를 로드할 때는 처리량과 신뢰성 향상을 위해 다음 모범 사례를 따르세요.
+ **여러 행을 다중 행 INSERT로 묶어 처리** - 왕복 횟수를 줄이도록 여러 행을 단일 `INSERT` 문으로 그룹화합니다. 예를 들어 `INSERT INTO my_table VALUES (1, 'a'), (2, 'b'), (3, 'c')`는 세 개의 개별 문보다 더 효율적입니다.
+ **파라미터화된 쿼리 사용** - 문자열 연결 대신 파라미터 바인딩과 함께 준비된 문을 사용합니다. 이렇게 하면 SQL 인젝션 위험이 방지되고 데이터베이스가 쿼리 계획을 재사용할 수 있습니다.
+ **트랜잭션을 작게 유지** - Aurora DSQL은 낙관적 동시성 제어를 사용하므로 많은 행을 처리하는 대규모 트랜잭션은 충돌이 발생할 가능성이 더 높습니다. 수천 행이 아닌 수백 행 정도의 트랜잭션을 목표로 하세요.
+ **재시도 로직 구현** - 분산 시스템에서는 낙관적 동시성 제어(OCC) 충돌과 같은 일시적인 오류가 발생할 수 있습니다. 실패한 트랜잭션에 대한 재시도를 통해 지수 백오프를 구현합니다.
+ **연결 간 병렬 처리** - 여러 연결을 열고 삽입을 분산 처리합니다. 각 연결은 서로 다른 데이터 하위 집합을 동시에 처리할 수 있습니다.
대부분의 사용 사례에서 Aurora DSQL 로더는 데이터 로드에 대한 더 간단하고 강력한 접근 방식을 제공합니다.
## 추가 리소스
+ [GitHub의 Aurora DSQL 로더](https://github.com/aws-samples/aurora-dsql-loader) - 소스 코드, 설명서 및 문제 추적
+ [Amazon Aurora DSQL에서 인증 토큰 생성](SECTION_authentication-token.md) - Aurora DSQL의 IAM 인증 토큰에 대한 자세한 정보
+ [PostgreSQL 호환 클라이언트를 사용하여 Aurora DSQL에 액세스](accessing.md) - 다양한 클라이언트 및 도구를 사용하여 Aurora DSQL에 연결