# Carregar dados no Aurora DSQL Seja migrando a partir de um banco de dados existente, importando arquivos de um Amazon Simple Storage Service ou carregando dados de seu sistema local, o Aurora DSQL fornece várias abordagens para inserir seus dados. Esta seção aborda as ferramentas e técnicas recomendadas para carregamentos de dados de todos os tamanhos, de poucos gigabytes a centenas de terabytes. ## Escolher uma abordagem de migração O Aurora DSQL oferece suporte aos comandos padrão de carregamento de dados do PostgreSQL, mas carregar dados de forma eficiente em grande escala exige lidar com paralelização, gerenciamento de conexões e recuperação de erros. A seguinte tabela resume suas opções: | Abordagem | Melhor para | Considerações | | --- | --- | --- | | Aurora DSQL Loader: utilitário de código aberto que facilita a paralelização de inserções ao usar o Aurora DSQL | A maioria dos cenários de carregamento de dados, especialmente migrações e importações em massa | Lida automaticamente com paralelização, agrupamento de conexões, resolução de conflitos e autenticação do IAM. Disponível como código-fonte ou binário. | | PostgreSQL \\copy: meta-comando psql do lado do cliente | Carregamentos simples quando há conexão pelo psql | Lê arquivos no cliente e transmite dados pela conexão; você gerencia a paralelização | | Transações INSERT: SQL DML padrão | Pequenos conjuntos de dados ou inserções orientadas por aplicações | Abordagem mais simples, mas mais lenta para dados em massa | Para a maioria das tarefas de carregamento de dados, use o Aurora DSQL Loader. Ele lida com a complexidade operacional de carregar dados em um banco de dados distribuído, incluindo a execução paralela em várias conexões e a repetição automática de operações com falha. ## Aurora DSQL Loader O [Aurora DSQL Loader](https://github.com/aws-samples/aurora-dsql-loader) é um utilitário de linha de comando de código aberto projetado para carregar dados com eficiência nos clusters do Aurora DSQL. Ele gerencia o agrupamento de conexões, paraleliza a transferência de dados entre vários trabalhadores e lida com conflitos e novas tentativas automaticamente. ### Atributos principais O Aurora DSQL Loader fornece os seguintes recursos: **Carregamento paralelo** Os threads de trabalho configuráveis permitem o carregamento simultâneo de dados em várias conexões para melhorar o desempenho. **Agrupamento de conexões** Gerencia um agrupamento de conexões ao cluster Aurora DSQL, gerenciando automaticamente a autenticação do IAM e o ciclo de vida da conexão. **Suporte ao novo formato de arquivo** Compatível com CSV (valores separados por vírgula), TSV (valores separados por tabulação) e formato colunar do Apache Parquet. O carregador detecta automaticamente o formato do arquivo com base na extensão do URI de origem. **Geração automática de esquemas** Quando usado com o sinalizador `--if-not-exists`, o carregador pode criar automaticamente tabelas com os tipos de coluna apropriados com base nos dados. **Criação automática de conflitos** Quando sua tabela de destino tiver restrições exclusivas, configure como o carregador lida com conflitos usando a opção `--on-conflict`: ignorar duplicatas, atualizar registros ou retornar um erro. **Tolerância a falhas** As novas tentativas automáticas e os recursos de retomada do trabalho garantem que as cargas interrompidas possam continuar a partir do ponto de parada em vez de serem reiniciadas. **Fontes locais e do S3** Carregue dados dos caminhos do sistema de arquivos local ou diretamente dos buckets do Amazon S3 usando URIs do S3. ### Pré-requisitos Antes de usar o Aurora DSQL Loader, verifique se tem o seguinte: + Um cluster ativo do Aurora DSQL com um endpoint válido. + Credenciais da AWS configuradas por meio da AWS CLI (**aws configure**), do AWS Single Sign-On (**aws sso login**) ou perfis do IAM. + Permissões do IAM: `dsql:DbConnectAdmin` ou `dsql:DbConnect` em seu cluster Aurora DSQL. + Para fontes do S3, permissões adequadas para ler da fonte do bucket. ### Instalação Baixe a versão mais recente na página de [versões do GitHub](https://github.com/aws-samples/aurora-dsql-loader/releases/latest). Binários pré-criados estão disponíveis para plataformas comuns. Para obter instruções sobre como criar a partir do código-fonte, consulte o [repositório do Aurora DSQL Loader](https://github.com/aws-samples/aurora-dsql-loader). ### Exemplos de uso Os exemplos a seguir demonstram casos de uso comuns do Aurora DSQL Loader. **Example Carregar um arquivo CSV local** Este exemplo carrega um arquivo CSV do seu sistema de arquivos local em uma tabela existente: ``` aurora-dsql-loader load \ --endpoint {{cluster-id}}.dsql.{{region}}.on.aws \ --source-uri {{data.csv}} \ --table {{my_table}} ``` **Example Carregar dados do Amazon S3** Este exemplo carrega um arquivo Parquet de um bucket do Amazon S3: ``` aurora-dsql-loader load \ --endpoint {{cluster-id}}.dsql.{{region}}.on.aws \ --source-uri s3://{{my-bucket}}/{{data.parquet}} \ --table {{my_table}} ``` **Example Criar esquemas automaticamente** Este exemplo cria uma tabela automaticamente com base no esquema de dados: ``` aurora-dsql-loader load \ --endpoint {{cluster-id}}.dsql.{{region}}.on.aws \ --source-uri {{data.csv}} \ --table {{my_table}} \ --if-not-exists ``` **Example Validar antes do carregamento** Este exemplo valida sua configuração sem realmente carregar dados: ``` aurora-dsql-loader load \ --endpoint {{cluster-id}}.dsql.{{region}}.on.aws \ --source-uri {{data.csv}} \ --table {{my_table}} \ --dry-run ``` **Example Retomar uma instância interrompida** Se uma operação de carregamento for interrompida, você poderá retomá-la usando o ID do trabalho da execução anterior: ``` 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}} ``` Ao retomar, o carregador ignora a maior parte do trabalho já concluído, mas pode tentar novamente alguns registros. Se sua tabela de destino tiver restrições exclusivas, use a opção `--on-conflict` para lidar com duplicatas. Por exemplo, use `DO NOTHING` para ignorá-las ou `DO UPDATE` para atualizar. ### Opções de linha de comando O Aurora DSQL Loader é compatível com as seguintes opções de linha de comando: `--endpoint` (Obrigatório) O endpoint do cluster do Aurora DSQL. Exemplo: `{{cluster-id}}.dsql.{{region}}.on.aws` `--source-uri` (Obrigatório) O caminho para o arquivo de dados. Pode ser um caminho de arquivo local ou um URI do S3 (por exemplo, `s3://{{bucket-name}}/{{file.parquet}}`). `--table` (Obrigatório) O nome da tabela de destino em seu banco de dados do Aurora DSQL. `--if-not-exists` (Opcional) Cria automaticamente uma tabela de destino se ela não existir. O carregador infere o esquema a partir dos dados. `--dry-run` (Opcional) Valide a configuração e os dados sem precisar carregá-los no banco de dados. `--resume-job-id` (Opcional) Retomar uma operação de carregamento interrompida anteriormente usando o ID do trabalho especificado. `--manifest-dir` (Opcional) Diretório para armazenar o estado e os manifestos do trabalho, usado para retomada do trabalho. `--on-conflict` (Opcional) Especifica como lidar com conflitos ao inserir linhas que violam restrições exclusivas na tabela de destino. Os valores válidos são `error` (retornar um erro), `do-nothing` (ignorar linhas duplicadas) ou `do-update` (atualizar as linhas existentes com novos valores). Para obter uma lista completa de opções e parâmetros adicionais de configuração, execute: ``` aurora-dsql-loader load --help ``` ### Práticas recomendadas + **Usar dry-run para validação:** sempre teste sua configuração de carga com `--dry-run` antes de carregar os dados nas tabelas de produção. + **Definir restrições exclusivas para retomada:** se você precisar retomar cargas interrompidas, defina restrições exclusivas em suas tabelas de destino e use a opção `--on-conflict` para lidar com registros já carregados. + **Usar o Parquet para grandes conjuntos de dados:** o formato colunar do Parquet normalmente fornece melhor compactação e carregamento mais rápido para grandes conjuntos de dados em comparação com CSV ou TSV. + **Preservar diretórios do manifesto:** mantenha o diretório do manifesto para trabalhos de carregamento até confirmar que o carregamento foi concluído com êxito, permitindo a retomada, se necessário. + **Pré-criar tabelas quando possível:** defina a tabela de destino com tipos de dados de coluna explícitos e chaves primárias antes de carregar os dados. Os esquemas pré-criados oferecem controle sobre a precisão e a indexação do tipo, o que normalmente resulta em melhor desempenho de consulta em comparação aos esquemas inferidos automaticamente. ### Solução de problemas Erros de autenticação Verifique se suas credenciais da AWS estão configuradas corretamente e se sua identidade do IAM tem as permissões `dsql:DbConnect` ou `dsql:DbConnectAdmin` necessárias no cluster de destino. Erros de acesso do S3 Verifique se sua identidade do IAM tem as permissões de leitura apropriadas do S3 para o bucket e os objetos de origem. Erros de validação de esquema Ao usar `--if-not-exists`, verifique se o arquivo de dados tem tipos de coluna consistentes. Tipos mistos em uma coluna podem fazer com que a inferência do esquema falhe. Erros de chave duplicados na retomada Se você encontrar erros de chave duplicada ao retomar um carregamento, adicione restrições exclusivas à sua tabela de destino para que o carregador possa usar `ON CONFLICT DO NOTHING` para ignorar registros já carregados. Para obter informações adicionais sobre solução de problemas, consulte o [repositório do GitHub do Aurora DSQL Loader](https://github.com/aws-samples/aurora-dsql-loader). ## Caminhos de migração As seções a seguir descrevem como migrar dados de sistemas de origem comuns para o Aurora DSQL. ### Migrar do PostgreSQL Para migrar dados de um banco de dados do PostgreSQL existente para o Aurora DSQL: 1. Exporte seus dados do PostgreSQL para o formato CVS ou Parquet. Você pode usar o comando `COPY` do PostgreSQL para exportar cada tabela: ``` COPY {{my_table}} TO '{{/path/to/my_table.csv}}' WITH (FORMAT csv, HEADER true); ``` 1. Crie a tabela de destino no Aurora DSQL. Você pode criar o esquema manualmente ou usar o sinalizador `--if-not-exists` do carregador para inferir o esquema a partir dos dados. 1. Carregue os dados exportados usando o Aurora DSQL Loader: ``` aurora-dsql-loader load \ --endpoint {{cluster-id}}.dsql.{{region}}.on.aws \ --source-uri {{/path/to/my_table.csv}} \ --table {{my_table}} ``` **dica** Para migrações maiores, considere exportar para o formato Parquet para obter melhor compactação e carregamento mais rápido. Ferramentas como o DuckDB podem converter arquivos CSV em Parquet de forma eficiente. ### Migrar do MySQL Para migrar dados do MySQL para o Aurora DSQL: 1. Exporte seus dados do MySQL para o formato CSV usando `SELECT INTO OUTFILE` ou uma ferramenta como **mysqldump** com a opção `--tab`: ``` SELECT * FROM {{my_table}} INTO OUTFILE '{{/path/to/my_table.csv}}' FIELDS TERMINATED BY ',' ENCLOSED BY '"' LINES TERMINATED BY '\n'; ``` 1. Crie a tabela de destino no Aurora DSQL com os tipos de dados apropriados compatíveis com o PostgreSQL. 1. Carregue os dados exportados usando o Aurora DSQL Loader: ``` aurora-dsql-loader load \ --endpoint {{cluster-id}}.dsql.{{region}}.on.aws \ --source-uri {{/path/to/my_table.csv}} \ --table {{my_table}} ``` **nota** O MySQL e o PostgreSQL têm sistemas de tipos de dados diferentes. Revise seu esquema e ajuste os tipos de dados conforme necessário ao criar tabelas no Aurora DSQL. ### Carregar do Amazon S3 Se os dados já estão no Amazon S3, você pode armazená-los diretamente sem baixar para o sistema local. O Aurora DSQL Loader oferece suporte nativo a URIs do S3: ``` aurora-dsql-loader load \ --endpoint {{cluster-id}}.dsql.{{region}}.on.aws \ --source-uri s3://{{my-bucket}}/{{path/to/data.parquet}} \ --table {{my_table}} ``` Verifique se sua identidade do IAM tem a permissão `s3:GetObject` nos objetos de origem. ## Usar \\copy do PostgreSQL Se já estiver conectado ao Aurora DSQL por meio de uma sessão do `psql` que gerencia a autenticação do IAM, você pode usar o meta-comando `\copy` do lado do cliente para carregar dados do seu sistema de arquivos local. Ao contrário da declaração `COPY` do lado do servidor, `\copy` lê o arquivo na máquina cliente e transmite os dados pela conexão existente, portanto, nenhum acesso ao arquivo do lado do servidor é necessário. Essa abordagem funciona bem para cargas simples e de thread único. **Example Carregar um arquivo CSV com \\copy** ``` \copy {{my_table}} FROM '{{/path/to/data.csv}}' WITH (FORMAT csv, HEADER true); ``` Ao usar `\copy` diretamente, você é responsável por: + Gerenciar a paralelização ao carregar vários arquivos ou grandes conjuntos de dados + Gerenciar o gerenciamento de conexões e a atualização do token de autenticação + Implementar a lógica de nova tentativa em operações com falha ### Práticas recomendadas para transações INSERT Ao usar declarações `INSERT` para carregar dados no Aurora DSQL, siga estas práticas para melhorar a taxa de throughput e a confiabilidade: + **Agrupe linhas em INSERTs de várias linhas:** agrupe várias linhas em uma única declaração `INSERT` para reduzir viagens de ida e volta. Por exemplo, `INSERT INTO my_table VALUES (1, 'a'), (2, 'b'), (3, 'c')` é mais eficiente do que três declarações separadas. + **Use consultas parametrizadas:** use declarações preparadas com associação de parâmetros em vez de concatenação de strings. Isso evita riscos de injeção de SQL e permite que o banco de dados reutilize planos de consulta. + **Mantenha as transações pequenas:** o Aurora DSQL usa um controle otimista de simultaneidade, portanto, transações grandes que tocam muitas linhas têm maior probabilidade de encontrar conflitos. Use transações de algumas centenas de linhas em vez de milhares. + **Implemente a lógica de repetição:** erros transitórios, como conflitos de Controle de simultaneidade otimista (OCC), são esperados em um sistema distribuído. Implemente um recuo exponencial com novas tentativas para transações com falha. + **Paralelize as conexões:** abra várias conexões e distribua as inserções entre elas. Cada conexão pode processar um subconjunto diferente de dados simultaneamente. Para a maioria dos casos de uso, o Aurora DSQL Loader fornece uma abordagem mais simples e robusta para o carregamento de dados. ## Recursos adicionais + [Aurora DSQL Loader no GitHub:](https://github.com/aws-samples/aurora-dsql-loader) código-fonte, documentação e rastreamento de problemas + [Gerar um token de autenticação no Amazon Aurora DSQL](SECTION_authentication-token.md): saiba mais sobre tokens de autenticação do IAM para o Aurora DSQL + [Acessar o Aurora DSQL com clientes compatíveis com o PostgreSQL](accessing.md): conecte-se ao Aurora DSQL usando vários clientes e ferramentas