Esegui l'upgrade della versione principale del database in loco

Questa pagina descrive come eseguire l'upgrade della versione principale del database eseguendo l'upgrade in situ dell'istanza Cloud SQL anziché eseguire la migrazione dei dati.

Introduzione

I fornitori di software per database rilasciano periodicamente nuove versioni principali che contengono nuove funzionalità, miglioramenti delle prestazioni e della sicurezza. Cloud SQL importa le nuove versioni dopo il loro rilascio. Quando Cloud SQL offre il supporto per una nuova versione principale, puoi eseguire l'upgrade delle istanze per mantenere aggiornato il database.

Puoi eseguire l'upgrade della versione del database di un'istanza in situ o tramite la migrazione dei dati. Gli upgrade in situ sono un modo più semplice per eseguire l'upgrade della versione principale dell'istanza. Non è necessario eseguire la migrazione dei dati o modificare le stringhe di connessione dell'applicazione. Con gli upgrade in place, puoi mantenere il nome, l'indirizzo IP e altre impostazioni della tua istanza attuale dopo l'upgrade. Gli upgrade in situ non richiedono lo spostamento dei file di dati e possono essere completati più rapidamente. In alcuni casi, il tempo di riposo è inferiore a quello necessario per la migrazione dei dati.

L'operazione di upgrade in situ di Cloud SQL per PostgreSQL utilizza l'utilità pg_upgrade.

Pianificare un upgrade della versione principale

  1. Scegli una versione principale di destinazione.

    gcloud

    Per informazioni su come installare e iniziare a utilizzare gcloud CLI, consulta Installare gcloud CLI. Per informazioni su come avviare Cloud Shell, consulta Utilizzare Cloud Shell.

    Per controllare le versioni del database che puoi scegliere come target per un upgrade in situ sulla tua istanza:

    1. Esegui questo comando.
      2. gcloud sql instances describe INSTANCE_NAME

      Sostituisci INSTANCE_NAME con il nome dell'istanza.

    2. Nell'output del comando, individua la sezione etichettata upgradableDatabaseVersions.
    3. Ogni sottosezione restituisce una versione del database disponibile per l'upgrade. In ogni sottosezione, controlla i seguenti campi.
      • majorVersion: la versione principale che puoi scegliere come target per l'upgrade in situ.
      • name: la stringa della versione del database che include la versione principale.
      • displayName: il nome visualizzato della versione del database.

    REST v1

    Per controllare quali versioni del database di destinazione sono disponibili per un upgrade in place della versione principale, utilizza il metodo instances.get dell'API Cloud SQL Admin.

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • INSTANCE_NAME: il nome dell'istanza.

    Metodo HTTP e URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Per inviare la richiesta, espandi una di queste opzioni:

    Dovresti ricevere una risposta JSON simile alla seguente:

    
upgradableDatabaseVersions:

{
  major_version: "POSTGRES_15_0"
  name: "POSTGRES_15_0"
  display_name: "PostgreSQL 15.0"
}

    REST v1beta4

    Per controllare quali versioni del database di destinazione sono disponibili per l'upgrade in situ della versione principale di un'istanza, utilizza il metodo instances.get dell'API Cloud SQL Admin.

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • INSTANCE_NAME: il nome dell'istanza.

    Metodo HTTP e URL: 

    GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

    Per inviare la richiesta, espandi una di queste opzioni:

    Dovresti ricevere una risposta JSON simile alla seguente:

    
upgradableDatabaseVersions:

{
  major_version: "POSTGRES_15_0"
  name: "POSTGRES_15_0"
  display_name: "PostgreSQL 15.0"
}

    Per l'elenco completo delle versioni del database supportate da Cloud SQL, consulta Versioni del database e criteri di versione.

  2. Prendi in considerazione le funzionalità offerte in ogni versione principale del database e risolvi le incompatibilità.

    Le nuove versioni principali introducono modifiche incompatibili che potrebbero richiedere la modifica del codice dell'applicazione, dello schema o delle impostazioni del database. Prima di eseguire l'upgrade dell'istanza di database, consulta le note di rilascio della versione principale di destinazione per determinare le incompatibilità da risolvere.

  3. Prova l'upgrade con una simulazione.

    Esegui una simulazione della procedura di upgrade end-to-end in un ambiente di test prima di eseguire l'upgrade del database di produzione. Puoi clonare l'istanza per creare una copia identica dei dati su cui testare la procedura di upgrade.

    Oltre a verificare che l'upgrade venga completato correttamente, esegui dei test per assicurarti che l'applicazione si comporti come previsto nel database di cui è stato eseguito l'upgrade.

  4. Decidi un orario per l'upgrade.

    L'upgrade richiede che l'istanza non sia disponibile per un determinato periodo di tempo. Pianifica l'upgrade in un periodo di tempo in cui l'attività del database è ridotta.

Prepararsi per un upgrade della versione principale

Prima di eseguire l'upgrade, completa i seguenti passaggi.

  1. Controlla il valore LC_COLLATE per i database template e postgres. Il set di caratteri per ogni database deve essere en_US.UTF8.

    Se il valore LC_COLLATE per i database template e postgres non è en_US.UTF8, l'upgrade della versione principale non va a buon fine. Per risolvere il problema, se uno dei database ha un set di caratteri diverso da en_US.UTF8, modifica il valore LC_COLLATE in en_US.UTF8 prima di eseguire l'upgrade.

    Per modificare la codifica di un database:

    1. Esegui il dump del database.
    2. Elimina il database.
    3. Crea un nuovo database con la codifica diversa (in questo esempio, en_US.UTF8).
    4. Ricarica i dati.

    Un'altra opzione è rinominare il database:

    1. Chiudi tutte le connessioni al database.
    2. Rinomina il database.
    3. Aggiorna le configurazioni dell'applicazione in modo da utilizzare il nuovo nome del database.
    4. Crea un nuovo database vuoto con la codifica predefinita.

    Ti consigliamo di eseguire questi passaggi su un'istanza clonata prima di applicarli a un'istanza di produzione.

  2. Gestisci le repliche di lettura.

    Cloud SQL per PostgreSQL non supporta la replica tra versioni, il che significa che non puoi eseguire l'upgrade dell'istanza principale mentre viene eseguita la replica alle repliche di lettura. Prima di eseguire l'upgrade, disabilita la replica per ogni replica di lettura o elimina le repliche di lettura.

  3. Se Cloud SQL è l'origine della replica logica, disattiva la replica dell'estensione pglogical come segue. Puoi riattivarla al termine dell'upgrade. Se Cloud SQL è la destinazione della replica logica, questi passaggi non sono necessari.
    1. Disattiva l'abbonamento e scollega la replica dal provider utilizzando il seguente comando: 
      SELECT * FROM pglogical.alter_subscription_disable(subscription_name name, immediate bool);

      Sostituisci name con il nome dell'abbonamento esistente.

      Imposta il valore del parametro immediate su true se l'abbonamento deve essere disattivato immediatamente. Per impostazione predefinita, il valore è false e l'abbonamento viene disattivato solo al termine della transazione in corso.

      Ad esempio: 

      postgres=> SELECT * FROM pglogical.alter_subscription_disable('test_sub', true);
 alter_subscription_disable
----------------------------
 t
(1 row)
    2. Elimina lo slot di replica connettendoti all'editore o all'istanza Cloud SQL principale ed eseguendo il seguente comando: 
      SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots
  WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);

      Ad esempio: 

      postgres=> SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots
postgres->    WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);
-[ RECORD 1 ]------------+-
pg_drop_replication_slot |

postgres=>

  4. Gestisci le estensioni PostgreSQL rimanenti.

    La maggior parte delle estensioni funziona nella versione principale del database di cui è stato eseguito l'upgrade. Rimuovi tutte le estensioni che non sono più supportate nella versione di destinazione. Ad esempio, elimina l'estensione chkpass se esegui l'upgrade a PostgreSQL 11 o versioni successive.

    Puoi eseguire l'upgrade di PostGIS e delle relative estensioni alle versioni supportate più recenti manualmente.

    A volte, l'upgrade da PostGIS 2.x può creare una situazione in cui rimangono oggetti di database non associati all'estensione PostGIS. Ciò può bloccare l'operazione di upgrade. Per informazioni sulla risoluzione di questo problema, consulta Correggere un'installazione di raster postgis non funzionante.

    A volte, l'upgrade a PostGIS 3.1.7 o versioni successive non può essere completato a causa di oggetti che utilizzano funzioni ritirate. Ciò può bloccare l'operazione di upgrade. Per controllare lo stato dell'upgrade, esegui SELECT PostGIS_full_version();. Se sono presenti avvisi, elimina tutti gli oggetti che utilizzano le funzioni ritirate e aggiorna l'estensione PostGIS a una versione intermedia o successiva. Dopo aver completato queste azioni, esegui di nuovo il comando SELECT PostGIS_full_version();. Verifica che non vengano visualizzati avvisi. Quindi, procedi con l'operazione di upgrade.

    Per scoprire di più sull'upgrade delle estensioni PostGIS, consulta Eseguire l'upgrade di PostGIS. Per i problemi associati all'upgrade di PostGIS, consulta Verificare la versione dell'istanza PostgreSQL.
  5. Gestisci i flag del database personalizzati. Controlla i nomi di eventuali flag di database personalizzati configurati per l'istanza PostgreSQL. Per i problemi associati a questi flag, consulta Controllare i flag personalizzati per l'istanza PostgreSQL.
  6. Quando esegui l'upgrade da una versione principale a un'altra, prova a connetterti a ciascun database per verificare se ci sono problemi di compatibilità. Assicurati che i database possano connettersi tra loro. Controlla il campo datallowconn per ogni database per assicurarti che sia consentita una connessione. Un valore t indica che è consentito, mentre un valore f indica che non è possibile stabilire una connessione.
  7. Se utilizzi l'installazione di Datadog per eseguire l'upgrade dell'istanza Cloud SQL a PostgreSQL 10 o versioni successive, prima di eseguire l'upgrade rimuovi la funzione pg_stat_activity().

Limitazioni note

Le seguenti limitazioni interessano gli upgrade in situ delle versioni principali per Cloud SQL per PostgreSQL:

  • Non puoi eseguire un upgrade in situ della versione principale su una replica esterna.
  • L'upgrade di istanze con più di 1000 database da una versione all'altra potrebbe richiedere molto tempo e scadere.
  • Utilizza l'istruzione select * from pg_largeobject_metadata; per eseguire una query sul numero di oggetti di grandi dimensioni in ogni database PostgreSQL della tua istanza Cloud SQL. Se il risultato di tutti i database è superiore a 10 milioni di oggetti di grandi dimensioni, l'upgrade non va a buon fine. Cloud SQL esegue il rollback alla versione precedente del database.
  • Prima di eseguire un upgrade in situ della versione principale a PostgreSQL 16 e versioni successive, esegui l'upgrade dell'estensione PostGIS per tutti i tuoi database alla versione 3.4.0.
  • Se utilizzi le versioni PostgreSQL 9.6, 10, 11 o 12, la versione 3.4.0 dell'estensione PostGIS non è supportata. Pertanto, per eseguire un upgrade in situ della versione principale a PostgreSQL 16 e versioni successive, devi prima eseguire l'upgrade a una versione intermedia di PostgreSQL (versioni 13, 14 o 15).

  • Se installi le estensioni pgRouting e pg_squeeze per la tua istanza, non puoi eseguire un upgrade alla versione principale. Per risolvere il problema, disinstalla queste estensioni ed esegui l'upgrade. Per ulteriori informazioni sulle estensioni, vedi Configurare le estensioni PostgreSQL.

  • Se attivi i flag vacuum_defer_cleanup_age e force_parallel_mode, non puoi eseguire l'upgrade a una versione principale. Per risolvere il problema, elimina questi flag ed esegui l'upgrade. Per ulteriori informazioni sui flag, inclusa la procedura per eliminarli, consulta Configurare i flag di database.

Esegui l'upgrade della versione principale del database in loco

Quando avvii un'operazione di upgrade, Cloud SQL controlla innanzitutto la configurazione dell'istanza per assicurarsi che sia compatibile con l'upgrade. Dopo aver verificato la configurazione, Cloud SQL rende l'istanza non disponibile, esegue un backup prima dell'upgrade, esegue l'upgrade, rende l'istanza disponibile ed esegue un backup dopo l'upgrade.

Console

  1. Nella console Google Cloud, vai alla pagina Istanze Cloud SQL.

    Vai a Istanze Cloud SQL

  2. Per aprire la pagina Panoramica di un'istanza, fai clic sul nome dell'istanza.
  3. Fai clic su Modifica.
  4. Nella sezione Informazioni sull'istanza, fai clic sul pulsante Esegui l'upgrade e conferma di voler passare alla pagina di upgrade.
  5. Nella pagina Scegli una versione del database, fai clic sull'elenco Versione del database per l'upgrade e seleziona una delle versioni principali del database disponibili.
  6. Fai clic su Continua.
  7. Nella casella ID istanza, inserisci il nome dell'istanza e fai clic sul pulsante Avvia l'upgrade.
Il completamento dell'operazione richiede diversi minuti.

Verifica che la versione principale del database di cui è stato eseguito l'upgrade venga visualizzata sotto il nome dell'istanza nella pagina Panoramica dell'istanza.

gcloud

  1. Avvia l'upgrade.

    Utilizza il comando gcloud sql instances patch con il flag --database-version.

    Prima di eseguire il comando, sostituisci quanto segue:

    • INSTANCE_NAME: il nome dell'istanza.
    • DATABASE_VERSION: l'enum per la versione principale del database, che deve essere successiva alla versione corrente. Specifica una versione del database per una versione principale disponibile come destinazione di upgrade per l'istanza. Puoi ottenere questo enum come primo passaggio di Pianifica l'upgrade. Se hai bisogno di un elenco completo degli enum delle versioni del database, consulta SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
--database-version=DATABASE_VERSION

    Gli upgrade delle versioni principali richiedono diversi minuti. Potresti visualizzare un messaggio che indica che l'operazione sta richiedendo più tempo del previsto. Puoi ignorare questo messaggio o eseguire il comando gcloud sql operations wait per ignorarlo.

  2. Recupera il nome dell'operazione di upgrade.

    Utilizza il comando gcloud sql operations list con il flag --instance.

    Prima di eseguire il comando, sostituisci la variabile INSTANCE_NAME con il nome dell'istanza. 

    gcloud sql operations list --instance=INSTANCE_NAME

  3. Monitora lo stato dell'upgrade.

    Utilizza il comando gcloud sql operations describe.

    Prima di eseguire il comando, sostituisci la variabile OPERATION con il nome dell'operazione di upgrade recuperato nel passaggio precedente. 

    gcloud sql operations describe OPERATION

REST v1

  1. Avvia l'upgrade in loco.

    Utilizza una richiesta PATCH con il metodo instances:patch.

    Prima di utilizzare i dati della richiesta, sostituisci queste variabili:

    • PROJECT_ID: l'ID del progetto.
    • INSTANCE_NAME: il nome dell'istanza.

    Metodo HTTP e URL: 

    PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Corpo JSON della richiesta: 

    {
  "databaseVersion": DATABASE_VERSION
}

    Sostituisci DATABASE_VERSION con l'enum per la versione principale del database, che deve essere successiva alla versione corrente. Specifica una versione del database per una versione principale disponibile come destinazione di upgrade per l'istanza. Puoi ottenere questo enum come primo passaggio di Pianifica l'upgrade. Se hai bisogno di un elenco completo degli enum delle versioni del database, consulta SqlDatabaseVersion.

  2. Recupera il nome dell'operazione di upgrade.

    Utilizza una richiesta GET con il metodo operations.list dopo aver sostituito PROJECT_ID con l'ID del progetto.

    Metodo HTTP e URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

  3. Monitora lo stato dell'upgrade.

    Utilizza una richiesta GET con il metodo operations.get dopo aver sostituito le seguenti variabili:

    • PROJECT_ID: l'ID del progetto.
    • OPERATION_NAME: il nome dell'operazione di upgrade recuperato nel passaggio precedente.

    Metodo HTTP e URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

Terraform

Per aggiornare la versione del database, utilizza una risorsa Terraform e il provider Terraform per Google Cloud, versione 4.34.0 o successiva.

resource "google_sql_database_instance" "instance" {
  name             = "postgres-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

Applica le modifiche

Per applicare la configurazione Terraform in un progetto Google Cloud, completa i passaggi nelle seguenti sezioni.

Prepara Cloud Shell

  1. Avvia Cloud Shell.

  2. Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.

    Devi eseguire questo comando una sola volta per progetto e puoi farlo in qualsiasi directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione di Terraform deve avere una propria directory (chiamata anche modulo principale).

  1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

    Copia il codice campione nel main.tf appena creato.

    Se vuoi, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

  3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
  4. Salva le modifiche.
  5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory. 
    terraform init

    Se vuoi, per utilizzare la versione più recente del provider Google, includi l'opzione -upgrade: 

    terraform init -upgrade

Applica le modifiche

  1. Rivedi la configurazione e verifica che le risorse che Terraform sta per creare o aggiornare corrispondano alle tue aspettative: 
    terraform plan

    Apporta le correzioni necessarie alla configurazione.

  2. Applica la configurazione di Terraform eseguendo il seguente comando e inserendo yes al prompt: 
    terraform apply

    Attendi che Terraform mostri il messaggio "Applicazione completata".

  3. Apri il tuo progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud, vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

Elimina le modifiche

Per eliminare le modifiche:

  1. Per disattivare la protezione dell'eliminazione, imposta l'argomento deletion_protection su false nel file di configurazione Terraform. 
    deletion_protection =  "false"
  2. Applica la configurazione Terraform aggiornata eseguendo il seguente comando e inserendo yes al prompt: 
    terraform apply

  1. Rimuovi le risorse applicate in precedenza con la configurazione Terraform eseguendo il seguente comando e inserendo yes al prompt:

    terraform destroy

Quando effettui una richiesta di upgrade in situ, Cloud SQL esegue innanzitutto un controllo pre-upgrade. Se Cloud SQL determina che l'istanza non è pronta per un upgrade, la richiesta di upgrade non va a buon fine e viene visualizzato un messaggio che suggerisce come risolvere il problema. Vedi anche Risolvere i problemi di un upgrade della versione principale.

Backup dell'upgrade automatico

Quando esegui un upgrade di una versione principale, Cloud SQL esegue automaticamente due backup on demand, chiamati backup di upgrade:

  • Il primo backup dell'upgrade è il backup pre-upgrade, che viene eseguito immediatamente prima dell'avvio dell'upgrade. Puoi utilizzare questo backup per ripristinare la tua istanza di database allo stato della versione precedente.
  • Il secondo backup dell'upgrade è il backup post-upgrade, che viene eseguito subito dopo che sono consentite nuove scritture nell'istanza del database di cui è stato eseguito l'upgrade.

Quando visualizzi l'elenco dei backup, i backup dell'upgrade sono elencati con il tipo On-demand. I backup di upgrade sono etichettati in modo da poterli identificare rapidamente. Ad esempio, se esegui l'upgrade da PostgreSQL 14 a PostgreSQL 15, il backup pre-upgrade è etichettato come Pre-upgrade backup, POSTGRES_14 to POSTGRES_15. e il backup post-upgrade come Post-upgrade backup, POSTGRES_14 to POSTGRES_15.

Come per gli altri backup on demand, i backup di upgrade rimangono visibili finché non li elimini o non elimini l'istanza. Se hai attivato il PITR, non puoi eliminare i backup dell'upgrade mentre si trovano nel periodo di conservazione. Se devi eliminare i backup dell'upgrade, devi disattivare la copia incrementale a livello di blocco o attendere che i backup dell'upgrade non siano più inclusi nel periodo di conservazione.

Completare l'upgrade della versione principale

Al termine dell'upgrade dell'istanza principale, svolgi i seguenti passaggi per completare l'upgrade:

  1. Attiva la replica di pglogical se la tua istanza la utilizzava prima dell'upgrade. In questo modo viene creato automaticamente lo spazio di replica necessario.
    1. Elimina l'abbonamento pglogical sulla replica di destinazione utilizzando il seguente comando: 
      select pglogical.drop_subscription(subscription_name name);

      Sostituisci name con il nome dell'abbonamento esistente.

      Ad esempio: 

      postgres=> select pglogical.drop_subscription(subscription_name := 'test_sub');
-[ RECORD 1 ]-----+--
drop_subscription | 1
    2. Ricrea l'abbonamento pglogical sulla destinazione (replica) fornendo i dettagli di connessione come segue all'istanza principale Cloud SQL: 
      SELECT pglogical.create_subscription(
    subscription_name := 'test_sub',
    provider_dsn := 'host=primary-ip port=5432 dbname=postgres user=replication_user password=replicapassword'
);

      Ad esempio: 

      postgres=> SELECT pglogical.create_subscription(
postgres(>     subscription_name := 'test_sub',
postgres(>     provider_dsn := 'host=10.58.64.90 port=5432 dbname=postgres user=postgres password=postgres'
postgres(> );
-[ RECORD 1 ]-------+-----------
create_subscription | 2769129391
    3. Controlla lo stato dell'abbonamento utilizzando il seguente comando: 
      SELECT * FROM pglogical.show_subscription_status('test_sub');
    4. Testa la replica eseguendo transazioni di scrittura e verifica che le modifiche siano visibili nella destinazione.

  2. Esegui l'upgrade delle repliche di lettura.

    Se hai interrotto la replica alle repliche di lettura, esegui l'upgrade una alla volta. Puoi utilizzare uno dei metodi utilizzati per eseguire l'upgrade dell'istanza principale. Quando esegui l'upgrade di una replica, Cloud SQL la ricrea preservando gli indirizzi IP, la aggiorna con i dati più recenti dell'istanza principale e la riavvia.

    Se hai eliminato le repliche di lettura prima di eseguire l'upgrade dell'istanza principale, puoi creare nuove repliche di lettura, di cui viene eseguito il provisioning automatico nella versione del database di cui è stato eseguito l'upgrade.

  3. Aggiorna le statistiche del database.

    Esegui ANALYZE sull'istanza principale per aggiornare le statistiche di sistema dopo l'upgrade. Statistiche accurate assicurano che lo strumento di pianificazione delle query PostgreSQL elabori le query in modo ottimale. Le statistiche mancanti possono portare a piani di query errati, che a loro volta potrebbero peggiorare le prestazioni e occupare una quantità eccessiva di memoria.

  4. Esegui i test di accettazione.

    Devi eseguire test per assicurarti che il sistema di cui è stato eseguito l'upgrade funzioni come previsto.

Risolvere i problemi di un upgrade della versione principale

Cloud SQL restituisce un messaggio di errore se provi a eseguire un comando di upgrade non valido, ad esempio se l'istanza contiene flag di database non validi per la nuova versione.

Se la richiesta di upgrade non va a buon fine, controlla la sintassi della richiesta. Se la richiesta ha una struttura valida, prova a esaminare i seguenti suggerimenti.

Visualizzare gli errori dei controlli di pre-upgrade

Gli errori di controllo pre-upgrade sono problemi o errori rilevati da Cloud SQL durante la procedura di verifica o convalida pre-upgrade. Questi errori si verificano prima dell'inizio della procedura di upgrade effettiva e hanno lo scopo di identificare potenziali problemi o incompatibilità che possono influire sul buon esito dell'upgrade.

Gli errori dei controlli pre-upgrade vengono visualizzati per le seguenti categorie:

  • Estensioni incompatibili: rileva le estensioni PostgreSQL non compatibili con la versione di destinazione dell'istanza.
  • Dipendenze non supportate: identifica le dipendenze che non sono più supportate o che devono essere aggiornate.
  • Incompatibilità dei formati di dati: verifica le incoerenze dei dati che derivano da vari fattori, tra cui differenze nelle strutture di dati specifiche della versione, alterazioni nella codifica e nella collazione, modifiche ai tipi di dati e aggiustamenti al catalogo di sistema.

La seguente tabella elenca gli errori di controllo pre-upgrade e i relativi messaggi di errore:

Errore di controllo pre-upgrade Messaggio di errore
Cloud SQL rileva un tipo di dati sconosciuto. Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Durante l'upgrade a PostgreSQL 12 o versioni successive, Cloud SQL rileva il tipo di dati 'sql_identifier'. Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cloud SQL rileva il tipo di dati reg*. Please remove the following usages of 'reg*' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cloud SQL rileva che il valore
LC_COLLATE per il database postgres è un set di caratteri diverso da en_US.UTF8.		 Please change the 'LC_COLLATE' value of the postgres database to 'en_US.UTF8' before attempting an upgrade
Cloud SQL rileva le tabelle con identificatori di oggetti (OID). Please remove the following usages of tables with OIDs before attempting an upgrade: (database: db_name, relation: rel_name)
Cloud SQL rileva i tipi di dati compositi. Please remove the following usages of 'composite' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cloud SQL rileva gli operatori postfix definiti dall'utente. Please remove the following usages of 'postfix operators' before attempting an upgrade: (database: db_name, operation id: op_id, operation namespace: op_namespace, operation name: op_name, type namespace: type_namespace, type name: type_name)
Cloud SQL rileva funzioni polimorfiche incompatibili. Please remove the following usages of 'incompatible polymorphic' functions before attempting an upgrade: (database: db_name, object kind: obj_kind, object name: obj_name)
Cloud SQL rileva le conversioni di codifica definite dall'utente. Please remove the following usages of user-defined encoding conversions before attempting an upgrade: (database: db_name, namespace name: namespace_name, encoding conversions name: encod_name)
Cloud SQL rileva un percorso di ricerca vuoto per la funzione ll_to_earth Please update the search path of the 'll_to_earth' function
Cloud SQL rileva la presenza di file raster PostGIS non pacchettizzati. PostGIS version upgrade has not been completed, unpackaged raster files present. Follow the steps at https://postgis.net/documentation/tips/tip-removing-raster-from-2-3/ to fix before major version upgrade.

Risolvere il problema del percorso di ricerca vuoto

Questo accade perché l'estensione earthdistance utilizza i tipi earth e cube senza specificare il percorso di ricerca della funzione. Devi specificare questo percorso, che è necessario durante la procedura di upgrade.

Per risolvere il problema, correggi il percorso di ricerca per la funzione ll_to_earth eseguendo questa query: ALTER FUNCTION ll_to_earth SET search_path = public;

Visualizza i log di upgrade

Se si verificano problemi con una richiesta di upgrade valida, Cloud SQL pubblica i log degli errori in projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log. Ogni voce di log contiene un'etichetta con l'identificatore dell'istanza per aiutarti a identificare l'istanza con l'errore di upgrade. Cerca questi errori di upgrade e risolvili.

Per visualizzare i log degli errori:

  1. Nella console Google Cloud, vai alla pagina Istanze Cloud SQL.

    Vai a Istanze Cloud SQL

  2. Per aprire la pagina Panoramica di un'istanza, fai clic sul nome dell'istanza.

  3. Nel riquadro Operazioni e log della pagina Panoramica dell'istanza, fai clic sul link Visualizza i log degli errori di PostgreSQL.

    Viene visualizzata la pagina Esplora log.

  4. Visualizza i log come segue:

    • Per elencare tutti i log di errore in un progetto, seleziona il nome del log nel filtro Nome log.

    Per ulteriori informazioni sui filtri delle query, consulta la sezione Query avanzate.

    • Per filtrare i log degli errori di upgrade per una singola istanza, inserisci la seguente query nella casella Cerca in tutti i campi, dopo aver sostituito DATABASE_ID

    con l'ID progetto seguito dal nome dell'istanza in questo formato: project_id:instance_name.

    resource.type="cloudsql_database"
resource.labels.database_id="DATABASE_ID"
logName : "projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

    Ad esempio, per filtrare i log degli errori di upgrade in base a un'istanza denominata shopping-db in esecuzione nel progetto buylots, utilizza il seguente filtro query:

     resource.type="cloudsql_database"
 resource.labels.database_id="buylots:shopping-db"
 logName : "projects/buylots/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

Le voci di log con il prefisso pg_upgrade_dump indicano che si è verificato un errore di upgrade. Ad esempio:

pg_upgrade_dump: error: query failed: ERROR: out of shared memory
HINT: You might need to increase max_locks_per_transaction.

Inoltre, le voci di log contrassegnate con un nome file secondario .txt potrebbero elencare altri errori che potresti voler risolvere prima di tentare di nuovo l'upgrade.

Tutti i nomi file si trovano nel file postgres-upgrade.log. Per trovare un nome file, controlla il campo labels.FILE_NAME.

I nomi file che potrebbero contenere errori da risolvere includono:

  • tables_with_oids.txt: Questo file contiene tabelle elencate con identificatori di oggetti (OID). Elimina le tabelle o modificale in modo che non utilizzino gli OID.
  • tables_using_composite.txt: Questo file contiene tabelle elencate utilizzando tipi composti definiti dal sistema. Elimina le tabelle o modificale in modo che non utilizzino questi tipi composti.
  • tables_using_unknown.txt: Questo file contiene tabelle elencate utilizzando il tipo di dati UNKNOWN. Elimina le tabelle o modificale in modo che non utilizzino questo tipo di dati.
  • tables_using_sql_identifier.txt: Questo file contiene tabelle elencate utilizzando il tipo di dati SQL_IDENTIFIER. Elimina le tabelle o modificale in modo che non utilizzino questo tipo di dati.
  • tables_using_reg.txt: Questo file contiene tabelle elencate utilizzando il tipo di dati REG* (ad esempio REGCOLLATION o REGNAMESPACE). Elimina le tabelle o modificale in modo che non utilizzino questo tipo di dati.
  • postfix_ops.txt: Questo file contiene tabelle elencate utilizzando operatori postfissari (unari a destra). Elimina le tabelle o modificale in modo che non utilizzino questi operatori.

Controllare la memoria

Se l'istanza ha memoria condivisa insufficiente, potresti visualizzare questo messaggio di errore: ERROR: out of shared memory. È più probabile che si verifichi questo errore se hai più di 10.000 tabelle.

Prima di tentare un upgrade, imposta il valore del max_locks_per_transaction flag su circa il doppio del numero di tabelle nell'istanza. L'istanza viene riavviata quando modifichi il valore di questo flag.

Controlla la capacità delle connessioni

Se la tua istanza ha una capacità di connessione insufficiente, potresti visualizzare questo messaggio di errore: ERROR: Insufficient connections.

Cloud SQL consiglia di aumentare il valore del flag max_connections in base al numero di database nell'istanza. L'istanza viene riavviata quando modifichi il valore di questo flag.

Controlla la presenza di un riferimento a una colonna ambiguo

Se nelle visualizzazioni è presente un riferimento a una colonna ambiguo, potresti visualizzare questo messaggio di errore: ERROR: column reference "<column_name>" is ambiguous. Questo problema si verifica quando una nuova versione di PostgreSQL introduce modifiche alla struttura delle visualizzazioni del catalogo di sistema, ad esempio pg_stat_activity e pg_stat_replication. Ciò può causare interruzioni nelle visualizzazioni personalizzate che si basano sull'ordine delle colonne.

Per verificare la presenza di questo messaggio di errore, aggiungi questa query all'editor di query: textPayload =~ "ERROR: column reference .+ is ambiguous at character \d+"

Puoi risolvere il problema nei seguenti modi:

  1. Adatta le visualizzazioni personalizzate.

    Aggiorna i riferimenti alle colonne nelle visualizzazioni personalizzate in modo che siano in linea con la nuova definizione della visualizzazione del catalogo di sistema (ad esempio pg_stat_activity e pg_stat_replication) nella versione PostgreSQL di destinazione.

  2. Ricrea le visualizzazioni.

    Elimina le visualizzazioni personalizzate prima di eseguire un upgrade della versione principale. Ricrea le visualizzazioni al termine dell'upgrade, assicurandoti che siano compatibili con la nuova struttura.

Per un esempio più dettagliato del problema e ulteriori approfondimenti, consulta questa discussione su Stack Overflow

Verificare la presenza di SRF nelle istruzioni CASE

Se stai eseguendo l'upgrade dell'istanza dalla versione 9.6 e utilizzi le funzioni di impostazione che restituiscono valori nelle istruzioni CASE, potresti visualizzare questo messaggio di erroreERROR: set-returning functions are not allowed in CASE. Questo problema si verifica perché dall'inizio della versione 10 non è consentito l'utilizzo di funzioni che restituiscono set nelle istruzioni CASE.

Per risolvere il problema ed eseguire correttamente l'upgrade dell'istanza, assicurati che tutte le istruzioni CASE che utilizzano funzioni che restituiscono set siano modificate per evitarne l'utilizzo prima di riprovare a eseguire l'upgrade. Alcuni SRF di uso comune includono:

  • unnest()
  • generate_series()
  • array_agg()
  • regexp_split_to_table()
  • jsonb_array_elements()
  • json_array_elements()
  • sonb_each()
  • json_each()

Controllare le visualizzazioni create sulle trasmissioni personalizzate

Se hai creato una visualizzazione su una trasmissione personalizzata, viene visualizzato un messaggio di errore simile al seguente: ERROR: cannot cast type <type_1> to <type_2>. Questo problema si verifica a causa di problemi di autorizzazione per le trasmissioni create personalizzate.

Per risolvere il problema, aggiorna l'istanza a [PostgreSQL version].R20240910.01_02

Per ulteriori informazioni, consulta la sezione Manutenzione self-service.

Controllare la proprietà dell'attivatore evento

Se un attivatore di eventi è di proprietà di un utente che non dispone del ruolo cloudsqlsuperuser, potresti visualizzare un messaggio di errore come ERROR: permission denied to change owner of event trigger "<trigger_name>". Questo problema è causato da problemi di autorizzazione durante il tentativo di ricreare questi attivatori durante l'upgrade. Puoi aggiungere la seguente query nell'editor di query per verificare la presenza di questo messaggio di errore.textPayload =~ "ERROR: permission denied to change owner of event trigger .+ "

Per risolvere il problema, verifica la proprietà di tutti gli attivatori di eventi all'interno dell'istanza. Assicurati che il proprietario di ogni attivatore sia un utente cloudsqlsuperuser. Se gli attivatori sono di proprietà di altri utenti, aggiorna la loro proprietà su un utente cloudsqlsuperuser prima di tentare di nuovo l'upgrade. Puoi utilizzare la seguente query per cambiare la proprietà ALTER EVENT TRIGGER <trigger_name> OWNER TO <cloudsqlsuperuser>;

Puoi utilizzare la seguente query per ottenere un elenco di attivatori di eventi e i dettagli del proprietario SELECT evtname AS trigger_name, evtowner::regrole AS owner FROM pg_event_trigger;

Controlla le colonne generate dalle tabelle non registrate

Se hai una tabella non registrata che ha generato colonne, potresti visualizzare il messaggio di errore ERROR: unexpected request for new relfilenumber in binary upgrade mode. Questo problema si verifica a causa di discrepanze nelle caratteristiche di persistenza tra le tabelle e le relative sequenze per le colonne generate.

Per risolvere il problema:

  1. Elimina le tabelle non registrate: se possibile, elimina le tabelle non registrate collegate alle colonne generate. Prima di procedere, assicurati che la perdita di dati possa essere mitigata in modo sicuro.
  2. Converti in tabelle permanenti: converti temporaneamente le tabelle non registrate in tabelle permanenti seguendo questa procedura:
    1. Converti la tabella in una tabella registrata ALTER TABLE SET LOGGED;
    2. Esegui l'upgrade della versione principale
    3. Ripristina la tabella in una tabella non registrata ALTER TABLE SET UNLOGGED

Puoi identificare tutte queste tabelle utilizzando la seguente query :

SELECT
  relnamespace::regnamespace,
  c.relname AS table_name,
  a.attname AS column_name,
  a.attidentity AS identity_type
FROM
  pg_catalog.pg_class c
  JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid
WHERE
  a.attidentity IN ('a', 'd') AND c.relkind = 'r' AND c.relpersistence = 'u'
ORDER BY c.relname, a.attname;

Controlla i flag personalizzati per l'istanza PostgreSQL

Se esegui l'upgrade a un'istanza PostgreSQL, versione 14 o successiva, controlla i nomi di eventuali flag di database personalizzati che hai configurato per l'istanza. Questo perché PostgreSQL ha imposto limitazioni aggiuntive ai nomi consentiti per i parametri personalizzati.

Il primo carattere di un flag del database personalizzato deve essere alfabetico (A-Z o a-z). Tutti i caratteri successivi possono essere alfanumerici, il carattere speciale trattino basso (_) o il carattere speciale dollaro ($).

Rimuovere le estensioni

Se stai eseguendo l'upgrade dell'istanza Cloud SQL, potresti visualizzare il seguente messaggio di errore: pg_restore: error: could not execute query: ERROR: role "16447" does not exist.

Per risolvere il problema, segui questi passaggi:

  1. Rimuovi le estensioni pg_stat_statements e pgstattuple.
  2. Esegui l'upgrade.
  3. Reinstalla le estensioni.

Ripristinare la versione principale precedente

Se il sistema di database di cui è stato eseguito l'upgrade non funziona come previsto, potrebbe essere necessario ripristinare l'istanza alla versione precedente. A tal fine, ripristina il backup pre-upgrade in un'istanza di recupero Cloud SQL, ovvero una nuova istanza che esegue la versione pre-upgrade.

Per ripristinare la versione precedente, svolgi i seguenti passaggi:

  1. Identifica il backup precedente all'upgrade.

    Consulta Backup automatici dell'upgrade.

  2. Crea un'istanza di ripristino.

    Crea una nuova istanza Cloud SQL utilizzando la versione principale su cui era in esecuzione Cloud SQL quando è stato eseguito il backup precedente all'upgrade. Imposta gli stessi flag e le stesse impostazioni dell'istanza utilizzate dall'istanza originale.

  3. Ripristina il backup precedente all'upgrade.

    Ripristina il backup precedente all'upgrade nell'istanza di recupero. L'operazione potrebbe richiedere diversi minuti.

  4. Aggiungi le repliche di lettura.

    Se utilizzavi repliche di lettura, aggiungile singolarmente.

  5. Collega l'applicazione.

    Dopo aver recuperato il sistema di database, aggiorna l'applicazione con i dettagli dell'istanza di recupero e delle relative repliche di lettura. Puoi riprendere la pubblicazione del traffico nella versione precedente del database.

Domande frequenti

Quando esegui l'upgrade della versione principale del database, potrebbero essere visualizzate le seguenti domande.

La mia istanza non è disponibile durante un upgrade?
Sì. L'istanza rimane non disponibile per un determinato periodo di tempo mentre Cloud SQL esegue l'upgrade.
Quanto tempo richiede un upgrade?

L'upgrade di una singola istanza richiede in genere meno di 10 minuti. Se la configurazione dell'istanza utilizza un numero ridotto di vCPU o memoria, l'upgrade potrebbe richiedere più tempo.

Se l'istanza ospita troppi database o tabelle oppure i database sono molto grandi, l'upgrade potrebbe richiedere ore o addirittura scadere perché il tempo di upgrade corrisponde al numero di oggetti nei database. Se hai più istanze di cui eseguire l'upgrade, il tempo totale dell'upgrade aumenta proporzionalmente.

Posso monitorare ogni passaggio della procedura di upgrade?
Sebbene Cloud SQL ti consenta di monitorare se un'operazione di upgrade è ancora in corso, non puoi monitorare i singoli passaggi di ogni upgrade.
Posso annullare l'upgrade dopo averlo avviato?
No, non puoi annullare un upgrade una volta avviato. Se l'upgrade non va a buon fine, Cloud SQL recupera automaticamente l'istanza nella versione precedente.
Cosa succede alle mie impostazioni durante un upgrade?

Quando esegui un upgrade in situ della versione principale, Cloud SQL conserva le impostazioni del database, tra cui il nome dell'istanza, l'indirizzo IP, i valori dei flag configurati in modo esplicito e i dati utente. Tuttavia, il valore predefinito delle variabili di sistema potrebbe cambiare. Ad esempio, il valore predefinito del flag password_encryption in PostgreSQL 13 e versioni precedenti è md5. Quando esegui l'upgrade a PostgreSQL 14, il valore predefinito di questo flag diventa scram-sha-256.

Per scoprire di più, consulta la sezione Configurare i flag di database. Se un determinato valore o flag non è più supportato nella versione di destinazione, Cloud SQL lo rimuove automaticamente durante l'upgrade.

Passaggi successivi