Exportação de dados

Nesta página, você verá como exportar dados de instâncias do Cloud SQL ou de um servidor de banco de dados não gerenciado pelo Cloud SQL.

As exportações usam recursos do banco de dados, mas não interferem nas operações normais do banco de dados, a menos que a instância tenha um provisionamento menor do que deveria ser.

Para ver as práticas recomendadas para exportação de dados, consulte Práticas recomendadas para importação e exportação de dados.

Antes de começar

Verifique se você configurou os papéis e permissões necessários. Para exportar dados para o Cloud Storage, a conta de serviço ou o usuário da instância precisa ter:

  • O papel de Editor do Cloud SQL ou um papel personalizado que inclua a permissão cloudsql.instances.export.
  • O papel do IAM roles/storage.legacyBucketWriter.
  • Se a conta de serviço ou o usuário também estiver executando operações de importação, conceda a permissão cloudsql.instances.import e o papel do IAM roles/storage.legacyObjectReader.

Para receber ajuda com os papéis do IAM, consulte Cloud Identity and Access Management para o Cloud Storage.

É possível encontrar o nome da conta de serviço da instância na página **Visão geral** da instância no Console do Google Cloud. É possível verificar os papéis do bucket do Cloud Storage usando a ferramenta gsutil para inspecionar o bucket:

gsutil iam get gs://[BUCKET_NAME]

Saiba mais sobre como usar o IAM com buckets.

Como exportar dados do Cloud SQL para um arquivo dump SQL no Cloud Storage

Ao usar o Cloud SQL para executar uma exportação, seja no Console do Cloud, na ferramenta de linha de comando gcloud ou na API, você estará usando o utilitário pg_dump com as opções necessárias para garantir que o arquivo de exportação resultante seja válido para importação no Cloud SQL.

Também é possível executar pg_dump manualmente usando o cliente psql, caso você esteja exportando para um banco de dados que não é gerenciado pelo Cloud SQL.

Se você pretende importar dados para o Cloud SQL, siga as instruções da seção Como exportar dados de um servidor de banco de dados externo para que o arquivo dump SQL seja formatado corretamente para Cloud SQL.

Para exportar dados de um banco de dados em uma instância do Cloud SQL para um arquivo dump SQL em um bucket do Cloud Storage, siga estas etapas:

Console

  1. Acesse a página "Instâncias" do Cloud SQL no Console do Google Cloud.

    Acesse a página "Instâncias" do Cloud SQL

  2. Clique na instância com os dados que você quer exportar para abrir a página Visão geral correspondente.
  3. Clique em EXPORTAR na barra de botões.
  4. Em Formato de arquivo, clique em SQL para criar um arquivo dump SQL.
  5. Na seção Dados a serem exportados, use o menu suspenso para selecionar o banco de dados de onde você quer exportar.
  6. Em Destino, selecione Procurar para pesquisar um bucket ou uma pasta do Cloud Storage para a exportação.
  7. Clique em Exportar para iniciar a exportação.

gcloud

  1. Crie um bucket do Cloud Storage, caso ainda não tenha feito isso.

    Se precisar de ajuda para criar um bucket, consulte Como criar buckets do Storage.

  2. Carregue o arquivo no seu bucket.

    Para ajuda sobre o upload de arquivos para buckets, consulte Como fazer o upload de um objeto.

  3. Descreva a instância usada para exportar:
      gcloud sql instances describe [INSTANCE_NAME]
      
  4. Copie o campo serviceAccountEmailAddress.
  5. Use gsutil iam para conceder o papel do IAM storage.objectAdmin à conta de serviço do bucket. Para ajuda com a configuração de permissões do IAM, consulte Como usar as permissões do Cloud IAM.
  6. Exporte o banco de dados:
      gcloud sql export sql [INSTANCE_NAME] gs://[BUCKET_NAME]/sqldumpfile.gz \
                                  --database=[DATABASE_NAME] --offload
      

    O comando export sql não contém gatilhos ou procedimentos armazenados, mas tem visualizações. Para exportar gatilhos e/ou procedimentos armazenados, use a ferramenta pg_dump (em inglês).

    Para mais informações sobre como usar o comando export sql, consulte a página de referência do comando sql export sql.

  7. Se você não precisar manter o papel do IAM definido anteriormente, revogue-o agora.

REST v1beta4

  1. Crie um bucket para a exportação:
    gsutil mb -p [PROJECT_NAME] -l [LOCATION_NAME] gs://[BUCKET_NAME]
    

    Essa etapa não é obrigatória, mas altamente recomendada para que você não abra acesso a outros dados.

  2. Forneça à instância o papel do IAM storage.objectAdmin no seu bucket. Para ajuda com a configuração de permissões do IAM, consulte Como usar as permissões do Cloud IAM.
  3. Exporte o banco de dados:

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • project-id: o ID do projeto
    • instance-id: o ID da instância
    • bucket_name: o nome do bucket do Cloud Storage
    • path_to_dump_file: o caminho para o arquivo dump SQL
    • database_name_1: o nome de um banco de dados dentro da instância do Cloud SQL
    • database_name_2: o nome de um banco de dados dentro da instância do Cloud SQL
    • offload: ativa a exportação sem servidor. Defina como true para usar a exportação sem servidor.

    Método HTTP e URL:

    POST https://www.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/export

    Corpo JSON da solicitação:

    {
     "exportContext":
       {
          "fileType": "SQL",
          "uri": "gs://bucket_name/path_to_dump_file",
          "databases": ["database_name"]
          "offload": true | false
        }
    }
    

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

  4. Se você não precisar manter o papel do IAM definido anteriormente, revogue-o agora.
Para ver a lista completa de parâmetros dessa solicitação, consulte a página instances:export.

Como exportar dados do Cloud SQL para um arquivo CSV no Cloud Storage

É possível exportar os dados no formato CSV, que pode ser usado por outras ferramentas e ambientes. As exportações acontecem no nível do banco de dados. Durante uma exportação de CSV, é possível especificar os esquemas que serão exportados. Todos os esquemas no nível do banco de dados estão qualificados para exportação.

Para exportar dados de um banco de dados em uma instância do Cloud SQL para um arquivo dump SQL em um bucket do Cloud Storage, faça o seguinte:

Console

  1. Acesse a página "Instâncias" do Cloud SQL no Console do Google Cloud.

    Acesse a página "Instâncias" do Cloud SQL

  2. Clique na instância para abrir a respectiva página de Visão geral.
  3. Clique em EXPORTAR.
  4. Em Local de exportação do Cloud Storage, selecione um bucket ou pasta do Cloud Storage para a exportação.
  5. No campo Nome, insira um nome para o arquivo de exportação e clique em Selecionar.

    É possível usar uma extensão de arquivo .gz para compactar o arquivo de exportação.

  6. Defina o Formato como CSV.
  7. Em Local de exportação do Cloud Storage, adicione o nome do bucket, a pasta e o arquivo que você quer exportar ou clique em Procurar para encontrar ou criar um bucket, uma pasta ou um arquivo.

    Se você clicar em Procurar:

    1. Em Local, selecione um bucket ou pasta do Cloud Storage para a exportação.
    2. Na caixa de texto Nome, adicione um nome para o arquivo CSV, ou se você criou o arquivo anteriormente, selecione-o na lista em Local.

      Use uma extensão de arquivo .gz (a extensão completa é .csv.gz) para compactar o arquivo de exportação.

    3. Clique em Selecionar.
  8. Em Formato, clique em CSV.
  9. Em Banco de dados para exportação, selecione o nome do banco de dados no menu suspenso.
  10. Em Consulta SQL, insira uma consulta SQL para especificar a tabela de onde os dados serão exportados.

    Por exemplo, para exportar todo o conteúdo da tabela entries no banco de dados guestbook, insira

    SELECT * FROM guestbook.entries;
    A consulta precisa especificar uma tabela no banco de dados. Não é possível exportar um banco de dados inteiro no formato CSV.

  11. Clique em Exportar para iniciar a exportação.
  12. A caixa de diálogo Exportar banco de dados? será aberta com uma mensagem informando que o processo pode levar uma hora ou mais para bancos de dados grandes. Durante a exportação, a única operação que pode ser executada na instância é a visualização de informações. Não será possível interromper a exportação depois que ela for iniciada. Se for um bom momento para iniciar uma exportação, clique em EXPORTAR. Caso contrário, clique em CANCELAR.

gcloud

  1. Crie um bucket do Cloud Storage, caso ainda não tenha feito isso.

    Se precisar de ajuda para criar um bucket, consulte Como criar buckets do Storage.

  2. Carregue o arquivo no seu bucket.

    Para ajuda sobre o upload de arquivos para buckets, consulte Como fazer o upload de um objeto.

  3. Descreva a instância usada para exportar:
    gcloud sql instances describe [INSTANCE_NAME]
    
  4. Use gsutil iam para conceder o papel do IAM storage.objectAdmin à conta de serviço do bucket. Para ajuda com a configuração de permissões do IAM, consulte Como usar as permissões do Cloud IAM.
  5. Exporte o banco de dados:
    gcloud sql export csv [INSTANCE_NAME] gs://[BUCKET_NAME]/[FILE_NAME] \
                                --database=[DATABASE_NAME] \
                                --offload \
                                --query=[SELECT_QUERY]
    

    Para informações sobre como usar o comando export csv, consulte a página de referência do comando sql export csv.

  6. Se você não precisar manter o papel do IAM definido anteriormente, revogue-o agora.

REST v1beta4

  1. Crie um bucket para a exportação:
    gsutil mb -p [PROJECT_NAME] -l [LOCATION_NAME] gs://[BUCKET_NAME]
    

    Essa etapa não é obrigatória, mas altamente recomendada para que você não abra acesso a outros dados.

  2. Forneça à instância o papel do IAM storage.objectAdmin no seu bucket. Para ajuda com a configuração de permissões do IAM, consulte Como usar as permissões do Cloud IAM.
  3. Exporte o banco de dados:

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • project-id: o ID do projeto
    • instance-id: o ID da instância
    • bucket_name: o nome do bucket do Cloud Storage
    • path_to_csv_file: o caminho para o arquivo CSV
    • database_name: o nome de um banco de dados dentro da instância do Cloud SQL
    • offload: ativa a exportação sem servidor. Defina como true para usar a exportação sem servidor.
    • select_query: consulta SQL para exportação

    Método HTTP e URL:

    POST https://www.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/export

    Corpo JSON da solicitação:

    {
     "exportContext":
       {
          "fileType": "CSV",
          "uri": "gs://bucket_name/path_to_csv_file",
          "databases": ["database_name"],
          "offload": true | false
          "csvExportOptions":
           {
               "selectQuery":"select_query"
           }
       }
    }
    

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

    É preciso especificar corretamente um banco de dados com a propriedade databases e, se a consulta de seleção especificar um banco de dados, ele deverá ser o mesmo.

  4. Se você não precisar manter o papel do IAM definido anteriormente, revogue-o agora.
Para ver a lista completa de parâmetros dessa solicitação, consulte a página instances:export.

A exportação de CSV cria saída CSV padrão. Se você precisar de um formato CSV não padrão, use a instrução a seguir em um cliente psql:

      \copy [table_name] TO '[csv_file_name].csv' WITH
          (FORMAT csv, ESCAPE '[escape_character]', QUOTE '[quote_character]',
          DELIMITER '[delimiter_character]', ENCODING 'UTF8', NULL '[null_marker_string]');
Para ver a lista completa de parâmetros dessa solicitação, consulte a página instances:export.

Como exportar dados de um servidor PostgreSQL local usando pg_dump

Para exportar um banco de dados que não é gerenciado pelo Cloud SQL, para importação posterior no Cloud SQL, use o utilitário pg_dump com as sinalizações a seguir:

  • --no-owner

    Os comandos de mudança de propriedade não podem ser incluídos no arquivo dump SQL.

  • --format

    Somente o formato SQL plain é compatível com a API Cloud SQL Admin.

    O formato custom será permitido se o arquivo dump for destinado ao uso com pg_restore.

  • --no-acl

    Esse sinalizador é necessário caso seu despejo tenha instruções para conceder ou revogar assinaturas em um papel SUPERUSER.

Além disso, remova todos os itens a seguir:

  • Instruções relacionadas à extensão, se o Cloud SQL não for compatível com ela. Consulte Extensões do PostgreSQL para acessar a lista de extensões compatíveis.
  • instruções CREATE EXTENSION ou DROP EXTENSION que referem a plpgsql. Essa extensão vem pré-instalada nas instâncias do Cloud SQL Postgres.
  • COMMENT ON EXTENSION.

Para o formato de texto simples, em uma linha de comando, execute pg_dump:

pg_dump -U [USERNAME] --format=plain --no-owner --no-acl [DATABASE_NAME] \
    | sed -E 's/(DROP|CREATE|COMMENT ON) EXTENSION/-- \1 EXTENSION/g' > [SQL_FILE].sql

Para formato personalizado, em uma linha de comando, execute pg_dump:

pg_dump -U [USERNAME] --format=custom --no-owner --no-acl [DATABASE_NAME] > [DATABASE_NAME].dmp

Os comentários de pós-processamento sed excluem todas as instruções de extensão do arquivo dump SQL.

Ao importar usando pg_restore, especifique a tabela processada do conteúdo com o argumento da linha de comando "--use-list=[DATABASE_NAME].toc".

Confirme se a codificação padrão dos dados, conforme determinado pelas configurações do banco de dados, está correta. Se necessário, é possível substituir o padrão com a sinalização --encoding.

Para exportar em paralelo, use a sinalização -j NUM_CORES. NUM_CORES é o número de núcleos na instância de origem. Use a mesma sinalização com pg_restore para importar em paralelo.

Se precisar de ajuda com pg_dump, consulte a referência de pg_dump.

Como automatizar operações de exportação

Embora o Cloud SQL não forneça uma maneira integrada de automatizar exportações de banco de dados, é possível criar sua própria ferramenta de automação usando vários componentes do Google Cloud. Para saber mais, consulte este tutorial.

Solução de problemas

Clique nos links da tabela para ver detalhes:

Para este problema... O problema pode ser... Tente o seguinte...
Não é possível ver o status da operação. A interface do usuário mostra apenas sucesso ou falha. Use estes comandos do banco de dados para saber mais.
408 Error (Timeout) durante a exportação. A exportação do SQL pode demorar muito, dependendo do tamanho do banco de dados e do conteúdo exportado. Use várias exportações de CSV para reduzir o tamanho de cada operação.
A exportação de CSV funcionou, mas a exportação de SQL falhou. A exportação de SQL tem mais chances de ter problemas de compatibilidade com o Cloud SQL. Use exportações de CSV para exportar apenas o que você precisa.
A exportação está demorando muito. O Cloud SQL não é compatível com operações síncronas simultâneas. Use o descarregamento de exportação. Saiba mais
Erro ao criar extensão. O arquivo dump contém referências a extensões não compatíveis. Edite o arquivo dump para remover as referências.
Erro ao usar pg_dumpall. A ferramenta exige o papel de superusuário. O papel de superusuário não é compatível.
A operação de exportação expira antes de exportar qualquer coisa. A consulta precisa produzir dados nos primeiros sete minutos. Tente uma exportação manual usando a ferramenta pg_dump.
Conexão fechada durante a operação de exportação. A consulta precisa produzir dados nos primeiros sete minutos. Teste a consulta manualmente. Saiba mais.
Erro desconhecido durante a exportação. Possível problema de largura de banda. Verifique se a instância e o bucket do Cloud Storage estão na mesma região.
Você quer automatizar as exportações. O Cloud SQL não oferece uma maneira de automatizar exportações. Crie seu próprio pipeline para executar essa funcionalidade. Saiba mais.

Não é possível ver o status da operação

Não é possível ver o status de uma operação em andamento.

O problema pode ser

O Console do Google Cloud informa apenas o sucesso ou falha no momento da conclusão e não foi projetado para retornar avisos.

O que você pode tentar

Conecte-se ao banco de dados e execute SHOW WARNINGS.


Erro 408 (tempo limite) durante a exportação

Você vê a mensagem de erro 408 Error (Timeout) ao executar um job de exportação no Cloud SQL.

O problema pode ser

Os formatos CSV e SQL são exportados de maneira diferente. O formato SQL exporta todo o banco de dados e provavelmente leva mais tempo para ser concluído. O formato CSV permite definir quais elementos do banco de dados serão incluídos na exportação.

O que você pode tentar

Use o formato CSV e execute vários jobs de exportação menores para reduzir o tamanho e a duração de cada operação.


A exportação de CSV funcionou, mas a exportação de SQL falhou

A exportação de CSV funcionou, mas a exportação de SQL falhou.

Possível problema

Os formatos CSV e SQL são exportados de maneira diferente. O formato SQL exporta todo o banco de dados e provavelmente leva mais tempo para ser concluído. O formato CSV permite definir quais elementos do banco de dados serão incluídos na exportação.

O que você pode tentar

Use exportações de CSV para exportar apenas o que você precisa.


A exportação está demorando muito

A exportação está demorando muito, bloqueando outras operações.

O problema pode ser

O Cloud SQL não é compatível com operações síncronas simultâneas.

O que você pode tentar

Tente exportar conjuntos de dados cada vez menores.



Erro ao usar pg_dumpall

Você recebe um erro ao tentar usar a ferramenta de linha de comando pg_dumpall externa.

O problema pode ser

Essa ferramenta exige o papel de superusuário.

O que você precisa tentar

O Cloud SQL é um serviço gerenciado e não concede aos usuários os papéis ou as permissões de superusuário.


Conexão redefinida pelo par

A operação de exportação expira antes que qualquer item seja exportado. Você vê a mensagem de erro Could not receive data from client: Connection reset by peer..

O problema pode ser

Se o Cloud Storage não recebe dados em um determinado período, a conexão é redefinida.

O que você pode tentar

Faça uma exportação manual usando a ferramenta pg_dump.


Conexão fechada durante a operação de exportação

Conexão fechada durante a operação de exportação.

O problema pode ser

A conexão com o Cloud Storage pode expirar porque a consulta em execução na exportação não está produzindo nenhum dado nos primeiros sete minutos desde que a exportação foi iniciada.

O que você pode tentar

Teste a consulta manualmente conectando-se a partir de qualquer cliente e enviando a saída da consulta para STDOUT com o comando abaixo:

COPY (INSERT_YOUR_QUERY_HERE) TO STDOUT WITH ( FORMAT csv, DELIMITER ',', ENCODING 'UTF8', QUOTE '"', ESCAPE '"' ).

Esse é o comportamento esperado, porque quando a exportação é iniciada, o cliente deve começar a enviar dados imediatamente. Caso a conexão continue sem dados enviados, ela acaba sendo interrompida e, por fim, resultando em falha na exportação e deixando a operação em um estado incerto. Além disso, é isso que a mensagem de erro do gcloud está tentando dizer com esta mensagem:

operation is taking longer than expected.


Erro desconhecido durante a exportação

Você verá a mensagem de erro Unknown error ao tentar exportar um banco de dados para um bucket do Cloud Storage.

O problema pode ser

A transferência pode falhar devido a um problema de largura de banda.

O que você pode tentar

A instância do Cloud SQL pode estar em uma região diferente do bucket do Cloud Storage. A leitura e a gravação de dados de um continente para outro envolve o uso excessivo de rede e pode causar problemas intermitentes como esse. Verifique as regiões da instância e do bucket.


Querer automatizar exportações

Você quer automatizar as exportações.

O problema pode ser

O Cloud SQL não oferece uma maneira de automatizar exportações.

O que você pode tentar

É possível criar seu próprio sistema de exportação automatizada usando produtos do Google Cloud, como Cloud Scheduler, Pub/Sub e Cloud Functions.


Houve um erro de sistema ERROR_RDBMS

Você vê a mensagem de erro [ERROR_RDBMS] system error occurred.

O problema pode ser

  • O usuário pode não ter todas as permissões necessárias do Cloud Storage.
  • A tabela de banco de dados pode não existir.

O que você pode tentar

  1. Verifique se você tem pelo menos as permissões WRITER no bucket e READER no arquivo de exportação. Para mais informações sobre como configurar o controle de acesso no Cloud Storage, consulte Criar e gerenciar listas de controle de acesso.
  2. Verifique se a tabela existe. Se a tabela existir, confirme se você tem as permissões corretas no bucket.

A seguir