Importar e exportar dados

Neste documento, descrevemos como migrar, fazer backup e transferir dados no Spanner Omni usando os formatos Avro e CSV. Use a CLI do Spanner Omni para mover conteúdo de banco de dados entre o Spanner Omni e soluções de armazenamento como Cloud Storage, Amazon Simple Storage Service (Amazon S3), armazenamento local compatível com S3 ou sistemas de arquivos locais (NFS). Os fluxos de dados de importação e exportação no Spanner Omni não são compatíveis com modelos, grupos de localidade ou posições.

As operações de importação e exportação são executadas em servidores do Spanner Omni e compartilham os recursos de sistema disponíveis. A importação exige muitos recursos e pode causar alto uso de RAM, CPU e disco, o que pode afetar as cargas de trabalho ativas. Embora essas tarefas geralmente sejam executadas com uma prioridade menor do que o tráfego normal, monitore sua implantação para possíveis impactos na performance.

Comparação de formatos de arquivo

A tabela a seguir compara os recursos dos formatos de arquivo Avro e CSV para importar e exportar dados do Spanner.

Capacidade Avro CSV
Importar ou exportar um banco de dados inteiro Sim Não
Importar tabelas exportadas anteriormente Sim Sim
Exportar em um carimbo de data/hora anterior Sim Sim
Importar ou exportar usando o Spanner Sim Sim
Importar dados de outros bancos de dados Não Sim

Os formatos Avro e CSV exportam todas as tabelas do banco de dados. O formato Avro também exporta o esquema para que você possa importá-lo novamente. O formato CSV não exporta o esquema.

Antes de começar

Antes de iniciar uma operação de importação ou exportação, verifique suas permissões e configure o acesso ao local de armazenamento de dados.

Permissões

Verifique se você tem as seguintes permissões antes de começar:

  • spanner.databases.import
  • spanner.databases.export

Para mais informações sobre o Identity and Access Management (IAM) no Spanner Omni, consulte Visão geral do IAM. Para saber como atualizar as funções de um usuário, consulte Atualizar usuários.

Origem e destino de dados

É possível armazenar dados em um bucket do Amazon Simple Storage Service (Amazon S3), bucket do Cloud Storage, em um armazenamento local compatível com o Amazon S3 (como o MinIO) ou em um sistema de arquivos local (NFS). Se você usar um sistema de arquivos local, verifique se os dados estão disponíveis no mesmo caminho em todos os servidores da implantação.

É possível dar acesso ao armazenamento de dados de duas maneiras:

  • Adicione armazenamento externo à implantação: esse é o método preferido se você planeja reutilizar um bucket.

  • Crie credenciais únicas: elas precisam durar mais do que a operação de importação ou exportação (por exemplo, 48 horas).

As credenciais precisam fornecer permissões para listar e ler objetos no bucket para importações. Para exportações para o Amazon S3, você precisa das seguintes permissões adicionais do Amazon S3:

  • s3:PutObject
  • s3:AbortMultipartUpload
  • s3:ListBucketMultipartUploads

Para mais informações, consulte Permissões do IAM.

Importar arquivos Avro do Spanner

Para importar dados que você exportou anteriormente de outro banco de dados do Spanner (Spanner ou Spanner Omni) no formato Avro, siga estas etapas.

Pré-requisitos para importação do Avro

Antes de começar a importação do Avro, verifique se o ambiente atende aos seguintes requisitos:

  • Você criou o banco de dados de destino.

  • Os objetos de esquema que você está importando ainda não existem no banco de dados. O processo de importação do Avro cria essas tabelas antes de importar os dados.

Instruções de importação do Avro

Identifique o caminho para a pasta que contém os dados exportados. A pasta contém o seguinte:

  • Um arquivo spanner-export.json

  • Um arquivo ENTITY_NAME-manifest.json para cada entidade exportada (como uma tabela, sequência ou esquema).

  • Todos os arquivos Avro listados nos arquivos de manifesto.

Se você já adicionou o armazenamento de dados como armazenamento externo, não precisa incluir credenciais no caminho. Você pode fornecer o caminho diretamente. Se você estiver usando credenciais únicas, use os seguintes formatos de URL:

  • Cloud Storage: gs://BUCKET_NAME/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY]. Use credenciais HMAC. Para mais informações, consulte Chaves HMAC.

  • Amazon S3: s3://S3_BUCKET/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY[&sessiontoken=SESSION_TOKEN]]

  • Pasta de arquivos local*: file:///PATH_TO_DIR

Para iniciar a importação, execute o seguinte comando:

spanner databases import DATABASE_ID --url="URL" --format=avro [--avro-skip-wait-for-index-creation]

Outras observações

Considere as seguintes informações ao importar arquivos Avro:

Quando a operação de importação é iniciada com sucesso, ela retorna um ID de operação de longa duração. Use esse ID para acompanhar o status da operação.

Importar arquivos CSV

Para importar dados de texto exportados de outro banco de dados, siga estas etapas.

Pré-requisitos para importação de CSV

Antes de começar a importação de CSV, faça o seguinte:

  • Verifique se as tabelas estão em um dos seguintes tipos de dados compatíveis: BOOL, INT64, FLOAT64, NUMERIC, STRING, DATE, TIMESTAMP, BYTES e JSON.

  • Crie o banco de dados de destino.

  • Crie todas as tabelas em que você quer importar dados. O processo de importação de CSV não cria tabelas.

  • Verifique se o arquivo CSV não tem uma linha de cabeçalho.

Instruções de importação de CSV

Para importar arquivos CSV, crie um arquivo de manifesto que descreva os dados a serem importados. O arquivo de manifesto usa a seguinte estrutura, definida aqui no formato protobuf:

message ImportManifest {
  // The per-table import manifest.
  message TableManifest {
    // Required. The name of the destination table.
    string table_name = 1;
    // Required. The CSV files to import. This value can be either a path or a glob pattern.
    repeated string file_patterns = 2;
    // The schema for a table column.
    message Column {
      // Required for each column that you specify. The name of the column in the
      // destination table.
      string column_name = 1;
      // Required for each column that you specify. The type of the column.
      string type_name = 2;
    }
    // Optional. The schema for the table columns.
    repeated Column columns = 3;
  }
  // Required. The TableManifest of the tables to be imported.
  repeated TableManifest tables = 1;

  enum ProtoDialect {
    GOOGLE_STANDARD_SQL = 0;
    POSTGRESQL = 1;
  }
  // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
  ProtoDialect dialect = 2;
}

Confira a seguir um exemplo de manifesto: 

{
  "tables": [
    {
      "table_name": "Albums",
      "file_patterns": [
        "gs://bucket1/Albums_1.csv",
        "gs://bucket1/Albums_2.csv"
      ]
    },
    {
      "table_name": "Singers",
      "file_patterns": [
        "gs://bucket1/Singers*.csv"
      ],
      "columns": [
        {"column_name": "SingerId", "type_name": "INT64"},
        {"column_name": "FirstName", "type_name": "STRING"},
        {"column_name": "LastName", "type_name": "STRING"}
      ]
    }
  ]
}

O URL no comando a seguir O arquivo CSV não contém um cabeçalhoimport precisa apontar para a pasta que contém um arquivo de manifesto no formato JSON, conforme descrito no exemplo de manifesto. Esse arquivo pode estar localizado no Cloud Storage, no Amazon S3 ou em uma pasta de arquivos local, usando o mesmo formato de URL para credenciais descrito nas instruções de importação do Avro. Para iniciar a importação, execute o seguinte comando:

spanner databases import DATABASE_ID --url="URL" --format=csv

Opções de importação de CSV

Use as flags a seguir para personalizar como o Spanner Omni processa arquivos de texto:

  • --csv-date-format: substitui o formato das colunas de data. O padrão é %Y-%m-%d. Exemplo: %d/%m/%Y.

  • --csv-timestamp-format: substitui o formato das colunas de carimbo de data/hora. Use isso apenas se o Spanner Omni não for compatível com o formato no CSV. Exemplo: %d/%m/%Y %H:%M:%S%Ez.

  • --csv-delimiter: substitui o caractere delimitador. O padrão é uma vírgula.

  • --csv-quote-char: substitui o caractere de aspas. O padrão é uma aspa dupla.

  • --csv-escape-char: substitui o caractere de escape. O padrão é uma aspa dupla.

  • --csv-null-string: substitui a string que representa valores NULL. O padrão é \N.

  • --csv-has-trailing-delimiters: especifica se os arquivos CSV têm delimitadores finais. O padrão é false.

Exportar para arquivos Avro

Para exportar dados para arquivos Avro, siga as instruções de formato de URL em Instruções de importação do Avro.

Qualquer servidor na implantação pode gravar dados no repositório de dados fornecido. Se você usar uma pasta de arquivos local como destino, verifique se todos os servidores têm acesso ao mesmo caminho e podem gravar nele em paralelo.

O sistema exporta todas as tabelas e entidades do banco de dados. Forneça um caminho de pasta novo e vazio para os dados exportados.

Para iniciar a exportação, execute o seguinte comando:

spanner databases export DATABASE_ID --url="URL" --format=avro

As exportações CSV só são compatíveis com tabelas e não exportam o esquema do banco de dados.

Exportar para arquivos CSV

As exportações CSV não exportam o esquema do banco de dados e oferecem suporte apenas a tabelas. Para exportar dados para arquivos CSV, execute o seguinte comando:

spanner databases export DATABASE_ID --url="URL" --format=csv

Solução de problemas

Se uma importação falhar, as atualizações de esquema e os dados importados não serão revertidos automaticamente. Limpe o banco de dados manualmente antes de tentar realizar a operação novamente.

A velocidade de uma operação de importação depende de vários fatores, incluindo o número de arquivos na pasta, os recursos de computação disponíveis na implantação e a velocidade do disco. Se houver recursos suficientes disponíveis, o sistema importará os arquivos em paralelo.