Esegui l'upgrade della versione principale del database in uso

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

Introduzione

I provider di software per i database rilasciano periodicamente nuove versioni principali che contengono nuove funzionalità e miglioramenti delle prestazioni e della sicurezza. Cloud SQL accetta le nuove versioni dopo che sono state rilasciate. Quando Cloud SQL offrirà 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 loco o eseguendo la migrazione dei dati. Gli upgrade in loco consentono di eseguire più facilmente 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 loco, puoi conservare il nome, l'indirizzo IP e altre impostazioni dell'istanza attuale dopo l'upgrade. Gli upgrade in loco non richiedono lo spostamento di file di dati e possono essere completati più velocemente. In alcuni casi, il tempo di inattività è più breve di quanto comporta la migrazione dei dati.

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

Pianifica un upgrade della versione principale

  1. Scegli una versione principale di destinazione.

    Consulta l'elenco delle versioni supportate da Cloud SQL.

  2. Considera 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, esamina le note di rilascio della versione principale di destinazione per determinare le incompatibilità da risolvere.

  3. Testa l'upgrade con una prova.

    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 il processo di upgrade.

    Oltre a verificare che l'upgrade venga completato correttamente, esegui test per assicurarti che l'applicazione funzioni come previsto nel database aggiornato.

  4. Decidi quando eseguire l'upgrade.

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

Preparati per un upgrade di una 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 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 la codifica diversa (per questo esempio, en_US.UTF8).
    4. Ricarica i dati.

  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 durante la replica dell'istanza nelle 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, disabilita la replica delle estensioni pglogical come segue. Puoi abilitarlo di nuovo dopo l'upgrade. Se Cloud SQL è la destinazione della replica logica, questi passaggi non sono obbligatori.
    1. Disabilita la sottoscrizione e disconnetti 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 disabilitato immediatamente. Per impostazione predefinita, il valore è false e l'abbonamento viene disattivato solo al termine della transazione corrente.

      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 al publisher o all'istanza principale di Cloud SQL ed eseguendo questo 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 sulla versione principale del database aggiornata. Rilascia eventuali 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 manualmente l'upgrade di PostGIS e delle sue estensioni correlate alle versioni più recenti supportate. Se la tua versione di PostGIS è precedente alla 3.1, utilizza il seguente comando per eseguire l'upgrade dell'estensione PostGIS: 

        ALTER EXTENSION postgis UPDATE TO '3.1.7';
    A volte, l'upgrade dalla versione 2.x di PostGIS può creare una situazione in cui sono presenti oggetti di database rimanenti che non sono associati all'estensione PostGIS. Questa operazione può bloccare l'operazione di upgrade. Per informazioni su come risolvere il problema, consulta Correggere un'installazione raster Postgis non funzionante.

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

Limitazioni note

Le seguenti limitazioni influiscono sugli upgrade delle versioni principali in loco per Cloud SQL per PostgreSQL:

  • L'upgrade delle istanze con più di 1000 database da una versione all'altra potrebbe richiedere molto tempo e timeout.
  • Utilizza l'istruzione select * from pg_largeobject_metadata; per eseguire query sul numero di oggetti di grandi dimensioni in ogni database PostgreSQL della tua istanza Cloud SQL. Se il risultato di tutti i tuoi database è più di 10 milioni di oggetti di grandi dimensioni, l'upgrade non va a buon fine. Cloud SQL esegue il rollback alla versione precedente del database.

Esegui l'upgrade della versione principale del database in uso

Quando avvii un'operazione di upgrade, Cloud SQL controlla innanzitutto la configurazione dell'istanza per verificare che sia compatibile per un upgrade. Dopo aver verificato la configurazione, Cloud SQL rende non disponibile l'istanza, esegue un backup precedente all'upgrade, esegue l'upgrade, rende disponibile l'istanza ed esegue un backup successivo all'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 istanza, fai clic sul pulsante Esegui l'upgrade e conferma di voler andare alla pagina dell'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 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 superiore alla versione corrente. Vedi le enumerazioni delle versioni del database disponibili.
    gcloud sql instances patch INSTANCE_NAME \
--database-version=DATABASE_VERSION

    Il completamento degli upgrade della versione principale richiede 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: 

    POST https://sqladmin.googleapis.com/sql/v1/projects/project-id/instances/instance_name

    Corpo JSON della richiesta: 

    {
  "databaseVersion": enum DATABASE_VERSION
}

    Sostituisci DATABASE_VERSION con l'enum per la versione principale del database, che deve essere superiore alla versione attuale. Vedi le enumerazioni delle versioni del database disponibili.

    Invia la richiesta utilizzando curl o PowerShell. Vedi Modificare le istanze.

  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/sql/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/sql/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 sezioni seguenti.

prepara Cloud Shell

  1. Avvia Cloud Shell.

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

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

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Se imposti valori espliciti nel file di configurazione Terraform, le variabili di ambiente vengono sostituite.

Prepara la directory

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

  1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome del file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è indicato come 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 file main.tf appena creato.

    Se vuoi, copia il codice da GitHub. Questa opzione è consigliata se 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

    Facoltativamente, 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 creerà o aggiornerà corrispondano alle tue aspettative: 
    terraform plan

    Apporta le correzioni necessarie alla configurazione.

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

    Attendi finché Terraform non visualizza il messaggio "Applicazione completata".

  3. Apri il 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 disabilitare la protezione dall'eliminazione, nel file di configurazione Terraform imposta l'argomento deletion_protection su false. 
    deletion_protection =  "false"
  2. Applica la configurazione Terraform aggiornata eseguendo il comando seguente e inserendo yes al prompt: 
    terraform apply

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

    terraform destroy

Quando effettui una richiesta di upgrade in loco, Cloud SQL esegue prima 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 mostra un messaggio che suggerisce come risolvere il problema. Vedi anche Risolvere i problemi di upgrade di una versione principale.

Backup degli upgrade automatici

Quando esegui un upgrade della versione principale, Cloud SQL effettua automaticamente due backup on demand, denominati backup dell'upgrade:

  • Il primo backup dell'upgrade è il backup precedente all'upgrade, che viene eseguito immediatamente prima di iniziare l'upgrade. Puoi utilizzare questo backup per ripristinare l'istanza di database allo stato precedente nella versione precedente.
  • Il secondo backup dell'upgrade è quello successivo all'upgrade, che viene eseguito immediatamente dopo che sono state consentite nuove scritture all'istanza del database di cui è stato eseguito l'upgrade.

Quando visualizza l'elenco dei backup, i backup degli upgrade sono elencati con il tipo On-demand. I backup degli upgrade sono etichettati in modo da identificarli facilmente. Ad esempio, se esegui l'upgrade da PostgreSQL 9.6 a PostgreSQL 13, il backup prima dell'upgrade è etichettato Pre-upgrade backup, POSTGRES_9_6 to POSTGRES_13. e il backup post-upgrade Post-upgrade backup, POSTGRES_13 from POSTGRES_9_6.

Come per altri backup on demand, i backup dell'upgrade vengono mantenuti finché non li elimini o elimini l'istanza. Se hai abilitato PITR, non puoi eliminare i backup dell'upgrade mentre si trovano nel periodo di conservazione. Se devi eliminare i backup degli upgrade, devi disabilitare PITR o attendere che i backup dell'upgrade non siano più nel periodo di conservazione.

Completa l'upgrade della versione principale

Una volta completato l'upgrade dell'istanza principale, esegui questi passaggi per completare l'upgrade:

  1. Abilita la replica pglogical se è stata utilizzata dalla tua istanza prima dell'upgrade. Questa operazione crea automaticamente lo slot di replica necessario.
    1. Elimina la sottoscrizione pglogical nella 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 la sottoscrizione pglogical sulla destinazione (replica) fornendo i dettagli di connessione come segue all'istanza principale di 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 della sottoscrizione utilizzando il seguente comando: 
      SELECT * FROM pglogical.show_subscription_status('test_sub');
    4. Testa la replica eseguendo transazioni di scrittura e verificando che le modifiche siano visibili nella destinazione.

  2. Esegui l'upgrade delle repliche di lettura.

    Se hai arrestato la replica per le repliche di lettura, eseguine 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 mantenendo gli indirizzi IP, la aggiorna con i dati più recenti di quella principale e riavvia la replica.

    Se hai eliminato le repliche di lettura prima di eseguire l'upgrade di quella principale, puoi crearne di nuove, di cui viene eseguito automaticamente il provisioning nella versione aggiornata del database.

  3. Aggiorna le statistiche del database.

    Esegui ANALYZE sulla tua istanza principale per aggiornare le statistiche di sistema dopo l'upgrade. Statistiche accurate garantiscono che lo Strumento di pianificazione di query PostgreSQL elabora le query in modo ottimale. La mancanza di statistiche può portare a piani di query errati, che a loro volta potrebbero ridurre le prestazioni e occupare una memoria eccessiva.

  4. Esegui test di accettazione.

    Devi eseguire dei 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 di 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. Se la richiesta ha una struttura valida, prova a esaminare i suggerimenti che seguono.

Visualizza gli errori dei controlli pre-upgrade

Gli errori dei controlli pre-upgrade sono problemi o errori che Cloud SQL rileva durante la procedura di verifica o convalida prima dell'upgrade. Questi errori si verificano prima dell'inizio dell'effettivo processo di upgrade e hanno lo scopo di identificare potenziali problemi o incompatibilità che possono influire sul successo dell'upgrade.

Gli errori dei controlli prima dell'upgrade sono visualizzati per le seguenti categorie:

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

Nella tabella seguente sono elencati gli errori dei controlli prima dell'upgrade e i relativi messaggi di errore:

Controllo pre-upgrade non riuscito 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 che hanno identificatori degli oggetti (OID). Please remove the following usages of tables with OIDs before attempting an upgrade: (database: db_name, relation: rel_name)
Cloud SQL rileva tipi di dati composti. 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 'composite' data types 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)

Visualizza i log di upgrade

Se si verificano problemi con una richiesta di upgrade valida, Cloud SQL pubblica i log degli errori su 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 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 di log Nome log.

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

    • Per filtrare i log degli errori dell'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 dell'upgrade in base a un'istanza denominata shopping-db in esecuzione nel progetto buylots, utilizza il seguente filtro delle 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 etichettate con un nome file secondario .txt potrebbero elencare altri errori che potresti voler risolvere prima di tentare nuovamente l'upgrade.

Tutti i nomi file sono disponibili nel file postgres-upgrade.log. Per individuare il nome di un file, guarda il campo labels.FILE_NAME.

I nomi di file che potrebbero contenere errori da risolvere includono:

  • tables_with_oids.txt: Questo file contiene tabelle elencate con gli identificatori degli 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 gli operatori postfix (unario destro). Elimina le tabelle o modificale in modo che non utilizzino questi operatori.

Controlla la memoria

Se l'istanza ha una memoria condivisa insufficiente, potrebbe essere visualizzato questo messaggio di errore: ERROR: out of shared memory. È più probabile che questo errore si verifichi 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.

Verifica la capacità delle connessioni

Se la capacità di connessione dell'istanza è insufficiente, è possibile che venga visualizzato questo messaggio di errore: ERROR: Insufficient connections.

Cloud SQL consiglia di aumentare il valore del flag max_connections del numero di database nella tua istanza. L'istanza viene riavviata quando modifichi il valore di questo flag.

Controlla la versione dell'istanza PostgreSQL

Se utilizzi la versione 9.6, 10 o 11 di un'istanza Cloud SQL per PostgreSQL e hai abilitato l'estensione PostGIS per l'istanza, l'upgrade di PostGIS potrebbe non riuscire a causa di un problema di autorizzazione. Per risolvere il problema, utilizza la manutenzione self-service per implementare l'immagine del gestore di sistemi (SSM) più recente. Questo ti autorizza a eseguire l'upgrade di PostGIS.

Controlla i flag personalizzati per la tua istanza PostgreSQL

Se esegui l'upgrade a un'istanza PostgreSQL 14 o versioni successive, controlla i nomi di eventuali flag di database personalizzati che hai configurato per l'istanza. Il motivo è che PostgreSQL ha posto limitazioni aggiuntive sui 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 trattino basso (_) o il carattere speciale del simbolo del dollaro ($).

Rimuovi le estensioni

Se esegui l'upgrade dell'istanza Cloud SQL dalla versione 10 alla versione 14, 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

Se il sistema di database di cui hai eseguito l'upgrade non funziona come previsto, potrebbe essere necessario ripristinare l'istanza alla versione precedente. Per farlo, devi ripristinare il backup precedente all'upgrade in un'istanza di ripristino di Cloud SQL, ovvero una nuova istanza che esegue la versione precedente all'upgrade.

Per ripristinare la versione precedente, svolgi i seguenti passaggi:

  1. Identifica il backup prima dell'upgrade.

    Vedi Backup degli upgrade automatici.

  2. Creare un'istanza di recupero.

    Crea una nuova istanza Cloud SQL utilizzando la versione principale utilizzata da Cloud SQL al momento dell'esecuzione del backup precedente all'upgrade. Imposta gli stessi flag e impostazioni dell'istanza utilizzati dall'istanza originale.

  3. Ripristina il backup precedente all'upgrade.

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

  4. Aggiungi le repliche di lettura.

    Se utilizzavi repliche di lettura, aggiungile singolarmente.

  5. Collega la tua applicazione.

    Dopo aver ripristinato il sistema di database, aggiorna l'applicazione con i dettagli sull'istanza di ripristino e sulle sue repliche di lettura. Puoi riprendere la gestione del traffico nella versione precedente all'upgrade 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 utilizza un numero ridotto di vCPU o memoria, l'upgrade potrebbe richiedere più tempo.

Se l'istanza ospita troppi database o tabelle oppure se i tuoi database sono molto grandi, l'upgrade potrebbe richiedere ore o addirittura un timeout perché la tempistica dell'upgrade corrisponde al numero di oggetti nei database. Se hai più istanze di cui è necessario eseguire l'upgrade, il tempo totale per l'upgrade aumenta in modo proporzionale.

Posso monitorare ogni passaggio del processo di upgrade?
Mentre Cloud SQL consente di monitorare se un'operazione di upgrade è ancora in corso, non puoi monitorare i singoli passaggi in ogni upgrade.
Posso annullare il mio upgrade dopo averlo avviato?
No, una volta avviato, non puoi annullare un upgrade. Se l'upgrade non va a buon fine, Cloud SQL recupera automaticamente l'istanza nella versione precedente.
Che cosa succede alle mie impostazioni durante un upgrade?

Quando esegui un upgrade della versione principale in loco, Cloud SQL conserva le impostazioni del database, tra cui il nome dell'istanza, l'indirizzo IP, i valori dei flag configurati esplicitamente 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 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