Exportar e importar usando arquivos CSV

Nesta página, descrevemos como exportar e importar dados para instâncias do Cloud SQL usando arquivos CSV.

Antes de começar

Antes de iniciar uma operação de exportação ou importação:

  • Verifique se o banco de dados tem espaço livre adequado.

    • As operações de exportação e importação 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.

  • Verifique se o arquivo CSV tem os dados esperados e se está no formato correto. Os arquivos CSV precisam ter uma linha para cada linha de campos de dados.
  • Siga as práticas recomendadas para exportar e importar dados.

Exportar dados do Cloud SQL para PostgreSQL

Permissões e papéis necessários para exportar do Cloud SQL para PostgreSQL

Para exportar dados do Cloud SQL para o Cloud Storage, o usuário que inicia a exportação precisa ter um dos seguintes papéis:

Além disso, a conta de serviço da instância do Cloud SQL precisa ter um dos seguintes papéis:

  • O papel storage.objectAdmin do Identity and Access Management (IAM)
  • Um papel personalizado, incluindo as seguintes permissões:
    • storage.objects.create
    • storage.objects.list (somente para exportar arquivos em paralelo)
    • storage.objects.delete (somente para exportar arquivos em paralelo)

Para receber ajuda com os papéis do IAM, consulte Gerenciamento de identidade e acesso.

Exportar dados para um arquivo CSV do Cloud SQL para Cloud SQL para PostgreSQL

É 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 CSV em um bucket do Cloud Storage:

Console

  1. No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

    Acesse "Instâncias do Cloud SQL"

  2. Para abrir a página Visão geral de uma instância, clique no nome da instância.
  3. Clique em Exportar.
  4. Selecione Descarregar exportação para permitir que outras operações ocorram enquanto a exportação estiver em andamento.
  5. Na seção 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. Na seção Local, selecione um bucket ou pasta do Cloud Storage para a exportação.

    2. Na caixa Nome, adicione um nome para o arquivo CSV ou selecione um arquivo existente na lista na seção 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.
  6. Na seção Formato, clique em CSV.
  7. Na seção Banco de dados para exportação, selecione o nome do banco de dados no menu suspenso.

  8. 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 especificado. Não é possível exportar um banco de dados inteiro no formato CSV.

  9. Clique em Exportar para iniciar a exportação.
  10. 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. Depois que a exportação for iniciada, será possível cancelar a operação. Se for um bom momento para iniciar uma exportação, clique em Exportar. Caso contrário, clique em Cancelar.

gcloud

  1. Criar um bucket do Cloud Storage

  2. Faça upload do arquivo no seu bucket.

    Para receber ajuda com o upload de arquivos para buckets, consulte Como fazer upload de objetos.

  3. Encontre a conta de serviço da instância do Cloud SQL da qual você está exportando. É possível fazer isso executando o comando gcloud sql instances describe. Procure o campo serviceAccountEmailAddress na saída. 
    gcloud sql instances describe INSTANCE_NAME
  4. Use gsutil iam para conceder o papel do IAM storage.objectAdmin à conta de serviço da instância do Cloud SQL. 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 v1

  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 legacyBucketWriter 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 (opcional)
    • escape_character: o caractere que precisa aparecer antes de um caractere de dados que precisa de escape. O valor desse argumento precisa ser um caractere no código ASCII hexadecimal. Por exemplo, "22" representa aspas duplas. (opcional)
    • quote_character:o caractere que inclui valores de colunas com um tipo de dados de string. O valor desse argumento precisa ser um caractere no código ASCII hexadecimal. Por exemplo, "22" representa aspas duplas. (opcional)
    • fields_terminated_by: o caractere que divide os valores da coluna. O valor desse argumento precisa ser um caractere no código ASCII hexadecimal. Por exemplo, "2C" representa uma vírgula. (opcional)
    • lines_terminated_by: o caractere que divide os registros de linha. O valor desse argumento precisa ser um caractere no código ASCII hexadecimal. Por exemplo, "0A" representa uma nova linha. (opcional)

    Método HTTP e URL:

    POST https://sqladmin.googleapis.com/v1/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",
           "escapeCharacter":"escape_character",
           "quoteCharacter":"quote_character",
           "fieldsTerminatedBy":"fields_terminated_by",
           "linesTerminatedBy":"lines_terminated_by"
       }
   }
}

    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 as permissões do IAM definidas anteriormente, remova-as agora.
Para ver a lista completa de parâmetros da solicitação, consulte a página instances:export

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 (opcional)
    • escape_character: o caractere que precisa aparecer antes de um caractere de dados que precisa de escape. O valor desse argumento precisa estar no formato ASCII hexadecimal. Por exemplo, "22" representa aspas duplas. (opcional)
    • quote_character: o caractere que inclui valores de colunas com um tipo de dados de string. O valor desse argumento precisa estar no formato ASCII hexadecimal. Por exemplo, "22" representa aspas duplas. (opcional)
    • fields_terminated_by: o caractere que divide os valores da coluna. O valor desse argumento precisa estar no formato ASCII hexadecimal. Por exemplo, "2C" representa uma vírgula. (opcional)
    • lines_terminated_by: o caractere que divide os registros de linha. O valor desse argumento precisa estar no formato ASCII hexadecimal. Por exemplo, "0A" representa uma nova linha. (opcional)

    Método HTTP e URL:

    POST https://sqladmin.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",
           "escapeCharacter":  "escape_character",
           "quoteCharacter": "quote_character",
           "fieldsTerminatedBy": "fields_terminated_by",
           "linesTerminatedBy": "lines_terminated_by"
       }
   }
}

    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 da solicitação, consulte a página instances:export

Personalizar o formato de um arquivo de exportação CSV

É possível usar gcloud ou a API REST para personalizar o formato do arquivo CSV. Ao executar uma exportação, você pode especificar as seguintes opções de formatação:

Opção de CSV Valor padrão Sinalização do gcloud Propriedade da API REST Descrição
Escape

"5C"

Código hexadecimal ASCII para o separador de arquivos.

--escape escapeCharacter

Caractere que aparece antes de um caractere de dados que precisa ser escapado.

Disponível apenas para MySQL e PostgreSQL.

Cotação

"22"

Código hexadecimal ASCII para aspas duplas.

--quote quoteCharacter

O caractere que inclui valores de colunas com um tipo de dados de string.

Disponível apenas para MySQL e PostgreSQL.

Delimitador de campo

"2C"

Código hexadecimal ASCII para vírgula.

--fields-terminated-by fieldsTerminatedBy

Caractere que divide os valores da coluna.

Disponível apenas para MySQL e PostgreSQL.

Caractere de nova linha

"0A"

Código hexadecimal ASCII para nova linha.

--lines-terminated-by linesTerminatedBy

Caractere que divide registros de linha.

Disponível apenas para MySQL.

Por exemplo, um comando gcloud que usa todos esses argumentos poderia se parecer com:

gcloud sql export csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
--database=DATABASE_NAME \
--offload \
--query=SELECT_QUERY \
--quote="22" \
--escape="5C" \
--fields-terminated-by="2C" \
--lines-terminated-by="0A"

O corpo da solicitação da API REST equivalente seria assim:

{
 "exportContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "databases": ["DATABASE_NAME"],
      "offload": true,
      "csvExportOptions":
       {
           "selectQuery": "SELECT_QUERY",
           "escapeCharacter":  "5C",
           "quoteCharacter": "22",
           "fieldsTerminatedBy": "2C",
           "linesTerminatedBy": "0A"
       }
   }
}

Por padrão, a exportação de CSV cria saída CSV padrão. Se você precisar de ainda mais opções do que o Cloud SQL oferece, use a seguinte instrução 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]');

Importar dados para o Cloud SQL para PostgreSQL

Permissões e papéis necessários para importar para o Cloud SQL para PostgreSQL

Para importar dados do Cloud Storage para o Cloud SQL, o usuário que inicia a importação precisa ter um dos seguintes papéis:

Além disso, a conta de serviço da instância do Cloud SQL precisa ter um dos seguintes papéis:

  • O papel storage.objectAdmin do IAM
  • Um papel personalizado, incluindo as seguintes permissões:
    • storage.objects.get
    • storage.objects.list (somente para importar arquivos em paralelo)

Para receber ajuda com os papéis do IAM, consulte Gerenciamento de identidade e acesso.

Importar dados de um arquivo CSV para o Cloud SQL para PostgreSQL

Requisitos de formato do arquivo CSV

Os arquivos CSV precisam ter uma linha para cada linha de dados e usar campos separados por vírgula.

Para importar dados para uma instância do Cloud SQL usando um arquivo CSV:

Console

  1. No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

    Acesse "Instâncias do Cloud SQL"

  2. Para abrir a página Visão geral de uma instância, clique no nome da instância.
  3. Clique em Importar.
  4. Na seção Escolha o arquivo do qual você quer importar dados, insira o caminho para o bucket e o arquivo CSV para a importação. Ou acesse o arquivo:
    1. Clique em Browse.
    2. Na seção Local, clique duas vezes no nome do bucket na lista.
    3. Selecione o arquivo na lista.
    4. Clique em Selecionar.

    É possível importar um arquivo compactado (.gz) ou descompactado (.csv).

  5. Na seção Formato, selecione CSV.
  6. Especifique o Banco de dados e a Tabela na instância do Cloud SQL em que você quer importar o arquivo CSV.
  7. Você pode, opcionalmente, especificar um usuário para a operação de importação.
  8. Clique em Importar para iniciar a importação.

gcloud

  1. Criar um bucket do Cloud Storage

  2. Faça upload do arquivo no seu bucket.

    Para receber ajuda com o upload de arquivos para buckets, consulte Como fazer upload de objetos.

  3. Faça upload dos dados do arquivo CSV para o bucket.
  4. Identifique a conta de serviço da instância do Cloud SQL da qual você está exportando. É possível fazer isso executando o comando gcloud sql instances describe com o nome da instância. Procure o campo serviceAccountEmailAddress na saída. 
    gcloud sql instances describe INSTANCE_NAME
  5. Copie o campo serviceAccountEmailAddress.
  6. Use gsutil iam para conceder o papel do IAM storage.objectAdmin à conta de serviço da instância do Cloud SQL do bucket. Para ajuda com a configuração de permissões do IAM, consulte Como usar as permissões do Cloud IAM.
  7. Importe o arquivo:
    gcloud sql import csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
--database=DATABASE_NAME \
--table=TABLE_NAME

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

  8. Se não for necessário manter as permissões do IAM definidas anteriormente, remova-as usando gsutil iam.

REST v1

  1. Criar um bucket do Cloud Storage

  2. Faça upload do arquivo no seu bucket.

    Para receber ajuda com o upload de arquivos para buckets, consulte Como fazer upload de objetos.

  3. Forneça à instância os papéis do IAM legacyBucketWriter e objectViewer do seu bucket. Para ajuda com a configuração de permissões do IAM, consulte Como usar as permissões do Cloud IAM.
  4. Importe o arquivo:

    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
    • table_name: o nome da tabela do banco de dados
    • escape_character: o caractere que precisa aparecer antes de um caractere de dados que precisa de escape. O valor desse argumento precisa ser um caractere no código ASCII hexadecimal. Por exemplo, "22" representa aspas duplas. (opcional)
    • quote_character: o caractere que inclui valores de colunas com um tipo de dados de string. O valor desse argumento precisa ser um caractere no código ASCII hexadecimal. Por exemplo, "22" representa aspas duplas. (opcional)
    • fields_terminated_by: o caractere que divide os valores da coluna. O valor desse argumento precisa ser um caractere no código ASCII hexadecimal. Por exemplo, "2C" representa uma vírgula. (opcional)
    • lines_terminated_by: o caractere que divide os registros de linha. O valor desse argumento precisa ser um caractere no código ASCII hexadecimal. Por exemplo, "0A" representa uma nova linha. (opcional)

    Método HTTP e URL:

    POST https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id/import

    Corpo JSON da solicitação:

    {
 "importContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "database": "database_name",
      "csvImportOptions":
       {
         "table": "table_name",
         "escapeCharacter": "escape_character",
         "quoteCharacter": "quote_character",
         "fieldsTerminatedBy": "fields_terminated_by",
         "linesTerminatedBy": "lines_terminated_by"
       }
   }
}

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

    Você receberá uma resposta JSON semelhante a esta:

    Para ver a lista completa de parâmetros da solicitação, consulte a página instances:import.
  5. Se você não precisar manter as permissões do Cloud IAM definidas anteriormente, remova-as.

REST v1beta4

  1. Criar um bucket do Cloud Storage

  2. Faça upload do arquivo no seu bucket.

    Para receber ajuda com o upload de arquivos para buckets, consulte Como fazer upload de objetos.

  3. 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.
  4. Importe o arquivo:

    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
    • table_name: o nome da tabela do banco de dados
    • escape_character: o caractere que precisa aparecer antes de um caractere de dados que precisa de escape. O valor desse argumento precisa estar no formato ASCII hexadecimal. Por exemplo, "22" representa aspas duplas. (opcional)
    • quote_character: o caractere que inclui valores de colunas com um tipo de dados de string. O valor desse argumento precisa estar no formato ASCII hexadecimal. Por exemplo, "22" representa aspas duplas. (opcional)
    • fields_terminated_by: o caractere que divide os valores da coluna. O valor desse argumento precisa estar no formato ASCII hexadecimal. Por exemplo, "2C" representa uma vírgula. (opcional)
    • lines_terminated_by: o caractere que divide os registros de linha. O valor desse argumento precisa estar no formato ASCII hexadecimal. Por exemplo, "0A" representa uma nova linha. (opcional)

    Método HTTP e URL:

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/import

    Corpo JSON da solicitação:

    {
 "importContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "database": "database_name",
      "csvImportOptions":
       {
         "table": "table_name",
         "escapeCharacter": "escape_character",
         "quoteCharacter": "quote_character",
         "fieldsTerminatedBy": "fields_terminated_by",
         "linesTerminatedBy": "lines_terminated_by"
       }
   }
}

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

    Você receberá uma resposta JSON semelhante a esta:

    Para ver a lista completa de parâmetros da solicitação, consulte a página instances:import.
  5. Se você não precisar manter as permissões do Cloud IAM definidas anteriormente, remova-as.

Personalizar o formato de um arquivo CSV para o Cloud SQL para PostgreSQL

É possível usar gcloud ou a API REST para personalizar o formato do arquivo CSV.

Um comando gcloud de amostra a seguir:

gcloud sql import csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
--database=DATABASE_NAME \
--table=TABLE_NAME \
--quote="22" \
--escape="5C" \
--fields-terminated-by="2C" \
--lines-terminated-by="0A"

O corpo da solicitação da API REST equivalente seria assim:

{
 "importContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "database": ["DATABASE_NAME"],
      "csvImportOptions":
       {
           "table": "TABLE_NAME",
           "escapeCharacter":  "5C",
           "quoteCharacter": "22",
           "fieldsTerminatedBy": "2C",
           "linesTerminatedBy": "0A"
       }
   }
}

Se você receber um erro como ERROR_RDBMS, verifique se a tabela existe. Se a tabela existir, confirme se você tem as permissões corretas no bucket. Para receber ajuda para configurar o controle de acesso no Cloud Storage, consulte Criar e gerenciar listas de controle de acesso.

Para ver como a solicitação da API REST subjacente é criada nesta tarefa, consulte o Explorador de APIs na página "instances:import".

Próximas etapas