Transferir arquivos entre o Amazon RDS para Oracle e um bucket do Amazon S3 - Amazon Relational Database Service
Requisitos e limitações das transferências de arquivosCarregar arquivos de uma instância de banco de dados do RDS para Oracle para um bucket do Amazon S3Baixar arquivos de um bucket do Amazon S3 para uma instância de banco de dados OracleMonitorar o status de uma transferência de arquivo

Transferir arquivos entre o Amazon RDS para Oracle e um bucket do Amazon S3

É possível usar um pacote rdsadmin_s3_tasks do Amazon RDS para transferir arquivos entre uma instância de banco de dados do RDS para Oracle e um bucket do Amazon S3. É possível compactar arquivos com o GZIP ao carregá-los e descompactá-los ao baixar.

Requisitos e limitações das transferências de arquivos

Antes de transferir arquivos entre a instância de banco de dados e um bucket do Amazon S3, observe o seguinte:

  • O pacote rdsadmin_s3_tasks transfere arquivos localizados em um único diretório. Não é possível incluir subdiretórios em uma transferência.

  • O tamanho máximo do objeto em um bucket do Amazon S3 é 5 TB.

  • Tarefas criadas por rdsadmin_s3_tasks são executadas de forma assíncrona.

  • É possível fazer upload de arquivos do diretório Data Pump, como DATA_PUMP_DIR, ou de qualquer diretório criado pelo usuário. Não é possível fazer upload de arquivos de um diretório usado pelos processos em segundo plano da Oracle, como os diretórios adump, bdump ou trace.

  • O limite de download é de 2 mil arquivos por chamada de procedimento para download_from_s3. Se você precisar baixar mais de 2.000 arquivos do Amazon S3, divida o download em ações separadas, com no máximo 2.000 arquivos por chamado do procedimento.

  • Se já existir um arquivo na pasta de download e você tentar baixar um arquivo com o mesmo nome, download_from_s3 vai ignorar o download. Para remover um arquivo do diretório de downloads, use o procedimento PL/SQL UTL_FILE.FREMOVE.

Carregar arquivos de uma instância de banco de dados do RDS para Oracle para um bucket do Amazon S3

Para carregar arquivos da instância de banco de dados para um bucket do Amazon S3, use o procedimento rdsadmin.rdsadmin_s3_tasks.upload_to_s3. Por exemplo, você pode carregar arquivos de backup do Oracle Recovery Manager (RMAN) ou arquivos do Oracle Data Pump. Para ter mais informações sobre como trabalhar com objetos, consulte o Guia do usuário do Amazon Simple Storage Service. Para ter mais informações sobre como executar backups do RMAN, consulte Realização de tarefas comuns do RMAN para instâncias de banco de dados Oracle.

O procedimento rdsadmin.rdsadmin_s3_tasks.upload_to_s3 tem os seguintes parâmetros.

Nome do parâmetro Tipo de dados Padrão Obrigatório Descrição

p_bucket_name

VARCHAR2

–

obrigatório

O nome do bucket do Amazon S3 no qual fazer o upload de arquivos.

p_directory_name

VARCHAR2

–

obrigatório

O nome do objeto de diretório Oracle do qual carregar arquivos. O diretório pode ser qualquer objeto de diretório criado pelo usuário ou o diretório Data Pump, como DATA_PUMP_DIR. Não é possível fazer upload de arquivos de um diretório usado pelos processos em segundo plano, como adump, bdump e trace.

nota

Você só pode fazer o upload de arquivos do diretório especificado. Não é possível fazer upload de arquivos em subdiretórios no diretório especificado.

p_s3_prefix

VARCHAR2

–

obrigatório

Um prefixo de nome de arquivo do Amazon S3 no qual os arquivos são carregados. Um prefixo vazio faz upload de todos os arquivos para o nível superior no bucket do Amazon S3 especificado e não adiciona um prefixo aos nomes de arquivos.

Por exemplo, se o prefixo for folder_1/oradb, os arquivos serão enviados em folder_1. Nesse caso, o prefixo oradb é adicionado a cada arquivo.

p_prefix

VARCHAR2

–

obrigatório

Um prefixo de nome de arquivo ao qual os nomes de arquivo devem corresponder para serem transferidos por upload. Um prefixo vazio faz upload de todos os arquivos no diretório especificado.

p_compression_level

NUMBER

0

optional

O nível de compactação do GZIP. O intervalo de valores válidos varia de 0 a 9.

  • 0: sem compactação

  • 1: compactação mais rápida

  • 9: maior compactação

p_bucket_owner_full_control

VARCHAR2

–

opcional

A configuração de controle de acesso do bucket. Os únicos valores válidos são nulo ou FULL_CONTROL. Essa configuração será necessária somente se você carregar arquivos de uma conta (conta A) em um bucket de propriedade de uma conta diferente (conta B), e a conta B precisar ter controle total dos arquivos.

O valor de retorno do procedimento rdsadmin.rdsadmin_s3_tasks.upload_to_s3 é um ID de tarefa.

O exemplo a seguir faz upload de todos os arquivos do diretório DATA_PUMP_DIR no bucket do Amazon S3 chamado amzn-s3-demo-bucket. Os arquivos não são compactados.

SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
      p_bucket_name    =>  'amzn-s3-demo-bucket',
      p_prefix         =>  '', 
      p_s3_prefix      =>  '', 
      p_directory_name =>  'DATA_PUMP_DIR') 
   AS TASK_ID FROM DUAL;

O exemplo a seguir faz upload todos os arquivos com o prefixo db no diretório DATA_PUMP_DIR para o bucket do Amazon S3 denominado amzn-s3-demo-bucket. O Amazon RDS aplica o nível mais alto de compactação GZIP aos arquivos.

SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
      p_bucket_name       =>  'amzn-s3-demo-bucket', 
      p_prefix            =>  'db', 
      p_s3_prefix         =>  '', 
      p_directory_name    =>  'DATA_PUMP_DIR',
      p_compression_level =>  9) 
   AS TASK_ID FROM DUAL;

O exemplo a seguir carrega todos os arquivos do diretório DATA_PUMP_DIR no bucket do Amazon S3 chamado amzn-s3-demo-bucket. Os arquivos são carregados em uma pasta dbfiles. Neste exemplo, o nível de compactação GZIP é 1, que é o nível de compactação mais rápido.

SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
      p_bucket_name       =>  'amzn-s3-demo-bucket', 
      p_prefix            =>  '', 
      p_s3_prefix         =>  'dbfiles/', 
      p_directory_name    =>  'DATA_PUMP_DIR',
      p_compression_level =>  1) 
   AS TASK_ID FROM DUAL;

O exemplo a seguir faz upload todos os arquivos no diretório DATA_PUMP_DIR para o bucket do Amazon S3 denominado amzn-s3-demo-bucket. Os arquivos são carregados em uma pasta dbfiles e ora é adicionado ao início de cada nome de arquivo. Nenhuma compactação é aplicada.

SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
      p_bucket_name    =>  'amzn-s3-demo-bucket', 
      p_prefix         =>  '', 
      p_s3_prefix      =>  'dbfiles/ora', 
      p_directory_name =>  'DATA_PUMP_DIR') 
   AS TASK_ID FROM DUAL;

O exemplo a seguir pressupõe que o comando é executado na conta A, mas a conta B requer o controle total do conteúdo do bucket. O comando rdsadmin_s3_tasks.upload_to_s3 transfere todos os arquivos no diretório DATA_PUMP_DIR para o bucket chamados3bucketOwnedByAccountB. O controle de acesso está definido como FULL_CONTROL para que a conta B possa acessar os arquivos no bucket. O nível de compactação GZIP é 6, o que equilibra a velocidade e o tamanho do arquivo.

SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
      p_bucket_name               =>  's3bucketOwnedByAccountB', 
      p_prefix                    =>  '', 
      p_s3_prefix                 =>  '', 
      p_directory_name            =>  'DATA_PUMP_DIR',
      p_bucket_owner_full_control =>  'FULL_CONTROL',
      p_compression_level         =>  6) 
   AS TASK_ID FROM DUAL;

Em cada exemplo, a instrução SELECT retorna o ID da tarefa em um tipo de dados VARCHAR2.

Você pode visualizar o resultado exibindo o arquivo de saída da tarefa.

SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));

Substitua task-id pelo ID da tarefa retornado pelo procedimento.

nota

As tarefas são executadas de forma assíncrona.

Baixar arquivos de um bucket do Amazon S3 para uma instância de banco de dados Oracle

Para baixar arquivos de um bucket do Amazon S3 para uma instância do RDS para Oracle, use o procedimento rdsadmin.rdsadmin_s3_tasks.download_from_s3 do Amazon RDS.

O procedimento download_from_s3 tem os seguintes parâmetros.

Nome do parâmetro Tipo de dados Padrão Obrigatório Descrição

p_bucket_name

VARCHAR2

–

Obrigatório

O nome do bucket do Amazon S3 do qual baixar arquivos.

p_directory_name

VARCHAR2

–

Obrigatório

O nome do objeto de diretório Oracle no qual baixar arquivos. O diretório pode ser qualquer objeto de diretório criado pelo usuário ou o diretório Data Pump, como DATA_PUMP_DIR.

p_error_on_zero_downloads

VARCHAR2

 FALSE

Opcional

Um sinalizador que determina se a tarefa gera um erro quando nenhum objeto no bucket do Amazon S3 corresponde ao prefixo. Se esse parâmetro não estiver definido ou estiver definido como FALSE (padrão), a tarefa imprimirá uma mensagem de que nenhum objeto foi encontrado, mas não vai gerar uma exceção nem uma falha. Se esse parâmetro for TRUE, a tarefa vai gerar uma exceção e ocorrerá uma falha.

Exemplos de especificações de prefixo que podem falhar nos testes de correspondência são espaços em prefixos, como em ' import/test9.log', e incompatibilidade de maiúsculas e minúsculas, como em test9.log e test9.LOG.

p_s3_prefix

VARCHAR2

–

Obrigatório

Um prefixo de nome de arquivo ao qual os nomes de arquivo devem corresponder para serem baixados. Um prefixo vazio baixa todos os arquivos de nível superior no bucket do Amazon S3 especificado, mas não os arquivos nas pastas do bucket.

O procedimento baixa objetos Amazon S3 somente da pasta de primeiro nível que corresponde ao prefixo. Estruturas de diretório aninhadas que correspondem ao prefixo especificado não são baixados.

Por exemplo, suponha que um bucket do Amazon S3 tenha a estrutura de pastas folder_1/folder_2/folder_3. Especifique o prefixo 'folder_1/folder_2/'. Nesse caso, somente os arquivos em folder_2 são baixados, e não os arquivos em folder_1 ou folder_3.

Em vez disso, se você especificar o prefixo 'folder_1/folder_2', todos os arquivos em folder_1 que correspondem ao prefixo 'folder_2' são baixados, e nenhum arquivo em folder_2 é baixado.

p_decompression_format

VARCHAR2

–

Opcional

O formato da descompactação. Os valores válidos são NONE para sem descompactação e GZIP para descompactação.

O valor de retorno do procedimento rdsadmin.rdsadmin_s3_tasks.download_from_s3 é um ID de tarefa.

O exemplo a seguir baixa todos os arquivos no bucket do Amazon S3 denominado amzn-s3-demo-bucket para o diretório DATA_PUMP_DIR. Os arquivos não são compactados, portanto, nenhuma descompactação é aplicada.

SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
      p_bucket_name    =>  'amzn-s3-demo-bucket',
      p_directory_name =>  'DATA_PUMP_DIR') 
   AS TASK_ID FROM DUAL;

O exemplo a seguir baixa todos os arquivos com o prefixo db no bucket do Amazon S3 denominado amzn-s3-demo-bucket para o diretório DATA_PUMP_DIR. Os arquivos são compactados com GZIP, portanto, nenhuma descompactação é aplicada. O parâmetro p_error_on_zero_downloads ativa a verificação de erros de prefixo, portanto, se o prefixo não corresponder a nenhum arquivo no bucket, a tarefa vai gerar uma exceção e ocorrerá uma falha.

SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
      p_bucket_name               =>  'amzn-s3-demo-bucket', 
      p_s3_prefix                 =>  'db', 
      p_directory_name            =>  'DATA_PUMP_DIR',
      p_decompression_format      =>  'GZIP',
      p_error_on_zero_downloads   =>  'TRUE') 
   AS TASK_ID FROM DUAL;

O exemplo a seguir baixa todos os arquivos da pasta myfolder/ no bucket do Amazon S3 denominado amzn-s3-demo-bucket para o diretório DATA_PUMP_DIR. Use o parâmetro p_s3_prefix para especificar a pasta Amazon S3. Os arquivos carregados são compactados com o GZIP, mas não são descompactados durante o download. 

SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
      p_bucket_name          =>  'amzn-s3-demo-bucket', 
      p_s3_prefix            =>  'myfolder/', 
      p_directory_name       =>  'DATA_PUMP_DIR',
      p_decompression_format =>  'NONE')
   AS TASK_ID FROM DUAL;

O exemplo a seguir baixa o arquivo mydumpfile.dmp no bucket do Simple Storage Service (Amazon S3) denominado amzn-s3-demo-bucket para o diretório DATA_PUMP_DIR. Nenhuma descompactação é aplicada.

SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
      p_bucket_name    =>  'amzn-s3-demo-bucket', 
      p_s3_prefix      =>  'mydumpfile.dmp', 
      p_directory_name =>  'DATA_PUMP_DIR') 
   AS TASK_ID FROM DUAL;

Em cada exemplo, a instrução SELECT retorna o ID da tarefa em um tipo de dados VARCHAR2.

Você pode visualizar o resultado exibindo o arquivo de saída da tarefa.

SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));

Substitua task-id pelo ID da tarefa retornado pelo procedimento.

nota

As tarefas são executadas de forma assíncrona.

Você pode usar o procedimento UTL_FILE.FREMOVE do Oracle para remover arquivos de um diretório. Para ter mais informações, consulte Procedimento FREMOVE na documentação da Oracle.

Monitorar o status de uma transferência de arquivo

Tarefas de transferência de arquivo de publicar eventos do Amazon RDS quando eles começam e quando são concluídos. A mensagem do evento contém o ID da tarefa para a transferência de arquivos. Para obter informações sobre como visualizar eventos, consulte Visualizar eventos do Amazon RDS.

Você pode visualizar o status de uma tarefa em andamento em um arquivo bdump. Os arquivos bdump estão localizados no diretório /rdsdbdata/log/trace. Cada nome de arquivo bdump está no seguinte formato.

dbtask-task-id.log

Substitua task-id pelo ID da tarefa que você deseja monitorar.

nota

As tarefas são executadas de forma assíncrona.

Você pode usar o procedimento armazenado rdsadmin.rds_file_util.read_text_file para ver o conteúdo dos arquivos bdump. Por exemplo, a consulta a seguir retorna o conteúdo do arquivo bdump dbtask-1234567890123-1234.log.

SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-1234567890123-1234.log'));

O exemplo a seguir mostra o arquivo de log de uma falha na transferência.

TASK_ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1234567890123-1234


TEXT                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
2023-04-17 18:21:33.993 UTC [INFO ] File #1: Uploading the file /rdsdbdata/datapump/A123B4CDEF567890G1234567890H1234/sample.dmp to Amazon S3 with bucket name amzn-s3-demo-bucket and key sample.dmp.
2023-04-17 18:21:34.188 UTC [ERROR] RDS doesn't have permission to write to Amazon S3 bucket name amzn-s3-demo-bucket and key sample.dmp.
2023-04-17 18:21:34.189 UTC [INFO ] The task failed.