Mettre à niveau la version majeure de la base de données sur place

Cette page décrit comment mettre à niveau la version majeure de la base de données en mettant à niveau votre instance Cloud SQL plutôt qu'en migrant les données.

Introduction

Les fournisseurs de logiciels de base de données publient régulièrement de nouvelles versions majeures contenant de nouvelles fonctionnalités, des améliorations de performances et des améliorations de sécurité. Cloud SQL intègre de nouvelles versions après leur publication. Une fois que Cloud SQL est compatible avec une nouvelle version majeure, vous pouvez mettre à jour vos instances pour maintenir votre base de données à jour.

Vous pouvez mettre à niveau la version de base de données d'une instance sur place ou en migrant les données. Les mises à niveau sur place constituent un moyen plus simple de mettre à niveau la version majeure de votre instance. Vous n'avez pas besoin de migrer les données ni de modifier les chaînes de connexion de l'application. Avec les mises à niveau sur place, vous pouvez conserver le nom, l'adresse IP et d'autres paramètres de votre instance actuelle après la mise à niveau. Les mises à niveau sur place ne nécessitent pas de déplacer de fichiers de données et peuvent être effectuées plus rapidement. Dans certains cas, le temps d'arrêt est plus court que celui qu'implique la migration de vos données.

L'utilitaire pg_upgrade est utilisé par Cloud SQL pour l'opération de mise à niveau sur place PostgreSQL.

Planifier une mise à niveau de version majeure

  1. Choisissez une version majeure cible.

    gcloud

    Pour en savoir plus sur l'installation et le démarrage avec la gcloud CLI, consultez la page Installer la gcloud CLI. Pour en savoir plus sur le démarrage de Cloud Shell, consultez la page Utiliser Cloud Shell.

    Pour vérifier les versions de bases de données que vous pouvez cibler pour une mise à niveau sur place sur votre instance, procédez comme suit :

    1. Exécutez la commande suivante :
      2. gcloud sql instances describe INSTANCE_NAME

      Remplacez INSTANCE_NAME par le nom de l'instance.

    2. Dans le résultat de la commande, localisez la section intitulée upgradableDatabaseVersions.
    3. Chaque sous-section renvoie une version de base de données disponible pour la mise à niveau. Dans chaque sous-section, examinez les champs suivants.
      • majorVersion : version majeure que vous pouvez cibler pour la mise à niveau sur place.
      • name : chaîne de version de base de données qui inclut la version majeure.
      • displayName : nom à afficher pour la version de base de données.

    REST v1

    Pour vérifier les versions de bases de données cibles disponibles pour la mise à niveau sur place d'une version majeure, utilisez la méthode instances.get de l'API Cloud SQL Admin.

    Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

    • INSTANCE_NAME : nom de l'instance.

    Méthode HTTP et URL : 

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

    Pour envoyer votre requête, développez l'une des options suivantes :

    Vous devriez recevoir une réponse JSON de ce type :

    
upgradableDatabaseVersions:

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

    REST v1beta4

    Pour vérifier les versions de bases de données cibles disponibles pour la mise à niveau sur place de la version majeure d'une instance, utilisez la méthode instances.get de l'API Cloud SQL Admin.

    Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

    • INSTANCE_NAME : nom de l'instance.

    Méthode HTTP et URL : 

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

    Pour envoyer votre requête, développez l'une des options suivantes :

    Vous devriez recevoir une réponse JSON de ce type :

    
upgradableDatabaseVersions:

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

    Pour obtenir la liste complète des versions de bases de données compatibles avec Cloud SQL, consultez Versions de bases de données et règles de version.

  2. Examinez les fonctionnalités proposées dans chaque version majeure de la base de données et corrigez les incompatibilités.

    Les nouvelles versions majeures présentent des modifications incompatibles qui peuvent vous obliger à modifier le code de l'application, le schéma ou les paramètres de la base de données. Avant de pouvoir mettre à niveau votre instance de base de données, consultez les notes de version de votre version majeure cible afin de déterminer les incompatibilités que vous devez corriger.

  3. Tester la mise à niveau avec une simulation

    Effectuer une simulation du processus de mise à niveau de bout en bout dans un environnement de test avant de mettre à jour la base de données de production. Vous pouvez cloner votre instance pour créer une copie identique des données sur lesquelles tester le processus de mise à niveau.

    En plus de vérifier que la mise à niveau a abouti, exécutez des tests pour vous assurer que l'application se comporte comme prévu sur la base de données mise à niveau.

  4. Choisissez une heure de mise à niveau.

    La mise à niveau rend l'instance indisponible pendant un certain temps. Prévoyez la mise à niveau pendant une période où l'activité de la base de données est faible.

Préparer une mise à niveau de version majeure

Avant de mettre à niveau, procédez comme suit :

  1. Vérifiez la valeur LC_COLLATE des bases de données template et postgres. Le jeu de caractères de chaque base de données doit être en_US.UTF8.

    Si la valeur LC_COLLATE des bases de données template et postgres n'est pas en_US.UTF8, la mise à niveau de version majeure échoue. Pour résoudre ce problème, si l'une des bases de données possède un jeu de caractères autre que en_US.UTF8, remplacez la valeur LC_COLLATE par en_US.UTF8 avant d'effectuer la mise à niveau.

    Pour modifier l'encodage d'une base de données :

    1. Videz votre base de données.
    2. Supprimez votre base de données.
    3. Créez une base de données avec un encodage différent (dans cet exemple, en_US.UTF8).
    4. Rechargez vos données.

  2. Gérez vos instances dupliquées avec accès en lecture.

    Cloud SQL pour PostgreSQL n'est pas compatible avec la réplication entre versions, ce qui signifie que vous ne pouvez pas mettre à niveau l'instance principale pendant que l'instance est en cours de réplication vers les instances dupliquées avec accès en lecture. Avant de procéder à la mise à niveau, désactivez la réplication pour chaque instance dupliquée avec accès en lecture ou supprimez les instances dupliquées avec accès en lecture.

  3. Si Cloud SQL est la source de réplication logique, désactivez la réplication de l'extension pglogical comme suit. Vous pourrez la réactiver après la mise à niveau. Si Cloud SQL est la cible de réplication logique, ces étapes ne sont pas obligatoires.
    1. Désactivez l'abonnement et déconnectez l'instance répliquée du fournisseur à l'aide de la commande suivante : 
      SELECT * FROM pglogical.alter_subscription_disable(subscription_name name, immediate bool);

      Remplacez name par le nom de l'abonnement existant.

      Définissez la valeur du paramètre immediate sur true si l'abonnement doit être désactivé immédiatement. Par défaut, la valeur est false et l'abonnement n'est désactivé qu'à la fin de la transaction en cours.

      Exemple : 

      postgres=> SELECT * FROM pglogical.alter_subscription_disable('test_sub', true);
 alter_subscription_disable
----------------------------
 t
(1 row)
    2. Supprimez l'emplacement de réplication en vous connectant à l'éditeur ou à l'instance principale Cloud SQL, puis en exécutant la commande suivante : 
      SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots
  WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);

      Exemple : 

      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. Gérez vos extensions PostgreSQL restantes.

    La plupart des extensions fonctionnent sur la version majeure de la base de données mise à niveau. Supprimez toutes les extensions qui ne sont plus compatibles dans votre version cible. Par exemple, supprimez l'extension chkpass si vous passez à PostgreSQL 11 ou à des versions ultérieures.

    Vous pouvez mettre à niveau manuellement PostGIS et ses extensions associées vers leurs dernières versions compatibles. Si votre version de PostGIS est antérieure à la version 3.1, utilisez la commande suivante pour mettre à niveau l'extension PostGIS : 

        ALTER EXTENSION postgis UPDATE TO '3.1.7';

    Parfois, la mise à niveau à partir d'une version 2.x de PostGIS peut créer une situation dans laquelle il subsiste des objets de base de données qui ne sont pas associés à l'extension PostGIS. Cela peut bloquer l'opération de mise à niveau. Pour en savoir plus sur la résolution de ce problème, consultez la section Résoudre un problème d'interruption d'une installation de fichier raster postgis.

    Pour en savoir plus sur la mise à niveau de vos extensions PostGIS, consultez la page Mettre à niveau PostGIS. Pour les problèmes associés à la mise à niveau de PostGIS, consultez la section Vérifier la version de votre instance PostgreSQL.
  5. Gérez vos options de base de données personnalisées. Vérifiez les noms des options de base de données personnalisées que vous avez configurées pour votre instance PostgreSQL. Pour les problèmes associés à ces options, consultez la section Vérifier les options personnalisées pour votre instance PostgreSQL.
  6. Lorsque vous effectuez une mise à niveau d'une version majeure vers une autre, essayez de vous connecter à chaque base de données pour vérifier la compatibilité. Assurez-vous que vos bases de données peuvent se connecter les unes aux autres. Vérifiez le champ datallowconn de chaque base de données pour vous assurer qu'une connexion est autorisée. Une valeur t signifie qu'elle est autorisée, et une valeur f indique qu'une connexion ne peut pas être établie.
  7. Si vous utilisez l'installation Datadog pour mettre à niveau votre instance Cloud SQL vers la version 10 ou une version ultérieure de PostgreSQL, supprimez la fonction pg_stat_activity() avant d'effectuer la mise à niveau.

Limitations connues

Les limites suivantes affectent les mises à niveau de versions majeures sur place de Cloud SQL pour PostgreSQL.

  • Vous ne pouvez pas effectuer de mise à niveau de version majeure sur place sur une instance répliquée externe.
  • La mise à niveau d'instances comportant plus de 1 000 bases de données d'une version à une autre peut prendre beaucoup de temps et expirer.
  • Utilisez l'instruction select * from pg_largeobject_metadata; pour interroger le nombre d'objets volumineux dans chaque base de données PostgreSQL de votre instance Cloud SQL. Si le résultat de toutes vos bases de données dépasse 10 millions d'objets volumineux, la mise à niveau échoue. Cloud SQL effectue un rollback vers la version précédente de votre base de données.
  • Avant d'effectuer une mise à niveau de version majeure sur place vers PostgreSQL 16, mettez à niveau l'extension PostGIS pour toutes vos bases de données vers la version 3.4.0.
  • Si vous utilisez les versions 9.6, 10, 11 ou 12 de PostgreSQL, la version 3.4.0 de l'extension PostGIS n'est pas compatible. Par conséquent, pour effectuer une mise à niveau de version majeure sur place vers PostgreSQL 16, vous devez d'abord passer à une version intermédiaire de PostgreSQL (versions 13, 14 ou 15).

  • Si vous installez les extensions pgRouting et pg_squeeze pour votre instance, vous ne pouvez pas effectuer de mise à niveau de version majeure. Pour résoudre ce problème, désinstallez ces extensions, puis effectuez la mise à niveau. Pour en savoir plus sur les extensions, consultez la section Configurer des extensions PostgreSQL.

  • Si vous activez les options vacuum_defer_cleanup_age et force_parallel_mode, vous ne pouvez pas effectuer de mise à niveau de version majeure. Pour résoudre ce problème, supprimez ces options, puis effectuez la mise à niveau. Pour en savoir plus sur les options, y compris sur leur suppression, consultez la section Configurer des options de base de données.

Mettre à niveau la version majeure de la base de données sur place

Lorsque vous lancez une opération de mise à niveau, Cloud SQL vérifie d'abord la configuration de votre instance pour s'assurer qu'elle est compatible avec une mise à niveau. Après avoir vérifié votre configuration, Cloud SQL rend votre instance indisponible, effectue une sauvegarde préalable à la mise à niveau, effectue la mise à niveau, relance votre instance, puis effectue une sauvegarde post-mise à niveau.

Console

  1. Dans Google Cloud Console, accédez à la page Instances Cloud SQL.

    Accéder à la page Instances Cloud SQL

  2. Pour ouvrir la page Présentation d'une instance, cliquez sur son nom.
  3. Cliquez sur Modifier.
  4. Dans la section Informations sur l'instance, cliquez sur le bouton Mettre à niveau, puis confirmez que vous souhaitez accéder à la page de mise à niveau.
  5. Sur la page Choisir une version de base de données, cliquez sur le champ Version de la base de données pour la mise à niveau, puis sélectionnez l'une des versions majeures disponibles.
  6. Cliquez sur Continuer.
  7. Dans la zone ID d'instance, saisissez le nom de l'instance, puis cliquez sur le bouton Démarrer la mise à niveau.
L'exécution de la requête prend plusieurs minutes.

Vérifiez que la version majeure de la base de données mise à niveau apparaît sous le nom de l'instance sur la page Présentation de l'instance.

gcloud

  1. Lancez la mise à niveau.

    Exécutez la commande gcloud sql instances patch avec l'option --database-version.

    Avant d'exécuter la commande, remplacez les éléments suivants :

    • INSTANCE_NAME : nom de l'instance
    • DATABASE_VERSION : énumération de la version majeure de la base de données, qui doit être postérieure à la version actuelle. Spécifiez une version de base de données pour une version majeure disponible en tant que cible de mise à niveau pour l'instance. Vous pouvez obtenir cette énumération comme première étape de la planification de la mise à niveau. Si vous avez besoin de la liste complète des énumérations de versions de bases de données, consultez SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
--database-version=DATABASE_VERSION

    Les mises à niveau de versions majeures prennent plusieurs minutes. Il est possible qu'un message indique que l'opération prend plus de temps que prévu. Vous pouvez ignorer ce message ou exécuter la commande gcloud sql operations wait pour l'ignorer.

  2. Obtenez le nom de l'opération de mise à niveau.

    Exécutez la commande gcloud sql operations list avec l'option --instance.

    Avant d'exécuter la commande, remplacez la variable INSTANCE_NAME par le nom de l'instance. 

    gcloud sql operations list --instance=INSTANCE_NAME

  3. Surveillez l'état de la mise à niveau.

    Exécutez la commande gcloud sql operations describe.

    Avant d'exécuter la commande, remplacez la variable OPERATION par le nom de l'opération de mise à niveau récupérée à l'étape précédente. 

    gcloud sql operations describe OPERATION

REST v1

  1. Démarrez la mise à niveau sur place.

    Exécutez une requête PATCH avec la méthode instances:patch.

    Avant d'utiliser les données de requête ci-dessous, remplacez les variables suivantes :

    • PROJECT_ID : ID du projet
    • INSTANCE_NAME : nom de l'instance

    Méthode HTTP et URL :

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

    Corps JSON de la requête : 

    {
  "databaseVersion": DATABASE_VERSION
}

    Remplacez DATABASE_VERSION par l'énumération de la version majeure de la base de données, qui doit être postérieure à la version actuelle. Spécifiez une version de base de données pour une version majeure disponible en tant que cible de mise à niveau pour l'instance. Vous pouvez obtenir cette énumération comme première étape de la planification de la mise à niveau. Si vous avez besoin de la liste complète des énumérations de versions de bases de données, consultez SqlDatabaseVersion.

  2. Obtenez le nom de l'opération de mise à niveau.

    Exécutez une requête GET avec la méthode operations.list après avoir remplacé PROJECT_ID par l'ID du projet.

    Méthode HTTP et URL :

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

  3. Surveillez l'état de la mise à niveau.

    Exécutez une requête GET avec la méthode operations.get après avoir remplacé les variables suivantes :

    • PROJECT_ID : ID du projet
    • OPERATION_NAME : nom de l'opération de mise à niveau récupérée à l'étape précédente.

    Méthode HTTP et URL : 

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

Terraform

Pour mettre à jour la version de la base de données, utilisez une ressource Terraform et le fournisseur Terraform pour Google Cloud, version 4.34.0 ou ultérieure.

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
}

Appliquer les modifications

Pour appliquer votre configuration Terraform dans un projet Google Cloud, suivez les procédures des sections suivantes.

Préparer Cloud Shell

  1. Lancez Cloud Shell.

  2. Définissez le projet Google Cloud par défaut dans lequel vous souhaitez appliquer vos configurations Terraform.

    Vous n'avez besoin d'exécuter cette commande qu'une seule fois par projet et vous pouvez l'exécuter dans n'importe quel répertoire.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Les variables d'environnement sont remplacées si vous définissez des valeurs explicites dans le fichier de configuration Terraform.

Préparer le répertoire

Chaque fichier de configuration Terraform doit avoir son propre répertoire (également appelé module racine).

  1. Dans Cloud Shell, créez un répertoire et un nouveau fichier dans ce répertoire. Le nom du fichier doit comporter l'extension .tf, par exemple main.tf. Dans ce tutoriel, le fichier est appelé main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Si vous suivez un tutoriel, vous pouvez copier l'exemple de code dans chaque section ou étape.

    Copiez l'exemple de code dans le fichier main.tf que vous venez de créer.

    Vous pouvez également copier le code depuis GitHub. Cela est recommandé lorsque l'extrait Terraform fait partie d'une solution de bout en bout.

  3. Examinez et modifiez les exemples de paramètres à appliquer à votre environnement.
  4. Enregistrez les modifications.
  5. Initialisez Terraform. Cette opération n'est à effectuer qu'une seule fois par répertoire. 
    terraform init

    Vous pouvez également utiliser la dernière version du fournisseur Google en incluant l'option -upgrade : 

    terraform init -upgrade

Appliquer les modifications

  1. Examinez la configuration et vérifiez que les ressources que Terraform va créer ou mettre à jour correspondent à vos attentes : 
    terraform plan

    Corrigez les modifications de la configuration si nécessaire.

  2. Appliquez la configuration Terraform en exécutant la commande suivante et en saisissant yes lorsque vous y êtes invité : 
    terraform apply

    Attendez que Terraform affiche le message "Apply completed!" (Application terminée).

  3. Ouvrez votre projet Google Cloud pour afficher les résultats. Dans la console Google Cloud, accédez à vos ressources dans l'interface utilisateur pour vous assurer que Terraform les a créées ou mises à jour.

Supprimer les modifications

Pour supprimer vos modifications, procédez comme suit :

  1. Pour désactiver la protection contre la suppression, définissez l'argument deletion_protection sur false dans le fichier de configuration Terraform. 
    deletion_protection =  "false"
  2. Appliquez la configuration Terraform mise à jour en exécutant la commande suivante et en saisissant yes lorsque vous y êtes invité : 
    terraform apply

  1. Supprimez les ressources précédemment appliquées à votre configuration Terraform en exécutant la commande suivante et en saisissant yes à la requête :

    terraform destroy

Lorsque vous placez une demande de mise à niveau sur place, Cloud SQL commence par effectuer une vérification de la mise à niveau. Si Cloud SQL détermine que votre instance n'est pas prête pour une mise à niveau, votre requête de mise à niveau échoue avec un message suggérant comment résoudre le problème. Consultez également la section Résoudre les problèmes liés à la mise à niveau d'une version majeure.

Sauvegardes automatiques des mises à niveau

Lorsque vous effectuez une mise à niveau de version majeure, Cloud SQL effectue automatiquement deux sauvegardes à la demande, appelées sauvegardes de mise à niveau :

  • La première sauvegarde de mise à niveau est la sauvegarde préalable à la mise à niveau, qui est effectuée immédiatement avant le début de la mise à niveau. Vous pouvez utiliser cette sauvegarde pour restaurer l'état de votre instance de base de données dans la version précédente.
  • La deuxième sauvegarde de mise à niveau est la sauvegarde post-mise à niveau, qui est effectuée immédiatement après l'autorisation des nouvelles écritures sur l'instance de base de données mise à niveau.

Lorsque vous affichez la liste de vos sauvegardes, les sauvegardes de mise à niveau sont répertoriées avec le type On-demand. Les sauvegardes de mise à niveau sont libellées afin de pouvoir les identifier facilement. Par exemple, si vous effectuez une mise à niveau de PostgreSQL 9.6 vers PostgreSQL 13, votre sauvegarde préalable est libellée Pre-upgrade backup, POSTGRES_9_6 to POSTGRES_13. et votre sauvegarde post-mise à niveau Post-upgrade backup, POSTGRES_13 from POSTGRES_9_6..

Comme pour les autres sauvegardes à la demande, les sauvegardes de mise à niveau sont conservées jusqu'à ce que vous les supprimiez ou que vous supprimiez l'instance. Si la récupération PITR est activée, vous ne pouvez pas supprimer vos sauvegardes de mise à niveau tant qu'elles sont dans votre période de conservation. Si vous devez supprimer vos sauvegardes de mise à niveau, vous devez désactiver la récupération PITR ou attendre que vos sauvegardes de mise à niveau ne se trouvent plus dans votre durée de conservation.

Terminer la mise à niveau de la version majeure

Une fois la mise à niveau terminée, procédez comme suit :

  1. Activez la réplication pglogical si votre instance l'a utilisée avant la mise à niveau. Cette opération crée automatiquement l'emplacement de réplication nécessaire.
    1. Supprimez l'abonnement pglogical sur l'instance répliquée de destination à l'aide de la commande suivante : 
      select pglogical.drop_subscription(subscription_name name);

      Remplacez name par le nom de l'abonnement existant.

      Exemple : 

      postgres=> select pglogical.drop_subscription(subscription_name := 'test_sub');
-[ RECORD 1 ]-----+--
drop_subscription | 1
    2. Recréez l'abonnement pglogical sur la destination (instance répliquée) en fournissant les détails de connexion comme suit à l'instance 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'
);

      Exemple : 

      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. Vérifiez l'état de l'abonnement à l'aide de la commande suivante : 
      SELECT * FROM pglogical.show_subscription_status('test_sub');
    4. Testez l'instance dupliquée en effectuant des transactions d'écriture et en vérifiant que les modifications sont visibles sur la destination.

  2. Mettez à niveau les instances dupliquées avec accès en lecture.

    Si vous avez arrêté la réplication pour lire les instances dupliquées, mettez-les à niveau individuellement. Vous pouvez utiliser l'une des méthodes utilisées pour mettre à niveau l'instance principale. Lorsque vous mettez à niveau une instance dupliquée, Cloud SQL la recrée en conservant les adresses IP, l'actualise avec les dernières données de l'instance principale et redémarre l'instance dupliquée.

    Si vous avez supprimé vos instances dupliquées avec accès en lecture avant de mettre à niveau votre instance principale, vous pouvez créer de nouvelles instances dupliquées avec accès en lecture qui sont automatiquement provisionnées sur la version mise à niveau de la base de données.

  3. Actualisez les statistiques de la base de données.

    Exécutez ANALYZE sur votre instance principale pour mettre à jour les statistiques système après la mise à niveau. Les statistiques précises garantissent que le planificateur de requêtes PostgreSQL traite les requêtes de manière optimale. Des statistiques manquantes peuvent entraîner des plans de requête de mauvaise qualité, ce qui peut dégrader les performances et entraîner une utilisation excessive de mémoire.

  4. Effectuez des tests de validation.

    Vous devez exécuter des tests pour vous assurer que le système mis à niveau fonctionne comme prévu.

Résoudre un problème de mise à niveau de version majeure

Cloud SQL renvoie un message d'erreur si vous tentez d'effectuer une commande de mise à niveau non valide, par exemple si votre instance contient des options de base de données non valides pour la nouvelle version.

Si votre requête de mise à niveau échoue, vérifiez sa syntaxe. Si la structure de la requête est valide, tentez de considérer les suggestions suivantes.

Afficher les échecs de la vérification préalable à la mise à niveau

Les échecs de la vérification préalable à la mise à niveau correspondent à des problèmes ou des erreurs détectés par Cloud SQL lors du processus de vérification ou de validation préalable à la mise à niveau. Ces échecs se produisent avant le début de la mise à niveau effective, et sont destinés à identifier les problèmes ou incompatibilités potentiels susceptibles de compromettre l'opération de mise à niveau.

Les échecs de la vérification préalable à la mise à niveau s'affichent pour les catégories suivantes :

  • Extensions incompatibles : détectez les extensions PostgreSQL qui ne sont pas compatibles avec la version de destination de l'instance.
  • Dépendances non compatibles : identifiez les dépendances qui ne sont plus compatibles ou qui doivent être mises à jour.
  • Incompatibilités de format de données : vérifiez les incohérences de données résultant de divers facteurs, y compris les différences au niveau des structures de données spécifiques à la version, des modifications de l'encodage et du classement, des modifications des types de données et des ajustements du catalogue système.

Le tableau suivant liste les échecs de la vérification préalable à la mise à niveau, et les messages d'erreur associés :

Échec de la vérification préalable à la mise à niveau Message d'erreur
Cloud SQL détecte un type de données inconnu. Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Lors de la mise à niveau vers PostgreSQL 12 ou une version ultérieure, Cloud SQL détecte le type de données '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 détecte le type de données 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 détecte que la valeur
LC_COLLATE de la base de données postgres est un jeu de caractères autre que en_US.UTF8.		 Please change the 'LC_COLLATE' value of the postgres database to 'en_US.UTF8' before attempting an upgrade
Cloud SQL détecte des tables qui ont des identifiants d'objets (OID). Please remove the following usages of tables with OIDs before attempting an upgrade: (database: db_name, relation: rel_name)
Cloud SQL détecte des types de données composites. Please remove the following usages of 'composite' data types before attempting an upgrade: (database: db_name, relation: rel_name, attribute: attr_name)
Cloud SQL détecte des opérateurs postfix définis par l'utilisateur. 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 détecte des fonctions polymorphes incompatibles. 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 détecte des conversions d'encodage définies par l'utilisateur. 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)

Afficher les journaux de mise à niveau

Si un problème survient lors d'une requête de mise à niveau valide, Cloud SQL publie les journaux d'erreurs dans projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log. Chaque entrée de journal contient un libellé avec l'identifiant d'instance pour vous aider à identifier l'instance avec l'erreur de mise à niveau. Recherchez ces erreurs de mise à niveau et corrigez-les.

Pour afficher les journaux d'erreurs, procédez comme suit :

  1. Dans Google Cloud Console, accédez à la page Instances Cloud SQL.

    Accéder à la page Instances Cloud SQL

  2. Pour ouvrir la page Présentation d'une instance, cliquez sur son nom.

  3. Dans le volet Opérations et journaux de la page Présentation de l'instance, cliquez sur le lien Afficher les journaux d'erreurs PostgreSQL.

    La page Explorateur de journaux s'affiche.

  4. Affichez les journaux comme suit :

    • Pour regrouper tous les journaux d'erreurs d'un projet, sélectionnez le nom du journal dans le filtre de journal Nom du journal.

    Pour en savoir plus sur les filtres de requête, consultez la page Requêtes avancées.

    • Pour filtrer les journaux d'erreurs de mise à niveau pour une seule instance, saisissez la requête suivante dans la zone Rechercher dans tous les champs, après avoir remplacé DATABASE_ID

    par l'ID du projet suivi du nom de l'instance au format suivant : 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"

    Par exemple, pour filtrer les journaux d'erreurs de mise à niveau selon une instance nommée shopping-db qui s'exécute dans le projet buylots, utilisez le filtre de requête suivant :

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

Les entrées de journal portant le préfixe pg_upgrade_dump indiquent qu'une erreur de mise à niveau s'est produite. Exemple :

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

En outre, les entrées de journal dotées d'un nom de fichier secondaire .txt peuvent regrouper d'autres erreurs qu'il peut s'avérer préférable de résoudre avant de relancer la mise à niveau.

Tous les noms de fichiers se trouvent dans le fichier postgres-upgrade.log. Pour localiser un nom de fichier, consultez le champ labels.FILE_NAME.

Les noms de fichiers susceptibles de contenir des erreurs sont les suivants :

  • tables_with_oids.txt: Ce fichier contient des tables répertoriées avec des identifiants d'objet (OID). Supprimez les tables ou modifiez-les pour qu'elles n'utilisent pas d'OID.
  • tables_using_composite.txt: Ce fichier contient des tables répertoriées à l'aide de types composites définis par le système. Supprimez les tables ou modifiez-les pour qu'elles n'utilisent pas ces types composites.
  • tables_using_unknown.txt: Ce fichier contient des tables répertoriées à l'aide du type de données UNKNOWN. Supprimez les tables ou modifiez-les pour qu'elles n'utilisent pas ce type de données.
  • tables_using_sql_identifier.txt: Ce fichier contient des tables répertoriées à l'aide du type de données SQL_IDENTIFIER. Supprimez les tables ou modifiez-les pour qu'elles n'utilisent pas ce type de données.
  • tables_using_reg.txt: Ce fichier contient des tables répertoriées à l'aide du type de données REG* (par exemple, REGCOLLATION ou REGNAMESPACE). Supprimez les tables ou modifiez-les pour qu'elles n'utilisent pas ce type de données.
  • postfix_ops.txt: Ce fichier contient des tables répertoriées à l'aide d'opérateurs postfix (unaire à droite). Supprimez les tables ou modifiez-les pour qu'elles n'utilisent pas ces opérateurs.

Vérifier la mémoire

Si l'instance dispose d'une mémoire partagée insuffisante, ce message d'erreur peut s'afficher : ERROR: out of shared memory. Cette erreur est plus susceptible de se produire si vous dépassez les 10 000 tables.

Avant de tenter de procéder à la mise à niveau, définissez la valeur de l'option max_locks_per_transaction sur environ deux fois le nombre de tables présentes dans l'instance. L'instance est redémarrée lorsque vous modifiez la valeur de cette option.

Vérifier la capacité des connexions

Si la capacité de la connexion de votre instance est insuffisante, le message d'erreur suivant peut s'afficher : ERROR: Insufficient connections.

Cloud SQL recommande d'augmenter la valeur de l'option max_connections en fonction du nombre de bases de données de votre instance. L'instance est redémarrée lorsque vous modifiez la valeur de cette option.

Vérifier la version de votre instance PostgreSQL

Si vous utilisez la version 9.6, 10 ou 11 d'une instance Cloud SQL pour PostgreSQL et que vous avez activé l'extension PostGIS pour l'instance, la mise à niveau de PostGIS peut échouer en raison d'un problème d'autorisation. Pour résoudre ce problème, utilisez la maintenance en libre-service pour déployer l'image de gestionnaire système (SSM) la plus récente. Vous obtiendrez l'autorisation de mettre à niveau PostGIS.

Vérifier les options personnalisées pour votre instance PostgreSQL

Si vous effectuez une mise à niveau vers une instance PostgreSQL version 14 ou ultérieure, vérifiez les noms des options de base de données personnalisées que vous avez configurées pour l'instance. En effet, PostgreSQL a mis en place des restrictions supplémentaires sur les noms autorisés pour les paramètres personnalisés.

Le premier caractère d'une option de base de données personnalisée doit être alphabétique (A-Z ou a-z). Tous les caractères suivants peuvent être alphanumériques, le trait de soulignement (_) ou le signe dollar ($).

Supprimer des extensions

Si vous mettez à niveau votre instance Cloud SQL de la version 10 vers la version 14, le message d'erreur suivant peut s'afficher : pg_restore: error: could not execute query: ERROR: role "16447" does not exist.

Pour résoudre ce problème, procédez comme suit :

  1. Supprimez les extensions pg_stat_statements et pgstattuple.
  2. Procédez à la mise à niveau.
  3. Réinstallez les extensions.

Restaurer la version majeure précédente

Si votre système de base de données mis à niveau ne fonctionne pas comme prévu, vous devrez peut-être restaurer la version précédente de l'instance. Pour ce faire, vous devez restaurer votre sauvegarde préalable à la mise à niveau sur une instance de récupération Cloud SQL, qui est une nouvelle instance exécutant la version préliminaire.

Pour restaurer la version précédente, procédez comme suit :

  1. Identifiez votre sauvegarde préalable à la mise à niveau.

    Consultez la section Sauvegardes automatiques.

  2. Créez une instance de récupération.

    Créez une instance Cloud SQL à l'aide de la version majeure en cours d'exécution par Cloud SQL lors de la sauvegarde préalable. Définissez les options et les paramètres d'instance utilisés par l'instance d'origine.

  3. Restaurez votre sauvegarde préalable à la mise à niveau.

    Restaurez votre sauvegarde préalable à la mise à niveau sur l'instance de récupération. Cette opération peut prendre plusieurs minutes.

  4. Ajoutez vos instances dupliquées avec accès en lecture.

    Si vous utilisiez des instances dupliquées avec accès en lecture, ajoutez-les individuellement.

  5. Connectez votre application.

    Après avoir récupéré votre système de base de données, mettez à jour votre application avec les détails de l'instance de récupération et de ses instances dupliquées avec accès en lecture. Vous pouvez reprendre la diffusion du trafic sur la version antérieure à la mise à niveau de votre base de données.

Questions fréquentes

Les questions suivantes peuvent vous être posées lors de la mise à niveau de la version majeure de la base de données.

Mon instance est-elle indisponible lors d'une mise à niveau ?
Oui. Votre instance reste indisponible pendant un certain temps pendant que Cloud SQL effectue la mise à niveau.
Combien de temps dure une mise à niveau ?

La mise à niveau d'une seule instance prend généralement moins de 10 minutes. Si la configuration de votre instance utilise un petit nombre de processeurs virtuels ou peu de mémoire, votre mise à niveau peut prendre plus de temps.

Si votre instance héberge trop de bases de données ou de tables, ou si vos bases de données sont très volumineuses, la mise à niveau peut prendre des heures, voire expirer, car la durée de mise à niveau correspond au nombre d'objets dans vos bases de données. Si vous devez mettre à niveau plusieurs instances, le temps total de mise à niveau augmente proportionnellement.

Puis-je surveiller chaque étape de mon processus de mise à niveau ?
Bien que Cloud SQL vous permet de vérifier si une opération de mise à niveau est toujours en cours, vous ne pouvez pas suivre les étapes de chaque mise à niveau.
Puis-je annuler ma mise à niveau après son lancement ?
Non, vous ne pouvez pas annuler une mise à niveau une fois celle-ci démarrée. En cas d'échec de la mise à niveau, Cloud SQL récupère automatiquement votre instance sur la version précédente.
Qu'advient-il de mes paramètres lors d'une mise à niveau ?

Lorsque vous effectuez une mise à niveau de version majeure sur place, Cloud SQL conserve vos paramètres de base de données, y compris le nom de l'instance, l'adresse IP, les valeurs des options configurées explicitement et les données utilisateur. Toutefois, la valeur par défaut des variables système peut changer. Par exemple, la valeur par défaut de l'option password_encryption dans PostgreSQL 13 et les versions antérieures est md5. Lorsque vous passez à PostgreSQL 14, la valeur par défaut de cette option passe à scram-sha-256.

Pour en savoir plus, consultez la section Configurer des options de base de données. Si une option ou une valeur spécifique n'est plus acceptée dans votre version cible, Cloud SQL le supprime automatiquement lors de la mise à niveau.

Étapes suivantes