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 dell'istanza Cloud SQL sul posto anziché eseguendo la migrazione dei dati.

Introduzione

I fornitori di software di database rilasciano periodicamente nuove versioni principali che contengono nuove funzionalità, miglioramenti delle prestazioni e miglioramenti della sicurezza. Cloud SQL accetta le nuove versioni dopo il loro rilascio. Dopo che 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 sul posto o tramite la migrazione dei dati. Gli upgrade in loco sono un modo più semplice per eseguire l'upgrade della versione principale dell'istanza. Non è necessario migrare i dati o modificare le stringhe di connessione dell'applicazione. Con gli upgrade sul posto, puoi conservare il nome, l'indirizzo IP e altre impostazioni dell'istanza corrente dopo l'upgrade. Gli upgrade sul posto non richiedono lo spostamento dei file di dati e possono essere completati più rapidamente. In alcuni casi, il tempo di inattività è inferiore a quello richiesto per la migrazione dei dati.

Pianificare un upgrade della versione principale

1. Verifica di disporre del ruolo richiesto per eseguire un upgrade della versione principale: Proprietario Cloud SQL o Amministratore Cloud SQL.

2. Scegli una versione principale di destinazione.

   gcloud

   Per informazioni sull'installazione e su come iniziare a utilizzare gcloud CLI, consulta Installare gcloud CLI. Per informazioni sull'avvio di Cloud Shell, consulta Utilizzare Cloud Shell.

   Per controllare le versioni del database a cui puoi fare riferimento per un upgrade in loco sulla tua istanza:

   1. Esegui questo comando.

   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, esamina i seguenti campi.
   • majorVersion: la versione principale a cui puoi fare riferimento per l'upgrade in loco.
   • name: la stringa della versione del database che include la versione principale.
   • displayName: il nome visualizzato per la versione del database.

   REST v1

   Per controllare quali versioni del database di destinazione sono disponibili per un upgrade in loco 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:

   curl (Linux, macOS o Cloud Shell)

   Esegui questo comando:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell (Windows)

   Esegui questo comando:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   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 loco 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:

   curl (Linux, macOS o Cloud Shell)

   Esegui questo comando:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell (Windows)

   Esegui questo comando:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   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 delle versioni.

3. Considera le funzionalità offerte in ogni versione principale del database e risolvi le incompatibilità.

   • PostgreSQL 17
   • PostgreSQL 16
   • PostgreSQL 15
   • PostgreSQL 14
   • PostgreSQL 13
   • PostgreSQL 12
   • PostgreSQL 11
   • PostgreSQL 10

   Le nuove versioni principali introducono modifiche incompatibili che potrebbero richiedere di modificare il codice dell'applicazione, lo schema o le 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.

4. Testa l'upgrade con un test dry run.

   Esegui una prova del processo 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 test per assicurarti che l'applicazione si comporti come previsto nel database aggiornato.

5. Decidi un orario per l'upgrade.

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

Prepararsi per un upgrade della versione principale

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

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

   Se il valore di 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 due 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 una codifica diversa (per 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 che utilizzino 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 estensioni PostgreSQL rimanenti.

   La maggior parte delle estensioni funziona sulla versione principale del database di cui è stato eseguito l'upgrade. Elimina le estensioni non 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 ultime versioni supportate manualmente.

   A volte, l'upgrade dalle versioni 2.x di PostGIS può creare una situazione in cui sono presenti oggetti di database rimanenti che non sono associati all'estensione PostGIS. Ciò può bloccare l'operazione di upgrade. Per informazioni sulla risoluzione del problema, consulta Risoluzione di un'installazione raster PostGIS danneggiata.

   A volte, l'upgrade alla versione 3.1.7 o successive di PostGIS non può essere completato a causa di oggetti che utilizzano funzioni deprecate. 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 deprecate 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. Dopodiché, procedi con l'operazione di upgrade.

   Per scoprire di più sull'upgrade delle estensioni PostGIS, vedi Eseguire l'upgrade di PostGIS. Per i problemi associati all'upgrade di PostGIS, consulta Controllare la versione dell'istanza PostgreSQL.
3. Gestisci i flag di database personalizzati. Controlla i nomi di eventuali flag di database personalizzati che hai configurato per l'istanza PostgreSQL. Per i problemi associati a questi flag, consulta Controllare i flag personalizzati per l'istanza PostgreSQL.
4. Quando esegui l'upgrade da una versione principale a un'altra, prova a connetterti a ogni 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.
5. 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, elimina la funzione pg_stat_activity().

Limitazioni note

I seguenti limiti influiscono sugli upgrade in loco della versione principale per Cloud SQL per PostgreSQL:

• Non puoi eseguire un upgrade in loco 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 causare un timeout.
• Utilizza l'istruzione select * from pg_largeobject_metadata; per eseguire query sul numero di oggetti di grandi dimensioni in ogni database PostgreSQL dell'istanza Cloud SQL. Se il risultato di tutti i tuoi database è superiore a 10 milioni di oggetti di grandi dimensioni, l'upgrade non riesce. Cloud SQL esegue il rollback alla versione precedente del database.
• Prima di eseguire un upgrade in loco 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.
• Prima di eseguire un upgrade in loco della versione principale a PostgreSQL 17, esegui l'upgrade dell'estensione rdkit per tutti i tuoi database alla versione 4.6.1.
• Se utilizzi PostgreSQL versioni 9.6, 10, 11 o 12, la versione 3.4.0 dell'estensione PostGIS non è supportata. Pertanto, per eseguire un upgrade in loco 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 pg_ivm o pg_squeeze per la tua istanza, non puoi eseguire l'upgrade a una versione principale. Per risolvere il problema, disinstalla queste estensioni e poi esegui l'upgrade. Per saperne di più sulle estensioni, vedi Configurare le estensioni PostgreSQL.

• Se abiliti i flag vacuum_defer_cleanup_age e force_parallel_mode, non puoi eseguire l'upgrade della versione principale. Per risolvere il problema, elimina questi flag e poi esegui l'upgrade. Per saperne di più sui flag, incluso come eliminarli, consulta Configurare i flag di database.

Esegui l'upgrade della versione principale

Puoi eseguire l'upgrade della versione principale di una singola istanza Cloud SQL oppure puoi eseguire l'upgrade della versione principale di un'istanza principale e includere tutte le relative repliche, incluse le repliche in cascata e le repliche cross-region.

Esegui l'upgrade della versione principale di una singola istanza

Quando avvii un'operazione di upgrade per una singola istanza, Cloud SQL esegue le seguenti operazioni:

1. Controlla la configurazione dell'istanza per assicurarsi che sia compatibile con un upgrade.
2. Dopo che Cloud SQL verifica la configurazione, Cloud SQL rende l'istanza non disponibile.
3. Esegue un backup pre-upgrade.
4. Esegue l'upgrade dell'istanza.
5. Rende disponibile l'istanza.
6. Esegue un backup post-upgrade.

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
}

Quando invii una richiesta di upgrade in loco, Cloud SQL esegue innanzitutto un controllo pre-upgrade. Se Cloud SQL determina che la tua 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 relativi all'upgrade di una versione principale.

Includi le repliche nell'upgrade della versione principale

Se l'istanza principale ha repliche, puoi includerle tutte nell'upgrade. Cloud SQL può eseguire l'upgrade di tutte le repliche dell'istanza principale, incluse le repliche cross-region e a cascata.

Quando includi le repliche in un upgrade della versione principale, Cloud SQL esegue le seguenti operazioni:

1. Controlla la configurazione dell'istanza principale e delle repliche per assicurarsi che l'istanza e le repliche siano compatibili per un upgrade.
2. Rende non disponibile l'istanza principale.
3. Crea un backup pre-upgrade dell'istanza principale.
4. Interrompe la replica per tutte le repliche.
5. Esegue l'upgrade sull'istanza principale.
6. Se l'upgrade sull'istanza primaria va a buon fine, l'istanza primaria torna disponibile e la replica viene riavviata.
7. Cloud SQL esegue un backup post-upgrade dell'istanza principale.
8. Cloud SQL procede all'upgrade di tutte le repliche.

Anche se l'upgrade della versione principale di una replica non va a buon fine, l'istanza principale continua a essere disponibile.

Per includere le repliche in un upgrade della versione principale, non puoi utilizzare la consoleGoogle Cloud o Terraform. Puoi utilizzare solo gcloud CLI o l'API Cloud SQL Admin.

Backup automatici degli upgrade

Quando esegui un upgrade della 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 di iniziare l'upgrade. Puoi utilizzare questo backup per ripristinare l'istanza di database allo stato della versione precedente.
• Il secondo backup dell'upgrade è il backup post-upgrade, che viene eseguito immediatamente dopo che sono consentite nuove scritture nell'istanza del database aggiornata.

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 Pre-upgrade backup, POSTGRES_14 to POSTGRES_15. e il backup post-upgrade è etichettato Post-upgrade backup, POSTGRES_14 to POSTGRES_15..

Come per gli altri backup on demand, i backup dell'upgrade vengono conservati finché non li elimini o finché non elimini l'istanza. Se hai abilitato 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 PITR o attendere che i backup dell'upgrade non rientrino più nella finestra di conservazione.

Completa l'upgrade della versione principale

Dopo aver completato l'upgrade dell'istanza principale, segui questi passaggi per completare l'upgrade:

1. Aggiorna le statistiche del database.

   Esegui ANALYZE sull'istanza principale per aggiornare le statistiche di sistema dopo l'upgrade. Statistiche accurate assicurano che il pianificatore di 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 memoria eccessiva.

2. Esegui test di accettazione.

   Esegui test per assicurarti che il sistema aggiornato funzioni come previsto.

Risolvere i problemi relativi all'upgrade di una versione principale

Cloud SQL restituisce un messaggio di errore se tenti 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 di controllo pre-upgrade

Gli errori di controllo pre-upgrade sono problemi o errori rilevati da Cloud SQL durante il processo di verifica o convalida pre-upgrade. Questi errori si verificano prima dell'inizio del processo di upgrade vero e proprio e hanno lo scopo di identificare potenziali problemi o incompatibilità che possono influire sulla riuscita dell'upgrade.

Gli errori di controllo 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à del formato dei dati: verifica le incoerenze dei dati derivanti da vari fattori, tra cui differenze nelle strutture dei dati specifiche della versione, modifiche alla codifica e al confronto, modifiche ai tipi di dati e aggiustamenti al catalogo del sistema.

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

Risolvere il problema del percorso di ricerca vuoto

Ciò accade perché l'estensione earthdistance utilizza i tipi earth e cubo senza specificare il percorso di ricerca della funzione. Devi specificare questo percorso, che è obbligatorio 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 log degli errori

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, utilizza la console Google Cloud:

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 log degli errori di PostgreSQL.

   Si apre la pagina Esplora log.

4. Visualizza i log nel seguente modo:

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

   Per maggiori 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"

   Puoi esaminare tutti i log segnalati in un determinato periodo di tempo oppure filtrare i log in base alla gravità. Un'opzione comune per la risoluzione dei problemi potrebbe includere la selezione dei seguenti filtri:

   • Emergenza
   • Avviso
   • Critico
   • Errore

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 etichettate con un nome file secondario .txt potrebbero elencare altri errori che potresti voler risolvere prima di tentare di nuovo l'upgrade.

Tutti i nomi dei file si trovano nel file postgres-upgrade.log. Per individuare un nome file, guarda 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 OID.
• tables_using_composite.txt: Questo file contiene tabelle elencate utilizzando tipi compositi definiti dal sistema. Elimina le tabelle o modificale in modo che non utilizzino questi tipi compositi.
• 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 di suffisso (unari a destra). Elimina le tabelle o modificale in modo che non utilizzino questi operatori.

Controllare la memoria

Se l'istanza non ha memoria condivisa sufficiente, potresti visualizzare questo messaggio di errore: ERROR: out of shared memory. Questo errore si verifica più facilmente se hai più di 10.000 tabelle.

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

Controllare la capacità di 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 di colonna ambiguo

Se nelle visualizzazioni è presente un riferimento ambiguo a una colonna, 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 viste del catalogo di sistema, ad esempio pg_stat_activity e pg_stat_replication. Ciò può interrompere le 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. Adattare le visualizzazioni personalizzate.

   Aggiorna i riferimenti alle colonne nelle visualizzazioni personalizzate in modo che siano allineati alla 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 tue 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.

Controllare la presenza di SRF nelle istruzioni CASE

Se stai eseguendo l'upgrade dell'istanza dalla versione 9.6 e utilizzi funzioni di restituzione di set nelle istruzioni CASE, potresti visualizzare questo messaggio di errore ERROR: set-returning functions are not allowed in CASE. Questo problema si verifica perché a partire dalla versione 10, l'utilizzo di funzioni che restituiscono set nelle istruzioni CASE non è consentito.

Per risolvere il problema ed eseguire l'upgrade dell'istanza, assicurati che tutte le istruzioni CASE che utilizzano funzioni che restituiscono set vengano modificate per evitarne l'utilizzo prima di riprovare 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 sui cast personalizzati

Se hai creato una visualizzazione su un cast personalizzato, 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 sui cast creati personalizzati.

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

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

Controllare la proprietà del trigger evento

Se un trigger di evento è di proprietà di un utente che non dispone del ruolo cloudsqlsuperuser, potresti ricevere 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 trigger durante l'upgrade. Puoi utilizzare 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 i trigger evento all'interno della tua istanza. Assicurati che il proprietario di ogni trigger sia un cloudsqlsuperuser. Se alcuni trigger sono di proprietà di altri utenti, aggiorna la loro proprietà a cloudsqlsuperuser prima di tentare di nuovo l'upgrade. Puoi utilizzare la seguente query per modificare la proprietà ALTER EVENT TRIGGER <trigger_name> OWNER TO <cloudsqlsuperuser>;

Puoi utilizzare la seguente query per ottenere un elenco di trigger 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 questo 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 utilizzando i seguenti passaggi:
   1. Converti la tabella in una tabella registrata ALTER TABLE SET LOGGED;
   2. Esegui l'upgrade della versione principale
   3. Converti di nuovo 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 successive, controlla i nomi di eventuali flag di database personalizzati che hai configurato per l'istanza. Questo perché PostgreSQL ha imposto ulteriori limitazioni ai nomi consentiti per i parametri personalizzati.

Il primo carattere di un flag di 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 segno del dollaro ($).

Rimuovere le estensioni

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

Per risolvere il problema:

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

Ripristina la versione principale precedente dell'istanza primaria

Se il sistema di database aggiornato non funziona come previsto, potrebbe essere necessario ripristinare la versione precedente dell'istanza principale. A questo scopo, ripristina il backup pre-upgrade in un'istanza di recupero Cloud SQL, ovvero una nuova istanza che esegue la versione pre-upgrade.

Per ripristinare una versione precedente dell'istanza primaria, segui questi passaggi:

1. Identifica il backup pre-upgrade.

   Consulta Backup automatici degli upgrade.

2. Crea un'istanza di recupero.

   Crea una nuova istanza Cloud SQL utilizzando la versione principale in esecuzione su Cloud SQL al momento della creazione del backup pre-upgrade. Imposta gli stessi flag e impostazioni dell'istanza utilizzate dall'istanza originale.

3. Ripristina il backup precedente all'upgrade.

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

4. Aggiungi le repliche di lettura.

   Se utilizzi repliche di lettura, aggiungile singolarmente.

5. Connetti la tua applicazione.

   Dopo aver recuperato il sistema di database, aggiorna l'applicazione con i dettagli sull'istanza di recupero e sulle relative repliche di lettura. Puoi riprendere a pubblicare il traffico nella versione precedente del database.

Domande frequenti

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

La mia istanza non è disponibile durante un upgrade?

Sì. L'istanza rimane non disponibile per un periodo di tempo mentre Cloud SQL esegue l'upgrade.

Quanto tempo richiede un upgrade?

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

Se la tua istanza ospita troppi database o tabelle oppure i tuoi database sono molto grandi, l'upgrade potrebbe richiedere ore o addirittura scadere perché il tempo totale di upgrade corrisponde al numero di oggetti nei tuoi database. Se hai più istanze di cui eseguire l'upgrade, il tempo di upgrade aumenta proporzionalmente. Se includi repliche nell'upgrade, l'operazione di upgrade può richiedere fino a un'ora, a seconda del numero di repliche dell'istanza principale.

Posso monitorare ogni passaggio della procedura di upgrade?

Anche se Cloud SQL ti consente 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 della versione principale sul posto, Cloud SQL conserva le impostazioni del database, inclusi 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 cambia in scram-sha-256.

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

Passaggi successivi

• Scopri di più sulle opzioni per connettersi a un'istanza.
• Scopri di più sull'importazione e sull'esportazione dei dati.
• Scopri di più sull'impostazione dei flag di database.