Crea y administra índices de réplicas de lectura

En este documento, se describe cómo crear, mantener y supervisar índices secundarios en réplicas de lectura de Cloud SQL.

Para obtener información conceptual sobre cómo funcionan los índices de réplica administrados, consulta Descripción general de los índices de réplica de lectura.

Índices de réplica administrados

En la siguiente tabla, se resume el flujo de trabajo para crear, configurar y supervisar índices de réplicas administradas:

Paso Procedimiento almacenado o marca de base de datos Dónde realizar el paso
Crea una definición de índice CALL mysql.cloudsql_replica_idx_defn_create('INDEX_DEFINITION_NAME', 'CREATE_INDEX_STATEMENT');

Este procedimiento almacenado devuelve un identificador de número entero único para la definición del índice, INDEX_DEFINITION_ID.

 Instancia principal
Asigna la definición al grupo CALL mysql.cloudsql_replica_idx_group_add(INDEX_DEFINITION_ID, 'GROUP_NAME');

GROUP_NAME es un nombre personalizado que puedes seleccionar. Si ese grupo no existe, Cloud SQL crea uno nuevo.

 Instancia principal
Asigna un grupo a la réplica Marca de base de datos: cloudsql_index_recreate_replica_group = GROUP_NAME Instancia de réplica de lectura
Verificar el estado CALL mysql.cloudsql_replica_idx_show_status(); Instancia de réplica de lectura
Errores de auditoría CALL mysql.cloudsql_replica_idx_show_errors(); Instancia de réplica de lectura

Cada llamada de procedimiento almacenado ejecuta una sentencia COMMIT que finaliza los cambios en tu sesión actual. Como resultado, las sentencias de lenguaje de manipulación de datos (DML) ejecutadas con estos procedimientos almacenados no se pueden revertir dentro de una transacción.

Cloud SQL no admite la actualización ni la alteración de los metadatos de índices existentes. Para modificar un índice de réplica administrado, debes descartar la definición de índice existente (o quitarla del grupo de réplicas) y crear una nueva definición de índice. Para obtener más información, consulta Modifica índices de réplicas administradas.

Rol y privilegios requeridos

Debes usar una cuenta de usuario de la base de datos que tenga asignado el rol cloudsqlsuperuser para ejecutar procedimientos almacenados para los índices de réplica administrados.

Crea índices de réplica administrados

Para crear y mantener índices de réplicas administradas en tus réplicas de lectura, sigue estos pasos:

  1. Crea una definición de índice en la instancia principal:

    Llama al procedimiento almacenado mysql.cloudsql_replica_idx_defn_create en la instancia principal de la base de datos:

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

    Reemplaza lo siguiente:

    • INDEX_DEFINITION_NAME: Es el nombre de la definición del índice.
    • CREATE_INDEX_STATEMENT: Es la instrucción de SQL que crea el índice secundario (por ejemplo, CREATE INDEX idx_age ON university.students (age)). Ten en cuenta que esta sentencia debe tener un prefijo de esquema.

    Toma nota del idx_id que se muestra (un identificador de número entero único para la definición) del resultado del procedimiento. Cloud SQL almacena estos datos en mysql.cloudsql_replica_idx_defn, y puedes recuperar el idx_id más adelante consultando esta tabla.

  2. Agrega la definición del índice a un grupo de réplicas:

    Asigna la definición del índice a un nombre de grupo de réplicas designado llamando a mysql.cloudsql_replica_idx_group_add en la instancia principal:

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

    Reemplaza lo siguiente:

    • INDEX_DEFINITION_ID: Es el ID de número entero único que se muestra cuando ejecutaste el procedimiento almacenado mysql.cloudsql_replica_idx_defn_create para crear el índice secundario.
    • GROUP_NAME: Es el nombre de la asignación del grupo de réplicas (por ejemplo, reporting_group). El GROUP_NAME es un nombre personalizado que puedes seleccionar. Si ese grupo no existe, Cloud SQL crea uno nuevo.

    Cloud SQL almacena estos datos en mysql.cloudsql_replica_idx_group_map, y puedes recuperar las asignaciones de grupos más adelante consultando esta tabla.

  3. Asigna el grupo a tu instancia de réplica:

    Habilita el grupo designado en tu réplica de lectura configurando la marca de base de datos cloudsql_index_recreate_replica_group con el nombre de tu grupo (por ejemplo, reporting_group).

  4. Verifica el progreso del restablecimiento:

    Conéctate a tu instancia de réplica de lectura y verifica el progreso de la creación y el estado de tus índices.

    • Verifica el progreso de la creación de índices en curso:

      CALL mysql.cloudsql_replica_idx_show_status();

    • Verifica los intentos fallidos y los mensajes de error:

      CALL mysql.cloudsql_replica_idx_show_errors();

    • Enumera el estado, los detalles de reintentos y las duraciones de todos los índices administrados:

      CALL mysql.cloudsql_replica_idx_show_all();

Verifica el estado del índice de la réplica administrada

Para verificar el estado operativo de la operación de índice, conéctate a tu instancia de réplica de lectura y consulta la tabla mysql.cloudsql_replica_idx_status:

SELECT * FROM mysql.cloudsql_replica_idx_status;

El resultado es similar a lo siguiente:

+--------+----------------------------------------------------+--------+-----------+---------------------+---------------------+-------------+---------+--------------------+---------+
| 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 realiza el mantenimiento de los índices de réplicas administradas por lotes. Cuando Cloud SQL selecciona un grupo de acciones CREATE o DROP, crea una entrada de estado PENDING para cada índice y, luego, ejecuta en serie cada sentencia de lenguaje de definición de datos (DDL). Una falla en un índice no bloquea la ejecución de los índices posteriores en la cola. Luego, Cloud SQL selecciona el siguiente lote después de aproximadamente cinco minutos.

Si falla la creación de un índice, Cloud SQL marca el estado como FAILED y vuelve a intentar la operación automáticamente después de una hora.

La tabla mysql.cloudsql_replica_idx_status contiene todas las entradas de estado de las operaciones de índice y las siguientes columnas:

  • idx_id: Es el identificador de número entero único para la definición del índice.
  • create_stmt: Es la instrucción de SQL CREATE INDEX.
  • action: Es la operación que se realiza (CREATE o DROP).
  • thread_id: Es el ID del subproceso de MySQL que ejecuta la operación.
  • start_time: Es la marca de tiempo en la que se inició la operación.
  • end_time: Es la marca de tiempo en la que se completó la operación.
  • retry_count: Es la cantidad de intentos de reintento para la operación. Cloud SQL vuelve a intentar crear los índices que fallaron después de una hora.
  • err_msg: Es el mensaje de error de la última operación que falló.
  • comment_tag: Es la etiqueta [SIC_X_Y] que se antepone al comentario del índice. Esta etiqueta se usa solo para la administración interna y no tiene funcionalidad.
  • status: Es el estado actual de la operación:
    • PENDING: Se agregó la operación de índice a la cola.
    • RUNNING: Comenzó la ejecución de la operación de índice.
    • DONE: La operación de indexación se completó correctamente.
    • FAILED: No se pudo realizar la operación de índice. Cloud SQL vuelve a intentar crear los índices que fallaron después de una hora.

Descarta los índices de réplica administrados

Para quitar un índice de un grupo de réplicas o borrar una definición de índice por completo, llama al procedimiento almacenado correspondiente en tu instancia principal:

  • Quita una definición de índice de un grupo de réplicas:

    Llama a mysql.cloudsql_replica_idx_group_drop en la instancia principal:

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

    Reemplaza lo siguiente:

    • INDEX_DEFINITION_ID: Es el ID de número entero único que se muestra cuando creaste la definición del índice secundario.
    • GROUP_NAME: Es el nombre de la asignación del grupo de réplicas (por ejemplo, reporting_group).

  • Borra una definición de índice:

    Llama a mysql.cloudsql_replica_idx_defn_drop en la instancia principal:

    CALL mysql.cloudsql_replica_idx_defn_drop
(INDEX_DEFINITION_ID);

    Reemplaza lo siguiente:

    • INDEX_DEFINITION_ID: Es el ID de número entero único de la definición del índice que se borrará.

Para obtener más información sobre los procedimientos almacenados, consulta Procedimientos almacenados de índices de réplicas administradas.

Modifica los índices de réplica administrados

Cloud SQL no admite la actualización ni la alteración de los metadatos de índices existentes. No puedes modificar directamente una definición de índice existente ni su instrucción de SQL.

Para modificar un índice de réplica administrado (por ejemplo, para cambiar las columnas indexadas o las opciones de índice), debes quitar o borrar la definición de índice existente y, luego, crear una nueva.

Para modificar un índice de réplica administrado, sigue estos pasos:

  1. Quita o borra la definición del índice existente en la instancia principal:

    • Para quitar la definición del índice de un grupo de réplicas, llama a mysql.cloudsql_replica_idx_group_drop:

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

    • Para borrar la definición del índice por completo, llama a mysql.cloudsql_replica_idx_defn_drop:

      CALL mysql.cloudsql_replica_idx_defn_drop
(INDEX_DEFINITION_ID);

    Reemplaza lo siguiente:

    • INDEX_DEFINITION_ID: Es el ID de número entero único de la definición del índice que se quitará o borrará.
    • GROUP_NAME: Es el nombre de la asignación del grupo de réplicas (por ejemplo, reporting_group).

  2. Crea una nueva definición de índice en la instancia principal:

    Llama a mysql.cloudsql_replica_idx_defn_create con la sentencia de índice actualizada:

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

    Reemplaza lo siguiente:

    • INDEX_DEFINITION_NAME: Es el nombre de la definición del índice nuevo.
    • CREATE_INDEX_STATEMENT: Es la instrucción de SQL actualizada que crea el índice secundario (por ejemplo, CREATE INDEX idx_age ON university.students (age, name)).

    Toma nota del nuevo idx_id que se devuelve en el resultado del procedimiento almacenado.

  3. Asigna la nueva definición de índice al grupo de réplicas:

    Llama a mysql.cloudsql_replica_idx_group_add en la instancia principal:

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

    Reemplaza lo siguiente:

    • INDEX_DEFINITION_ID: Es el nuevo ID de número entero único que se devolvió en el paso 2.
    • GROUP_NAME: Es el nombre de la asignación del grupo de réplicas (por ejemplo, reporting_group).

Después de asignar la definición del índice nuevo al grupo de réplicas, el proceso de mantenimiento en segundo plano quita el índice existente de la réplica de lectura y, luego, crea el índice nuevo en la réplica con la definición actualizada.

Marcas de configuración de la base de datos para índices de réplicas administradas

Puedes personalizar el comportamiento del índice de réplica administrada de forma dinámica con las siguientes marcas de base de datos globales:

  • cloudsql_index_recreate_enable: habilita o inhabilita el proceso de recreación. De forma predeterminada, la marca se establece en on. Si configuras la marca como off, se finalizan de inmediato las operaciones de mantenimiento de índices en curso.

  • cloudsql_index_recreate_replica_group: Es el nombre del grupo de réplicas designado para la réplica (el valor predeterminado es NULL). Una réplica se puede asignar a un solo grupo de réplicas a la vez. Las réplicas compilan todos los índices asignados a este nombre de grupo de réplicas.

Índices de réplica autoadministrados

Cloud SQL incluye dos procedimientos almacenados en el esquema mysql que puedes usar para agregar y descartar índices secundarios en una réplica de lectura de MySQL. Ten en cuenta que, si bien estos procedimientos almacenados pueden ejecutarse en una instancia de origen principal, están diseñados para réplicas de lectura.

Estos índices no se conservan si se vuelve a crear la réplica.

mysql.addSecondaryIdxOnReplica
Agrega un índice secundario a la base de datos. Este procedimiento almacenado es un wrapper de la declaración DDL CREATE INDEX.

Parámetros:

  • idxType: Es el tipo de índice que se creará. Por ejemplo, pasa UNIQUE para crear un índice único.
  • idxName: Es el nombre del índice.
  • tableName: Es el nombre de la tabla en el formato de schema.name.
  • idxDefinition: Es la definición del índice. No incluyas los paréntesis exteriores.
  • idxOption: cualquier opción adicional que se deba pasar en la creación del índice. Por ejemplo, en MySQL 8.0, puedes pasar la opción INVISIBLE para un índice invisible.

Sintaxis:

mysql.addSecondaryIdxOnReplica(idxType, idxName, tableName, idxDefinition, idxOption)
mysql.dropSecondaryIdxOnReplica
Agrega un índice secundario a la base de datos. Este procedimiento almacenado es un wrapper de la declaración DDL DROP INDEX.

Parámetros:

  • idxName: Es el nombre del índice.
  • tableName: Es el nombre de la tabla en el formato schema.name.
  • idxOption: Son las opciones adicionales que se deben pasar cuando se borra un índice. Por ejemplo, una opción de algoritmo como INPLACE.

Sintaxis:

mysql.dropSecondaryIdxOnReplica(idxName, tableName, idxOption)

Para los parámetros idxType y idxOption, consulta la documentación de la versión principal de MySQL que se ejecuta en la instancia de Cloud SQL.

Ejemplos

En esta sección, se proporcionan ejemplos de cómo puedes agregar o quitar índices de réplica autoadministrados de forma correcta o incorrecta.

Uso correcto

Estas son algunas invocaciones de ejemplo de los procedimientos. Supongamos que tienes una tabla con la siguiente definición:

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 deseas crear un índice normal llamado t1_fname_lname en las columnas first_name y last_name, ejecuta la siguiente sentencia:

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

Si también quieres crear un índice único llamado t1_license_id en la columna license_id con el comentario "ID de licencia único", ejecuta la siguiente sentencia:

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

Si deseas descartar el índice t1_fname_lname, ejecuta la siguiente sentencia:

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

uso incorrecto

El siguiente intento de crear un índice en las columnas first_name y last_name falla debido a los paréntesis exteriores en el parámetro idxDefinition:

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

Solo puedes agregar índices en las tablas creadas por el cliente. El siguiente intento de crear un índice en la columna host de la tabla mysql.servers falla:

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

Solo puedes usar el procedimiento dropSecondaryIdxOnReplica para descartar los índices que creaste antes mediante el procedimiento addSecondaryIdxOnReplica. Por ejemplo, la siguiente llamada para descartar el índice idx_fname existente falla:

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

La inyección de SQL en estas llamadas de procedimiento falla. Por ejemplo, la siguiente inyección de SQL con una secuencia de comentarios falla:

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

Del mismo modo, este intento de inyección de SQL con un delimitador falla:

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

Migra de índices de réplica autoadministrados a administrados

Aunque los índices de réplica administrados y los índices de réplica autoadministrados pueden coexistir en la misma instancia, puedes migrar a índices de réplica administrados.

Para migrar de índices de réplica autoadministrados a administrados, sigue estos pasos:

  1. Registra las definiciones de índice en la instancia principal:

    Llama a mysql.cloudsql_replica_idx_defn_create en tu instancia principal para cada índice secundario:

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

    Toma nota del idx_id que se muestra (un identificador de número entero único para la definición) del resultado del procedimiento.

  2. Agrega la definición del índice a un grupo de réplicas:

    Asigna la definición del índice a un nombre de grupo de réplicas designado llamando a mysql.cloudsql_replica_idx_group_add en la instancia principal:

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

  3. Configura la marca del grupo de réplicas en la réplica de lectura:

    Establece la marca de base de datos cloudsql_index_recreate_replica_group en tu instancia de réplica de lectura para que se oriente al nombre del grupo:

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

    Asegúrate de que el nombre del grupo proporcionado en la marca de base de datos cloudsql_index_recreate_replica_group coincida exactamente con el nombre del grupo especificado en mysql.cloudsql_replica_idx_group_add.

  4. Verifica o realiza la transición de los índices existentes:

    Debido a que el índice ya existe en la réplica de lectura, es posible que veas errores con un estado FAILED en mysql.cloudsql_replica_idx_status cuando el proceso en segundo plano intente crear el índice. Puedes elegir uno de los siguientes enfoques:

    • Espera a que se vuelva a crear la réplica: puedes ignorar sin problemas el estado FAILED en la tabla de estado. Cloud SQL vuelve a crear automáticamente el índice secundario con el método de índice de réplica administrada después de un evento de recreación de réplica.

    • Transición inmediata: Si quieres que Cloud SQL administre el índice de inmediato sin esperar a que se vuelva a crear una réplica, conéctate a la réplica de lectura y quita el índice autoadministrado con el procedimiento almacenado mysql.dropSecondaryIdxOnReplica:

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

      Durante el siguiente ciclo de mantenimiento en segundo plano (aproximadamente cada cinco minutos), Cloud SQL vuelve a crear y hace un seguimiento automático del índice de réplica administrado.

Soluciona problemas de índices de réplica

Para solucionar problemas con los índices de réplica, verifica lo siguiente:

  • Verifica que los índices de réplica administrados estén habilitados para la instancia de réplica:

    Si usas índices de réplica administrados, asegúrate de que la marca de base de datos cloudsql_index_recreate_enable esté configurada como on en la réplica de lectura.

    Para obtener más información sobre cómo configurar marcas de base de datos, consulta Configura marcas de base de datos.

  • Verifica el estado operativo y los errores:

    Conéctate a la réplica de lectura y consulta mysql.cloudsql_replica_idx_status o ejecuta CALL mysql.cloudsql_replica_idx_show_errors(); para ver los mensajes de error de las operaciones con errores. Una falla en un índice no bloquea la ejecución de los índices posteriores en la cola.

¿Qué sigue?