Créer et gérer des index d'instances dupliquées avec accès en lecture

Ce document explique comment créer, gérer et surveiller des index secondaires sur des instances dupliquées avec accès en lecture Cloud SQL.

Pour en savoir plus sur le fonctionnement des index d'instances dupliquées gérées, consultez Présentation des index d'instances dupliquées avec accès en lecture.

Index d'instances répliquées gérés

Le tableau suivant récapitule le workflow de création, de configuration et de surveillance des index d'instances répliquées gérées :

Étape Procédure stockée ou indicateur de base de données Où effectuer l'étape
Créer une définition d'index CALL mysql.cloudsql_replica_idx_defn_create('INDEX_DEFINITION_NAME', 'CREATE_INDEX_STATEMENT');

Cette procédure stockée renvoie un identifiant entier unique pour la définition d'index, INDEX_DEFINITION_ID.

 Instance principale
Mapper la définition au groupe CALL mysql.cloudsql_replica_idx_group_add(INDEX_DEFINITION_ID, 'GROUP_NAME');

GROUP_NAME est un nom personnalisé que vous pouvez sélectionner. Si ce groupe n'existe pas, Cloud SQL en crée un.

 Instance principale
Attribuer un groupe à l'instance répliquée Indicateur de base de données : cloudsql_index_recreate_replica_group = GROUP_NAME Instance répliquée avec accès en lecture
Vérifier l'état CALL mysql.cloudsql_replica_idx_show_status(); Instance répliquée avec accès en lecture
Erreurs d'audit CALL mysql.cloudsql_replica_idx_show_errors(); Instance répliquée avec accès en lecture

Chaque appel de procédure stockée exécute une instruction COMMIT qui finalise les modifications de votre session en cours. Par conséquent, les instructions de langage de manipulation de données (LMD) exécutées à l'aide de ces procédures stockées ne peuvent pas être annulées dans une transaction.

Cloud SQL ne permet pas de mettre à jour ni de modifier les métadonnées d'index existantes. Pour modifier un index d'instance répliquée géré, vous devez supprimer la définition d'index existante (ou la supprimer du groupe d'instances répliquées) et créer une définition d'index. Pour en savoir plus, consultez Modifier les index d'instances répliquées gérées.

Rôle et droits requis

Vous devez utiliser un compte utilisateur de base de données auquel est attribué le rôle cloudsqlsuperuser pour exécuter des procédures stockées pour les index d'instances répliquées gérées.

Créer des index d'instances répliquées gérées

Pour créer et gérer des index d'instances dupliquées gérées sur vos instances dupliquées avec accès en lecture, procédez comme suit :

  1. Créez une définition d'index sur l'instance principale :

    Appelez la procédure stockée mysql.cloudsql_replica_idx_defn_create sur l'instance principale de votre base de données :

    CALL mysql.cloudsql_replica_idx_defn_create
('INDEX_DEFINITION_NAME', 'CREATE_INDEX_STATEMENT');

    Remplacez les éléments suivants :

    • INDEX_DEFINITION_NAME : nom de la définition d'index.
    • CREATE_INDEX_STATEMENT : instruction SQL qui crée l'index secondaire (par exemple, CREATE INDEX idx_age ON university.students (age)). Notez que cette instruction doit être précédée d'un schéma.

    Notez l'élément idx_id renvoyé (un identifiant entier unique pour la définition) à partir du résultat de la procédure. Cloud SQL stocke ces données dans mysql.cloudsql_replica_idx_defn, et vous pouvez récupérer l'idx_id ultérieurement en interrogeant cette table.

  2. Ajoutez la définition d'index à un groupe d'instances dupliquées :

    Mappez la définition d'index à un nom de groupe d'instances répliquées désigné en appelant mysql.cloudsql_replica_idx_group_add sur l'instance principale :

    CALL mysql.cloudsql_replica_idx_group_add
(INDEX_DEFINITION_ID, 'GROUP_NAME');

    Remplacez les éléments suivants :

    • INDEX_DEFINITION_ID : ID entier unique renvoyé lorsque vous avez exécuté la procédure stockée mysql.cloudsql_replica_idx_defn_create pour créer l'index secondaire.
    • GROUP_NAME : nom du mappage du groupe d'instances répliquées (par exemple, reporting_group). GROUP_NAME est un nom personnalisé que vous pouvez sélectionner. Si ce groupe n'existe pas, Cloud SQL en crée un.

    Cloud SQL stocke ces données dans mysql.cloudsql_replica_idx_group_map, et vous pouvez récupérer les mappages de groupes ultérieurement en interrogeant cette table.

  3. Attribuez le groupe à votre instance dupliquée :

    Activez le groupe désigné sur votre instance dupliquée avec accès en lecture en définissant l'option de base de données cloudsql_index_recreate_replica_group sur le nom de votre groupe (par exemple, reporting_group).

  4. Vérifiez la progression de la restauration :

    Connectez-vous à votre instance dupliquée avec accès en lecture, puis vérifiez la progression de la création et l'état de vos index.

    • Vérifiez la progression de la création de l'index en cours :

      CALL mysql.cloudsql_replica_idx_show_status();

    • Vérifiez les tentatives ayant échoué et les messages d'erreur :

      CALL mysql.cloudsql_replica_idx_show_errors();

    • Répertoriez l'état, les détails des nouvelles tentatives et les durées de tous les index gérés :

      CALL mysql.cloudsql_replica_idx_show_all();

Vérifier l'état de l'index de l'instance répliquée gérée

Pour vérifier l'état de l'opération d'indexation, connectez-vous à votre instance répliquée avec accès en lecture et interrogez la table mysql.cloudsql_replica_idx_status :

SELECT * FROM mysql.cloudsql_replica_idx_status;

Le résultat ressemble à ce qui suit :

+--------+----------------------------------------------------+--------+-----------+---------------------+---------------------+-------------+---------+--------------------+---------+
| idx_id | create_stmt                                        | action | thread_id | start_time          | end_time            | retry_count | err_msg | comment_tag        | status  |
+--------+----------------------------------------------------+--------+-----------+---------------------+---------------------+-------------+---------+--------------------+---------+
|      2 | CREATE INDEX t1_fname ON sampletest.t1(first_name) | CREATE |      8140 | 2026-08-26 10:52:13 | NULL                |           0 | NULL    | [SIC_4_1787741231] | RUNNING |
|      4 | CREATE INDEX t2_lname ON sampletest.t2(last_name)  | DROP   |      NULL | 2026-08-26 10:52:13 | 2026-08-26 10:53:15 |           0 | NULL    | [SIC_4_1787741533] | DONE    |
|      5 | CREATE INDEX t1_lname ON sampletest.t1(last_name)  | CREATE |      8142 | 2026-08-26 10:53:14 | NULL                |           0 | NULL    | [SIC_5_1787741594] | RUNNING |
+--------+----------------------------------------------------+--------+-----------+---------------------+---------------------+-------------+---------+--------------------+---------+

Cloud SQL effectue la maintenance des index des instances répliquées gérées par lots. Lorsque Cloud SQL récupère un groupe d'actions CREATE ou DROP, il crée une entrée d'état PENDING pour chaque index, puis exécute en série chaque instruction de langage de définition de données (LDD). Un échec sur un index ne bloque pas l'exécution des index suivants dans la file d'attente. Cloud SQL récupère ensuite le lot suivant après environ cinq minutes.

Si la création d'un index échoue, Cloud SQL marque l'état comme FAILED et relance automatiquement l'opération au bout d'une heure.

La table mysql.cloudsql_replica_idx_status contient toutes les entrées d'état des opérations d'indexation et inclut les colonnes suivantes :

  • idx_id : identifiant entier unique de la définition d'index.
  • create_stmt : instruction SQL CREATE INDEX.
  • action : opération en cours d'exécution (CREATE ou DROP).
  • thread_id : ID du thread MySQL exécutant l'opération.
  • start_time : code temporel du début de l'opération.
  • end_time : code temporel de la fin de l'opération.
  • retry_count : nombre de nouvelles tentatives pour l'opération. Cloud SQL réessaie de créer les index ayant échoué après une heure.
  • err_msg : message d'erreur de la dernière opération ayant échoué.
  • comment_tag : tag [SIC_X_Y] ajouté au commentaire de l'index. Ce tag est utilisé uniquement pour la gestion interne et n'a aucune fonctionnalité.
  • status : état actuel de l'opération :
    • PENDING : l'opération d'indexation a été ajoutée à la file d'attente.
    • RUNNING : l'exécution de l'opération d'indexation a commencé.
    • DONE : l'opération d'indexation a bien été effectuée.
    • FAILED : l'opération d'indexation a échoué. Cloud SQL réessaie de créer les index ayant échoué après une heure.

Supprimer les index d'instances répliquées gérées

Pour supprimer un index d'un groupe d'instances répliquées ou supprimer entièrement une définition d'index, appelez la procédure stockée correspondante sur votre instance principale :

  • Supprimez une définition d'index d'un groupe d'instances répliquées :

    Appelez mysql.cloudsql_replica_idx_group_drop sur l'instance principale :

    CALL mysql.cloudsql_replica_idx_group_drop
(INDEX_DEFINITION_ID, 'GROUP_NAME');

    Remplacez les éléments suivants :

    • INDEX_DEFINITION_ID : ID entier unique renvoyé lorsque vous avez créé la définition de l'index secondaire.
    • GROUP_NAME : nom du mappage du groupe d'instances répliquées (par exemple, reporting_group).

  • Supprimer une définition d'index :

    Appelez mysql.cloudsql_replica_idx_defn_drop sur l'instance principale :

    CALL mysql.cloudsql_replica_idx_defn_drop
(INDEX_DEFINITION_ID);

    Remplacez les éléments suivants :

    • INDEX_DEFINITION_ID : ID entier unique de la définition d'index à supprimer.

Pour en savoir plus sur les procédures stockées, consultez Procédures stockées des index d'instances répliquées gérées.

Modifier les index d'instances répliquées gérées

Cloud SQL ne permet pas de mettre à jour ni de modifier les métadonnées d'index existantes. Vous ne pouvez pas modifier directement une définition d'index existante ni son instruction SQL.

Pour modifier un index d'instance répliquée gérée (par exemple, pour modifier des colonnes indexées ou des options d'index), vous devez supprimer la définition d'index existante, puis en créer une autre.

Pour modifier un index d'instance répliquée gérée, procédez comme suit :

  1. Supprimez la définition d'index existante sur l'instance principale :

    • Pour supprimer la définition d'index d'un groupe d'instances répliquées, appelez mysql.cloudsql_replica_idx_group_drop :

      CALL mysql.cloudsql_replica_idx_group_drop
(INDEX_DEFINITION_ID, 'GROUP_NAME');

    • Pour supprimer complètement la définition de l'index, appelez mysql.cloudsql_replica_idx_defn_drop :

      CALL mysql.cloudsql_replica_idx_defn_drop
(INDEX_DEFINITION_ID);

    Remplacez les éléments suivants :

    • INDEX_DEFINITION_ID : ID entier unique de la définition d'index à supprimer.
    • GROUP_NAME : nom du mappage du groupe d'instances répliquées (par exemple, reporting_group).

  2. Créez une définition d'index sur l'instance principale :

    Appelez mysql.cloudsql_replica_idx_defn_create avec l'instruction d'index mise à jour :

    CALL mysql.cloudsql_replica_idx_defn_create
('INDEX_DEFINITION_NAME', 'CREATE_INDEX_STATEMENT');

    Remplacez les éléments suivants :

    • INDEX_DEFINITION_NAME : nom de la nouvelle définition d'index.
    • CREATE_INDEX_STATEMENT : instruction SQL mise à jour qui crée l'index secondaire (par exemple, CREATE INDEX idx_age ON university.students (age, name)).

    Notez le nouveau idx_id renvoyé dans le résultat de la procédure stockée.

  3. Mappez la nouvelle définition d'index au groupe d'instances répliquées :

    Appelez mysql.cloudsql_replica_idx_group_add sur l'instance principale :

    CALL mysql.cloudsql_replica_idx_group_add
(INDEX_DEFINITION_ID, 'GROUP_NAME');

    Remplacez les éléments suivants :

    • INDEX_DEFINITION_ID : nouvel ID entier unique renvoyé à l'étape 2.
    • GROUP_NAME : nom du mappage du groupe d'instances répliquées (par exemple, reporting_group).

Une fois que vous avez mappé la nouvelle définition d'index au groupe d'instances dupliquées, le processus de maintenance en arrière-plan supprime l'index existant de l'instance dupliquée avec accès en lecture, puis crée le nouvel index sur l'instance dupliquée à l'aide de la définition mise à jour.

Options de configuration de base de données pour les index d'instances répliquées gérées

Vous pouvez personnaliser le comportement de l'index de l'instance répliquée gérée de manière dynamique à l'aide des indicateurs de base de données globaux suivants :

  • cloudsql_index_recreate_enable : active ou désactive le processus de recréation. Par défaut, l'option est définie sur on. Si vous définissez l'option sur off, les opérations de maintenance d'index en cours sont immédiatement arrêtées.

  • cloudsql_index_recreate_replica_group : nom du groupe d'instances répliquées désigné pour l'instance répliquée (la valeur par défaut est NULL). Une instance répliquée ne peut être attribuée qu'à un seul groupe d'instances répliquées à la fois. Les instances répliquées créent tous les index mappés à ce nom de groupe d'instances répliquées.

Index d'instances répliquées autogérés

Cloud SQL inclut deux procédures stockées dans le schéma mysql que vous pouvez utiliser pour ajouter et supprimer des index secondaires sur une instance dupliquée avec accès en lecture MySQL. Notez que, bien que ces procédures stockées puissent s'exécuter sur une instance source principale, elles sont conçues pour les instances répliquées avec accès en lecture.

Ces index ne persistent pas si l'instance répliquée est recréée.

mysql.addSecondaryIdxOnReplica
Ajoute un index secondaire sur la base de données. Cette procédure stockée est un wrapper pour l'instruction LDD CREATE INDEX.

Paramètres :

  • idxType : type d'index à créer. Par exemple, transmettez UNIQUE pour créer un index unique.
  • idxName : nom de l'index.
  • tableName : nom de la table au format schema.name.
  • idxDefinition : définition de l'index. N'incluez pas les parenthèses extérieures.
  • idxOption : toutes les options supplémentaires à transmettre lors de la création de l'index. Par exemple, dans MySQL 8.0, vous pouvez transmettre l'option INVISIBLE pour un index invisible.

Syntaxe :

mysql.addSecondaryIdxOnReplica(idxType, idxName, tableName, idxDefinition, idxOption)
mysql.dropSecondaryIdxOnReplica
Supprime un index secondaire sur la base de données. Cette procédure stockée est un wrapper pour l'instruction LDD DROP INDEX.

Paramètres :

  • idxName : nom de l'index.
  • tableName : nom de la table au format schema.name.
  • idxOption : toutes les options supplémentaires à transmettre lors de la suppression d'un index. Par exemple, une option d'algorithme telle que INPLACE.

Syntaxe :

mysql.dropSecondaryIdxOnReplica(idxName, tableName, idxOption)

Pour les paramètres idxType et idxOption, consultez la documentation de la version majeure de MySQL exécutée sur l'instance Cloud SQL.

Exemples

Cette section fournit des exemples d'ajout ou de suppression corrects ou incorrects d'index d'instances répliquées autogérées.

Utilisation correcte

Voici quelques exemples d'appels des procédures. Supposons que vous disposiez d'une table avec la définition suivante :

CREATE TABLE sampletest.t1(
   id int(10) unsigned NOT NULL AUTO_INCREMENT,
   first_name varchar(64) NOT NULL,
   last_name varchar(64) NOT NULL,
   license_id int NOT NULL,
   PRIMARY KEY (id),
   KEY idx_fname (first_name)
) ENGINE=InnoDB DEFAULT CHARSET=utf8

Si vous souhaitez créer un index standard nommé t1_fname_lname sur les colonnes first_name et last_name, exécutez l'instruction suivante :

CALL mysql.addSecondaryIdxOnReplica('', 't1_fname_lname', 'sampletest.t1', 'first_name, last_name', '')

Si vous souhaitez également créer un index unique nommé t1_license_id sur la colonne license_id avec le commentaire "ID de licence unique", exécutez l'instruction suivante :

CALL mysql.addSecondaryIdxOnReplica('unique', 't1_license_id', 'sampletest.t1', 'license_id', 'comment "unique license ID"')

Si vous souhaitez supprimer l'index t1_fname_lname, exécutez l'instruction suivante :

CALL mysql.dropSecondaryIdxOnReplica('t1_fname_lname', 'sampletest.t1', '')

Utilisation incorrecte

La tentative suivante de création d'un index sur les colonnes first_name et last_name échoue en raison des parenthèses extérieures du paramètre idxDefinition :

CALL mysql.addSecondaryIdxOnReplica('', 't1_extra_parenthesis', 'sampletest.t1', '(first_name, last_name)', '')

Vous ne pouvez ajouter des index qu'aux tables créées par le client. La tentative suivante de création d'un index sur la colonne host de la table mysql.servers échoue :

CALL mysql.addSecondaryIdxOnReplica('', 'idx_invalid', 'mysql.servers', 'host', '')

Vous ne pouvez utiliser la procédure dropSecondaryIdxOnReplica que pour supprimer des index précédemment créés à l'aide de la procédure addSecondaryIdxOnReplica. Par exemple, l'appel suivant pour supprimer l'index idx_fname existant échoue :

CALL mysql.dropSecondaryIdxOnReplica('idx_fname', 'sampletest.t1', '')

L'injection SQL dans ces appels de procédure échoue. Par exemple, l'injection SQL suivante avec une séquence de commentaires échoue :

CALL mysql.addSecondaryIdxOnReplica("user 'a'@'%' --", 'idx_fname', 'sampletest.t1', 'first_name', '')

De même, cette tentative d'injection SQL avec un délimiteur échoue :

CALL mysql.addSecondaryIdxOnReplica('', 'idx_fname', 'sampletest.t1', 'first_name', ';flush status')

Migrer des index d'instances répliquées autogérés vers des index d'instances répliquées gérés

Bien que les index d'instances répliquées gérés et autogérés puissent coexister sur la même instance, vous pouvez migrer vers des index d'instances répliquées gérés.

Pour migrer d'index d'instances répliquées autogérés vers des index d'instances répliquées gérés, procédez comme suit :

  1. Enregistrez les définitions d'index sur l'instance principale :

    Appelez mysql.cloudsql_replica_idx_defn_create sur votre instance principale pour chaque index secondaire :

    CALL mysql.cloudsql_replica_idx_defn_create
('INDEX_DEFINITION_NAME',
'CREATE INDEX INDEX_NAME ON DATABASE.TABLE (COLUMNS)');

    Notez l'élément idx_id renvoyé (un identifiant entier unique pour la définition) à partir du résultat de la procédure.

  2. Ajoutez la définition d'index à un groupe d'instances dupliquées :

    Mappez la définition d'index à un nom de groupe d'instances répliquées désigné en appelant mysql.cloudsql_replica_idx_group_add sur l'instance principale :

    CALL mysql.cloudsql_replica_idx_group_add
(INDEX_DEFINITION_ID, 'REPLICA_GROUP');

  3. Configurez l'option de groupe d'instances dupliquées sur l'instance dupliquée avec accès en lecture :

    Définissez l'indicateur de base de données cloudsql_index_recreate_replica_group sur votre instance d'instance répliquée avec accès en lecture pour cibler le nom du groupe :

    gcloud sql instances patch REPLICA_INSTANCE_NAME \
--database-flags=EXISTING_FLAGS,cloudsql_index_recreate_replica_group=REPLICA_GROUP

    Assurez-vous que le nom du groupe fourni dans l'indicateur de base de données cloudsql_index_recreate_replica_group correspond exactement au nom du groupe spécifié dans mysql.cloudsql_replica_idx_group_add.

  4. Vérifiez ou effectuez la transition des index existants :

    Étant donné que l'index existe déjà sur l'instance répliquée avec accès en lecture, des erreurs avec l'état FAILED peuvent s'afficher dans mysql.cloudsql_replica_idx_status lorsque le processus en arrière-plan tente de créer l'index. Vous pouvez choisir l'une des approches suivantes :

    • Attendez que l'instance répliquée soit recréée : vous pouvez ignorer l'état FAILED dans le tableau d'état. Cloud SQL recrée automatiquement l'index secondaire à l'aide de la méthode d'index d'instance répliquée gérée après un événement de recréation d'instance répliquée.

    • Transition immédiate : si vous souhaitez que Cloud SQL gère l'index immédiatement sans attendre la recréation de l'instance dupliquée, connectez-vous à l'instance dupliquée avec accès en lecture et supprimez l'index autogéré à l'aide de la procédure stockée mysql.dropSecondaryIdxOnReplica :

      CALL mysql.dropSecondaryIdxOnReplica('INDEX_NAME', 'DATABASE.TABLE', '');

      Lors du cycle de maintenance en arrière-plan suivant (environ toutes les cinq minutes), Cloud SQL recrée et suit automatiquement l'index de l'instance répliquée gérée.

Résoudre les problèmes liés aux index d'instances dupliquées

Pour résoudre les problèmes liés aux index d'instances répliquées, vérifiez les points suivants :

  • Vérifiez que les index d'instances répliquées gérées sont activés pour l'instance répliquée :

    Si vous utilisez des index d'instances répliquées gérées, assurez-vous que l'indicateur de base de données cloudsql_index_recreate_enable est défini sur on sur l'instance répliquée avec accès en lecture.

    Pour en savoir plus sur la configuration des indicateurs de base de données, consultez Configurer des indicateurs de base de données.

  • Vérifiez l'état de l'opération et les erreurs :

    Connectez-vous à l'instance répliquée avec accès en lecture et interrogez mysql.cloudsql_replica_idx_status ou exécutez CALL mysql.cloudsql_replica_idx_show_errors(); pour afficher les messages d'erreur des opérations ayant échoué. Un échec sur un index ne bloque pas l'exécution des index suivants dans la file d'attente.

Étapes suivantes