Importare dati da database non Spanner

Questa pagina descrive come preparare i file Avro esportati da database non Spanner e poi importarli in Spanner. Queste procedure includono informazioni sia per i database con dialetto GoogleSQL sia per i database con dialetto PostgreSQL. Se vuoi importare un database Spanner che hai esportato in precedenza, consulta Importa file Avro di Spanner.

Il processo utilizza Dataflow; importa i dati da un bucket Cloud Storage che contiene un insieme di file Avro e un file manifest JSON che specifica le tabelle di destinazione e i file Avro che compilano ogni tabella.

Prima di iniziare

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

Abilita le API

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

Requisiti relativi alle quote

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

• Spanner: devi disporre di una capacità di calcolo sufficiente per supportare la quantità di dati che stai importando. Non è richiesta capacità di calcolo aggiuntiva per importare un database, anche se potrebbe essere necessario aggiungere ulteriore capacità di calcolo per completare il job in un periodo di tempo ragionevole. Per ulteriori dettagli, consulta Ottimizza i job.
• Cloud Storage: per l'importazione, devi avere un bucket contenente i file esportati in precedenza. Non è necessario impostare una dimensione per il bucket.
• Dataflow: i job di importazione sono soggetti alle stesse quote di Compute Engine relative a CPU, utilizzo del disco e indirizzi IP degli altri job Dataflow.

• Compute Engine: prima di eseguire il job di importazione, devi configurare le quote iniziali per Compute Engine, utilizzate da Dataflow. Queste quote rappresentano il numero massimo di risorse che consenti a Dataflow di utilizzare per il tuo job. I valori iniziali consigliati sono:

  • CPU: 200
  • Indirizzi IP in uso: 200
  • Standard Persistent Disk: 50 TB

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

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per esportare un database, chiedi all'amministratore di concederti i seguenti ruoli IAM sul tuo account di servizio worker Dataflow:

• Cloud Spanner Viewer (roles/spanner.viewer)
• Dataflow Worker (roles/dataflow.worker)
• Storage Admin (roles/storage.admin)
• Spanner Database Reader (roles/spanner.databaseReader)
• Database Admin (roles/spanner.databaseAdmin)

Esporta i dati da un database non Spanner in file Avro

Il processo di importazione recupera i dati dai file Avro che si trovano in un bucket Cloud Storage. Puoi esportare i dati in formato Avro da qualsiasi origine e puoi utilizzare qualsiasi metodo disponibile per farlo.

Per esportare i dati da un database non Spanner in file Avro, segui questi passaggi:

Quando esporti i dati, tieni presente quanto segue:

• Puoi eseguire l'esportazione utilizzando uno qualsiasi dei tipi primitivi Avro e il tipo complesso array.

• Ogni colonna dei file Avro deve utilizzare uno dei seguenti tipi di colonna:

  • ARRAY
  • BOOL
  • BYTES^*
  • DOUBLE
  • FLOAT
  • INT
  • LONG^†
  • STRING^‡

  ^* Viene utilizzata una colonna di tipo BYTES per importare un NUMERIC Spanner; per i dettagli, consulta la sezione Mappature consigliate di seguito.

  ^†,‡ Puoi importare un LONG che memorizza un timestamp o un STRING che memorizza un timestamp come TIMESTAMP Spanner; per i dettagli, consulta la sezione Mappature consigliate di seguito.

• Non è necessario includere o generare metadati quando esporti i file Avro.

• Non è necessario seguire una convenzione di denominazione specifica per i file.

Se non esporti i file direttamente in Cloud Storage, devi caricare i file Avro in un bucket Cloud Storage. Per istruzioni dettagliate, consulta Carica oggetti in Cloud Storage.

Importa file Avro da database non Spanner in Spanner

Per importare file Avro da un database non Spanner in Spanner, segui questi passaggi:

1. Crea tabelle di destinazione e definisci lo schema per il tuo database Spanner.
2. Crea un file spanner-export.json nel bucket Cloud Storage.
3. Esegui un job di importazione Dataflow utilizzando Google Cloud CLI.

Passaggio 1: crea lo schema per il database Spanner

Prima di eseguire l'importazione, devi creare la tabella di destinazione in Spanner e definirne lo schema.

Devi creare uno schema che utilizzi il tipo di colonna appropriato per ogni colonna dei file Avro.

Mappature consigliate

Passaggio 2: crea un file spanner-export.json

Devi anche creare un file denominato spanner-export.json nel tuo bucket Cloud Storage. Questo file specifica il dialetto del database e contiene un array tables che elenca il nome e le posizioni dei file di dati per ogni tabella.

I contenuti del file hanno il seguente formato:

{
  "tables": [
   {
    "name": "TABLE1",
    "dataFiles": [
      "RELATIVE/PATH/TO/TABLE1_FILE1",
      "RELATIVE/PATH/TO/TABLE1_FILE2"
    ]
   },
   {
    "name": "TABLE2",
    "dataFiles": ["RELATIVE/PATH/TO/TABLE2_FILE1"]
   }
  ],
  "dialect":"DATABASE_DIALECT"
}

Dove DATABASE_DIALECT = {GOOGLE_STANDARD_SQL | POSTGRESQL}

Se l'elemento dialect viene omesso, il dialetto predefinito è GOOGLE_STANDARD_SQL.

Passaggio 3: esegui un job di importazione Dataflow utilizzando gcloud CLI

Per avviare il job di importazione, segui le istruzioni per l'utilizzo di gcloud CLI per eseguire un job con il modello da Avro a Spanner.

Dopo aver avviato un job di importazione, puoi visualizzare i dettagli del job nella console Google Cloud .

Al termine del job di importazione, aggiungi gli indici secondari e le chiavi esterne necessarie.

Scegli una regione per il job di importazione

Ti consigliamo di scegliere una regione diversa in base alla località del tuo 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 della rete senza costi scegliendo la stessa regione per il job di importazione, supponendo che sia disponibile.

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

• Se non è disponibile una regione in co-location per il job di importazione o se la località del bucket Cloud Storage è una multi-regione, si applicano le tariffe per il trasferimento di dati in uscita. Consulta i prezzi del trasferimento di dati di Cloud Storage per scegliere una regione che comporta i costi di trasferimento di dati più bassi.

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

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

Visualizza i dettagli del job Dataflow

Per visualizzare i dettagli di tutti i job di importazione o esportazione eseguiti nell'ultima settimana, inclusi quelli 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:

   

   La console Google Cloud mostra i dettagli del job Dataflow.

Per visualizzare un job eseguito più di una settimana fa:

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

   Vai a Job

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

   La console Google Cloud mostra i dettagli del job Dataflow.

Visualizza i log di Dataflow per il tuo job

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

Se un job non va a buon fine, cerca gli errori nei log. Se sono presenti errori, il numero di errori viene visualizzato accanto a Log:

Per visualizzare gli errori dei job:

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

   La console Google Cloud mostra i log del job. Potresti dover scorrere per visualizzare gli errori.

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

3. Fai clic su una singola voce di log per espanderne i contenuti.

Per saperne di più sulla risoluzione dei problemi relativi ai job Dataflow, consulta Risolvi i problemi della pipeline.

Risolvi i problemi relativi ai job di importazione non riusciti

Se nei log dei job vengono visualizzati i seguenti errori:

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 scrittura del 99% nella scheda Monitoraggio del tuo database Spanner nella consoleGoogle Cloud . Se mostra valori elevati (più secondi), significa che l'istanza è sovraccarica, il che causa il timeout e l'errore delle scritture.

Una causa della latenza elevata è che il job Dataflow è in esecuzione con troppi worker, il che sovraccarica l'istanza Spanner.

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

Risolvi l'errore di rete

Quando esporti i database Spanner, potrebbe verificarsi il seguente errore:

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

Questo errore si verifica perché Spanner presuppone che tu voglia utilizzare una rete VPC in modalità automatica denominata default nello stesso progetto del job Dataflow. Se non hai una rete VPC predefinita nel progetto o se la tua rete VPC è in modalità personalizzata, devi creare un job Dataflow e specificare una rete o una subnet alternativa.

Ottimizza i job di importazione lenti

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

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

• Assicurati di avere risorse Dataflow sufficienti: se le quote di Compute Engine pertinenti limitano le risorse del job Dataflow, la pagina Dataflow del job nella console Google Cloud mostra 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 ulteriori addebiti per Compute Engine.

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

Fattori che influiscono sulle prestazioni dei job di importazione

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

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

• Schema di database Spanner, tra cui:

  • 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 ottenere prestazioni ottimali, è necessario un numero ottimale di worker Dataflow. Utilizzando la scalabilità automatica, Dataflow sceglie il numero di worker per il job in base alla quantità di lavoro da svolgere. Il numero di worker, tuttavia, sarà limitato dalle quote per le CPU, gli indirizzi IP in uso e il disco permanente standard. L'interfaccia utente di Dataflow mostra un'icona di avviso se rileva limiti di quota. In questa situazione, l'avanzamento è più lento, ma il job dovrebbe comunque essere completato. La scalabilità automatica può sovraccaricare Spanner, causando errori quando è presente una grande quantità di dati da importare.

• Carico esistente su Spanner: un job di importazione aggiunge un carico della CPU significativo su un'istanza Spanner. Se l'istanza ha già un carico esistente sostanziale, 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.

Ottimizza i worker per ottenere buone prestazioni di importazione

Quando avvii un job di importazione di Spanner, i worker Dataflow devono essere impostati su un valore ottimale per garantire prestazioni elevate. Un numero eccessivo di worker sovraccarica Spanner, mentre un numero insufficiente di worker comporta prestazioni di importazione deludenti.

Il numero massimo di worker dipende in gran parte dalle dimensioni dei dati, ma idealmente l'utilizzo totale della CPU di Spanner dovrebbe essere compreso tra il 70% e il 90%. In questo modo, si ottiene un buon equilibrio tra l'efficienza di Spanner e il completamento dei job senza errori.

Per raggiungere questo target di utilizzo nella maggior parte degli schemi e degli scenari, consigliamo un numero massimo di vCPU worker compreso tra 4 e 6 volte il numero di nodi Spanner.

Ad esempio, per un'istanza Spanner di 10 nodi, utilizzando worker n1-standard-2, imposteresti il numero massimo di worker su 25, ottenendo 50 vCPU.