Importazione ed esportazione di dati

Questo documento descrive come eseguire la migrazione, il backup e il trasferimento dei dati in Spanner Omni utilizzando i formati Avro e CSV. Utilizza la CLI Spanner Omni per spostare i contenuti del database tra Spanner Omni e soluzioni di archiviazione come Cloud Storage, Amazon Simple Storage Service (Amazon S3), spazio di archiviazione locale compatibile con S3 o file system locali (NFS). I flussi di dati di importazione ed esportazione in Spanner Omni non supportano modelli, gruppi di località o posizionamenti.

Le operazioni di importazione ed esportazione vengono eseguite sui server Spanner Omni e condividono le risorse di sistema disponibili. L'importazione richiede molte risorse e può causare un elevato utilizzo di RAM, CPU e disco, il che potrebbe influire sui carichi di lavoro attivi. Sebbene queste attività vengano in genere eseguite con una priorità inferiore rispetto al traffico normale, devi monitorare la distribuzione per rilevare potenziali impatti sul rendimento.

Confronto dei formati di file

La seguente tabella confronta le funzionalità dei formati di file Avro e CSV per l'importazione e l'esportazione dei dati di Spanner.

Capacità	Avro	CSV
Importare o esportare un intero database	Sì	No
Importare tabelle esportate in precedenza	Sì	Sì
Esportare a un timestamp precedente	Sì	Sì
Importare o esportare utilizzando Spanner	Sì	Sì
Importare dati da altri database	No	Sì

I formati Avro e CSV esportano tutte le tabelle del database. Il formato Avro esporta anche lo schema, in modo che tu possa importarlo di nuovo. Il formato CSV non esporta lo schema.

Prima di iniziare

Prima di avviare un'operazione di importazione o esportazione, verifica le tue autorizzazioni e configura l'accesso alla posizione di archiviazione dei dati.

Autorizzazioni

Prima di iniziare, assicurati di disporre delle seguenti autorizzazioni:

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

Per saperne di più su Identity and Access Management (IAM) in Spanner Omni, consulta la panoramica di IAM. Per scoprire come aggiornare i ruoli di un utente, vedi Aggiorna gli utenti.

Origine e destinazione dei dati

Puoi archiviare i dati in un bucket Amazon Simple Storage Service (Amazon S3), in un bucket Cloud Storage, in uno spazio di archiviazione locale compatibile con Amazon S3 (ad esempio MinIO) o in un file system locale (NFS). Se utilizzi un file system locale, assicurati che i dati siano disponibili nello stesso percorso su tutti i server del deployment.

Puoi fornire l'accesso al datastore in due modi:

• Aggiungi spazio di archiviazione esterno al deployment: questo è il metodo preferito se prevedi di riutilizzare un bucket.

• Crea credenziali temporanee: assicurati che queste credenziali durino più a lungo della durata dell'operazione di importazione o esportazione (ad esempio, 48 ore).

Le credenziali devono fornire le autorizzazioni per elencare e leggere gli oggetti nel bucket per le importazioni. Per le esportazioni in Amazon S3, devi disporre delle seguenti autorizzazioni Amazon S3 aggiuntive:

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

Per saperne di più, consulta Autorizzazioni IAM.

Importa file Avro Spanner

Per importare i dati che hai esportato in precedenza da un altro database Spanner (Spanner o Spanner Omni) in formato Avro, segui questi passaggi.

Prerequisiti per l'importazione Avro

Prima di iniziare l'importazione Avro, assicurati che il tuo ambiente soddisfi i seguenti requisiti:

• Hai creato il database di destinazione.

• Gli oggetti dello schema che stai importando non esistono già nel database. La procedura di importazione Avro crea queste tabelle prima di importare i dati.

Istruzioni per l'importazione di Avro

Identifica il percorso della cartella contenente i dati esportati. La cartella contiene quanto segue:

• Un file spanner-export.json.

• Un file ENTITY_NAME-manifest.json per ogni entità esportata (ad esempio una tabella, una sequenza o uno schema).

• Tutti i file Avro elencati nei file manifest.

Se hai già aggiunto il datastore come spazio di archiviazione esterno, non devi includere le credenziali nel percorso. Puoi fornire il percorso direttamente. Se utilizzi credenziali monouso, utilizza i seguenti formati URL:

• Cloud Storage: gs://BUCKET_NAME/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY]. Utilizza le credenziali HMAC. Per saperne di più, consulta Chiavi HMAC.

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

• Cartella di file locale*: file:///PATH_TO_DIR

Per avviare l'importazione, esegui questo comando:

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

Note aggiuntive

Tieni presente le seguenti informazioni quando importi i file Avro:

• Nota sull'importazione di colonne generate e modifiche in tempo reale nella documentazione di Spanner.

• Una nota sull'importazione di sequenze nella documentazione di Spanner.

• Una nota sull'importazione di tabelle con interleaving e chiavi esterne nella documentazione di Spanner.

• Per saltare l'importazione di entità specifiche, rimuovile dal file spanner-export.json.

• La creazione dell'indice può richiedere molto tempo per i set di dati di grandi dimensioni. Per evitare di attendere la creazione dell'indice, utilizza il flag --avro-skip-wait-for-index-creation facoltativo.

Quando l'operazione di importazione viene avviata correttamente, restituisce un ID operazione a lunga esecuzione. Utilizza questo ID per monitorare lo stato dell'operazione.

Importare file CSV

Per importare i dati di testo che hai esportato da un altro database, segui questi passaggi.

Prerequisiti per l'importazione CSV

Prima di iniziare l'importazione del file CSV, assicurati di:

• Assicurati che le tabelle siano in uno dei seguenti tipi di dati supportati: BOOL, INT64, FLOAT64, NUMERIC, STRING, DATE, TIMESTAMP, BYTES e JSON.

• Crea il database di destinazione.

• Crea tutte le tabelle in cui vuoi importare i dati. Il processo di importazione CSV non crea tabelle.

• Assicurati che il file CSV non contenga una riga di intestazione.

Istruzioni per l'importazione CSV

Per importare i file CSV, crea un file manifest che descriva i dati da importare. Il file manifest utilizza la seguente struttura, definita qui in 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;
}

Di seguito è riportato un esempio di manifest:

{
  "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"}
      ]
    }
  ]
}

L'URL nel seguente comando import deve indirizzare alla cartella contenente un file manifest in formato JSON, come descritto nel manifest di esempio. Questo file può trovarsi in Cloud Storage, Amazon S3 o in una cartella di file locale, utilizzando lo stesso formato URL per le credenziali descritto nelle istruzioni per l'importazione Avro. Per avviare l'importazione, esegui questo comando:

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

Opzioni di importazione CSV

Utilizza i seguenti flag per personalizzare la gestione dei file di testo da parte di Spanner Omni:

• --csv-date-format: sostituisce il formato delle colonne di date. Il valore predefinito è %Y-%m-%d. Esempio: %d/%m/%Y.

• --csv-timestamp-format: sostituisce il formato delle colonne timestamp. Utilizza questa opzione solo se Spanner Omni non supporta il formato nel file CSV. Esempio: %d/%m/%Y %H:%M:%S%Ez.

• --csv-delimiter: esegue l'override del carattere delimitatore. Il valore predefinito è una virgola.

• --csv-quote-char: esegue l'override del carattere di citazione. Il valore predefinito è una virgoletta doppia.

• --csv-escape-char: esegue l'override del carattere di escape. Il valore predefinito è una virgoletta doppia.

• --csv-null-string: sostituisce la stringa che rappresenta i valori NULL. Il valore predefinito è \N.

• --csv-has-trailing-delimiters: specifica se i file CSV hanno delimitatori finali. Il valore predefinito è false.

Esportare in file Avro

Per esportare i dati nei file Avro, segui le istruzioni sul formato URL riportate nelle istruzioni per l'importazione di Avro.

Qualsiasi server nel deployment può scrivere dati nel datastore fornito. Se utilizzi una cartella di file locale come destinazione, assicurati che tutti i server abbiano accesso allo stesso percorso e possano scrivervi in parallelo.

Il sistema esporta tutte le tabelle e le entità nel database. Assicurati di fornire un percorso di cartella nuovo e vuoto per i dati esportati.

Per avviare l'esportazione, esegui questo comando:

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

Le esportazioni CSV supportano solo le tabelle e non esportano lo schema del database.

Esportare in file CSV

Le esportazioni CSV non esportano lo schema del database e supportano solo le tabelle. Per esportare i dati in file CSV, esegui questo comando:

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

Risoluzione dei problemi

Se un'importazione non va a buon fine, gli aggiornamenti dello schema e i dati importati non vengono ripristinati automaticamente. Libera spazio nel database manualmente prima di riprovare l'operazione.

La velocità di un'operazione di importazione dipende da diversi fattori, tra cui il numero di file nella cartella, le risorse di calcolo disponibili nella deployment e la velocità del disco. Se sono disponibili risorse sufficienti, il sistema importa i file in parallelo.