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. Vérifiez que vous disposez du rôle requis pour effectuer une mise à niveau de version majeure : Propriétaire Cloud SQL ou Administrateur Cloud SQL.

  2. 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.

  3. 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.

  4. Effectuez la vérification préalable des mises à niveau.

  5. 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.

  6. 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.

    Vous pouvez également renommer la base de données :

    1. Fermez toutes les connexions à la base de données.
    2. Renommez la base de données.
    3. Mettez à jour les configurations de vos applications pour qu'elles utilisent le nouveau nom de base de données.
    4. Créez une base de données vide avec l'encodage par défaut.

    Nous vous recommandons d'effectuer ces étapes sur une instance clonée avant de les appliquer à une instance de production.

  2. 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.

    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 Résoudre un problème d'interruption d'une installation de fichier raster PostGIS.

    Parfois, la mise à niveau vers PostGIS version 3.1.7 ou ultérieure ne peut pas être effectuée en raison d'objets utilisant des fonctions obsolètes. Cela peut bloquer l'opération de mise à niveau. Pour vérifier l'état de la mise à niveau, exécutez SELECT PostGIS_full_version();. Si des avertissements sont présents, supprimez tous les objets à l'aide des fonctions obsolètes et mettez à jour l'extension PostGIS vers une version intermédiaire ou ultérieure. Une fois ces actions effectuées, exécutez à nouveau la commande SELECT PostGIS_full_version();. Vérifiez qu'aucun avertissement ne s'affiche. Poursuivez ensuite l'opération de mise à niveau.

    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.
  3. 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.
  4. 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.
  5. 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 et versions ultérieures, mettez à niveau l'extension PostGIS pour toutes vos bases de données vers la version 3.4.0. Pour PostgreSQL 18, passez à la version 3.6.0 de PostGIS.
  • Avant d'effectuer une mise à niveau de version majeure sur place vers PostgreSQL 17, mettez à niveau l'extension rdkit pour toutes vos bases de données vers la version 4.6.1.
  • Avant d'effectuer une mise à niveau de version majeure sur place vers PostgreSQL 16, 17 ou 18, mettez à niveau l'extension pg_squeeze pour toutes vos bases de données vers la version 1.6, 1.7 ou 1.8, respectivement.
  • 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 et versions ultérieures, vous devez d'abord passer à une version intermédiaire de PostgreSQL (versions 13, 14 ou 15).

  • Si vous installez l'extension pg_ivm pour votre instance, vous ne pouvez pas effectuer de mise à niveau de version majeure. Pour résoudre ce problème, désinstallez cette extension, puis effectuez la mise à niveau. Pour en savoir plus sur les extensions, consultez 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.

Évaluer l'état de préparation de votre instance pour la mise à niveau

Cloud SQL vous permet d'exécuter une vérification préalable sur votre instance avant la mise à niveau d'une version majeure. Cette vérification préalable est une opération de longue durée (OLD) qui vérifie si votre instance est prête pour une mise à niveau. Il permet de détecter les problèmes potentiels tels que les incompatibilités, les problèmes de configuration ou les problèmes de données avant l'opération de mise à niveau.

La vérification préalable confirme que votre instance peut être mise à niveau ou liste les problèmes que vous devez résoudre en premier, ainsi que leurs solutions. Ces problèmes peuvent être dus à des extensions incompatibles, à des dépendances non compatibles ou à des problèmes de format de données.

La vérification préalable lit principalement les métadonnées de votre instance et effectue des vérifications. Ces tâches n'affectent pas les performances de votre instance et n'entraînent pas de temps d'arrêt. Nous vous recommandons vivement d'exécuter la vérification préalable, car elle permet d'éviter les échecs de mise à niveau et les temps d'arrêt inattendus.

Lorsque vous exécutez la vérification préalable, l'une des situations suivantes se produit :

  • Aucun problème détecté : la vérification préalable s'est terminée avec succès et aucun problème n'a été détecté.
  • Problèmes bloquant la mise à niveau détectés : la vérification préalable s'est terminée avec succès, mais des erreurs bloquant la mise à niveau ont été détectées. Les problèmes doivent être résolus avant la migration.
  • Avertissements non bloquants détectés : la vérification préalable s'est terminée avec succès et a détecté des avertissements, mais aucun d'eux n'empêche la mise à niveau.

En fonction des résultats de la vérification préalable, vous pouvez procéder à la mise à niveau ou résoudre les problèmes identifiés avant la mise à niveau.

Limites

Lorsque vous utilisez le précontrôle de mise à niveau de version majeure, tenez compte des limites suivantes :

  • L'état de l'instance doit être défini sur RUNNING.
  • L'instance doit être une instance principale. precheck n'est pas compatible avec les instances répliquées.

  • Aucune opération bloquante ne doit être en attente sur l'instance. Si une opération bloquante est en attente, la vérification préliminaire génère une erreur avec le message suivant :

    Operation failed because another operation was already in progress. Try
your request after the current operation is complete.

  • La vérification préalable doit se connecter à toutes les bases de données de l'instance. Si une base de données est inaccessible, verrouillée ou ne répond pas, la vérification préalable peut échouer ou afficher des erreurs. Bien que le précontrôle n'affecte pas les performances de votre instance ni n'entraîne de temps d'arrêt, nous vous recommandons de l'exécuter lorsque la charge de la base de données est faible.

Avant de commencer

  • Assurez-vous que l'API Cloud SQL Admin est activée pour votre instance.
  • Vérifiez que vous disposez de l'autorisation IAM cloudsql.instances.preCheckMajorVersionUpgrade.

Effectuer la vérification préalable

Pour effectuer le précontrôle de la mise à niveau de version majeure, procédez comme suit :

gcloud

  1. Exécutez la vérification préalable :

    gcloud sql instances pre-check-major-version-upgrade INSTANCE_NAME \
--target-database-version=TARGET_DATABASE_VERSION \
--project=PROJECT_ID \
[--async]

    Remplacez les éléments suivants :

    • INSTANCE_NAME : nom de l'instance.
    • TARGET_DATABASE_VERSION : version majeure vers laquelle vous souhaitez mettre à niveau votre instance. Pour trouver la version de la base de données, consultez Planifier une mise à niveau.
    • PROJECT_ID : ID de votre projet Google Cloud .

  2. Obtenez le nom de l'opération de vérification préalable :

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

    gcloud sql operations list --instance=INSTANCE_NAME

    Remplacez les éléments suivants :

    • INSTANCE_NAME : nom de l'instance.

  3. Surveillez l'état du précontrôle.

    Exécutez la commande gcloud sql operations describe :

    gcloud sql operations describe OPERATION_NAME

    Remplacez les éléments suivants :

    • OPERATION_NAME : nom de l'opération de prévérification récupérée à l'étape précédente.

REST v1

  1. Exécutez la vérification préalable.

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

    • PROJECT_ID : ID du projet
    • INSTANCE_ID : ID de l'instance
    • TARGET_DATABASE_VERSION : version majeure vers laquelle effectuer la mise à niveau. Pour obtenir la liste des versions de base de données disponibles, consultez Planifier une mise à niveau.

    Méthode HTTP et URL : 

    POST https://sqladmin.googleapis.com/sql/v1b/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

    Corps JSON de la requête :

    {
  "preCheckMajorVersionUpgradeContext": {
    "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
  }
}

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

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

    {
  "message": "Precheck description of finding",
  "message_type": "ERROR",
  "actions_required": [
    "Precheck action required to fix the finding"
  ]
}

  2. Obtenez le nom de l'opération de vérification préalable.

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

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

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .

  3. Surveillez l'état du précontrôle.

    Exécutez la requête GET avec la méthode operations.list :

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

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • OPERATION_NAME : nom de l'opération de prévérification récupérée à l'étape précédente.

REST v1beta4

  1. Exécutez la vérification préalable.

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

    • PROJECT_ID : ID du projet
    • INSTANCE_ID : ID de l'instance
    • TARGET_DATABASE_VERSION : version majeure vers laquelle effectuer la mise à niveau. Pour obtenir la liste des versions de bases de données disponibles, consultez Planifier une mise à niveau.

    Méthode HTTP et URL : 

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

    Corps JSON de la requête :

    {
  "preCheckMajorVersionUpgradeContext": {
    "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
  }
}

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

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

    {
  "message": "Precheck description of finding",
  "message_type": "ERROR",
  "actions_required": [
    "Precheck action required to fix the finding"
  ]
}

  2. Obtenez le nom de l'opération de vérification préalable.

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

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

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .

  3. Surveillez l'état du précontrôle.

    Exécutez la requête GET avec la méthode operations.list :

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

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • operation_name : nom de l'opération de prévérification récupérée à l'étape précédente.

Examiner les résultats de la vérification préalable

Une fois la vérification préalable terminée, votre instance est prête pour la mise à niveau ou présente des problèmes qui nécessitent votre attention.

Mise à niveau disponible

Si la vérification préalable se termine correctement et que le tableau preCheckResponse est vide, cela signifie qu'aucun problème ni avertissement n'ont été détectés. Votre instance est prête pour la mise à niveau de version majeure. Pour continuer, consultez Effectuer une mise à niveau de version majeure.

Pas prêt pour la mise à niveau

Si la vérification préalable s'est déroulée correctement et que le tableau preCheckResponse contient des problèmes, votre instance n'est pas prête pour la mise à niveau et nécessite votre attention. Les problèmes identifiés peuvent ou non bloquer la mise à niveau. Ces problèmes sont indiqués dans le preCheckResponse avec les types de messages suivants :

Type Description Bloquer la mise à niveau ?
INFO Message d'information. Non
WARNING Un problème potentiel a été détecté, mais il ne bloque pas la mise à niveau. Cloud SQL recommande de consulter l'avertissement et d'y remédier avant de procéder à la mise à niveau pour garantir une compatibilité totale. Non
ERROR Un problème critique bloquant la mise à niveau a été détecté. Ces problèmes peuvent entraîner l'échec de la mise à niveau. Vous devez les résoudre avant de mettre à niveau votre instance. Oui

Si votre instance ne comporte que des messages INFO ou WARNING, vous pouvez la mettre à niveau, mais vous risquez de rencontrer des problèmes après la mise à niveau. Nous vous recommandons de consulter les détails du message et de résoudre le problème avant de procéder à la mise à niveau. Si votre instance comporte des messages ERROR, vous devez résoudre ces problèmes avant de procéder à la mise à niveau.

Chaque type de problème comprend un champ message et un champ actions_required. Examinez chaque problème pour comprendre son type et savoir comment le résoudre. Pour en savoir plus sur les problèmes courants et leurs solutions, consultez Erreurs courantes lors de la vérification préalable à la mise à niveau de la version majeure.

Une fois les problèmes résolus, exécutez à nouveau la vérification préalable pour confirmer que votre instance est prête pour la mise à niveau. Ensuite, procédez à la mise à niveau de votre instance une fois que la vérification préalable est terminée.

Effectuer la mise à niveau de version majeure

Vous pouvez mettre à niveau la version majeure d'une seule instance Cloud SQL, ou celle d'une instance principale et inclure toutes ses instances répliquées dans la mise à niveau, y compris les instances répliquées en cascade et les instances répliquées multirégionales.

Mettre à niveau la version majeure d'une seule instance

Lorsque vous lancez une opération de mise à niveau pour une seule instance, Cloud SQL effectue les opérations suivantes :

  1. Vérifie la configuration de votre instance pour s'assurer qu'elle est compatible avec une mise à niveau.
  2. Une fois que Cloud SQL a vérifié la configuration, il rend l'instance indisponible.
  3. Effectue une sauvegarde avant la mise à niveau.
  4. Effectue la mise à niveau sur l'instance.
  5. Rend votre instance disponible.
  6. Effectue une sauvegarde post-mise à niveau.

Console

  1. Dans la console Google Cloud , 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 à l'invite :

    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.

Inclure des réplicas dans la mise à niveau de version majeure

Si votre instance principale comporte des instances répliquées, vous pouvez les inclure toutes dans la mise à niveau. Cloud SQL peut mettre à niveau toutes les instances répliquées de l'instance principale, y compris les instances répliquées interrégionales et en cascade.

Lorsque vous incluez des réplicas dans une mise à niveau de version majeure, Cloud SQL effectue les opérations suivantes :

  1. Vérifie la configuration de votre instance principale et de vos répliques pour s'assurer qu'elles sont compatibles avec une mise à niveau.
  2. Rend votre instance principale indisponible.
  3. Effectue une sauvegarde de l'instance principale avant la mise à niveau.
  4. Arrête la réplication pour toutes les instances dupliquées.
  5. Effectue la mise à niveau sur l'instance principale.
  6. Si la mise à niveau de l'instance principale aboutit, l'instance principale redevient disponible et la réplication redémarre.
  7. Cloud SQL effectue une sauvegarde après mise à niveau de l'instance principale.
  8. Cloud SQL procède à la mise à niveau de toutes les instances répliquées.

Même si la mise à niveau de la version majeure d'une instance répliquée échoue, l'instance principale reste disponible.

Pour inclure des réplicas dans une mise à niveau de version majeure, vous ne pouvez pas utiliser la consoleGoogle Cloud ni Terraform. Vous ne pouvez utiliser que gcloud CLI ou l'API Cloud SQL Admin.

gcloud

  1. Lancez la mise à niveau.

    Exécutez la commande gcloud sql instances patch avec les options --database-version et --include-replicas-for-major-version-upgrade.

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

    • INSTANCE_NAME : nom de l'instance principale.
    • 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 \
  --include-replicas-for-major-version-upgrade

    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. La mise à niveau des réplicas peut prendre plusieurs minutes. Pour vérifier l'état de la mise à niveau, procédez comme suit :

  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

  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
  "includeReplicasForMajorVersionUpgrade": true
}

    • 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.
    • Dans le champ includeReplicasForMajorVersionUpgrade, spécifiez true.

  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

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 rapidement. Par exemple, si vous effectuez une mise à niveau de PostgreSQL 14 vers PostgreSQL 15, votre sauvegarde préalable est libellée Pre-upgrade backup, POSTGRES_14 to POSTGRES_15. et votre sauvegarde post-mise à niveau est libellée Post-upgrade backup, POSTGRES_14 to POSTGRES_15..

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 de l'instance principale terminée, procédez comme suit :

  1. 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. Des 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.

  2. Effectuez des tests de validation.

    Exécutez 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 journaux d'erreurs

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

  1. Dans la console Google Cloud , 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"

    Vous pouvez examiner tous les journaux signalés au cours d'une période donnée ou les filtrer par niveau de gravité. Pour résoudre les problèmes, vous pouvez sélectionner les filtres suivants :

    • Urgence
    • Alerte
    • Critique
    • Erreur

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 si une référence de colonne est ambiguë

Cloud SQL effectue automatiquement une vérification avant la mise à niveau pour identifier les vues définies par l'utilisateur qui dépendent des vues du catalogue système, telles que pg_stat_activity ou pg_stat_replication. La structure des colonnes de ces vues de catalogue système peut changer entre les versions majeures de PostgreSQL. Si vous avez des vues qui select * ou qui s'appuient sur l'ordre des colonnes de ces vues système, elles peuvent devenir incompatibles après une mise à niveau, ce qui peut entraîner une erreur, telle que ERROR: column reference "column_name" is ambiguous.

La vérification préalable à la mise à niveau détecte ces vues en recherchant les dépendances. Si des vues incompatibles sont détectées, le processus de mise à niveau est arrêté et un message d'erreur s'affiche. Ce message liste les vues incompatibles dans chaque base de données qui doivent être traitées.

Exemple de message d'erreur

  • Pour les problèmes liés à pg_stat_activity : 

    Please remove the following usages of views that depend on functions returning
data types of pg_stat_activity before attempting an upgrade:
(database: my_db, schema name: public, view name: my_stat_activity_view)

  • Pour les problèmes liés à pg_stat_replication :

    Please remove the following usages of views that depend on functions returning
data types of pg_stat_replication before attempting an upgrade:
(database: my_db, schema name: public, view name: my_replication_stats_view)

Pour résoudre ces problèmes et procéder à la mise à niveau : 1. Identifiez les vues listées dans le message d'erreur de la vérification préalable à la mise à niveau.

  1. Supprimez ces vues à l'aide de DROP VIEW view_name;.

  2. Réessayez d'effectuer la mise à niveau de version majeure.

  3. Une fois la mise à niveau terminée, recréez les vues. Assurez-vous que les nouvelles définitions de vues sont compatibles avec le schéma des vues du catalogue système dans la version actuelle de PostgreSQL. Vous devrez peut-être lister explicitement les colonnes au lieu d'utiliser select * pour éviter tout problème à l'avenir.

Pour obtenir un exemple plus détaillé du problème et d'autres informations, consultez cette discussion sur Stack Overflow.

Rechercher des SRF dans les instructions CASE

Si vous mettez à niveau votre instance à partir de la version 9.6 et que vous utilisez des fonctions de renvoi d'ensemble dans vos instructions CASE, le message d'erreur ERROR: set-returning functions are not allowed in CASE peut s'afficher. Ce problème se produit, car à partir de la version 10, l'utilisation de fonctions renvoyant des ensembles dans les instructions CASE n'est pas autorisée.

Pour résoudre ce problème et mettre à niveau votre instance, assurez-vous que toutes les instructions CASE utilisant des fonctions de renvoi d'ensemble sont modifiées pour éviter leur utilisation avant de réessayer la mise à niveau. Voici quelques exemples de SRF couramment utilisés :

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

Vérifier les vues générées sur les diffusions personnalisées

Si vous avez créé une vue sur un cast personnalisé, un message d'erreur semblable à celui-ci s'affiche : ERROR: cannot cast type <type_1> to <type_2>. Ce problème se produit en raison de problèmes d'autorisation sur les diffusions créées sur mesure.

Pour résoudre ce problème, mettez à jour votre instance vers [PostgreSQL version].R20240910.01_02.

Pour en savoir plus, consultez Maintenance en libre-service.

Vérifier la propriété du déclencheur d'événement

Dans Cloud SQL, tous les déclencheurs d'événements doivent appartenir à un utilisateur disposant du rôle cloudsqlsuperuser. Cloud SQL effectue une vérification préalable à la mise à niveau pour valider la propriété de tous les déclencheurs d'événements. Si un déclencheur d'événement appartient à un utilisateur qui ne dispose pas du rôle cloudsqlsuperuser, le processus de mise à niveau est interrompu et un message d'erreur peut s'afficher, par exemple :

Please ensure that the owners of all event triggers have the cloudsqlsuperuser
role assigned to them before attempting an upgrade:
(database: your_db, triggerName your_trigger, owner: non_super_user)

Pour résoudre ce problème, modifiez le propriétaire du déclencheur d'événement et attribuez-le à un utilisateur disposant du rôle cloudsqlsuperuser, tel que postgres, ou accordez le rôle cloudsqlsuperuser au propriétaire actuel.

Pour identifier les déclencheurs d'événements dont les propriétaires ne disposent pas du rôle requis, exécutez la commande suivante :

SELECT
  t.evtname AS trigger_name,
  r.rolname AS current_owner
FROM pg_event_trigger t
JOIN pg_roles r ON t.evtowner = r.oid
WHERE NOT pg_has_role(r.rolname, 'cloudsqlsuperuser', 'member');

Les résultats affichent tous les déclencheurs d'événements dont le propriétaire ne dispose pas du rôle cloudsqlsuperuser.

Vérifier les colonnes générées à partir de tables non consignées

Si vous disposez d'une table non consignée comportant des colonnes générées, le message d'erreur ERROR: unexpected request for new relfilenumber in binary upgrade mode peut s'afficher. Ce problème se produit en raison d'écarts dans les caractéristiques de persistance entre les tables et leurs séquences pour les colonnes générées.

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

  1. Supprimez les tables non consignées : si possible, supprimez toutes les tables non consignées associées aux colonnes générées. Avant de continuer, assurez-vous que la perte de données peut être atténuée de manière sûre.
  2. Convertir en tables permanentes : convertissez temporairement les tables non enregistrées en tables permanentes en procédant comme suit :
    1. Convertir le tableau en tableau consigné ALTER TABLE SET LOGGED;
    2. Effectuer une mise à niveau de version majeure
    3. Reconvertir la table en table non journalisée ALTER TABLE SET UNLOGGED

Vous pouvez identifier toutes ces tables à l'aide de la requête suivante :

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;

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, 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.

Opération MVU en cours depuis plus longtemps

La mise à niveau d'une version majeure implique deux tâches sous-jacentes :

  • Opération de pré-vérification : renvoie une erreur de délai avant expiration si elle n'est pas terminée dans les trois heures.
  • Opération de mise à niveau : renvoie une erreur de délai avant expiration si elle n'est pas terminée dans les six heures.

Si l'instance a une opération MAJOR_VERSION_UPGRADE en cours depuis plus longtemps que prévu, examinez les journaux d'erreurs PostgreSQL. Cela peut être dû à des problèmes courants tels que :

  • Un grand nombre de tables, de vues ou d'index
  • Ressources insuffisantes (processeur ou mémoire, par exemple)
  • Transactions majeures bloquant l'arrêt des bases de données pour que le processus de mise à niveau puisse commencer. Vous pouvez utiliser la console Google Cloud pour vérifier les processus en cours.

Erreurs courantes lors de la vérification préalable de la mise à niveau de version majeure

Les problèmes détectés par la vérification préalable à la mise à niveau de version majeure appartiennent aux catégories suivantes :

  • Extensions incompatibles : il s'agit d'extensions Cloud SQL pour PostgreSQL sur votre instance qui ne fonctionnent pas avec la nouvelle version majeure.

  • Dépendances non compatibles : il s'agit de dépendances qui ne sont pas compatibles avec la nouvelle version majeure ou qui doivent être mises à jour pour fonctionner avec celle-ci.

  • Incompatibilités de base de données : il s'agit de problèmes liés à votre base de données ou à vos données qui peuvent survenir après une mise à niveau vers une version majeure. Cela inclut les différences au niveau des structures de base de données, des types de données, de l'encodage, du classement ou des modifications du catalogue système spécifiques à la nouvelle version.

Extensions incompatibles

Le tableau suivant liste les erreurs courantes liées aux extensions incompatibles que la vérification préalable à la mise à niveau de la version majeure peut détecter :

Type Exemple d'erreur Solution
Extension non compatible ou obsolète Your installation contains unsupported extensions for the new version. These extensions must be removed before attempting an upgrade: (database: %s, Extension name: %s) Supprimez l'extension de toutes les bases de données qui l'utilisent avec DROP EXTENSION $extension_name;.
Version d'extension incompatible Your installation contains incompatible version extensions. These extensions must be upgraded to a compatible version before attempting an upgrade: (database: %s, Extension name: %s) Mettez à jour l'extension vers une version compatible avec votre version cible de Cloud SQL pour PostgreSQL. Pour connaître les versions compatibles, consultez Configurer des extensions Cloud SQL pour PostgreSQL.
PostGIS fichiers non empaquetés PostGIS version upgrade has not been completed, unpackaged raster files present. Follow the steps at https://postgis.net/documentation/tips/tip-removing-raster-from-2-3/ to fix before major version upgrade. Nettoyez les fichiers raster non compressés.
PostGIS fonctions obsolètes PostGIS version upgrade has not been completed, deprecated functions present. Please drop all objects using deprecated functions and upgrade to a different version of PostGIS before major version upgrade. Recherchez et supprimez ou modifiez tous les objets de base de données qui utilisent des fonctions PostGIS obsolètes avant de mettre à niveau l'extension PostGIS.
Propriété des extensions Please ensure that the owner of the postgres_fdw extension has the cloudsqlsuperuser role assigned to them before attempting an upgrade: (database: my_db, extension name: postgres_fdw, owner: some_user) Modifiez le propriétaire de l'extension à l'aide de ALTER EXTENSION postgres_fdw OWNER TO postgres;.

Dépendances non compatibles

Le tableau suivant répertorie les erreurs courantes liées aux dépendances non compatibles que la vérification préalable à la mise à niveau de la version majeure peut détecter :

Type Exemple d'erreur Solution
Propriété du déclencheur d'événement Please ensure that the owners of all event triggers have the cloudsqlsuperuser role assigned to them before attempting an upgrade: (database: your_db, triggerName your_trigger, owner: non_super_user) Connectez-vous à la base de données identifiée à l'aide de psql ou de Cloud SQL Studio, puis remplacez le propriétaire du déclencheur par un utilisateur postgres.
Instructions préparées non validées Please commit/rollback the following usages of 'Uncommitted Prepared Statements'... (database: my_db, gid: my_prepared_xact) Validez ou annulez l'instruction préparée.
Options obsolètes flag "force_parallel_mode" is deprecated in new postgres version, Please delete this flag before retrying again Supprimez l'option de base de données de la configuration de l'instance.

Incompatibilités de base de données

Le tableau suivant répertorie les erreurs courantes liées aux incompatibilités de format de données que le contrôle préalable à la mise à niveau de la version majeure peut détecter :

Type Exemple d'erreur Solution
Type de données inconnu Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) Supprimez la colonne ou la table, ou modifiez le type de données de la table à l'aide de ALTER TABLE my_table ALTER COLUMN my_column TYPE TEXT;.
Type de données reg* Please remove the following usages of 'reg*' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) Supprimez la colonne ou modifiez son type de données.
Type de données supprimé Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: ... Convertissez-le en TEXT, timestamptz ou un autre type de données approprié.
Format interne ​​aclitem Please remove the following usages of 'aclitem' data types before attempting an upgrade: ... Arrêtez d'utiliser aclitem dans les définitions de table de votre base de données.
Types de données composites définis par le système Please remove the following usages of 'composite' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) Modifiez les colonnes identifiées pour qu'elles utilisent un type composite défini par l'utilisateur ou un type de données standard. Les types composites système peuvent ne pas être cohérents entre les versions majeures.
Tableaux avec OIDS Please remove the following usages of tables with OIDs before attempting an upgrade: (database: my_db, relation: my_table) Mettez à jour la table à l'aide de ALTER TABLE my_table SET WITHOUT OIDS;.
Opérateurs postfix définis par l'utilisateur Please remove the following usages of 'postfix operators' before attempting an upgrade: (database: my_db, operation id: 12345, operation namespace: public, operation name: !!, type namespace: public, type name: mytype) Supprimez les opérateurs postfix personnalisés. Vous devrez peut-être réécrire votre code pour utiliser des opérateurs de préfixe ou des appels de fonction à la place.
Fonctions polymorphes incompatibles Please remove the following usages of 'incompatible polymorphic' functions before attempting an upgrade: (database: my_db, object kind: function, object name: public.my_poly_func) Supprimez ou modifiez la fonction pour supprimer les fonctions polymorphes incompatibles. Cela peut impliquer d'ajuster les signatures ou la logique des fonctions pour qu'elles fonctionnent avec Cloud SQL pour PostgreSQL 14 et versions ultérieures.
Conversions d'encodage définies par l'utilisateur Please remove the following usages of user-defined encoding conversions before attempting an upgrade: (database: my_db, namespace name: public, encoding conversions name: my_encoding_conv) Supprimez la conversion d'encodage définie par l'utilisateur. Vous devrez peut-être le recréer après la mise à niveau avec une signature compatible avec la nouvelle version.
Vérifier si une référence de colonne est ambiguë Cloud SQL recherche automatiquement les vues définies par l'utilisateur qui s'appuient sur des vues du catalogue système. La structure des colonnes de ces vues de catalogue système peut changer entre les versions majeures.

Please remove the following usages of views that depend on functions returning data types of pg_stat_activity before attempting an upgrade: (database: my_db, schema name: public, view name: my_stat_activity_view) 		Recherchez les vues listées dans le message d'erreur et supprimez-les à l'aide de la commande DROP VIEW. Après la mise à niveau, recréez les vues.
Tables non consignées avec des colonnes générées ou des séquences consignées Please drop the following usages of 'Unlogged Tables with Logged Sequence' before attempting an upgrade: (database: your_db, table name: problematic_table) Vous pouvez convertir la table en LOGGED ou la supprimer à l'aide de la commande DROP TABLE. Recréez la table après la mise à niveau.
Résoudre le problème de chemin de recherche vide Please update the search path of the 'll_to_earth' function (database: your_db, search path: ) L'extension earthdistance utilise earth et cube types sans spécifier le chemin de recherche de la fonction. Mettez à jour le chemin de recherche à l'aide de ALTER FUNCTION ll_to_earth SET search_path = public;.

Restaurer la version majeure précédente de l'instance principale

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 votre instance principale. 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 une instance principale vers 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 utilisez des instances répliqué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 totale de mise à niveau correspond au nombre d'objets dans vos bases de données. Si vous devez mettre à niveau plusieurs instances, le temps de mise à niveau augmente proportionnellement. Si vous incluez des instances répliquées dans votre mise à niveau, l'opération peut prendre jusqu'à une heure, selon le nombre d'instances répliquées de votre instance principale.

Puis-je surveiller chaque étape de mon processus de mise à niveau ?
Bien que Cloud SQL vous permette 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