Criar e gerenciar índices de réplicas de leitura

Neste documento, descrevemos como criar, manter e monitorar índices secundários em réplicas de leitura do Cloud SQL.

Para informações conceituais sobre como os índices de réplica gerenciados funcionam, consulte Visão geral dos índices de réplica de leitura.

Índices de réplica gerenciados

A tabela a seguir resume o fluxo de trabalho para criar, configurar e monitorar índices de réplica gerenciados:

Etapa Procedimento armazenado ou flag de banco de dados Onde realizar a etapa
Criar definição de índice CALL mysql.cloudsql_replica_idx_defn_create('INDEX_DEFINITION_NAME', 'CREATE_INDEX_STATEMENT');

Esse procedimento armazenado retorna um identificador inteiro exclusivo para a definição do índice, INDEX_DEFINITION_ID.

 Instância principal
Mapear definição para grupo CALL mysql.cloudsql_replica_idx_group_add(INDEX_DEFINITION_ID, 'GROUP_NAME');

GROUP_NAME é um nome personalizado que você pode selecionar. Se esse grupo não existir, o Cloud SQL vai criar um novo.

 Instância principal
Atribuir grupo à réplica Flag de banco de dados: cloudsql_index_recreate_replica_group = GROUP_NAME Ler instância da réplica
Verificar status CALL mysql.cloudsql_replica_idx_show_status(); Ler instância da réplica
Erros de auditoria CALL mysql.cloudsql_replica_idx_show_errors(); Ler instância da réplica

Cada chamada de procedimento armazenado executa uma instrução COMMIT que finaliza as mudanças na sessão atual. Como resultado, as instruções de linguagem de manipulação de dados (DML) executadas usando esses procedimentos armazenados não podem ser revertidas em uma transação.

O Cloud SQL não permite atualizar ou alterar os metadados de índices atuais. Para modificar um índice de réplica gerenciada, é necessário eliminar a definição de índice atual (ou removê-la do grupo de réplicas) e criar uma nova definição de índice. Para mais informações, consulte Modificar índices de réplica gerenciada.

Função e privilégios necessários

É necessário usar uma conta de usuário do banco de dados que tenha o papel cloudsqlsuperuser para executar procedimentos armazenados para índices de réplica gerenciados.

Criar índices de réplica gerenciados

Para criar e manter índices de réplica gerenciados nas réplicas de leitura, siga estas etapas:

  1. Crie uma definição de índice na instância principal:

    Chame o procedimento armazenado mysql.cloudsql_replica_idx_defn_create na instância principal do banco de dados:

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

    Substitua:

    • INDEX_DEFINITION_NAME: o nome da definição do índice.
    • CREATE_INDEX_STATEMENT: a instrução SQL que cria o índice secundário (por exemplo, CREATE INDEX idx_age ON university.students (age)). Essa instrução precisa ter um prefixo de esquema.

    Anote o idx_id retornado (um identificador de número inteiro exclusivo para a definição) da saída do procedimento. O Cloud SQL armazena esses dados em mysql.cloudsql_replica_idx_defn, e é possível recuperar o idx_id mais tarde consultando essa tabela.

  2. Adicione a definição de índice a um grupo de réplicas:

    Mapeie a definição do índice para um nome de grupo de réplicas designado chamando mysql.cloudsql_replica_idx_group_add na instância principal:

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

    Substitua:

    • INDEX_DEFINITION_ID: o ID inteiro exclusivo retornado quando você executou o procedimento armazenado mysql.cloudsql_replica_idx_defn_create para criar o índice secundário.
    • GROUP_NAME: o nome do mapeamento do grupo de réplicas (por exemplo, reporting_group). O GROUP_NAME é um nome personalizado que você pode selecionar. Se esse grupo não existir, o Cloud SQL vai criar um novo.

    O Cloud SQL armazena esses dados em mysql.cloudsql_replica_idx_group_map, e é possível recuperar os mapeamentos de grupo mais tarde consultando essa tabela.

  3. Atribua o grupo à instância de réplica:

    Ative o grupo designado na réplica de leitura definindo a flag de banco de dados cloudsql_index_recreate_replica_group como o nome do grupo (por exemplo, reporting_group).

  4. Verifique o progresso da restauração:

    Conecte-se à instância da réplica de leitura e verifique o progresso da criação e o status dos índices.

    • Verifique o progresso da criação do índice em andamento:

      CALL mysql.cloudsql_replica_idx_show_status();

    • Verifique as tentativas com falha e as mensagens de erro:

      CALL mysql.cloudsql_replica_idx_show_errors();

    • Liste o status, os detalhes de nova tentativa e as durações de todos os índices gerenciados:

      CALL mysql.cloudsql_replica_idx_show_all();

Verificar o status do índice da réplica gerenciada

Para verificar o status de funcionamento da operação de índice, conecte-se à instância da réplica de leitura e consulte a tabela mysql.cloudsql_replica_idx_status:

SELECT * FROM mysql.cloudsql_replica_idx_status;

O resultado será o seguinte:

+--------+----------------------------------------------------+--------+-----------+---------------------+---------------------+-------------+---------+--------------------+---------+
| 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 |
+--------+----------------------------------------------------+--------+-----------+---------------------+---------------------+-------------+---------+--------------------+---------+

O Cloud SQL realiza a manutenção do índice de réplica gerenciada em lotes. Quando o Cloud SQL seleciona um grupo de ações CREATE ou DROP, ele cria uma entrada de status PENDING para cada índice e, em seguida, executa em série cada instrução de linguagem de definição de dados (DDL). Uma falha em um índice não bloqueia a execução dos índices subsequentes na fila. Em seguida, o Cloud SQL seleciona o próximo lote após aproximadamente cinco minutos.

Se a criação de um índice falhar, o Cloud SQL marcará o status como FAILED e tentará a operação novamente de forma automática após uma hora.

A tabela mysql.cloudsql_replica_idx_status contém todas as entradas de status da operação de índice e inclui as seguintes colunas:

  • idx_id: o identificador inteiro exclusivo da definição do índice.
  • create_stmt: a instrução SQL CREATE INDEX.
  • action: a operação que está sendo realizada (CREATE ou DROP).
  • thread_id: o ID da linha de execução do MySQL que executa a operação.
  • start_time: o carimbo de data/hora de quando a operação começou.
  • end_time: o carimbo de data/hora de quando a operação foi concluída.
  • retry_count: o número de tentativas de repetição da operação. O Cloud SQL tenta criar os índices que falharam após uma hora.
  • err_msg: a mensagem de erro da última operação que falhou.
  • comment_tag: a tag [SIC_X_Y] anexada ao comentário do índice. Essa tag é usada apenas para gerenciamento interno e não tem funcionalidade.
  • status: o status atual da operação:
    • PENDING: a operação de índice foi adicionada à fila.
    • RUNNING: a execução da operação de índice foi iniciada.
    • DONE: a operação de índice foi concluída.
    • FAILED: falha na operação de índice. O Cloud SQL tenta criar os índices com falha novamente após uma hora.

Remover índices de réplica gerenciados

Para remover um índice de um grupo de réplicas ou excluir totalmente uma definição de índice, chame o procedimento armazenado correspondente na instância principal:

  • Remova uma definição de índice de um grupo de réplicas:

    Chame mysql.cloudsql_replica_idx_group_drop na instância principal:

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

    Substitua:

    • INDEX_DEFINITION_ID: o ID de número inteiro exclusivo retornado quando você criou a definição do índice secundário.
    • GROUP_NAME: o nome do mapeamento do grupo de réplicas (por exemplo, reporting_group).

  • Excluir uma definição de índice:

    Chame mysql.cloudsql_replica_idx_defn_drop na instância principal:

    CALL mysql.cloudsql_replica_idx_defn_drop
(INDEX_DEFINITION_ID);

    Substitua:

    • INDEX_DEFINITION_ID: o ID inteiro exclusivo da definição de índice a ser excluída.

Para mais informações sobre procedimentos armazenados, consulte Procedimentos armazenados de índices de réplica gerenciados.

Modificar índices de réplica gerenciados

O Cloud SQL não permite atualizar ou alterar os metadados de índices atuais. Não é possível modificar diretamente uma definição de índice ou a instrução SQL dela.

Para modificar um índice de réplica gerenciada (por exemplo, para alterar colunas indexadas ou opções de índice), remova ou exclua a definição de índice atual e, em seguida, crie uma nova definição de índice.

Para modificar um índice de réplica gerenciada, siga estas etapas:

  1. Remova ou exclua a definição de índice atual na instância principal:

    • Para remover a definição de índice de um grupo de réplicas, chame mysql.cloudsql_replica_idx_group_drop:

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

    • Para excluir completamente a definição do índice, chame mysql.cloudsql_replica_idx_defn_drop:

      CALL mysql.cloudsql_replica_idx_defn_drop
(INDEX_DEFINITION_ID);

    Substitua:

    • INDEX_DEFINITION_ID: o ID inteiro exclusivo da definição de índice a ser removida ou excluída.
    • GROUP_NAME: o nome do mapeamento do grupo de réplicas (por exemplo, reporting_group).

  2. Crie uma nova definição de índice na instância principal:

    Chame mysql.cloudsql_replica_idx_defn_create com a instrução de índice atualizada:

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

    Substitua:

    • INDEX_DEFINITION_NAME: o nome da nova definição de índice.
    • CREATE_INDEX_STATEMENT: a instrução SQL atualizada que cria o índice secundário (por exemplo, CREATE INDEX idx_age ON university.students (age, name)).

    Anote o novo idx_id retornado na saída do procedimento armazenado.

  3. Mapeie a nova definição de índice para o grupo de réplicas:

    Chame mysql.cloudsql_replica_idx_group_add na instância principal:

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

    Substitua:

    • INDEX_DEFINITION_ID: o novo ID de número inteiro exclusivo retornado na etapa 2.
    • GROUP_NAME: o nome do mapeamento do grupo de réplicas (por exemplo, reporting_group).

Depois de mapear a nova definição de índice para o grupo de réplicas, o processo de manutenção em segundo plano descarta o índice atual da réplica de leitura e cria o novo índice na réplica usando a definição atualizada.

Flags de configuração do banco de dados para índices de réplica gerenciada

É possível personalizar o comportamento do índice de réplica gerenciada dinamicamente usando as seguintes flags globais de banco de dados:

  • cloudsql_index_recreate_enable: ativa ou desativa o processo de recriação. Por padrão, a flag é definida como on. Definir a flag como off encerra imediatamente as operações de manutenção de índice em andamento.

  • cloudsql_index_recreate_replica_group: nome do grupo de réplicas designado para a réplica (o padrão é NULL). Uma réplica só pode ser atribuída a um grupo de réplicas por vez. As réplicas criam todos os índices mapeados para esse nome de grupo de réplicas.

Índices de réplica autogerenciados

O Cloud SQL inclui dois procedimentos armazenados no esquema mysql que podem ser usados para adicionar e descartar índices secundários em uma réplica de leitura do MySQL. Embora esses procedimentos armazenados possam ser executados em uma instância de origem primária, eles são projetados para réplicas de leitura.

Esses índices não persistem se a réplica for recriada.

mysql.addSecondaryIdxOnReplica
Adiciona um índice secundário no banco de dados. Este procedimento armazenado é um wrapper para a instrução DDL CRIAR ÍNDICE.

Parâmetros:

  • idxType: tipo de índice a ser criado. Por exemplo, transmita UNIQUE para criar um índice exclusivo.
  • idxName: nome do índice.
  • tableName: nome da tabela no formato schema.name.
  • idxDefinition: definição do índice. Não inclua os parênteses externos.
  • idxOption: todas as outras opções para transmitir na criação do índice. Por exemplo, no MySQL 8.0, é possível transmitir a opção INVISIBLE para um índice invisível.

Sintaxe:

mysql.addSecondaryIdxOnReplica(idxType, idxName, tableName, idxDefinition, idxOption)
mysql.dropSecondaryIdxOnReplica
Descarta um índice secundário no banco de dados. Este procedimento armazenado é um wrapper para a instrução DDL DESCARTAR ÍNDICE

Parâmetros:

  • idxName: nome do índice.
  • tableName: nome da tabela no formato schema.name.
  • idxOption: todas as outras opções a serem transmitidas ao remover um índice. Por exemplo, uma opção de algoritmo como INPLACE.

Sintaxe:

mysql.dropSecondaryIdxOnReplica(idxName, tableName, idxOption)

Para os parâmetros idxType e idxOption, consulte a documentação da versão principal do MySQL em execução na instância do Cloud SQL.

Exemplos

Nesta seção, mostramos exemplos de como adicionar ou remover corretamente ou incorretamente índices de réplica autogerenciados.

Uso correto

Veja alguns exemplos de invocações dos procedimentos. Suponha que você tenha uma tabela com a seguinte definição:

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 você quiser criar um índice regular chamado t1_fname_lname nas colunas first_name e last_name, execute a seguinte instrução:

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

Se você também quiser criar um índice exclusivo chamado t1_license_id na coluna license_id com o comentário "ID de licença exclusivo", execute a seguinte instrução:

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

Se você quiser descartar o índice t1_fname_lname, execute a seguinte instrução:

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

uso incorreto

A tentativa a seguir de criar um índice nas colunas first_name e last_name falha devido aos parênteses externos no parâmetro idxDefinition:

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

Só é possível adicionar índices em tabelas criadas pelo cliente. A tentativa a seguir de criar um índice na coluna host da tabela mysql.servers falha:

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

Só é possível usar o procedimento dropSecondaryIdxOnReplica para descartar índices criados anteriormente usando o procedimento addSecondaryIdxOnReplica. Por exemplo, a seguinte chamada para descartar o índice idx_fname atual falha:

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

A injeção de SQL nessas chamadas de procedimento falha. Por exemplo, a seguinte injeção de SQL com uma sequência de comentários falha:

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

Da mesma forma, esta tentativa de injeção de SQL com um delimitador falha:

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

Migrar de índices de réplica autogerenciados para gerenciados

Embora os índices de réplica gerenciados e autogerenciados possam coexistir na mesma instância, é possível migrar para índices de réplica gerenciados.

Para migrar de índices de réplica autogerenciados para gerenciados, siga estas etapas:

  1. Registre as definições de índice na instância principal:

    Chame mysql.cloudsql_replica_idx_defn_create na instância principal para cada índice secundário:

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

    Anote o idx_id retornado (um identificador de número inteiro exclusivo para a definição) da saída do procedimento.

  2. Adicione a definição de índice a um grupo de réplicas:

    Mapeie a definição do índice para um nome de grupo de réplicas designado chamando mysql.cloudsql_replica_idx_group_add na instância principal:

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

  3. Configure a flag do grupo de réplicas na réplica de leitura:

    Defina a flag de banco de dados cloudsql_index_recreate_replica_group na instância da réplica de leitura para segmentar o nome do grupo:

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

    Verifique se o nome do grupo fornecido na flag de banco de dados cloudsql_index_recreate_replica_group corresponde exatamente ao nome do grupo especificado em mysql.cloudsql_replica_idx_group_add.

  4. Verifique ou faça a transição dos índices atuais:

    Como o índice já existe na réplica de leitura, talvez você veja erros com um status FAILED em mysql.cloudsql_replica_idx_status quando o processo em segundo plano tentar criar o índice. É possível escolher uma das seguintes abordagens:

    • Aguarde a recriação da réplica: é possível ignorar o status FAILED na tabela de status. O Cloud SQL recria automaticamente o índice secundário usando o método de índice de réplica gerenciada após um evento de recriação de réplica.

    • Transição imediata: se você quiser que o Cloud SQL gerencie o índice imediatamente sem esperar pela recriação de uma réplica, conecte-se à réplica de leitura e remova o índice autogerenciado usando o procedimento armazenado mysql.dropSecondaryIdxOnReplica:

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

      Durante o próximo ciclo de manutenção em segundo plano (aproximadamente a cada cinco minutos), o Cloud SQL recria e rastreia automaticamente o índice de réplica gerenciada.

Resolver problemas de índices de réplica

Para resolver problemas com índices de réplica, verifique o seguinte:

  • Verifique se os índices de réplica gerenciados estão ativados para a instância de réplica:

    Se você estiver usando índices de réplica gerenciados, verifique se a flag de banco de dados cloudsql_index_recreate_enable está definida como on na réplica de leitura.

    Para mais informações sobre como configurar flags de banco de dados, consulte Configurar flags de banco de dados.

  • Verifique o status de funcionamento e os erros:

    Conecte-se à réplica de leitura e consulte mysql.cloudsql_replica_idx_status ou execute CALL mysql.cloudsql_replica_idx_show_errors(); para ver as mensagens de erro de todas as operações com falha. Uma falha em um índice não bloqueia a execução dos índices subsequentes na fila.

A seguir