# Aurora DSQL へのデータのロード
既存のデータベースから移行する場合も、Amazon Simple Storage Service からファイルをインポートする場合も、ローカルシステムからデータをロードする場合も、Aurora DSQL はデータを取得するための複数のアプローチを提供します。このセクションでは、ギガバイトから数百テラバイトまでのすべてのサイズのデータロードに推奨されるツールと手法について説明します。
## ロードアプローチの選択
Aurora DSQL は標準の PostgreSQL データロードコマンドをサポートしていますが、データの大規模なロードを効率的に行うには、並列化、接続管理、エラー復旧を処理する必要があります。次の表に、オプションをまとめます。
| アプローチ | 次の用途に適しています | 考慮事項 |
| --- | --- | --- |
| Aurora DSQL Loader - Aurora DSQL の使用時に挿入を簡単に並列化できるオープンソースユーティリティ | ほとんどのデータロードシナリオ (特に移行と一括インポート) | 並列化、接続プーリング、競合解決、IAM 認証を自動的に処理します。ソースコードまたはバイナリとして使用できます。 |
| PostgreSQL \\copy - クライアント側の psql メタコマンド | psql を介して既に接続している場合の単純なロード | クライアント上のファイルを読み取り、接続経由でデータをストリーミングします。並列化は自分で管理します。 |
| INSERT トランザクション - 標準 SQL DML | 小さなデータセットまたはアプリケーション駆動型挿入 | 最もシンプルなアプローチであるが、データの一括処理は最も遅い |
ほとんどのデータロードタスクでは、Aurora DSQL Loader を使用します。複数の接続での並列実行や失敗したオペレーションの自動再試行など、分散データベースへのデータのロードに伴う運用上の複雑さを処理します。
## Aurora DSQL Loader
[Aurora DSQL Loader](https://github.com/aws-samples/aurora-dsql-loader) は、Aurora DSQL クラスターにデータを効率的にロードするように設計されたオープンソースのコマンドラインユーティリティです。接続プーリングを管理し、複数のワーカー間でデータ転送を並列化し、競合と再試行を自動的に処理します。
### 主な特徴
Aurora DSQL Loader には以下の機能があります。
**並列ロード**
設定可能なワーカースレッドにより、複数の接続間で同時データロードが可能になり、パフォーマンスが向上します。
**接続プーリング**
Aurora DSQL クラスターへの接続プールを管理し、IAM 認証と接続ライフサイクルを自動的に処理します。
**複数のファイル形式のサポート**
CSV (カンマ区切り値)、TSV (タブ区切り値)、および Apache Parquet 列形式をサポートします。ローダーは、ソース URI 拡張子に基づいてファイル形式を自動的に検出します。
**自動スキーマ推論**
`--if-not-exists` フラグとともに使用すると、ローダーはデータに基づいて適切な列タイプを持つテーブルを自動的に作成できます。
**競合処理**
ターゲットテーブルにユニーク制約がある場合、`--on-conflict` オプションを使用してローダーが競合を処理する方法 (重複をスキップする、レコードを upsert する、またはエラーを返す) を設定します。
**耐障害性**
自動再試行とジョブ再開機能により、中断されたロードを最初から開始するのではなく、停止ポイントから継続できます。
**ローカルソースと S3 ソース**
ローカルのファイルシステムパス、または S3 URI を使用して Amazon S3 バケットから直接、データをロードします。
### 前提条件
Aurora DSQL Loader を使用する前に、以下があることを確認してください。
+ 有効なエンドポイントを持つアクティブな Aurora DSQL クラスター。
+ AWS CLI (**aws configure**)、AWS シングルサインオン (**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 Loader リポジトリ](https://github.com/aws-samples/aurora-dsql-loader)」を参照してください。
### 使用例
以下の例は、Aurora DSQL Loader の一般的なユースケースを示しています。
**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` を使用してスキップしたり、`DO UPDATE` を使用して upsert したりします。
### コマンドラインオプション
Aurora DSQL Loader は、以下のコマンドラインオプションをサポートしています。
`--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 認証情報が正しく設定されていること、およびターゲットクラスターに必要な `dsql:DbConnect` アクセス許可または `dsql:DbConnectAdmin` アクセス許可を IAM ID が持っていることを確認します。
S3 アクセスエラー
ソースバケットとオブジェクトに対する適切な S3 読み取りアクセス許可を IAM ID が持っていることを確認します。
スキーマ推論エラー
`--if-not-exists` を使用する場合は、データファイルに一貫した列タイプがあることを確認してください。複数の列タイプが混在していると、スキーマ推論が失敗する可能性があります。
再開時の重複キーエラー
ロードを再開するときに重複キーエラーが発生した場合は、ターゲットテーブルにユニーク制約を追加して、ローダーが `ON CONFLICT DO NOTHING` を使用してロード済みのレコードをスキップできるようにします。
トラブルシューティングの詳細については、「[Aurora DSQL Loader 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 Loader を使用してエクスポートされたデータをロードします。
```
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` を使用するか、`--tab` オプションで **mysqldump** などのツールを使用して、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 Loader を使用してエクスポートされたデータをロードします。
```
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 Loader は 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}}
```
ソースオブジェクトに対する `s3:GetObject` アクセス許可を IAM ID が持っていることを確認します。
## 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 にする** – 複数の行を 1 つの `INSERT` ステートメントにグループ化して、ラウンドトリップを減らします。例えば、`INSERT INTO my_table VALUES (1, 'a'), (2, 'b'), (3, 'c')` は 3 つの個別のステートメントよりも効率的です。
+ **パラメータ化されたクエリを使用する** – 文字列連結ではなく、パラメータバインディングによるプリペアドステートメントを使用します。これにより、SQL インジェクションのリスクが回避され、データベースでクエリプランを再利用できます。
+ **トランザクションを小さくする** – Aurora DSQL はオプティミスティック同時実行制御を使用するため、多くの行に影響を与える大規模なトランザクションでは競合が発生する可能性が高くなります。数千行ではなく数百行のトランザクションを対象とします。
+ **再試行ロジックを実装する** – オプティミスティック同時実行制御 (OCC) の競合などの一時的なエラーが分散システムで予期されます。失敗したトランザクションを再試行してエクスポネンシャルバックオフを実装します。
+ **接続間で並列化する** — 複数の接続を開き、接続間に挿入を分散します。接続ごとにデータの異なるサブセットを同時に処理できます。
ほとんどのユースケースの場合、Aurora DSQL Loader はデータロードに対する、よりシンプルで堅牢なアプローチを提供します。
## その他のリソース
+ [GitHub の Aurora DSQL Loader](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 に接続する