# 将数据加载到 Aurora DSQL 中
无论您是从现有数据库进行迁移、从 Amazon Simple Storage Service 导入文件，还是从本地系统加载数据，Aurora DSQL 都提供了多种方法来获取数据。本节介绍适用于各种大小（从千兆字节到数百 TB）的数据加载的推荐工具和技术。
## 选择加载方法
Aurora DSQL 支持标准 PostgreSQL 数据加载命令，但是大规模高效加载数据需要处理并行化、连接管理和错误恢复。下表汇总了您的选项：
| 方法 | 适用于 | 注意事项 |
| --- | --- | --- |
| Aurora DSQL 加载器：开源实用程序，可在使用 Aurora DSQL 时轻松并行处理插入 | 大多数数据加载场景，尤其是迁移和批量导入 | 自动处理并行化、连接池、冲突解决和 IAM 身份验证。以源代码或二进制形式提供。 |
| PostgreSQL \\copy：客户端 psql 元命令 | 当您已经通过 psql 进行连接时，加载过程很简单 | 读取客户端上的文件并通过连接流式传输数据；您自行管理并行化 |
| INSERT 事务：标准 SQL DML | 小型数据集或应用程序驱动的插入 | 处理批量数据的方法最简单，但速度最慢 |
对于大多数数据加载任务，请使用 Aurora DSQL 加载器。它可以处理将数据加载到分布式数据库中的操作复杂性，包括跨多个连接并行执行和自动重试失败的操作。
## Aurora DSQL 加载器
[Aurora DSQL Loader](https://github.com/aws-samples/aurora-dsql-loader) 是一个开源命令行实用程序，旨在高效地将数据加载到 Aurora DSQL 集群中。它管理连接池，并行处理多个工作线程之间的数据传输，并自动处理冲突和重试。
### 主要 功能
Aurora DSQL 加载器提供以下功能：
**并行加载**
可配置的工作线程支持跨多个连接并行加载数据，从而提高性能。
**连接池**
管理与 Aurora DSQL 集群的连接池，自动处理 IAM 身份验证和连接生命周期。
**多种文件格式支持**
支持 CSV（逗号分隔值）、TSV（制表符分隔值）和 Apache Parquet 列式格式。加载器会根据源 URI 扩展名自动检测文件格式。
**自动架构推理**
与 `--if-not-exists` 标志一起使用时，加载器可以根据数据自动创建具有适当列类型的表。
**冲突处理**
当目标表具有唯一约束时，使用以下 `--on-conflict` 选项配置加载器处理冲突的方式：跳过重复项、更新插入记录或返回错误。
**容错能力**
自动重试和任务恢复功能可确保中断的加载可以从其停止点继续，而不是完全重新开始。
**本地和 S3 源**
从本地文件系统路径或使用 S3 URI 直接从 Amazon S3 存储桶加载数据。
### 先决条件
在使用 Aurora DSQL 加载器之前，请确保您拥有以下各项：
+ 具有有效端点的活动 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 加载器的常见使用案例。
**Example 加载本地 CSV 文件**
此示例将 CSV 文件从本地文件系统加载到现有表中：
```
aurora-dsql-loader load \
--endpoint {{cluster-id}}.dsql.{{region}}.on.aws \
--source-uri {{data.csv}} \
--table {{my_table}}
```
**Example 从 Simple Storage Service（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` 以执行更新插入。
### 命令行选项
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 处理大型数据集**：与 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 加载器加载导出的数据：
```
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 身份对源对象拥有 `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 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