Esporta database da Spanner ad Avro

Questa pagina descrive come esportare i database Spanner con la console Google Cloud. Per esportare un database Spanner utilizzando l'API REST o lo strumento a riga di comando gcloud spanner, completa i passaggi nella sezione Prima di iniziare di questa pagina, quindi consulta le istruzioni dettagliate in Spanner in Cloud Storage Avro nella documentazione di Dataflow. Il processo di esportazione utilizza Dataflow e scrive i dati in una cartella di un bucket Cloud Storage. La cartella risultante contiene un insieme di file Avro e file manifest JSON.

Prima di iniziare

Per esportare un database Spanner, devi prima abilitare le API Spanner, Cloud Storage, Compute Engine e Dataflow:

Abilita le API

Devi inoltre disporre di una quota sufficiente e delle autorizzazioni IAM richieste.

Requisiti per le quote

I requisiti di quota per i job di esportazione sono i seguenti:

• Spanner: non è necessaria capacità di calcolo aggiuntiva per esportare un database, anche se potrebbe essere necessario aggiungerne maggiore in modo che il job venga completato in un periodo di tempo ragionevole. Per ulteriori dettagli, vedi Ottimizzare i lavori.
• Cloud Storage: per l'esportazione, devi creare un bucket per i file esportati, se non ne hai già uno. Puoi farlo nella console Google Cloud, tramite la pagina Cloud Storage o durante la creazione dell'esportazione tramite la pagina Spanner. Non è necessario impostare le dimensioni del bucket.
• Dataflow: i job di esportazione sono soggetti alle stesse quote di Compute Engine di CPU, utilizzo del disco e indirizzo IP degli altri job Dataflow.

• Compute Engine: prima di eseguire il job di esportazione, devi impostare le quote iniziali per Compute Engine, utilizzato da Dataflow. Queste quote rappresentano il numero massimo di risorse che Dataflow può utilizzare per il tuo job. I valori iniziali consigliati sono:

  • CPU: 200
  • Indirizzi IP in uso: 200
  • Disco permanente standard: 50 TB

  In genere, non devi apportare altre modifiche. Dataflow fornisce la scalabilità automatica in modo che tu paghi solo per le risorse effettive utilizzate durante l'esportazione. Se il job può utilizzare più risorse, la UI di Dataflow mostra un'icona di avviso. Il job dovrebbe terminare anche se è presente un'icona di avviso.

Requisiti IAM

Per esportare un database, devi anche disporre di ruoli IAM con autorizzazioni sufficienti per utilizzare tutti i servizi coinvolti in un job di esportazione. Per informazioni sulla concessione di ruoli e autorizzazioni, consulta Applicare i ruoli IAM.

Per esportare un database, devi disporre dei seguenti ruoli:

• A livello di progetto Google Cloud:
  • Spanner Viewer (roles/spanner.viewer)
  • Amministratore Dataflow (roles/dataflow.admin)
  • Amministratore Storage (roles/storage.admin)
• A livello di database o istanza Spanner oppure a livello di progetto Google Cloud:
  • Lettore database Spanner (roles/spanner.databaseReader)
  • Amministratore database Spanner (roles/spanner.databaseAdmin)

Nota: il ruolo Amministratore database Spanner è richiesto solo per i job di importazione.

Per utilizzare le risorse di calcolo indipendenti di Spanner Data Boost durante un'esportazione, devi avere anche l'autorizzazione IAM spanner.databases.useDataBoost. Per ulteriori informazioni, consulta la panoramica di Data Boost.

Esporta un database

Dopo aver soddisfatto i requisiti di quota e IAM descritti in precedenza, puoi esportare un database Spanner esistente.

Nota: puoi esportare in sicurezza un database in uso. Tuttavia, eventuali modifiche apportate dopo la creazione di una transazione Spanner da parte di Dataflow non vengono acquisite dall'esportazione, perché tutti i dati esportati provengono dallo stesso snapshot del database.

Per esportare il database Spanner in un bucket Cloud Storage, segui questi passaggi.

1. Vai alla pagina Istanze di Spanner.

   Vai alla pagina delle istanze

2. Fai clic sul nome dell'istanza che contiene il database.

3. Fai clic sulla voce di menu Importa/Esporta nel riquadro a sinistra, quindi fai clic sul pulsante Esporta.

4. Nella sezione Scegli dove archiviare i tuoi dati esportati, fai clic su Sfoglia.

5. Se non hai ancora un bucket Cloud Storage per l'esportazione:

   1. Fai clic su Nuovo bucket .
   2. Inserisci un nome per il bucket. I nomi dei bucket devono essere univoci in Cloud Storage.
   3. Seleziona una classe di archiviazione e una posizione predefinite, quindi fai clic su Crea.
   4. Fai clic sul bucket per selezionarlo.

   Se hai già un bucket, seleziona il bucket dall'elenco iniziale o fai clic su Cerca per filtrare l'elenco, quindi fai clic sul tuo bucket per selezionarlo.

6. Fai clic su Seleziona.

7. Seleziona il database da esportare nel menu a discesa Scegli un database da esportare.

8. (Facoltativo) Per esportare il database da un momento precedente, seleziona la casella e inserisci un timestamp.

9. Seleziona una regione nel menu a discesa Scegli una regione per il job di esportazione.

   Nota: per evitare addebiti per il trasferimento di dati, scegli una regione che si sovrapponga alla configurazione dell'istanza. Per saperne di più, vedi Scegliere una regione.

10. (Facoltativo) Per criptare lo stato della pipeline Dataflow con una chiave di crittografia gestita dal cliente:

    1. Fai clic su Mostra opzioni di crittografia.
    2. Seleziona Utilizza una chiave di crittografia gestita dal cliente (CMEK).
    3. Seleziona la chiave dall'elenco a discesa.

    Questa opzione non influisce sulla crittografia di destinazione a livello di bucket Cloud Storage. Per abilitare CMEK per il tuo bucket Cloud Storage, consulta Utilizzare CMEK con Cloud Storage.

11. (Facoltativo) Per eseguire l'esportazione con Spanner Data Boost, seleziona la casella di controllo Utilizza Spanner Data Boost. Per ulteriori informazioni, consulta la panoramica di Data Boost.

12. Seleziona la casella di controllo in Conferma addebiti per confermare che sono previsti addebiti oltre a quelli sostenuti dall'istanza Spanner esistente.

13. Fai clic su Esporta.

    Nella console Google Cloud viene visualizzata la pagina Importazione/esportazione database, che ora mostra una voce per il job di esportazione nell'elenco dei job di importazione/esportazione, incluso il tempo trascorso del job:

    

Quando il job viene completato o terminato, lo stato viene aggiornato nell'elenco di importazione/esportazione. Se il job è riuscito, viene visualizzato lo stato Riuscito:

Se il job non è riuscito, viene visualizzato lo stato Non riuscito:

Per visualizzare i dettagli dell'operazione Dataflow per il tuo job, fai clic sul nome del job nella colonna Nome job Dataflow.

Se il job non riesce, controlla i log di Dataflow del job per i dettagli dell'errore.

Per evitare addebiti a Cloud Storage per i file creati dal job di esportazione non riuscito, elimina la cartella e i relativi file. Per informazioni su come trovare la cartella, consulta Visualizzare l'esportazione.

Nota sull'esportazione delle colonne generate e delle modifiche in tempo reale

I valori in una colonna generata archiviata non vengono esportati. La definizione della colonna viene esportata nello schema Avro come campo di record di tipo null, con la definizione della colonna come proprietà personalizzate del campo. Fino al completamento dell'operazione di backfill di una colonna generata di recente, la colonna generata viene ignorata come se non esistesse nello schema.

I flussi di modifiche esportati come file Avro contengono solo lo schema dei modifiche in tempo reale e non i record delle modifiche dei dati.

Nota sull'esportazione delle sequenze

Le sequenze (GoogleSQL e PostgreSQL) sono oggetti schema che utilizzi per generare valori interi univoci. Spanner esporta ciascuno degli oggetti dello schema nello schema Avro come campo di record, con il tipo di sequenza, l'intervallo ignorato e il contatore come proprietà del campo. Tieni presente che, per evitare che una sequenza venga reimpostata e generi valori duplicati dopo l'importazione, durante l'esportazione dello schema la funzione GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) acquisisce il contatore delle sequenze. Spanner aggiunge un buffer di 1000 al contatore e scrive il nuovo valore del contatore nel campo del record. Questo approccio evita errori di valori duplicati che potrebbero verificarsi dopo l'importazione. Se sono presenti più scritture sul database di origine durante l'esportazione dei dati, devi modificare il contatore delle sequenze effettivo utilizzando l'istruzione ALTER SEQUENCE (GoogleSQL, PostgreSQL).

Al momento dell'importazione, la sequenza inizia da questo nuovo contatore anziché da quello presente nello schema. In alternativa, puoi utilizzare l'istruzione ALTER SEQUENCE (GoogleSQL, PostgreSQL) per aggiornare la sequenza con un nuovo contatore.

Visualizza l'esportazione in Cloud Storage

Per visualizzare nella console Google Cloud la cartella contenente il database esportato, vai al browser Cloud Storage e scegli il bucket selezionato in precedenza:

Vai al browser di Cloud Storage

Il bucket ora contiene una cartella contenente il database esportato. Il nome della cartella inizia con l'ID dell'istanza, il nome del database e il timestamp del job di esportazione. La cartella contiene:

• Un file spanner-export.json
• Un file TableName-manifest.json per ogni tabella del database che hai esportato.

• Uno o più file TableName.avro-#####-of-#####. Il primo numero nell'estensione .avro-#####-of-##### rappresenta l'indice del file Avro, a partire da zero, e il secondo rappresenta il numero di file Avro generati per ogni tabella.

  Ad esempio, Songs.avro-00001-of-00002 è il secondo dei due file che contengono i dati per la tabella Songs.

• Un file ChangeStreamName-manifest.json per ogni flusso di modifiche nel database esportato.

• Un file ChangeStreamName.avro-00000-of-00001 per ogni flusso di modifiche. Questo file contiene dati vuoti con solo lo schema Avro del flusso di modifiche.

Scegli una regione per il job di importazione

Puoi scegliere una regione diversa in base alla località del bucket Cloud Storage. Per evitare addebiti per il trasferimento di dati in uscita, scegli una regione che corrisponda alla località del bucket Cloud Storage.

• Se la località del bucket Cloud Storage è una regione, puoi usufruire dell'utilizzo gratuito della rete scegliendo la stessa regione per il job di importazione, supponendo che quella regione sia disponibile.

• Se la località del bucket Cloud Storage è a due regioni, puoi usufruire dell'utilizzo gratuito della rete scegliendo una delle due regioni che compongono la doppia regione per il job di importazione, supponendo che una delle regioni sia disponibile.

• Se una regione con sede condivisa non è disponibile per il job di importazione o se la località bucket Cloud Storage è multiregionale, si applicano i costi per il trasferimento dei dati in uscita. Consulta i prezzi del trasferimento di dati di Cloud Storage per scegliere una regione in cui vengono addebitati i costi più bassi per il trasferimento di dati.

Esportare un sottoinsieme di tabelle

Se vuoi esportare solo i dati di determinate tabelle e non l'intero database, puoi specificare queste tabelle durante l'esportazione. In questo caso, Spanner esporta l'intero schema del database, inclusi i dati delle tabelle specificate, lasciando tutte le altre tabelle presenti ma vuote nel file esportato.

Puoi specificare un sottoinsieme di tabelle da esportare utilizzando la pagina Dataflow nella console Google Cloud o la riga di comando. La pagina Spanner non fornisce questa azione.

Se esporti i dati di una tabella figlio di un'altra, devi esportare anche i dati della relativa tabella parent. Se gli elementi principali non vengono esportati, il job di esportazione non va a buon fine.

Per esportare un sottoinsieme di tabelle, avvia l'esportazione utilizzando il modello Avro da Spanner a Cloud Storage di Dataflow e specifica le tabelle utilizzando la pagina Dataflow nella console Google Cloud o Google Cloud CLI, come descritto di seguito:

Console Google Cloud

Se utilizzi la pagina Dataflow nella console Google Cloud, il parametro Nomi tabelle Cloud Spanner si trova nella sezione Parametri facoltativi della pagina Crea job da modello. È possibile specificare più tabelle in formato separato da virgole.

Interfaccia a riga di comando gcloud

Se utilizzi Google Cloud CLI, utilizza l'argomento tableNames per specificare la tabella. Ad esempio:

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=table1,outputDir=gs://my-gcs-bucket' \
--max-workers=10

Per specificare più tabelle in gcloud è necessario eseguire l'escape dell'argomento di tipo dizionario. L'esempio seguente utilizza "|" come carattere di escape:

 gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='^|^instanceId=test-instance|databaseId=example-db|tableNames=table1,table2|outputDir=gs://my-gcs-bucket' \
--max-workers=10

Il parametro shouldExportRelatedTables è un'opzione utile per esportare automaticamente tutte le tabelle padre delle tabelle desiderate. Ad esempio, in questa gerarchia di schema con le tabelle Singers, Albums e Songs, dobbiamo solo specificare Songs. L'opzione shouldExportRelatedTables esporterà anche Singers e Albums perché Songs è un discendente di entrambi.

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=Songs,shouldExportRelatedTables=true,outputDir=gs://my-gcs-bucket' \
--max-workers=10

Visualizza o risolvi i problemi dei job nell'interfaccia utente di Dataflow

Dopo aver avviato un job di esportazione, puoi visualizzare i dettagli del job, inclusi i log, nella sezione Dataflow della console Google Cloud.

Visualizza dettagli job Dataflow

Per visualizzare i dettagli di eventuali job di importazione/esportazione che hai eseguito nell'ultima settimana, inclusi eventuali job attualmente in esecuzione:

1. Vai alla pagina Panoramica del database per il database.
2. Fai clic sulla voce di menu Importa/Esporta nel riquadro a sinistra. La pagina Importa/Esporta del database mostra un elenco dei job recenti.

3. Nella pagina Importa/Esporta del database, fai clic sul nome del job nella colonna Nome job Dataflow:

   

   Nella console Google Cloud vengono visualizzati i dettagli del job Dataflow.

Per visualizzare un lavoro che hai eseguito più di una settimana fa:

1. Vai alla pagina dei job Dataflow nella console Google Cloud.

   Vai alla pagina dei job

2. Trova il job nell'elenco e fai clic sul suo nome.

   Nella console Google Cloud vengono visualizzati i dettagli del job Dataflow.

Nota: i job dello stesso tipo per lo stesso database hanno lo stesso nome. Puoi distinguere i job in base ai valori nelle colonne Start time (Ora di inizio) o End time (Ora di fine).

Visualizza i log di Dataflow per il tuo job

Per visualizzare i log di un job Dataflow, vai alla pagina dei dettagli del job come descritto in precedenza, quindi fai clic su Log a destra del nome del job.

Se un job non riesce, cerca gli errori nei log. In caso di errori, il numero di errori viene visualizzato accanto a Log:

Per visualizzare gli errori del job:

1. Fai clic sul conteggio degli errori accanto a Log.

   Nella console Google Cloud vengono visualizzati i log del job. Potresti dover scorrere per vedere gli errori.

2. Individua le voci con l'icona di errore .

3. Fai clic su una singola voce di log per espanderne il contenuto.

Per ulteriori informazioni sulla risoluzione dei problemi dei job Dataflow, consulta Risoluzione dei problemi della pipeline.

Risolvere i problemi relativi ai job di esportazione non riusciti

Se visualizzi i seguenti errori nei log del job:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Controlla la latenza di lettura del 99% nella scheda Monitoring del database Spanner nella console Google Cloud. Se mostra valori elevati (più secondi), significa che l'istanza è sovraccarico, causando il timeout delle letture e l'esito negativo.

Una causa dell'alta latenza è che il job Dataflow viene eseguito utilizzando troppi worker, determinando un carico eccessivo sull'istanza Spanner.

Per specificare un limite per il numero di worker Dataflow, anziché utilizzare la scheda Importa/Esporta nella pagina dei dettagli dell'istanza del database Spanner nella console Google Cloud, devi avviare l'esportazione utilizzando il modello Avro da Cloud Spanner a Cloud Storage e specificare il numero massimo di worker come descritto di seguito:

• Se utilizzi la console di Dataflow, il parametro Numero massimo di worker si trova nella sezione Parametri facoltativi della pagina Crea job da modello.

• Se utilizzi gcloud, specifica l'argomento max-workers. Ad esempio:

  gcloud dataflow jobs run my-export-job \
  --gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
  --region=us-central1 \
  --parameters='instanceId=test-instance,databaseId=example-db,outputDir=gs://my-gcs-bucket' \
  --max-workers=10
  

Ottimizza i job di esportazione a esecuzione lenta

Se hai seguito i suggerimenti nelle impostazioni iniziali, in genere non dovresti apportare altre modifiche. Se il job viene eseguito lentamente, puoi provare alcune altre ottimizzazioni:

• Ottimizza il job e la località dei dati: esegui il job Dataflow nella stessa regione in cui si trovano l'istanza Spanner e il bucket Cloud Storage.

• Garantisci un numero sufficiente di risorse Dataflow: se le quote di Compute Engine pertinenti limitano le risorse del tuo job Dataflow, nella pagina Dataflow del job nella console Google Cloud vengono visualizzati un'icona di avviso e messaggi di log:

  

  In questo caso, l'aumento delle quote per CPU, indirizzi IP in uso e disco permanente standard potrebbe ridurre il tempo di esecuzione del job, ma potresti incorrere in addebiti più alti di Compute Engine.

• Controlla l'utilizzo della CPU di Spanner: se noti che l'utilizzo della CPU per l'istanza è superiore al 65%, puoi aumentare la capacità di calcolo in quell'istanza. La capacità aggiunge più risorse di Spanner e il job dovrebbe velocizzare il processo, ma ti verranno addebitati ulteriori costi di Spanner.

Fattori che influiscono sulle prestazioni dei job di esportazione

Il tempo necessario per completare un job di esportazione dipende da diversi fattori.

• Dimensioni del database Spanner: l'elaborazione di più dati richiede più tempo e risorse.

• Schema del database Spanner, che include:

  • Il numero di tabelle
  • La dimensione delle righe.
  • Il numero di indici secondari
  • Il numero di chiavi esterne
  • Il numero di modifiche in tempo reale

• Posizione dei dati: i dati vengono trasferiti tra Spanner e Cloud Storage utilizzando Dataflow. Idealmente, tutti e tre i componenti si trovano nella stessa regione. Se i componenti non si trovano nella stessa regione, lo spostamento dei dati tra regioni rallenta il job.

• Numero di worker Dataflow: per buone prestazioni sono necessari worker Dataflow ottimali. Mediante la scalabilità automatica, Dataflow sceglie il numero di worker per il job in base alla quantità di lavoro da svolgere. Il numero di worker sarà tuttavia limitato dalle quote per CPU, indirizzi IP in uso e disco permanente standard. La UI di Dataflow mostra un'icona di avviso in caso di limiti di quota. In questo caso, l'avanzamento è più lento, ma il job dovrebbe comunque essere completato.

• Carico esistente su Spanner: un job di esportazione in genere aggiunge un carico leggero su un'istanza Spanner. Se l'istanza ha già un carico esistente considerevole, il job viene eseguito più lentamente.

• Quantità di capacità di calcolo di Spanner: se l'utilizzo della CPU per l'istanza è superiore al 65%, il job viene eseguito più lentamente.