Esegui la migrazione a Cloud SQL da un file fisico XtraBackup

MySQL | PostgreSQL | SQL Server

Questa pagina descrive come eseguire la migrazione di un database MySQL da un server esterno a Cloud SQL utilizzando un file fisico Percona XtraBackup per MySQL.

Cloud SQL supporta la migrazione dei database MySQL su server esterni alle istanze Cloud SQL per MySQL utilizzando Percona XtraBackup. Puoi generare file fisici con l'utilità XtraBackup e quindi caricarli in Cloud Storage. L'utilizzo di file fisici può migliorare la velocità complessiva della migrazione fino a 10 volte rispetto a una normale migrazione basata su file di dump logico.

Cloud SQL supporta la migrazione fisica basata su file per MySQL 5.7 e 8.0. MySQL 5.6 non è supportato. La migrazione da Amazon Aurora o MySQL su database Amazon RDS non è supportata. Inoltre, l'istanza di replica di destinazione in Cloud SQL per MySQL deve essere installata con la stessa versione principale di MySQL del server esterno. Tuttavia, la replica di destinazione può utilizzare una versione secondaria successiva. Ad esempio, se il database esterno utilizza MySQL 8.0.31, la replica di destinazione deve essere Cloud SQL per MySQL versione 8.0.31 o successive.

La procedura descritta in questo documento utilizza l'API Cloud SQL per MySQL Admin. Puoi anche utilizzare Database Migration Service per eseguire questa migrazione. Per ulteriori informazioni sull'utilizzo di Database Migration Service, consulta Eseguire la migrazione dei database utilizzando un file fisico Percona XtraBackup.

Prima di iniziare

Questa sezione fornisce i passaggi da seguire prima di eseguire la migrazione del database MySQL a Google Cloud.

Configura un progetto Google Cloud

Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

Vai al selettore progetti

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Attiva l'API Cloud SQL Admin.

Abilita l'API

Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

Vai al selettore progetti

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Attiva l'API Cloud SQL Admin.

Abilita l'API

Assicurati di disporre dei ruoli Amministratore Cloud SQL, Amministratore Storage e Visualizzatore Compute per il tuo account utente.

Vai alla pagina IAM

Configurare un bucket Cloud Storage

Se non lo hai già fatto, crea un bucket Cloud Storage.

Installa Google Cloud SDK

Per utilizzare i comandi gcloud CLI sul tuo server esterno, installa Google Cloud SDK.

Prepara il server esterno per la migrazione

Installa una delle seguenti versioni dell'utilità XtraBackup sul tuo server esterno.
- Per MySQL 5.7, installa Percona XtraBackup 2.4.
- Per MySQL 8.0, installa Percona XtraBackup 8.0.x.
Per MySQL 8.0, devi installare una versione di XtraBackup uguale o superiore alla versione del server di origine. Per ulteriori informazioni, consulta la sezione Confronto tra versioni del server e versioni di backup nella documentazione di Percona XtraBackup.
Assicurati che il server esterno soddisfi tutti i requisiti necessari per la replica. Per maggiori informazioni, consulta Configurare il server esterno per la replica.

Oltre ai requisiti del server esterno per la replica, la migrazione da un file fisico XtraBackup prevede i seguenti requisiti:
- Il database MySQL deve essere un database on-premise o un database MySQL autogestito su una VM di Compute Engine. La migrazione da Amazon Aurora o MySQL su database Amazon RDS non è supportata.
- Devi configurare il parametro innodb_data_file_path con un solo file di dati che utilizzi il nome file di dati predefinito ibdata1. Se il database è configurato con due file di dati o ha un file di dati con un nome diverso, non puoi eseguire la migrazione del database utilizzando un file fisico XtraBackup. Ad esempio, un database configurato con innodb_data_file_path=ibdata01:50M:autoextend non è supportato per la migrazione.
- Il parametro innodb_page_size nel database esterno di origine deve essere configurato con il valore predefinito 16384.
Se non ne hai già configurato uno, crea un account utente di replica. Avrai bisogno del nome utente e della password di questo account utente.

Esegui la migrazione

Completa tutti i passaggi nelle seguenti sezioni per eseguire la migrazione del tuo database MySQL esterno a Cloud SQL.

Crea e prepara il file fisico XtraBackup

Sul server esterno, utilizza XtraBackup per eseguire un backup completo del database di origine. Per ulteriori informazioni sull'esecuzione di un backup completo, vedi Creare un backup completo nella documentazione di Percona XtraBackup.

Altri tipi di backup, come quello incrementale e parziale, non sono supportati.

Ad esempio:
```
sudo xtrabackup --backup \
--target-dir=XTRABACKUP_PATH \
--user=USERNAME \
--password=PASSWORD
```
Sostituisci le seguenti variabili:
- XTRABACKUP_PATH: la posizione del file di backup di output
- USERNAME: un utente con privilegi BACKUP_ADMIN nel database di origine
- PASSWORD: la password dell'utente
Utilizza l'utilità XtraBackup per preparare il file di backup. Il file deve essere in uno stato coerente. Per ulteriori informazioni sulla preparazione di un backup completo, consulta Preparare un backup completo. Ad esempio:
```
sudo xtrabackup --prepare --target-dir=XTRABACKUP_PATH
```
Sostituisci XTRABACKUP_PATH con la posizione del file di backup di output. Il completamento di questo comando potrebbe richiedere alcuni minuti, a seconda delle dimensioni del database.

Carica il file fisico XtraBackup su Cloud Storage

Utilizza l'utilità gsutil per caricare il file di backup in Cloud Storage.

  time gsutil -m rsync -r XTRABACKUP_PATH CLOUD_STORAGE_BUCKET

Sostituisci XTRABACKUP_PATH con la posizione del file di backup di output e CLOUD_STORAGE_BUCKET con il percorso del bucket Cloud Storage.

Non c'è limite alle dimensioni dei tuoi file XtraBackup. Tuttavia, esiste un limite di 5 TB per la dimensione di ogni singolo file che puoi caricare in un bucket Cloud Storage.

Definisci l'istanza della rappresentazione di origine

Crea un file source.json che definisce l'istanza di rappresentazione di origine per il server esterno. Un'istanza di rappresentazione di origine fornisce i metadati per il server esterno in Cloud SQL.

Nel file source.json, fornisci le seguenti informazioni di base sul tuo server esterno.

{
"name": "SOURCE_NAME",
 "region": "REGION",
 "databaseVersion": "DATABASE_VERSION",
 "onPremisesConfiguration": {
    "hostPort": "SOURCE_HOST:3306",
    "username": "REPLICATION_USER_NAME",
    "password": "REPLICATION_USER_PASSWORD",
    "dumpFilePath": "CLOUD_STORAGE_BUCKET"
    "caCertificate": "SOURCE_CERT",
    "clientCertificate": "CLIENT_CERT",
    "clientKey": "CLIENT_KEY"
  }
}

Proprietà	Description
`SOURCE_NAME`	Il nome dell'istanza della rappresentazione di origine da creare.
`REGION`	La regione in cui deve risiedere l'istanza della rappresentazione di origine. Specifica la stessa regione in cui creerai l'istanza di replica Cloud SQL di destinazione.
`DATABASE_VERSION`	La versione del database in esecuzione sul server esterno. Le uniche opzioni supportate sono `MYSQL_5_7` o `MYSQL_8_0`.
`SOURCE_HOST`	L'indirizzo IPv4 e la porta per il server esterno o l'indirizzo DNS per il server esterno. Se utilizzi un indirizzo DNS, questo può contenere fino a 60 caratteri.
`USERNAME`	L'account utente di replica sul server esterno.
`PASSWORD`	La password per l'account utente di replica.
`CLOUD_STORAGE_BUCKET`	Il nome del bucket Cloud Storage che contiene il file fisico XtraBackup.
`CLIENT_CA_CERT`	Il certificato CA sul server esterno. Includi solo se sul server esterno viene utilizzato SSL/TLS.
`CLIENT_CERT`	Il certificato client sul server esterno. Obbligatorio solo per l' autenticazione server-client. Includi solo se sul server esterno viene utilizzato SSL/TLS.
`CLIENT_KEY`	Il file della chiave privata per il certificato client sul server esterno. Obbligatorio solo per l' autenticazione server-client. Includi solo se sul server esterno viene utilizzato SSL/TLS.

Crea l'istanza della rappresentazione di origine inviando una richiesta all'API Cloud SQL Admin con il seguente comando curl. Nei dati della richiesta, fornisci il file source.json che hai creato.

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header 'Content-Type: application/json' \
    --data @./source.json \
    -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

Proprietà	Description
`PROJECT_ID`	L'ID del tuo progetto in Google Cloud.

Identifica un'istanza di replica di destinazione

Crea un file che identifichi la replica di destinazione in Cloud SQL per la migrazione. Puoi eseguire la migrazione dei dati in una nuova istanza creando una replica oppure utilizzare un'istanza Cloud SQL esistente retrocedendo una replica.

Opzione 1: crea un'istanza di replica

Per creare un'istanza di replica, utilizza il seguente file replica.json di esempio:

{
"name": "REPLICA_NAME",
"region": "REGION",
"databaseVersion": "DB_VERSION",
"settings": {
   "tier": "INSTANCE_TIER",
   "dataDiskSizeGb": "DISK_SIZE_GB",
   "edition": "EDITION_NAME"
},
"masterInstanceName": "SOURCE_NAME"
}

Proprietà	Descrizione
`REPLICA_NAME`	Il nome della replica Cloud SQL da creare.
`REGION`	Specifica la stessa regione che hai assegnato all'istanza della rappresentazione di origine.
`DATABASE_VERSION`	La versione del database da utilizzare con la replica di Cloud SQL. Le opzioni per questa versione sono `MYSQL_5_7` o `MYSQL_8_0`. Questa versione principale del database deve corrispondere alla versione del database specificata per il server esterno. Puoi anche specificare una versione secondaria, ma questa deve essere la stessa o una versione successiva rispetto alla versione installata sul server esterno. Per un elenco delle stringhe disponibili per MySQL, consulta SqlDatabaseVersion.
`INSTANCE_TIER`	Il tipo di macchina su cui ospitare l'istanza di replica. Devi specificare un tipo di macchina corrispondente all'edizione della tua istanza. Ad esempio, se specifichi `ENTERPRISE_PLUS` per il campo `edition`, devi specificare un tipo di macchina ottimizzata per db-perf. Per un elenco dei tipi di macchina supportati, vedi Tipo di macchina.
`DISK_SIZE_GB`	La dimensione dello spazio di archiviazione per la replica Cloud SQL, in GB. Importante: devi specificare una dimensione di archiviazione superiore a quella del file fisico che hai caricato in Cloud Storage.
`EDITION_NAME`	La versione di Cloud SQL da utilizzare per la replica. I valori possibili sono `ENTERPRISE_PLUS` (solo MySQL 8.0) o `ENTERPRISE`.
`SOURCE_NAME`	Il nome che hai assegnato all'istanza di rappresentazione di origine.

Crea l'istanza di replica di destinazione inviando una richiesta all'API Cloud SQL Admin con il seguente comando curl. Nei dati della richiesta, fornisci il file JSON che hai creato.

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header 'Content-Type: application/json' \
    --data @./replica.json \
    -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

Proprietà	Description
`PROJECT_ID`	L'ID del tuo progetto in Google Cloud.

Opzione 2: utilizza un'istanza di replica esistente

Assicurati che l'istanza di replica esistente abbia almeno la stessa quantità di spazio su disco libero dei file fisici che hai caricato nel bucket Cloud Storage. L'istanza deve avere un disco sufficiente per scaricare la stessa quantità di dati da Cloud Storage.
Per utilizzare un'istanza di replica esistente, usa il seguente file di esempio replica.json:
```
{
"demoteContext": {
    "sourceRepresentativeInstanceName": "SOURCE_NAME"
  }
}
```
Proprietà Descrizione

SOURCE_NAME Il nome che hai assegnato all'istanza di rappresentazione di origine.
Retrocedi l'istanza di replica di destinazione esistente inviando una richiesta all'API Cloud SQL Admin con il seguente comando curl. Nei dati della richiesta, fornisci il file JSON che hai creato.
```
gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header 'Content-Type: application/json' \
    --data @./replica.json \
    -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/EXISTING_INSTANCE_ID/demote
```
Proprietà Description

PROJECT_ID L'ID del tuo progetto in Google Cloud.

EXISTING_INSTANCE_ID L'ID dell'istanza di replica esistente che vuoi utilizzare per la migrazione.

Proprietà	Descrizione
`SOURCE_NAME`	Il nome che hai assegnato all'istanza di rappresentazione di origine.

Verifica le impostazioni di migrazione

Verifica che le istanze siano configurate correttamente per la migrazione eseguendo questo comando.

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{
             "syncMode": "SYNC_MODE",
             "skipVerification": false,
             "migrationType": "PHYSICAL"
               }' \
     -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/verifyExternalSyncSettings

Proprietà	Description
`SYNC_MODE`	Specifica `offline` per configurare la migrazione come processo una tantum. Per configurare la replica continua dal server esterno, specifica `online`.
`PROJECT_ID`	L'ID del tuo progetto in Google Cloud.
`REPLICA_NAME`	Il nome che hai assegnato all'istanza della replica di destinazione.

Come risposta iniziale, questo passaggio di verifica restituisce un account di servizio. Devi fornire a questo account di servizio le autorizzazioni di Cloud Storage per continuare il processo di migrazione. È previsto il messaggio di errore Autorizzazioni insufficienti. Di seguito è riportato un esempio di risposta:

{
    "kind": "sql#externalSyncSettingError",
    "type": "INSUFFICIENT_GCS_PERMISSIONS",
    "detail": "Service account
              p703314288590-df3om0@my-project.iam.gserviceaccount.com
              is missing necessary permissions storage.objects.list and
              storage.objects.get to access Google Cloud Storage bucket"
}

Aggiungi autorizzazioni Cloud Storage all'account di servizio restituito

Per aggiungere le autorizzazioni richieste:

Nella console Google Cloud, vai alla pagina Bucket in Cloud Storage.

Vai a Bucket
Fai clic sulla scheda Autorizzazioni.
Fai clic su Concedi l'accesso.
Nel campo Nuove entità, digita il nome dell'account di servizio restituito nella risposta di verifica. Ad esempio, nell'output di esempio del passaggio precedente, il nome dell'account di servizio restituito è p703314288590-df3om0@my-project.iam.gserviceaccount.com.
Nel menu a discesa Seleziona un ruolo, seleziona il ruolo Storage Object Viewer.
Fai clic su Salva.

Esegui di nuovo la verifica

Dopo aver aggiunto le autorizzazioni richieste all'account di servizio, esegui nuovamente il passaggio di verifica per assicurarti che l'account di servizio abbia accesso al bucket Cloud Storage.

Il passaggio di verifica controlla quanto segue:

La connettività tra la replica Cloud SQL e il server esterno è presente, ma solo se la migrazione è continua
I privilegi utente per la replica sono sufficienti
Le versioni sono compatibili
La replica Cloud SQL non è già in fase di replica
I binlog sono abilitati sul server esterno

Se vengono rilevati problemi, Cloud SQL restituisce un messaggio di errore.

Aggiungi utenti alla replica di Cloud SQL

Non puoi importare o eseguire la migrazione degli account utente del database dal server esterno. Se devi aggiungere account utente del database alla replica Cloud SQL, aggiungili prima di avviare la replica. Per maggiori informazioni, consulta Gestire gli utenti con l'autenticazione integrata.

Avvia la migrazione

Una volta completata la verifica e dopo che non sono stati restituiti errori, potrai avviare la migrazione. Per eseguire la migrazione del server esterno, utilizza l'API startExternalSync.

Utilizza il seguente comando:

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{
               "syncMode": "SYNC_MODE",
               "skipVerification": false,
               "migrationType": "PHYSICAL"
              }' \
     -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/startExternalSync

Proprietà	Description
`SYNC_MODE`	Specifica `offline` per configurare la migrazione come processo una tantum. Per configurare la replica continua dal server esterno, specifica `online`.
`PROJECT_ID`	L'ID del tuo progetto in Google Cloud.
`REPLICA_NAME`	Il nome che hai assegnato all'istanza della replica di destinazione.

Monitoraggio della migrazione

Per controllare lo stato della migrazione, puoi fare quanto segue:

Recupera l'ID operazione del job di migrazione dalla risposta dell'API startExternalSync. Ad esempio:

{
"kind": "sql#operation",
 "targetLink": "https://sqladmin.googleapis.com/v1/projects/my-project/instances/replica-instance",
 "status": "PENDING",
 "user": "user@example.com",
 "insertTime": "******",
 "operationType": "START_EXTERNAL_SYNC",
 "name": "******",
 "targetId": "replica-instance",
 "selfLink": "https://sqladmin.googleapis.com/v1/projects/my-project/operations/OPERATION_ID",
 "targetProject": "my-project"
}

Utilizza l'ID operazione nel comando seguente.

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header 'Content-Type: application/json' \
    -X GET \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/START_EXTERNAL_SYNC_OPERATION_ID

Proprietà	Description
`PROJECT_ID`	L'ID del tuo progetto in Google Cloud.
`START_EXTERNAL_SYNC_OPERATION_ID`	L'ID operazione del job di migrazione.

Monitora replica

Quando l'istanza di replica di destinazione in Cloud SQL completa il caricamento iniziale dei dati, l'istanza si connette al server esterno e applica tutti gli aggiornamenti eseguiti dopo l'operazione di esportazione.

Per monitorare lo stato della replica, consulta Confermare lo stato della replica.

Dopo che la replica Cloud SQL ha ricevuto tutte le modifiche dal server esterno e non si verifica alcun ritardo di replica sulla replica Cloud SQL, connettiti al tuo database. Esegui i comandi del database appropriati per assicurarti che i contenuti siano quelli previsti rispetto al server esterno.

Dopo aver promosso la replica di destinazione a un'istanza autonoma, puoi eliminare i file fisici XtraBackup nel bucket Cloud Storage. Conserva il server esterno fino al completamento delle convalide necessarie.

Limitazioni

Questa sezione elenca le limitazioni con il processo di migrazione XtraBackup:

È necessario utilizzare Percona XtraBackup per eseguire il backup dei dati nel bucket Cloud Storage. Altre utilità di backup non sono supportate.
La migrazione non è supportata alle versioni principali o secondarie del database precedenti. Ad esempio, non puoi eseguire la migrazione da MySQL 8.0 a 5.7 o da MySQL da 8.0.36 a 8.0.16.
La migrazione dei database da un file fisico XtraBackup è supportata solo per i database MySQL on-premise o per un database MySQL autogestito in esecuzione su una VM Compute Engine. La migrazione da Amazon Aurora o MySQL su database Amazon RDS non è supportata.
Puoi eseguire la migrazione solo da un backup completo. Altri tipi di backup, come quelli incrementali o parziali, non sono supportati.
La migrazione del database non include privilegi o utenti del database.
Devi impostare il formato del log binario su ROW. Se configuri il log binario in un altro formato, ad esempio STATEMENT o MIXED, la replica potrebbe non riuscire.
Cloud Storage limita a 5 TB le dimensioni di un file che puoi caricare in un bucket.
Non puoi eseguire la migrazione di plug-in dal database esterno.
Se hai configurato l'alta disponibilità per la tua istanza, lo SLA (accordo sul livello del servizio) non verrà applicato fino al completamento della fase iniziale della migrazione. Questa fase è considerata completata quando tutti i dati dei file fisici di XtraBackup sono stati importati nell'istanza Cloud SQL.

Risolvere i problemi

In questa sezione sono elencati gli scenari comuni di risoluzione dei problemi.

Importazione non riuscita

Se viene visualizzato un messaggio di errore simile a Attempt 1/2: import failed quando esegui la migrazione, devi specificare PHYSICAL per migrationType quando avvii la migrazione.

Se non specifichi un migrationType, il tipo sarà impostato in modo predefinito su LOGICAL.

Annullare o interrompere una migrazione

Se devi annullare o interrompere una migrazione, puoi eseguire questo comando:

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
    -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/restart

Proprietà	Description
`PROJECT_ID`	L'ID del tuo progetto in Google Cloud.
`REPLICA_NAME`	Il nome che hai assegnato all'istanza della replica di destinazione.

Proprietà	Description
`PROJECT_ID`	L'ID del tuo progetto in Google Cloud.
`EXISTING_INSTANCE_ID`	L'ID dell'istanza di replica esistente che vuoi utilizzare per la migrazione.

Esegui la migrazione a Cloud SQL da un file fisico XtraBackup

Prima di iniziare

Configura un progetto Google Cloud

Configurare un bucket Cloud Storage

Installa Google Cloud SDK

Prepara il server esterno per la migrazione

Esegui la migrazione

Crea e prepara il file fisico XtraBackup

Carica il file fisico XtraBackup su Cloud Storage

Definisci l'istanza della rappresentazione di origine

Identifica un'istanza di replica di destinazione

Opzione 1: crea un'istanza di replica

Opzione 2: utilizza un'istanza di replica esistente

Verifica le impostazioni di migrazione

Aggiungi autorizzazioni Cloud Storage all'account di servizio restituito

Esegui di nuovo la verifica

Aggiungi utenti alla replica di Cloud SQL

Avvia la migrazione

Monitoraggio della migrazione

Monitora replica

Limitazioni

Risolvere i problemi

Importazione non riuscita

Annullare o interrompere una migrazione

Passaggi successivi