Guia Completo sobre a Função mysqli_thread_id em PHP

Quando você trabalha com bancos de dados MySQL em PHP, a extensão mysqli expõe muitas funções para gerenciar conexões e consultas. Uma delas é mysqli_thread_id(), que retorna o ID de thread — um número que o servidor MySQL atribui à sua conexão enquanto ela permanece aberta.

Este guia explica o que é esse ID de thread, quando ele é realmente útil, como chamar a função corretamente (nos estilos procedural e orientado a objetos) e as armadilhas a observar.

O que é a função mysqli_thread_id?

mysqli_thread_id() retorna o identificador único de conexão (thread) que o servidor MySQL atribuiu à conexão atual. O mesmo número é o que SELECT CONNECTION_ID() reporta, e é o valor que você passa para uma instrução KILL para encerrar uma conexão travada.

mysqli_thread_id(mysqli $mysql): int

• Parâmetro — $mysql: um objeto de conexão retornado por mysqli_connect() (ou uma instância new mysqli(...)).
• Valor de retorno — um int: o ID de thread para a conexão.

O ID é válido apenas durante o tempo de vida dessa conexão. Assim que a conexão é encerrada (ou cai e reconecta), o MySQL fornece um novo ID de thread — portanto, nunca o armazene em cache entre requisições nem presuma que ele é estável.

A chamada procedural mysqli_thread_id($connection) e o estilo orientado a objetos $connection->thread_id são equivalentes.

Quando devo usá-lo?

O ID de thread é uma ferramenta de diagnóstico e administração, não algo que a maioria dos códigos CRUD precisa. Utilize-o quando quiser:

• Encerrar uma conexão travada. Capture o ID e, em outra sessão, execute KILL <id> para abortar uma consulta de longa duração.
• Rastrear uma conexão no log de consultas lentas ou em SHOW PROCESSLIST, onde cada linha é identificada por esse mesmo ID.
• Depurar pool de conexões / conexões persistentes, pois ajuda a confirmar se você está reutilizando uma conexão ou abrindo uma nova.

Como usar mysqli_thread_id

1. Abrir uma conexão

mysqli_thread_id() precisa de uma conexão ativa, portanto conecte-se primeiro:

<?php

$host     = 'localhost';
$user     = 'username';
$password = 'password';
$database = 'mydatabase';

$connection = mysqli_connect($host, $user, $password, $database);

if (!$connection) {
    die('Connection failed: ' . mysqli_connect_error());
}

2. Ler o ID de thread

Com uma conexão válida em mãos, chame a função e utilize o valor:

<?php

$threadId = mysqli_thread_id($connection);
echo "Thread ID: " . $threadId; // e.g. Thread ID: 42

O equivalente orientado a objetos lê a propriedade em vez de chamar uma função:

<?php

$mysqli   = new mysqli($host, $user, $password, $database);
$threadId = $mysqli->thread_id;

echo "Thread ID: " . $threadId;

3. Usar o ID para encerrar a conexão (opcional)

Um uso comum no mundo real é capturar o ID para que uma outra sessão possa encerrar esta se ela travar:

<?php

$threadId = mysqli_thread_id($connection);

// From another connection you could now run:
//   KILL 42;
// mysqli_kill() does this for the current connection object:
mysqli_kill($connection, $threadId);

Armadilhas comuns

• Não armazene o ID em cache. Ele muda toda vez que a conexão é reestabelecida, portanto armazená-lo em uma sessão ou banco de dados não tem sentido após uma reconexão.
• Passe uma conexão válida. Chamar a função com uma conexão que falhou ou já foi encerrada dispara um aviso/erro — sempre verifique o resultado de mysqli_connect() primeiro, como mostrado acima.
• Ele identifica a conexão, não a requisição PHP. Dois scripts que compartilham uma conexão persistente podem reportar o mesmo ID de thread; duas requisições em conexões separadas serão diferentes.

Conclusão

mysqli_thread_id() fornece o identificador do servidor MySQL para a conexão atual — o mesmo valor usado por CONNECTION_ID(), SHOW PROCESSLIST e KILL. É uma ferramenta pequena, mas útil para monitorar, depurar e gerenciar conexões. Lembre-se de que o ID existe e morre com a conexão, portanto leia-o quando precisar em vez de armazená-lo em cache.

Para auxiliares de conexão relacionados, consulte Conectar ao MySQL e o guia mais abrangente Banco de Dados MySQL em PHP.

Prática