connect_errno

A função mysqli_connect_errno() retorna o código de erro da última tentativa de conexão MySQLi, ou 0 se nenhum erro ocorreu. É a forma padrão de verificar se uma chamada a mysqli_connect() (ou o construtor new mysqli()) foi bem-sucedida antes de executar qualquer consulta. Esta página aborda sua sintaxe, valor de retorno, como ela difere de funções relacionadas e os detalhes importantes a observar.

Por que verificar a conexão é importante

Quando uma conexão MySQLi falha, o identificador $mysqli ainda é retornado, mas não pode ser usado. Se você pular a verificação e executar uma consulta imediatamente, o PHP emite um aviso e seu script continua com uma conexão inválida — frequentemente gerando erros confusos mais adiante. Chamar mysqli_connect_errno() logo após a conexão permite falhar rapidamente com uma mensagem clara.

Um detalhe importante: mysqli_connect_errno() é uma função independente. Você a chama sem argumentos — ela lê o estado global da tentativa de conexão mais recente, não um objeto de conexão específico.

Sintaxe

mysqli_connect_errno(): int

O código numérico corresponde a um número de erro do cliente MySQL/MariaDB — por exemplo, 1045 para acesso negado ou 2002 para conexão recusada. Para a mensagem legível, use-o em conjunto com mysqli_connect_error().

Uso básico (estilo procedural)

Chame a função imediatamente após mysqli_connect() e encerre cedo se o retorno for diferente de zero:

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

Se as credenciais estiverem erradas, isso imprime algo como Failed to connect to MySQL: Access denied for user 'username'@'localhost' e para. Em caso de sucesso, imprime Connected successfully.. Como o código de erro só é verdadeiro quando diferente de zero, if (mysqli_connect_errno()) se lê naturalmente como "se ocorreu um erro".

Estilo orientado a objetos

Quando você usa a classe mysqli, o equivalente de mysqli_connect_errno() é a propriedade connect_errno do objeto. Leia-a da mesma forma — logo após a construção:

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

Aqui, $mysqli->connect_errno contém o código numérico e $mysqli->connect_error contém a mensagem — combiná-los (por exemplo, (1045) Access denied...) facilita a busca em logs.

connect_errno vs. funções relacionadas

É fácil confundir as funções de erro de conexão com as funções gerais de erro do MySQLi. Elas reportam coisas diferentes:

Em resumo: use connect_errno/connect_error para o handshake, e errno/error para consultas uma vez conectado.

Armadilhas comuns

• Reflete apenas a tentativa mais recente. Se você abrir várias conexões, mysqli_connect_errno() reporta a última delas. Para precisão por objeto em código OO, prefira $mysqli->connect_errno.
• Verifique antes da primeira consulta, não depois. Depois de executar uma consulta, mysqli_connect_errno() ainda reflete a tentativa de conexão, mas confundi-lo com mysqli_errno() gera bugs.
• Uma verificação de valor verdadeiro é suficiente. Raramente você precisa comparar o código a um número específico; if (mysqli_connect_errno()) cobre todas as falhas.
• Considere usar exceções. Desde o PHP 8.1, o MySQLi lança mysqli_sql_exception em erros por padrão (mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT)), então uma conexão com falha gera uma exceção em vez de retornar um identificador inválido. Nesse modo, envolva a conexão em try/catch em vez de verificar connect_errno.

Funções relacionadas

• mysqli_connect() — abre uma conexão.
• mysqli_connect_error() — mensagem do último erro de conexão.
• mysqli_real_connect() — abre uma conexão com opções adicionais.
• Visão geral da extensão MySQLi — contexto mais amplo sobre MySQLi.

Conclusão

mysqli_connect_errno() é a verificação mais rápida e confiável de que uma conexão MySQLi foi aberta corretamente: um retorno diferente de zero significa que o handshake falhou; 0 significa que você pode executar consultas. Use-o junto com mysqli_connect_error() para mensagens legíveis, mantenha-o distinto do mysqli_errno() em nível de consulta e, no PHP 8.1+, considere try/catch com modo de exceção como alternativa moderna.

Prática