本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 將資料載入 Aurora DSQL
無論您是從現有的資料庫遷移、從 Amazon Simple Storage Service 匯入檔案，還是從本機系統載入資料，Aurora DSQL 都會提供多種方法來取得您的資料。本節涵蓋所有大小資料載入的建議工具和技術，從 GB 到數百 TB。
## 選擇載入方法
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 來源**
使用 Amazon S3 S3 儲存貯體載入資料。 URIs
### 先決條件
使用 Aurora DSQL Loader 之前，請確定您有下列項目：
+ 具有有效端點的作用中 Aurora DSQL 叢集。
+ AWS 透過 AWS CLI (**aws configure**)、 AWS 單一登入 (**aws sso login**) 或 IAM 角色設定的憑證。
+ IAM 許可： `dsql:DbConnectAdmin`或 Aurora DSQL 叢集`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** – 相較於 CSV 或 TSV，Parquet 的單欄格式通常會為大型資料集提供更好的壓縮和更快的載入。
+ **保留資訊清單目錄** – 保留載入任務的資訊清單目錄，直到您確認載入成功完成，以便在需要時恢復。
+ **盡可能預先建立資料表** – 在載入資料之前，使用明確的資料欄資料類型和主索引鍵定義目標資料表。預先建立的結構描述可讓您控制類型精確度和索引，相較於自動推斷結構描述，這通常會產生更好的查詢效能。
### 疑難排解
身分驗證錯誤
確認您的 AWS 登入資料設定正確，且您的 IAM 身分在目標叢集上具有必要的 `dsql:DbConnect`或 `dsql:DbConnectAdmin`許可。
S3 存取錯誤
確保您的 IAM 身分具有來源儲存貯體和物件的適當 S3 讀取許可。
結構描述推論錯誤
使用 時`--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`或 等工具**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 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 URIs：
```
aurora-dsql-loader load \
--endpoint {{cluster-id}}.dsql.{{region}}.on.aws \
--source-uri s3://{{my-bucket}}/{{path/to/data.parquet}} \
--table {{my_table}}
```
確保您的 IAM 身分具有來源物件的`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 時，請遵循下列實務來改善輸送量和可靠性：
+ **將資料列批次成多列 INSERTs**將多列分組成單一`INSERT`陳述式，以減少往返。例如， `INSERT INTO my_table VALUES (1, 'a'), (2, 'b'), (3, 'c')` 比三個單獨的陳述式更有效率。
+ **使用參數化查詢** – 使用預備陳述式搭配參數繫結，而非字串串連。這可避免 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