Guía completa de la función mysqli_thread_id en PHP

Cuando trabajas con bases de datos MySQL en PHP, la extensión mysqli expone muchas funciones para gestionar conexiones y consultas. Una de ellas es mysqli_thread_id(), que devuelve el ID de hilo — un número que el servidor MySQL asigna a tu conexión mientras permanece abierta.

Esta guía explica qué es ese ID de hilo, cuándo resulta realmente útil, cómo llamar a la función correctamente (tanto en estilo procedimental como orientado a objetos) y los errores comunes que debes evitar.

¿Qué es la función mysqli_thread_id?

mysqli_thread_id() devuelve el identificador único de conexión (hilo) que el servidor MySQL ha asignado a la conexión actual. Este mismo número es el que reporta SELECT CONNECTION_ID(), y es el valor que se pasa a una instrucción KILL para terminar una conexión bloqueada.

mysqli_thread_id(mysqli $mysql): int

• Parámetro — $mysql: un objeto de conexión devuelto por mysqli_connect() (o una instancia de new mysqli(...)).
• Valor de retorno — un int: el ID de hilo para la conexión.

El ID solo es válido durante el tiempo de vida de esa conexión. En cuanto la conexión se cierra (o se cae y se reconecta), MySQL asigna un nuevo ID de hilo — por eso nunca lo almacenes en caché entre solicitudes ni asumas que es estable.

La llamada procedimental mysqli_thread_id($connection) y el estilo orientado a objetos $connection->thread_id son equivalentes.

¿Cuándo lo usaría?

El ID de hilo es una herramienta de diagnóstico y administración, no algo que la mayoría del código CRUD necesita. Úsalo cuando quieras:

• Terminar una conexión bloqueada. Captura el ID y luego, desde otra sesión, ejecuta KILL <id> para abortar una consulta de larga duración.
• Rastrear una conexión en el registro de consultas lentas o en SHOW PROCESSLIST, donde cada fila se identifica por este mismo ID.
• Depurar la agrupación de conexiones / conexiones persistentes, donde ayuda a confirmar si estás reutilizando una conexión o abriendo una nueva.

Cómo usar mysqli_thread_id

1. Abrir una conexión

mysqli_thread_id() necesita una conexión activa, así que conéctate primero:

<?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. Leer el ID de hilo

Con una conexión válida a mano, llama a la función y utiliza el valor:

<?php

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

El equivalente orientado a objetos lee la propiedad en lugar de llamar a una función:

<?php

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

echo "Thread ID: " . $threadId;

3. Usar el ID para terminar la conexión (opcional)

Un uso común en la vida real es obtener el ID para que una sesión diferente pueda terminar esta si se bloquea:

<?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);

Errores comunes

• No almacenes el ID en caché. Cambia cada vez que se restablece la conexión, por lo que guardarlo en una sesión o base de datos no tiene sentido después de una reconexión.
• Pasa una conexión válida. Llamar a la función con una conexión fallida o ya cerrada genera una advertencia/error — comprueba siempre el resultado de mysqli_connect() primero, como se muestra arriba.
• Identifica la conexión, no la solicitud PHP. Dos scripts que comparten una conexión persistente pueden reportar el mismo ID de hilo; dos solicitudes en conexiones separadas diferirán.

Conclusión

mysqli_thread_id() te proporciona el identificador del servidor MySQL para la conexión actual — el mismo valor utilizado por CONNECTION_ID(), SHOW PROCESSLIST y KILL. Es una herramienta pequeña pero útil para monitorizar, depurar y gestionar conexiones. Recuerda que el ID vive y muere con la conexión, así que léelo cuando lo necesites en lugar de almacenarlo en caché.

Para helpers de conexión relacionados, consulta Conectar a MySQL y la guía más amplia sobre Base de datos PHP MySQL.

Práctica