Crea e gestisci gli indici delle repliche di lettura

Questo documento descrive come creare, gestire e monitorare gli indici secondari nelle repliche di lettura di Cloud SQL.

Per informazioni concettuali sul funzionamento degli indici delle repliche gestite, consulta Panoramica degli indici delle repliche di lettura.

Indici delle repliche gestite

La tabella seguente riassume il flusso di lavoro per la creazione, la configurazione e il monitoraggio degli indici di replica gestiti:

Passaggio Stored procedure o flag di database Dove eseguire il passaggio
Crea definizione dell'indice CALL mysql.cloudsql_replica_idx_defn_create('INDEX_DEFINITION_NAME', 'CREATE_INDEX_STATEMENT');

Questa stored procedure restituisce un identificatore intero univoco per la definizione dell'indice, INDEX_DEFINITION_ID.

 Istanza principale
Mappa la definizione al gruppo CALL mysql.cloudsql_replica_idx_group_add(INDEX_DEFINITION_ID, 'GROUP_NAME');

GROUP_NAME è un nome personalizzato che puoi selezionare. Se il gruppo non esiste, Cloud SQL ne crea uno nuovo.

 Istanza principale
Assegna gruppo alla replica Flag di database: cloudsql_index_recreate_replica_group = GROUP_NAME Istanza replica di lettura
Verifica lo stato CALL mysql.cloudsql_replica_idx_show_status(); Istanza replica di lettura
Errori di controllo CALL mysql.cloudsql_replica_idx_show_errors(); Istanza replica di lettura

Ogni chiamata alla stored procedure esegue un'istruzione COMMIT che finalizza le modifiche nella sessione corrente. Di conseguenza, non è possibile eseguire il rollback delle istruzioni DML (Data Manipulation Language) eseguite utilizzando queste stored procedure all'interno di una transazione.

Cloud SQL non supporta l'aggiornamento o la modifica dei metadati dell'indice esistenti. Per modificare un indice di replica gestita, devi eliminare la definizione dell'indice esistente (o rimuoverla dal gruppo di replica) e creare una nuova definizione dell'indice. Per saperne di più, consulta Modifica gli indici delle repliche gestite.

Ruolo e privilegi richiesti

Per eseguire le stored procedure per gli indici delle repliche gestite, devi utilizzare un account utente del database a cui è assegnato il ruolo cloudsqlsuperuser.

Crea indici di replica gestiti

Per creare e gestire gli indici delle repliche gestite sulle repliche di lettura, segui questi passaggi:

  1. Crea una definizione di indice nell'istanza principale:

    Chiama la stored procedure mysql.cloudsql_replica_idx_defn_create nell'istanza principale del database:

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

    Sostituisci quanto segue:

    • INDEX_DEFINITION_NAME: il nome della definizione dell'indice.
    • CREATE_INDEX_STATEMENT: l'istruzione SQL che crea l'indice secondario (ad esempio CREATE INDEX idx_age ON university.students (age)). Tieni presente che questa istruzione deve avere il prefisso dello schema.

    Prendi nota del valore idx_id restituito (un identificatore intero univoco per la definizione) dall'output della procedura. Cloud SQL archivia questi dati in mysql.cloudsql_replica_idx_defn e puoi recuperare idx_id in un secondo momento eseguendo una query su questa tabella.

  2. Aggiungi la definizione dell'indice a un gruppo di repliche:

    Mappa la definizione dell'indice a un nome del gruppo di repliche designato chiamando mysql.cloudsql_replica_idx_group_add nell'istanza principale:

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

    Sostituisci quanto segue:

    • INDEX_DEFINITION_ID: l'ID intero univoco restituito quando hai eseguito la stored procedure mysql.cloudsql_replica_idx_defn_create per creare l'indice secondario.
    • GROUP_NAME: il nome della mappatura del gruppo di repliche (ad esempio, reporting_group). GROUP_NAME è un nome personalizzato che puoi selezionare. Se il gruppo non esiste, Cloud SQL ne crea uno nuovo.

    Cloud SQL archivia questi dati in mysql.cloudsql_replica_idx_group_map e puoi recuperare le mappature dei gruppi in un secondo momento eseguendo una query su questa tabella.

  3. Assegna il gruppo all'istanza di replica:

    Attiva il gruppo designato nella replica di lettura impostando il flag di database cloudsql_index_recreate_replica_group sul nome del gruppo (ad esempio, reporting_group).

  4. Verifica l'avanzamento del ripristino:

    Connettiti all'istanza di replica di lettura e controlla l'avanzamento della creazione e lo stato degli indici.

    • Controlla l'avanzamento della creazione dell'indice in corso:

      CALL mysql.cloudsql_replica_idx_show_status();

    • Controlla i tentativi non riusciti e i messaggi di errore:

      CALL mysql.cloudsql_replica_idx_show_errors();

    • Elenca lo stato, i dettagli dei nuovi tentativi e le durate di tutti gli indici gestiti:

      CALL mysql.cloudsql_replica_idx_show_all();

Controlla lo stato dell'indice della replica gestita

Per controllare lo stato di attività dell'operazione di indicizzazione, connettiti all'istanza di replica di lettura ed esegui una query sulla tabella mysql.cloudsql_replica_idx_status:

SELECT * FROM mysql.cloudsql_replica_idx_status;

L'output è simile al seguente:

+--------+----------------------------------------------------+--------+-----------+---------------------+---------------------+-------------+---------+--------------------+---------+
| 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 esegue la manutenzione degli indici delle repliche gestite in batch. Quando Cloud SQL rileva un gruppo di azioni CREATE o DROP, crea una voce di stato PENDING per ogni indice, quindi esegue in serie ogni istruzione del linguaggio di definizione dei dati (DDL). Un errore in un indice non blocca l'esecuzione degli indici successivi nella coda. Cloud SQL preleva quindi il batch successivo dopo circa cinque minuti.

Se la creazione di un indice non va a buon fine, Cloud SQL contrassegna lo stato come FAILED e riprova automaticamente l'operazione dopo un'ora.

La tabella mysql.cloudsql_replica_idx_status contiene tutte le voci relative allo stato delle operazioni di indicizzazione e include le seguenti colonne:

  • idx_id: l'identificatore univoco di tipo numero intero per la definizione dell'indice.
  • create_stmt: l'istruzione SQL CREATE INDEX.
  • action: l'operazione in esecuzione (CREATE o DROP).
  • thread_id: l'ID thread MySQL che esegue l'operazione.
  • start_time: il timestamp dell'inizio dell'operazione.
  • end_time: il timestamp del completamento dell'operazione.
  • retry_count: il numero di tentativi di ripetizione dell'operazione. Cloud SQL riprova a creare gli indici non riusciti dopo un'ora.
  • err_msg: il messaggio di errore dell'ultima operazione non riuscita.
  • comment_tag: il tag [SIC_X_Y] aggiunto prima del commento dell'indice. Questo tag viene utilizzato esclusivamente per la gestione interna e non ha alcuna funzionalità.
  • status: lo stato attuale dell'operazione:
    • PENDING: l'operazione di indicizzazione è stata aggiunta alla coda.
    • RUNNING: l'esecuzione dell'operazione di indicizzazione è iniziata.
    • DONE: l'operazione di indicizzazione è stata completata correttamente.
    • FAILED: l'operazione di indicizzazione non è riuscita. Cloud SQL riprova a creare gli indici non riusciti dopo un'ora.

Elimina gli indici delle repliche gestite

Per rimuovere un indice da un gruppo di repliche o eliminare completamente una definizione di indice, chiama la stored procedure corrispondente nell'istanza principale:

  • Rimuovi una definizione di indice da un gruppo di repliche:

    Chiama mysql.cloudsql_replica_idx_group_drop sull'istanza principale:

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

    Sostituisci quanto segue:

    • INDEX_DEFINITION_ID: l'ID intero univoco restituito quando hai creato la definizione dell'indice secondario.
    • GROUP_NAME: il nome della mappatura del gruppo di repliche (ad esempio reporting_group).

  • Elimina una definizione di indice:

    Chiama mysql.cloudsql_replica_idx_defn_drop sull'istanza principale:

    CALL mysql.cloudsql_replica_idx_defn_drop
(INDEX_DEFINITION_ID);

    Sostituisci quanto segue:

    • INDEX_DEFINITION_ID: l'ID intero univoco della definizione dell'indice da eliminare.

Per saperne di più sulle stored procedure, consulta Stored procedure per gli indici delle repliche gestite.

Modifica gli indici delle repliche gestite

Cloud SQL non supporta l'aggiornamento o la modifica dei metadati dell'indice esistenti. Non puoi modificare direttamente una definizione di indice esistente o la relativa istruzione SQL.

Per modificare un indice di replica gestita (ad esempio, per cambiare le colonne indicizzate o le opzioni di indice), devi rimuovere o eliminare la definizione dell'indice esistente, quindi crearne una nuova.

Per modificare un indice di replica gestita, segui questi passaggi:

  1. Rimuovi o elimina la definizione dell'indice esistente nell'istanza principale:

    • Per rimuovere la definizione dell'indice da un gruppo di repliche, chiama mysql.cloudsql_replica_idx_group_drop:

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

    • Per eliminare completamente la definizione dell'indice, chiama mysql.cloudsql_replica_idx_defn_drop:

      CALL mysql.cloudsql_replica_idx_defn_drop
(INDEX_DEFINITION_ID);

    Sostituisci quanto segue:

    • INDEX_DEFINITION_ID: l'ID intero univoco della definizione dell'indice da rimuovere o eliminare.
    • GROUP_NAME: il nome della mappatura del gruppo di repliche (ad esempio reporting_group).

  2. Crea una nuova definizione di indice nell'istanza principale:

    Chiama mysql.cloudsql_replica_idx_defn_create con l'istruzione di indice aggiornata:

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

    Sostituisci quanto segue:

    • INDEX_DEFINITION_NAME: il nome della nuova definizione dell'indice.
    • CREATE_INDEX_STATEMENT: l'istruzione SQL aggiornata che crea l'indice secondario (ad esempio CREATE INDEX idx_age ON university.students (age, name)).

    Prendi nota del nuovo idx_id restituito nell'output della stored procedure.

  3. Mappa la nuova definizione dell'indice al gruppo di replica:

    Chiama mysql.cloudsql_replica_idx_group_add sull'istanza principale:

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

    Sostituisci quanto segue:

    • INDEX_DEFINITION_ID: il nuovo ID intero univoco restituito nel passaggio 2.
    • GROUP_NAME: il nome della mappatura del gruppo di repliche (ad esempio reporting_group).

Dopo aver mappato la nuova definizione dell'indice al gruppo di repliche, il processo di manutenzione in background elimina l'indice esistente dalla replica di lettura e crea il nuovo indice sulla replica utilizzando la definizione aggiornata.

Flag di configurazione del database per gli indici delle repliche gestite

Puoi personalizzare il comportamento dell'indice delle repliche gestite in modo dinamico utilizzando i seguenti flag di database globali:

  • cloudsql_index_recreate_enable: attiva o disattiva il processo di ricreazione. Per impostazione predefinita, il flag è impostato su on. Se imposti il flag su off, le operazioni di manutenzione dell'indice in corso vengono terminate immediatamente.

  • cloudsql_index_recreate_replica_group: nome del gruppo di repliche designato per la replica (il valore predefinito è NULL). Una replica può essere assegnata a un solo gruppo di repliche alla volta. Le repliche creano tutti gli indici mappati a questo nome del gruppo di repliche.

Indici di replica autogestiti

Cloud SQL include due stored procedure nello schema mysql che puoi utilizzare per aggiungere ed eliminare indici secondari in una replica di lettura MySQL. Tieni presente che, sebbene queste stored procedure possano essere eseguite su un'istanza di origine principale, sono progettate per le repliche di lettura.

Questi indici non vengono mantenuti se la replica viene ricreata.

mysql.addSecondaryIdxOnReplica
Aggiunge un indice secondario al database. Questa stored procedure è un wrapper per l'istruzione DDL CREATE INDEX.

Parametri:

  • idxType: il tipo di indice da creare. Ad esempio, passa UNIQUE per creare un indice univoco.
  • idxName: il nome dell'indice.
  • tableName: il nome della tabella nel formato schema.name.
  • idxDefinition: la definizione dell'indice. Non includere le parentesi esterne.
  • idxOption: eventuali opzioni aggiuntive da passare alla creazione dell'indice. Ad esempio, in MySQL 8.0, puoi passare l'opzione INVISIBLE per un indice invisibile.

Sintassi:

mysql.addSecondaryIdxOnReplica(idxType, idxName, tableName, idxDefinition, idxOption)
mysql.dropSecondaryIdxOnReplica
Elimina un indice secondario nel database. Questa stored procedure è un wrapper per l'istruzione DDL DROP INDEX.

Parametri:

  • idxName: il nome dell'indice.
  • tableName: il nome della tabella nel formato schema.name.
  • idxOption: eventuali opzioni aggiuntive da passare quando si elimina un indice. Ad esempio, un'opzione di algoritmo come INPLACE.

Sintassi:

mysql.dropSecondaryIdxOnReplica(idxName, tableName, idxOption)

Per i parametri idxType e idxOption, consulta la documentazione della versione principale di MySQL in esecuzione sull'istanza Cloud SQL.

Esempi

Questa sezione fornisce esempi di come aggiungere o eliminare correttamente o in modo errato gli indici delle repliche autogestite.

Utilizzo corretto

Ecco alcuni esempi di chiamate delle procedure. Supponiamo di avere una tabella con la seguente definizione:

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

Se vuoi creare un indice regolare denominato t1_fname_lname sulle colonne first_name e last_name, esegui la seguente istruzione:

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

Se vuoi anche creare un indice univoco denominato t1_license_id nella colonna license_id con il commento "ID licenza univoco", esegui la seguente istruzione:

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

Se vuoi eliminare l'indice t1_fname_lname, esegui la seguente istruzione:

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

Utilizzo non corretto

Il seguente tentativo di creare un indice sulle colonne first_name e last_name non va a buon fine a causa delle parentesi esterne nel parametro idxDefinition:

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

Puoi aggiungere indici solo alle tabelle create dai clienti. Il seguente tentativo di creare un indice sulla colonna host della tabella mysql.servers non va a buon fine:

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

Puoi utilizzare la procedura dropSecondaryIdxOnReplica solo per eliminare gli indici creati in precedenza utilizzando la procedura addSecondaryIdxOnReplica. Ad esempio, la seguente chiamata per eliminare l'indice idx_fname esistente non va a buon fine:

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

La SQL injection in queste chiamate di procedura non va a buon fine. Ad esempio, la seguente SQL injection con una sequenza di commenti non va a buon fine:

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

Analogamente, questo tentativo di SQL injection con un delimitatore non va a buon fine:

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

Esegui la migrazione dagli indici di replica autogestiti a quelli gestiti

Sebbene gli indici di replica gestiti e quelli autogestiti possano coesistere nella stessa istanza, puoi eseguire la migrazione agli indici di replica gestiti.

Per eseguire la migrazione dagli indici di replica autogestiti a quelli gestiti, segui questi passaggi:

  1. Registra le definizioni degli indici nell'istanza principale:

    Chiama mysql.cloudsql_replica_idx_defn_create nell'istanza principale per ogni indice secondario:

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

    Prendi nota del valore idx_id restituito (un identificatore intero univoco per la definizione) dall'output della procedura.

  2. Aggiungi la definizione dell'indice a un gruppo di repliche:

    Mappa la definizione dell'indice a un nome del gruppo di repliche designato chiamando mysql.cloudsql_replica_idx_group_add nell'istanza principale:

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

  3. Configura il flag del gruppo di repliche sulla replica di lettura:

    Imposta il flag di database cloudsql_index_recreate_replica_group sull'istanza di replica di lettura in modo che abbia come target il nome del gruppo:

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

    Assicurati che il nome del gruppo fornito nel flag di database cloudsql_index_recreate_replica_group corrisponda esattamente al nome del gruppo specificato in mysql.cloudsql_replica_idx_group_add.

  4. Verifica o esegui la transizione degli indici esistenti:

    Poiché l'indice esiste già nella replica di lettura, potresti visualizzare errori con uno stato FAILED in mysql.cloudsql_replica_idx_status quando il processo in background tenta di creare l'indice. Puoi scegliere uno dei seguenti approcci:

    • Attendi la ricreazione della replica: puoi ignorare lo stato FAILED nella tabella degli stati. Cloud SQL ricrea automaticamente l'indice secondario utilizzando il metodo dell'indice della replica gestita dopo un evento di ricreazione della replica.

    • Transizione immediata: se vuoi che Cloud SQL gestisca l'indice immediatamente senza attendere la nuova creazione della replica, connettiti alla replica di lettura e rimuovi l'indice autogestito utilizzando la stored procedure mysql.dropSecondaryIdxOnReplica:

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

      Durante il ciclo di manutenzione in background successivo (circa ogni cinque minuti), Cloud SQL ricrea e monitora automaticamente l'indice della replica gestita.

Risolvi i problemi relativi agli indici di replica

Per risolvere i problemi relativi agli indici di replica, verifica quanto segue:

  • Verifica che gli indici delle repliche gestite siano abilitati per l'istanza di replica:

    Se utilizzi indici di replica gestiti, assicurati che il flag di database cloudsql_index_recreate_enable sia impostato su on nella replica di lettura.

    Per saperne di più sulla configurazione dei flag di database, consulta Configura i flag di database.

  • Controlla lo stato di attività e gli errori:

    Connettiti alla replica di lettura ed esegui una query su mysql.cloudsql_replica_idx_status o esegui CALL mysql.cloudsql_replica_idx_show_errors(); per visualizzare i messaggi di errore per eventuali operazioni non riuscite. Un errore in un indice non blocca l'esecuzione degli indici successivi nella coda.

Passaggi successivi