connect_errno

La función mysqli_connect_errno() devuelve el código de error del último intento de conexión MySQLi, o 0 si no se produjo ningún error. Es la forma estándar de comprobar si una llamada a mysqli_connect() (o al constructor new mysqli()) tuvo éxito antes de ejecutar cualquier consulta. Esta página cubre su sintaxis, valor de retorno, diferencias con funciones relacionadas y los errores comunes a tener en cuenta.

Por qué es importante comprobar la conexión

Cuando una conexión MySQLi falla, el manejador $mysqli se devuelve igualmente, pero no es utilizable. Si omites la verificación y ejecutas una consulta de inmediato, PHP emite una advertencia y el script continúa ejecutándose con una conexión rota, lo que suele generar errores confusos más adelante. Llamar a mysqli_connect_errno() justo después de conectarte te permite fallar rápidamente con un mensaje claro.

Un detalle clave: mysqli_connect_errno() es una función independiente. Se llama sin argumentos — lee el estado global del intento de conexión más reciente, no un objeto de conexión específico.

Sintaxis

mysqli_connect_errno(): int

El código numérico corresponde a un número de error del cliente MySQL/MariaDB — por ejemplo 1045 para acceso denegado o 2002 para conexión rechazada. Para obtener el mensaje legible por humanos, combínalo con mysqli_connect_error().

Uso básico (estilo procedural)

Llama a la función inmediatamente después de mysqli_connect() y sal pronto si el valor es distinto de cero:

<?php
$mysqli = mysqli_connect("localhost", "username", "password", "database");

if (mysqli_connect_errno()) {
    echo "Failed to connect to MySQL: " . mysqli_connect_error();
    exit();
}

echo "Connected successfully.";
// execute queries using $mysqli

mysqli_close($mysqli);
?>

Si las credenciales son incorrectas, esto imprime algo como Failed to connect to MySQL: Access denied for user 'username'@'localhost' y se detiene. En caso de éxito, imprime Connected successfully. Como el código de error es verdadero solo cuando es distinto de cero, if (mysqli_connect_errno()) se lee de forma natural como "si ocurrió un error."

Estilo orientado a objetos

Cuando usas la clase mysqli, el equivalente de mysqli_connect_errno() es la propiedad connect_errno del objeto. Léela de la misma manera — justo después de la construcción:

<?php
$mysqli = new mysqli("localhost", "username", "password", "database");

if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
    exit();
}

echo "Connected successfully.";
// execute queries using $mysqli

$mysqli->close();
?>

Aquí $mysqli->connect_errno contiene el código numérico y $mysqli->connect_error contiene el mensaje — combinarlos (p. ej. (1045) Access denied...) facilita la búsqueda en los registros de log.

connect_errno frente a funciones relacionadas

Es fácil confundir las funciones de error de conexión con las funciones generales de error de MySQLi. Cada una informa sobre cosas distintas:

En resumen: usa connect_errno/connect_error para el protocolo de enlace, y errno/error para las consultas una vez que estés conectado.

Errores comunes a evitar

• Solo refleja el intento más reciente. Si abres varias conexiones, mysqli_connect_errno() informa sobre la última. Para mayor precisión por objeto en código OO, prefiere $mysqli->connect_errno.
• Compruébalo antes de la primera consulta, no después. Una vez que ejecutas una consulta, mysqli_connect_errno() sigue reflejando el intento de conexión, pero confundirlo con mysqli_errno() genera errores.
• Una comprobación de verdad es suficiente. Rara vez necesitas comparar el código con un número específico; if (mysqli_connect_errno()) cubre cualquier fallo.
• Considera usar excepciones en su lugar. Desde PHP 8.1, MySQLi lanza mysqli_sql_exception en caso de errores por defecto (mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT)), por lo que una conexión fallida lanza una excepción en lugar de devolver un manejador inválido. En ese modo, envuelves la conexión en try/catch en lugar de consultar connect_errno.

Funciones relacionadas

• mysqli_connect() — abrir una conexión.
• mysqli_connect_error() — mensaje del último error de conexión.
• mysqli_real_connect() — abrir una conexión con opciones adicionales.
• Descripción general de la extensión MySQLi — contexto más amplio sobre MySQLi.

Conclusión

mysqli_connect_errno() es la forma más rápida y fiable de verificar que una conexión MySQLi se abrió correctamente: un valor de retorno distinto de cero significa que el protocolo de enlace falló, mientras que 0 indica que puedes ejecutar consultas. Combínala con mysqli_connect_error() para obtener mensajes legibles, mantenla separada de mysqli_errno() a nivel de consulta, y en PHP 8.1+ considera el uso de try/catch con el modo de excepción como alternativa moderna.

Práctica