Exportar e importar arquivos em paralelo

Nesta página, descrevemos como exportar e importar arquivos para instâncias do Cloud SQL em paralelo.

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 de banco de dados, mas não interferem nas operações típicas de banco de dados, a menos que a instância tenha um provisionamento insuficiente.

  • Siga as práticas recomendadas para exportar e importar dados.
  • Depois de concluir uma operação de importação, verifique os resultados.

Exportar dados do Cloud SQL para PostgreSQL para vários arquivos em paralelo

As seções a seguir contêm informações sobre como exportar dados do Cloud SQL para PostgreSQL para vários arquivos em paralelo.

Permissões e papéis necessários para exportar dados do Cloud SQL para PostgreSQL para vários arquivos em paralelo

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 vários arquivos em paralelo

É possível exportar dados em paralelo de vários arquivos que residem no Cloud SQL para o Cloud Storage. Para fazer isso, use o utilitário pg_dump com a opção --jobs.

Se você planeja importar seus dados para o Cloud SQL, siga as instruções fornecidas em Como exportar dados de um servidor de banco de dados externo para que os arquivos sejam formatados corretamente para o Cloud SQL.

gcloud

Para exportar dados do Cloud SQL para vários arquivos em paralelo, siga estas etapas:

  1. Crie um bucket do Cloud Storage.
  2. Para encontrar a conta de serviço da instância do Cloud SQL da qual você está exportando arquivos, use o comando
    gcloud sql instances describe. 
    gcloud sql instances describe INSTANCE_NAME

    3. Substitua INSTANCE_NAME pelo nome da instância do Cloud SQL.

    Na saída, procure o valor associado ao campo serviceAccountEmailAddress.

  3. Para conceder o papel do IAM storage.objectAdmin à conta de serviço, use o comando gcloud storage buckets add-iam-policy-binding. Para ajuda com a configuração de permissões do IAM, consulte Usar as permissões do Cloud IAM.
  4. Para exportar dados do Cloud SQL para vários arquivos em paralelo, use o comando gcloud sql export sql: 
    gcloud sql export sql INSTANCE_NAME gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME \
--offload \
--parallel \
--threads=THREAD_NUMBER \
--database=DATABASE_NAME \
--table=TABLE_EXPRESSION

    Faça as seguintes substituições:

    • INSTANCE_NAME: o nome da instância do Cloud SQL da qual você está exportando arquivos em paralelo.
    • BUCKET_NAME pelo nome do bucket do Cloud Storage.
    • BUCKET_PATH: o caminho do bucket em que os arquivos de exportação estão armazenados.
    • FOLDER_NAME: a pasta onde os arquivos de exportação são armazenados.
    • THREAD_NUMBER: o número de linhas de execução que o Cloud SQL usa para exportar arquivos em paralelo. Por exemplo, se você quiser exportar três arquivos de cada vez em paralelo, especifique 3 como o valor desse parâmetro.
    • DATABASE_NAME: o nome do banco de dados dentro da instância do Cloud SQL a partir da qual a exportação é feita. É preciso especificar apenas um banco de dados.
    • TABLE_EXPRESSION: as tabelas a serem exportadas do banco de dados especificado.

    O comando export sql não contém gatilhos ou procedimentos armazenados, mas contém visualizações. Para exportar gatilhos ou procedimentos armazenados, use uma única linha de execução para a exportação. Esta linha de execução usa a ferramenta pg_dump.

    Após a conclusão da exportação, você terá arquivos em uma pasta no bucket do Cloud Storage no formato de diretório pg_dump.

  5. Se você não precisar do papel do IAM definido em Permissões e papéis obrigatórios para exportar do Cloud SQL para PostgreSQL, revoke.

REST v1

Para exportar dados do Cloud SQL para vários arquivos em paralelo, siga estas etapas:

  1. Crie um bucket do Cloud Storage: 
    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_NAME --location=LOCATION_NAME
    Faça as seguintes substituições:
    • BUCKET_NAME: o nome do bucket, sujeito a requisitos de nomenclatura. Por exemplo, my-bucket.
    • PROJECT_NAME: o nome do projeto do Google Cloud que contém o bucket do Cloud Storage que você está criando.
    • LOCATION_NAME: o local do bucket em que você quer armazenar os arquivos que está exportando. Por exemplo, us-east1.
  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 Usar as permissões do Cloud IAM.

  3. Exporte dados do Cloud SQL para vários arquivos em paralelo:

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

    • PROJECT_NAME: o nome do projeto do Google Cloud que contém o bucket do Cloud Storage que você criou.
    • INSTANCE_NAME: o nome da instância do Cloud SQL da qual você está exportando arquivos em paralelo.
    • BUCKET_NAME pelo nome do bucket do Cloud Storage.
    • BUCKET_PATH: o caminho do bucket em que os arquivos de exportação estão armazenados.
    • FOLDER_NAME: a pasta onde os arquivos de exportação são armazenados.
    • DATABASE_NAME: o nome do banco de dados dentro da instância do Cloud SQL a partir da qual a exportação é feita. É preciso especificar apenas um banco de dados.
    • THREAD_NUMBER: o número de linhas de execução que o Cloud SQL usa para exportar arquivos em paralelo. Por exemplo, se você quiser exportar três arquivos de cada vez em paralelo, especifique 3 como o valor desse parâmetro.

    Método HTTP e URL: 

    POST https://sqladmin.googleapis.com/v1/projects/PROJECT_NAME/instances/INSTANCE_NAME/export

    Corpo JSON da solicitação:

    {
 "exportContext":
   {
      "fileType": "SQL",
      "uri": "gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME",
      "databases": ["DATABASE_NAME"],
      "offload": [TRUE|FALSE],
      "sqlExportOptions": {
        "parallel": [TRUE|FALSE],
        "threads": [THREAD_NUMBER]
       }
   }
}

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

    Você receberá uma resposta JSON semelhante a esta:

    4. Após a conclusão da exportação, você terá arquivos em uma pasta no bucket do Cloud Storage no formato de diretório pg_dump.

  4. Se você não precisar do papel do IAM definido em Permissões e papéis obrigatórios para exportar do Cloud SQL para PostgreSQL, revoke.
Para ver a lista completa de parâmetros da solicitação, consulte a página API Cloud SQL Admin.

REST v1beta4

Para exportar dados do Cloud SQL para vários arquivos em paralelo, siga estas etapas:

  1. Crie um bucket do Cloud Storage: 
    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_NAME --location=LOCATION_NAME
     Faça as seguintes substituições:
    • BUCKET_NAME: o nome do bucket, sujeito a requisitos de nomenclatura. Por exemplo, my-bucket.
    • PROJECT_NAME: o nome do projeto do Google Cloud que contém o bucket do Cloud Storage que você está criando.
    • LOCATION_NAME: o local do bucket em que você quer armazenar os arquivos que está exportando. Por exemplo, us-east1.
  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 Usar as permissões do Cloud IAM.

  3. Exporte dados do Cloud SQL para vários arquivos em paralelo:

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

    • PROJECT_NAME: o nome do projeto do Google Cloud que contém o bucket do Cloud Storage que você criou.
    • INSTANCE_NAME: o nome da instância do Cloud SQL da qual você está exportando arquivos em paralelo.
    • BUCKET_NAME pelo nome do bucket do Cloud Storage.
    • BUCKET_PATH: o caminho do bucket em que os arquivos de exportação estão armazenados.
    • FOLDER_NAME: a pasta onde os arquivos de exportação são armazenados.
    • DATABASE_NAME: o nome do banco de dados dentro da instância do Cloud SQL a partir da qual a exportação é feita. É preciso especificar apenas um banco de dados.
    • THREAD_NUMBER: o número de linhas de execução que o Cloud SQL usa para exportar arquivos em paralelo. Por exemplo, se você quiser exportar três arquivos de cada vez em paralelo, especifique 3 como o valor desse parâmetro.

    Método HTTP e URL: 

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_NAME/instances/INSTANCE_NAME/export

    Corpo JSON da solicitação:

    {
 "exportContext":
   {
      "fileType": "SQL",
      "uri": "gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME",
      "databases": ["DATABASE_NAME"],
      "offload": [TRUE|FALSE],
      "sqlExportOptions": {
        "parallel": [TRUE|FALSE],
        "threads": [THREAD_NUMBER]
       }
   }
}

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

    Você receberá uma resposta JSON semelhante a esta:

    4. Após a conclusão da exportação, você terá arquivos em uma pasta no bucket do Cloud Storage no formato de diretório pg_dump.

  4. Se você não precisar do papel do IAM definido em Permissões e papéis obrigatórios para exportar do Cloud SQL para PostgreSQL, revoke.
Para ver a lista completa de parâmetros da solicitação, consulte a página API Cloud SQL Admin.

Importe dados de vários arquivos em paralelo ao Cloud SQL para PostgreSQL

As seções a seguir contêm informações sobre como importar dados de vários arquivos em paralelo com o Cloud SQL para PostgreSQL.

Permissões e papéis necessários para importar dados de vários arquivos em paralelo ao 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 para o Cloud SQL para PostgreSQL

É possível importar dados em paralelo de vários arquivos que residem no Cloud Storage para seu banco de dados. Para fazer isso, use o utilitário pg_restore com a opção --jobs.

gcloud

Para importar dados de vários arquivos em paralelo para o Cloud SQL, siga estas etapas:

  1. Crie um bucket do Cloud Storage.

  2. Faça upload dos arquivos para o bucket.

    Se precisar de ajuda com o upload de arquivos para buckets, consulte Fazer upload de objetos de arquivos.

  3. Para encontrar a conta de serviço da instância do Cloud SQL para a qual você está importando arquivos, use o comando
    gcloud sql instances describe. 
    gcloud sql instances describe INSTANCE_NAME

    4. Substitua INSTANCE_NAME pelo nome da instância do Cloud SQL.

    Na saída, procure o valor associado ao campo serviceAccountEmailAddress.

  4. Para conceder o papel do IAM storage.objectAdmin à conta de serviço, use o utilitário gcloud storage buckets add-iam-policy-binding. Para ajuda com a configuração de permissões do IAM, consulte Usar as permissões do Cloud IAM.
  5. Para importar dados de vários arquivos em paralelo no Cloud SQL, use o comando gcloud sql import sql: 
    gcloud sql import sql INSTANCE_NAME gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME \
--offload \
--parallel \ 
--threads=THREAD_NUMBER \
--database=DATABASE_NAME

    Faça as seguintes substituições:

    • INSTANCE_NAME: o nome da instância do Cloud SQL para a qual os arquivos são importados em paralelo.
    • BUCKET_NAME pelo nome do bucket do Cloud Storage.
    • BUCKET_PATH: o caminho do bucket em que os arquivos de importação estão armazenados.
    • FOLDER_NAME: a pasta onde os arquivos de importação são armazenados.
    • THREAD_NUMBER: o número de linhas de execução que o Cloud SQL usa para importar arquivos em paralelo. Por exemplo, se você quiser importar três arquivos de uma vez em paralelo, especifique 3 como o valor desse parâmetro.
    • DATABASE_NAME: o nome do banco de dados dentro da instância do Cloud SQL em que a importação é feita. É preciso especificar apenas um banco de dados.

    Se o comando retornar um erro como ERROR_RDBMS, revise as permissões. Esse erro costuma ser causado por problemas de permissões.

  6. Se você não precisar das permissões do IAM definidas em Papéis e permissões necessárias para importação para o Cloud SQL para PostgreSQL, use gcloud storage buckets remove-iam-policy-binding para removê-las.

REST v1

Para importar dados de vários arquivos em paralelo para o Cloud SQL, siga estas etapas:

  1. Crie um bucket do Cloud Storage: 
    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_NAME --location=LOCATION_NAME
    Faça as seguintes substituições:
    • BUCKET_NAME: o nome do bucket, sujeito a requisitos de nomenclatura. Por exemplo, my-bucket.
    • PROJECT_NAME: o nome do projeto do Google Cloud que contém o bucket do Cloud Storage que você está criando.
    • LOCATION_NAME: o local do bucket em que você quer armazenar os arquivos que está importando. Por exemplo, us-east1.

  2. Faça upload dos arquivos para o bucket.

    Se precisar de ajuda com o upload de arquivos para buckets, consulte Fazer upload de objetos de arquivos.

  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 Usar as permissões do Cloud IAM.

  4. Importe dados de vários arquivos em paralelo para o Cloud SQL:

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

    • PROJECT_NAME: o nome do projeto do Google Cloud que contém o bucket do Cloud Storage que você criou.
    • INSTANCE_NAME: o nome da instância do Cloud SQL para a qual os arquivos são importados em paralelo.
    • BUCKET_NAME pelo nome do bucket do Cloud Storage.
    • BUCKET_PATH: o caminho do bucket em que os arquivos de importação estão armazenados.
    • FOLDER_NAME: a pasta onde os arquivos de importação são armazenados.
    • DATABASE_NAME: o nome do banco de dados dentro da instância do Cloud SQL em que a importação é feita. É preciso especificar apenas um banco de dados.
    • THREAD_NUMBER: o número de linhas de execução que o Cloud SQL usa para importar arquivos em paralelo. Por exemplo, se você quiser importar três arquivos de uma vez em paralelo, especifique 3 como o valor desse parâmetro.

    Método HTTP e URL: 

    POST https://sqladmin.googleapis.com/v1/projects/PROJECT_NAME/instances/INSTANCE_NAME/import

    Corpo JSON da solicitação:

    
{
  "importContext":
    {
       "fileType": "SQL",
       "uri": "gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME",
       "databases": ["DATABASE_NAME"],
       "offload": [TRUE|FALSE],
       "sqlImportOptions": {
         "parallel": [TRUE|FALSE],
         "clean": [TRUE|FALSE],
         "ifExists": [TRUE|FALSE],
         "threads": [THREAD_NUMBER]
        }
    }
 }

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

    Você receberá uma resposta JSON semelhante a esta:

    Para usar um usuário diferente para a importação, especifique a propriedade importContext.importUser.

    Para ver a lista completa de parâmetros da solicitação, consulte a página API Cloud SQL Admin.
  5. Se você não precisar das permissões do IAM definidas em Papéis e permissões necessárias para importação para o Cloud SQL para PostgreSQL, use gcloud storage buckets remove-iam-policy-binding para removê-las.

REST v1beta4

Para importar dados de vários arquivos em paralelo para o Cloud SQL, siga estas etapas:

  1. Crie um bucket do Cloud Storage: 
    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_NAME --location=LOCATION_NAME
    Faça as seguintes substituições:
    • BUCKET_NAME: o nome do bucket, sujeito a requisitos de nomenclatura. Por exemplo, my-bucket.
    • PROJECT_NAME: o nome do projeto do Google Cloud que contém o bucket do Cloud Storage que você está criando.
    • LOCATION_NAME: o local do bucket em que você quer armazenar os arquivos que está importando. Por exemplo, us-east1.

  2. Faça upload dos arquivos para o bucket.

    Se precisar de ajuda com o upload de arquivos para buckets, consulte Fazer upload de objetos de arquivos.

  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 Usar as permissões do Cloud IAM.

  4. Importe dados de vários arquivos em paralelo para o Cloud SQL:

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

    • PROJECT_NAME: o nome do projeto do Google Cloud que contém o bucket do Cloud Storage que você criou.
    • INSTANCE_NAME: o nome da instância do Cloud SQL da qual os arquivos são importados em paralelo.
    • BUCKET_NAME pelo nome do bucket do Cloud Storage.
    • BUCKET_PATH: o caminho do bucket em que os arquivos de importação estão armazenados.
    • FOLDER_NAME: a pasta onde os arquivos de importação são armazenados.
    • DATABASE_NAME: o nome do banco de dados dentro da instância do Cloud SQL em que a importação é feita. É preciso especificar apenas um banco de dados.
    • THREAD_NUMBER: o número de linhas de execução que o Cloud SQL usa para importar arquivos em paralelo. Por exemplo, se você quiser importar três arquivos de uma vez em paralelo, especifique 3 como o valor desse parâmetro.

    Método HTTP e URL: 

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_NAME/instances/INSTANCE_NAME/import

    Corpo JSON da solicitação:

    
 {
   "importContext":
     {
        "fileType": "SQL",
        "uri": "gs://BUCKET_NAME/BUCKET_PATH/FOLDER_NAME",
        "databases": ["DATABASE_NAME"],
        "offload": [TRUE|FALSE],
        "sqlImportOptions": {
          "parallel": [TRUE|FALSE],
          "clean": [TRUE|FALSE],
          "ifExists": [TRUE|FALSE],
          "threads": [THREAD_NUMBER]
         }
     }
  }

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

    Você receberá uma resposta JSON semelhante a esta:

    Para usar um usuário diferente para a importação, especifique a propriedade importContext.importUser.

    Para ver a lista completa de parâmetros da solicitação, consulte a página API Cloud SQL Admin.
  5. Se você não precisar das permissões do IAM definidas em Papéis e permissões necessárias para importação para o Cloud SQL para PostgreSQL, use gcloud storage buckets remove-iam-policy-binding para removê-las.

Limitações

  • Se você especificar muitas linhas de execução ao importar ou exportar dados de vários arquivos em paralelo, talvez use mais memória do que sua instância do Cloud SQL tem. Se isso ocorrer, uma mensagem de erro interna será exibida. Verifique o uso de memória da instância e aumente o tamanho dela, conforme necessário. Para mais informações, consulte Sobre as configurações da instância.
  • Ao realizar uma exportação, não há suporte para vírgulas em nomes de bancos de dados ou nomes de tabelas nos campos databases ou tables.
  • Verifique se você tem espaço em disco suficiente para o download inicial do arquivo dump. Caso contrário, um erro no space left on disk será exibido.
  • Se a instância tiver apenas uma CPU virtual (vCPU), não será possível importar ou exportar vários arquivos em paralelo. O número de vCPUs da instância não pode ser menor que o número de linhas de execução usado para a operação de importação ou exportação, e o número de linhas de execução precisa ser pelo menos dois.
  • O utilitário pg_dump não pode dividir as tabelas que você exporta. Portanto, se você tiver uma tabela muito grande, ela poderá se tornar um gargalo para a velocidade da operação de exportação.

A seguir