Lesereplikatindexe erstellen und verwalten

In diesem Dokument wird beschrieben, wie Sie sekundäre Indexe für Cloud SQL-Lesereplikate erstellen, verwalten und überwachen.

Konzeptionelle Informationen zur Funktionsweise von verwalteten Replikatindexen finden Sie unter Übersicht über Lesereplikatindexe.

Verwaltete Replikatindexe

In der folgenden Tabelle ist der Workflow zum Erstellen, Konfigurieren und Überwachen von verwalteten Replikatindexen zusammengefasst:

Schritt Gespeicherte Prozedur oder Datenbank-Flag Wo der Schritt ausgeführt werden soll
Indexdefinition erstellen CALL mysql.cloudsql_replica_idx_defn_create('INDEX_DEFINITION_NAME', 'CREATE_INDEX_STATEMENT');

Diese gespeicherte Prozedur gibt eine eindeutige Ganzzahl-ID für die Indexdefinition INDEX_DEFINITION_ID zurück.

 Primäre Instanz
Definition einer Gruppe zuordnen CALL mysql.cloudsql_replica_idx_group_add(INDEX_DEFINITION_ID, 'GROUP_NAME');

GROUP_NAME ist ein benutzerdefinierter Name, den Sie auswählen können. Wenn diese Gruppe nicht vorhanden ist, erstellt Cloud SQL eine neue.

 Primäre Instanz
Gruppe dem Replikat zuweisen Datenbank-Flag: cloudsql_index_recreate_replica_group = GROUP_NAME Lesereplikatinstanz
Status prüfen CALL mysql.cloudsql_replica_idx_show_status(); Lesereplikatinstanz
Prüfungsfehler CALL mysql.cloudsql_replica_idx_show_errors(); Lesereplikatinstanz

Bei jedem Aufruf einer gespeicherten Prozedur wird eine COMMIT-Anweisung ausgeführt, mit der die Änderungen in der aktuellen Sitzung abgeschlossen werden. Daher können DML-Anweisungen (Datenbearbeitungssprache), die mit diesen gespeicherten Prozeduren ausgeführt werden, nicht innerhalb einer Transaktion rückgängig gemacht werden.

Cloud SQL unterstützt nicht das Aktualisieren oder Ändern vorhandener Indexmetadaten. Wenn Sie einen verwalteten Replikatindex ändern möchten, müssen Sie die vorhandene Indexdefinition löschen (oder aus der Replikatgruppe entfernen) und eine neue Indexdefinition erstellen. Weitere Informationen finden Sie unter Verwaltete Replikatindexe ändern.

Erforderliche Rolle und Berechtigungen

Sie müssen ein Datenbanknutzerkonto verwenden, dem die Rolle cloudsqlsuperuser zugewiesen ist, um gespeicherte Prozeduren für verwaltete Replikatindexe auszuführen.

Verwaltete Replikatindexe erstellen

So erstellen und verwalten Sie verwaltete Replikatindexe auf Ihren Lesereplikaten:

  1. Erstellen Sie eine Indexdefinition auf der primären Instanz:

    Rufen Sie die gespeicherte Prozedur mysql.cloudsql_replica_idx_defn_create auf der primären Instanz Ihrer Datenbank auf:

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

    Ersetzen Sie Folgendes:

    • INDEX_DEFINITION_NAME: der Name der Indexdefinition.
    • CREATE_INDEX_STATEMENT: die SQL-Anweisung, die den sekundären Index erstellt (z. B. CREATE INDEX idx_age ON university.students (age)). Beachten Sie, dass diese Anweisung ein Schema-Präfix haben muss.

    Notieren Sie sich die zurückgegebene idx_id (eine eindeutige Ganzzahlkennung für die Definition) aus der Ausgabe des Verfahrens. Cloud SQL speichert diese Daten in mysql.cloudsql_replica_idx_defn. Sie können die idx_id später abrufen, indem Sie diese Tabelle abfragen.

  2. Indexdefinition zu einer Replikatgruppe hinzufügen:

    Ordnen Sie die Indexdefinition einem bestimmten Replikatgruppennamen zu, indem Sie mysql.cloudsql_replica_idx_group_add auf der primären Instanz aufrufen:

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

    Ersetzen Sie Folgendes:

    • INDEX_DEFINITION_ID: die eindeutige Ganzzahl-ID, die zurückgegeben wurde, als Sie die gespeicherte Prozedur mysql.cloudsql_replica_idx_defn_create ausgeführt haben, um den sekundären Index zu erstellen.
    • GROUP_NAME: der Name der Replikationsgruppenzuordnung (z. B. reporting_group). GROUP_NAME ist ein benutzerdefinierter Name, den Sie auswählen können. Wenn diese Gruppe nicht vorhanden ist, erstellt Cloud SQL eine neue.

    Cloud SQL speichert diese Daten in mysql.cloudsql_replica_idx_group_map. Sie können die Gruppenzuordnungen später durch Abfragen dieser Tabelle abrufen.

  3. Weisen Sie die Gruppe Ihrer Replikatinstanz zu:

    Aktivieren Sie die festgelegte Gruppe auf Ihrem Lesereplikat, indem Sie das Datenbank-Flag cloudsql_index_recreate_replica_group auf den Namen Ihrer Gruppe festlegen (z. B. reporting_group).

  4. Prüfen Sie den Fortschritt der Wiederherstellung:

    Stellen Sie eine Verbindung zu Ihrer Lesereplikatinstanz her und prüfen Sie den Erstellungsfortschritt und den Status Ihrer Indexe.

    • So prüfen Sie den Fortschritt der Indexerstellung:

      CALL mysql.cloudsql_replica_idx_show_status();

    • Fehlgeschlagene Versuche und Fehlermeldungen prüfen:

      CALL mysql.cloudsql_replica_idx_show_errors();

    • Listen Sie den Status, die Wiederholungsdetails und die Dauer für alle verwalteten Indexe auf:

      CALL mysql.cloudsql_replica_idx_show_all();

Status des verwalteten Replikatindex prüfen

Wenn Sie den Status des Indexvorgangs prüfen möchten, stellen Sie eine Verbindung zu Ihrer Lesereplikatinstanz her und fragen Sie die Tabelle mysql.cloudsql_replica_idx_status ab:

SELECT * FROM mysql.cloudsql_replica_idx_status;

Die Ausgabe sieht etwa so aus:

+--------+----------------------------------------------------+--------+-----------+---------------------+---------------------+-------------+---------+--------------------+---------+
| 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 führt die Indexwartung für verwaltete Replikate in Batches durch. Wenn Cloud SQL eine Gruppe von CREATE- oder DROP-Aktionen aufnimmt, wird für jeden Index ein PENDING-Statuseintrag erstellt und dann jede DDL-Anweisung (Data Definition Language) nacheinander ausgeführt. Ein Fehler bei einem Index blockiert nicht die Ausführung nachfolgender Indexe in der Warteschlange. Cloud SQL ruft dann nach etwa fünf Minuten den nächsten Batch ab.

Wenn die Indexerstellung fehlschlägt, markiert Cloud SQL den Status als FAILED und wiederholt den Vorgang nach einer Stunde automatisch.

Die Tabelle mysql.cloudsql_replica_idx_status enthält alle Statuseinträge für Indexvorgänge und die folgenden Spalten:

  • idx_id: die eindeutige Ganzzahl-ID für die Indexdefinition.
  • create_stmt: die SQL-Anweisung CREATE INDEX.
  • action: der ausgeführte Vorgang (CREATE oder DROP).
  • thread_id: Die MySQL-Thread-ID, die den Vorgang ausführt.
  • start_time: der Zeitstempel, der angibt, wann der Vorgang gestartet wurde.
  • end_time: der Zeitstempel, der angibt, wann der Vorgang abgeschlossen wurde.
  • retry_count: die Anzahl der Wiederholungsversuche für den Vorgang. Cloud SQL versucht nach einer Stunde noch einmal, fehlgeschlagene Indexerstellungen auszuführen.
  • err_msg: die Fehlermeldung des letzten fehlgeschlagenen Vorgangs.
  • comment_tag: Das Tag [SIC_X_Y], das dem Indexkommentar vorangestellt wird. Dieses Tag wird nur für die interne Verwaltung verwendet und hat keine Funktion.
  • status: der aktuelle Status des Vorgangs:
    • PENDING: Der Indexvorgang wurde der Warteschlange hinzugefügt.
    • RUNNING: Die Ausführung des Indexvorgangs hat begonnen.
    • DONE: Der Indexvorgang wurde erfolgreich abgeschlossen.
    • FAILED: Der Indexvorgang ist fehlgeschlagen. Cloud SQL wiederholt fehlgeschlagene Indexerstellungen nach einer Stunde.

Verwaltete Replikatsindexe löschen

Wenn Sie einen Index aus einer Replikatgruppe entfernen oder eine Indexdefinition vollständig löschen möchten, rufen Sie die entsprechende gespeicherte Prozedur auf Ihrer primären Instanz auf:

  • Indexdefinition aus einer Replikationsgruppe entfernen:

    Rufen Sie mysql.cloudsql_replica_idx_group_drop für die primäre Instanz auf:

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

    Ersetzen Sie Folgendes:

    • INDEX_DEFINITION_ID: Die eindeutige Ganzzahl-ID, die beim Erstellen der sekundären Indexdefinition zurückgegeben wurde.
    • GROUP_NAME: der Name der Zuordnung der Replikatgruppe (z. B. reporting_group).

  • Indexdefinition löschen:

    Rufen Sie mysql.cloudsql_replica_idx_defn_drop für die primäre Instanz auf:

    CALL mysql.cloudsql_replica_idx_defn_drop
(INDEX_DEFINITION_ID);

    Ersetzen Sie Folgendes:

    • INDEX_DEFINITION_ID: die eindeutige Ganzzahl-ID der zu löschenden Indexdefinition.

Weitere Informationen zu gespeicherten Prozeduren finden Sie unter Gespeicherte Prozeduren für verwaltete Replikatindexe.

Verwaltete Replikatindexe ändern

Cloud SQL unterstützt nicht das Aktualisieren oder Ändern vorhandener Indexmetadaten. Sie können eine vorhandene Indexdefinition oder die zugehörige SQL-Anweisung nicht direkt ändern.

Wenn Sie einen verwalteten Replikatindex ändern möchten (z. B. um indexierte Spalten oder Indexoptionen zu ändern), müssen Sie die vorhandene Indexdefinition entfernen oder löschen und dann eine neue Indexdefinition erstellen.

So ändern Sie einen verwalteten Replikatindex:

  1. Entfernen oder löschen Sie die vorhandene Indexdefinition auf der primären Instanz:

    • Rufen Sie mysql.cloudsql_replica_idx_group_drop auf, um die Indexdefinition aus einer Replikatgruppe zu entfernen:

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

    • Wenn Sie die Indexdefinition vollständig löschen möchten, rufen Sie mysql.cloudsql_replica_idx_defn_drop auf:

      CALL mysql.cloudsql_replica_idx_defn_drop
(INDEX_DEFINITION_ID);

    Ersetzen Sie Folgendes:

    • INDEX_DEFINITION_ID: die eindeutige Ganzzahl-ID der Indexdefinition, die entfernt oder gelöscht werden soll.
    • GROUP_NAME: der Name der Zuordnung der Replikatgruppe (z. B. reporting_group).

  2. Erstellen Sie eine neue Indexdefinition auf der primären Instanz:

    Rufen Sie mysql.cloudsql_replica_idx_defn_create mit der aktualisierten Indexanweisung auf:

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

    Ersetzen Sie Folgendes:

    • INDEX_DEFINITION_NAME: der Name der neuen Indexdefinition.
    • CREATE_INDEX_STATEMENT: die aktualisierte SQL-Anweisung, mit der der sekundäre Index erstellt wird, z. B. CREATE INDEX idx_age ON university.students (age, name).

    Notieren Sie sich den neuen idx_id, der in der Ausgabe der gespeicherten Prozedur zurückgegeben wird.

  3. Neue Indexdefinition der Replikatgruppe zuordnen:

    Rufen Sie mysql.cloudsql_replica_idx_group_add für die primäre Instanz auf:

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

    Ersetzen Sie Folgendes:

    • INDEX_DEFINITION_ID: die neue eindeutige Ganzzahl-ID, die in Schritt 2 zurückgegeben wurde.
    • GROUP_NAME: der Name der Zuordnung der Replikatgruppe (z. B. reporting_group).

Nachdem Sie die neue Indexdefinition der Replikatgruppe zugeordnet haben, wird der vorhandene Index vom Hintergrundwartungsprozess aus dem Lesereplikat gelöscht und dann der neue Index auf dem Replikat mit der aktualisierten Definition erstellt.

Datenbankkonfigurations-Flags für verwaltete Replikatindexe

Sie können das Verhalten des verwalteten Replikatindex dynamisch mit den folgenden globalen Datenbank-Flags anpassen:

  • cloudsql_index_recreate_enable: Aktiviert oder deaktiviert den Neuerstellungsprozess. Standardmäßig ist das Flag auf on gesetzt. Wenn Sie das Flag auf off setzen, werden laufende Indexwartungsvorgänge sofort beendet.

  • cloudsql_index_recreate_replica_group: Name der zugewiesenen Replikatgruppe für das Replikat (Standard ist NULL). Ein Replikat kann jeweils nur einer Replikatgruppe zugewiesen werden. Replikate erstellen alle Indexe, die diesem Replikatgruppennamen zugeordnet sind.

Selbstverwaltete Replikatindexe

Cloud SQL enthält zwei gespeicherte Prozeduren im mysql-Schema, mit denen Sie sekundäre Indexe auf einem MySQL-Lesereplikat hinzufügen und löschen können. Diese gespeicherten Prozeduren können zwar auf einer primären Quellinstanz ausgeführt werden, sind aber für Lesereplikate konzipiert.

Diese Indexe bleiben nicht erhalten, wenn das Replikat neu erstellt wird.

mysql.addSecondaryIdxOnReplica
Fügt Sie der Datenbank einen sekundären Index hinzu. Diese gespeicherte Prozedur ist ein Wrapper für die DDL-Anweisung CREATE INDEX.

Parameter:

  • idxType: Typ des zu erstellenden Index. Übergeben Sie beispielsweise UNIQUE, um einen eindeutigen Index zu erstellen.
  • idxName: Name des Index.
  • tableName: Name der Tabelle im Format schema.name.
  • idxDefinition: Definition des Index. Geben Sie nicht die äußeren Klammern an.
  • idxOption: Alle zusätzlichen Optionen, die bei der Indexerstellung übergeben werden sollen. In MySQL 8.0 können Sie beispielsweise die Option INVISIBLE für einen unsichtbaren Index übergeben.

Syntax:

mysql.addSecondaryIdxOnReplica(idxType, idxName, tableName, idxDefinition, idxOption)
mysql.dropSecondaryIdxOnReplica
Löscht einen sekundären Index für die Datenbank. Diese gespeicherte Prozedur ist ein Wrapper für die DDL-Anweisung DROP INDEX.

Parameter:

  • idxName: Name des Index.
  • tableName: Name der Tabelle im Format schema.name.
  • idxOption: Alle zusätzlichen Optionen, die beim Löschen eines Index übergeben werden sollen. Beispiel: eine Algorithmusoption wie INPLACE.

Syntax:

mysql.dropSecondaryIdxOnReplica(idxName, tableName, idxOption)

Informationen zu den Parametern idxType und idxOption finden Sie in der Dokumentation der Hauptversion von MySQL, die auf der Cloud SQL-Instanz ausgeführt wird.

Beispiele

In diesem Abschnitt finden Sie Beispiele dafür, wie Sie selbstverwaltete Replikatindexe richtig oder falsch hinzufügen oder löschen können.

Richtige Verwendung

Im Folgenden finden Sie einige Beispielaufrufe der Prozeduren. Angenommen, Sie haben eine Tabelle mit der folgenden Definition:

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

Wenn Sie einen regulären Index mit dem Namen t1_fname_lname für die Spalten first_name und last_name erstellen möchten, führen Sie die folgende Anweisung aus:

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

Wenn Sie außerdem einen eindeutigen Index mit dem Namen t1_license_id für die Spalte license_id mit dem Kommentar „eindeutige Lizenz-ID“ erstellen möchten, führen Sie die folgende Anweisung aus:

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

Wenn Sie den Index t1_fname_lname löschen möchten, führen Sie die folgende Anweisung aus:

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

Falsche Verwendung

Der folgende Versuch, einen Index für die Spalten first_name und last_name zu erstellen, schlägt aufgrund der äußeren Klammern im Parameter idxDefinition fehl:

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

Sie können nur Indizes zu vom Kunden erstellten Tabellen hinzufügen. Der folgende Versuch, einen Index für die Spalte host der Tabelle mysql.servers zu erstellen, schlägt fehl:

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

Sie können die Prozedur dropSecondaryIdxOnReplica nur verwenden, um Indexe zu löschen, die zuvor mit der Prozedur addSecondaryIdxOnReplica erstellt wurden. Der folgende Aufruf zum Löschen des vorhandenen Index idx_fname schlägt beispielsweise fehl:

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

SQL-Injection in diesen Prozeduraufrufen schlagen fehl. Die folgende SQL-Injection mit einer Kommentarsequenz schlägt beispielsweise fehl:

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

Ähnlich schlägt dieser SQL-Injection-Versuch mit einem Trennzeichen fehl:

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

Von selbstverwalteten zu verwalteten Replikatindexen migrieren

Obwohl sowohl verwaltete als auch selbstverwaltete Replikatindexe auf derselben Instanz vorhanden sein können, können Sie zu verwalteten Replikatindexen migrieren.

So migrieren Sie von selbstverwalteten zu verwalteten Replikatindexen:

  1. Indexdefinitionen auf der primären Instanz registrieren:

    Rufen Sie mysql.cloudsql_replica_idx_defn_create für jeden sekundären Index auf Ihrer primären Instanz auf:

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

    Notieren Sie sich die zurückgegebene idx_id (eine eindeutige Ganzzahlkennung für die Definition) aus der Ausgabe des Verfahrens.

  2. Indexdefinition zu einer Replikatgruppe hinzufügen:

    Ordnen Sie die Indexdefinition einem bestimmten Replikatgruppennamen zu, indem Sie mysql.cloudsql_replica_idx_group_add auf der primären Instanz aufrufen:

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

  3. Konfigurieren Sie das Flag für die Replikatgruppe auf dem Lesereplikat:

    Legen Sie das Datenbank-Flag cloudsql_index_recreate_replica_group auf Ihrer Lesereplikatinstanz auf den Gruppennamen fest:

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

    Achten Sie darauf, dass der im Datenbank-Flag cloudsql_index_recreate_replica_group angegebene Gruppenname genau mit dem in mysql.cloudsql_replica_idx_group_add angegebenen Gruppennamen übereinstimmt.

  4. Vorhandene Indexe prüfen oder umstellen:

    Da der Index bereits im Lesereplikat vorhanden ist, werden möglicherweise Fehler mit dem Status FAILED in mysql.cloudsql_replica_idx_status angezeigt, wenn der Hintergrundprozess versucht, den Index zu erstellen. Sie können einen der folgenden Ansätze wählen:

    • Warten Sie, bis das Replikat neu erstellt wurde: Sie können den Status FAILED in der Statustabelle ignorieren. Cloud SQL erstellt den sekundären Index nach einem Ereignis zur Neuerstellung des Replikats automatisch mit der Methode für verwaltete Replikatindexe neu.

    • Sofort umstellen: Wenn Sie möchten, dass Cloud SQL den Index sofort verwaltet, ohne auf die Neuerstellung eines Replikats zu warten, stellen Sie eine Verbindung zum Lesereplikat her und entfernen Sie den selbstverwalteten Index mit der gespeicherten Prozedur mysql.dropSecondaryIdxOnReplica:

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

      Während des nächsten Wartungszyklus im Hintergrund (etwa alle fünf Minuten) erstellt und verfolgt Cloud SQL den verwalteten Replikatindex automatisch neu.

Fehlerbehebung bei Replikatindexen

Prüfen Sie Folgendes, um Probleme mit Replikatindexen zu beheben:

  • Prüfen Sie, ob verwaltete Replikatindexe für die Replikatinstanz aktiviert sind:

    Wenn Sie verwaltete Replikatindexe verwenden, muss das Datenbank-Flag cloudsql_index_recreate_enable auf dem Lesereplikat auf on gesetzt sein.

    Weitere Informationen zum Konfigurieren von Datenbank-Flags finden Sie unter Datenbank-Flags konfigurieren.

  • Vorgangsstatus und Fehler prüfen:

    Stellen Sie eine Verbindung zum Lesereplikat her und fragen Sie mysql.cloudsql_replica_idx_status ab oder führen Sie CALL mysql.cloudsql_replica_idx_show_errors(); aus, um Fehlermeldungen für fehlgeschlagene Vorgänge aufzurufen. Ein Fehler bei einem Index blockiert nicht die Ausführung nachfolgender Indexe in der Warteschlange.

Nächste Schritte