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 é 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. 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.

Exemplos de uso

Os exemplos a seguir demonstram casos de uso comuns do Aurora DSQL Loader.

exemplo 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

exemplo 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

exemplo 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

exemplo 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

exemplo 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

nota

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.

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);

2. 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.

3. 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';

2. Crie a tabela de destino no Aurora DSQL com os tipos de dados apropriados compatíveis com o PostgreSQL.

3. 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.

exemplo 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: código-fonte, documentação e rastreamento de problemas

• Gerar um token de autenticação no Amazon Aurora DSQL: saiba mais sobre tokens de autenticação do IAM para o Aurora DSQL

• Acessar o Aurora DSQL com clientes compatíveis com o PostgreSQL: conecte-se ao Aurora DSQL usando vários clientes e ferramentas