connect_error

A função mysqli_connect_error() retorna uma string que descreve o último erro de conexão gerado pelo MySQLi. É o primeiro recurso a ser utilizado quando mysqli_connect() falha e você precisa saber o motivo — host incorreto, credenciais inválidas, banco de dados inexistente ou servidor inacessível. Esta página explica o que a função retorna, como ela difere da relacionada mysqli_connect_errno(), e como utilizá-la corretamente tanto na API MySQLi procedural quanto na orientada a objetos.

Sintaxe

mysqli_connect_error() não recebe argumentos porque, por design, uma tentativa de conexão malsucedida não produz um objeto MySQLi utilizável — portanto, não há nada a ser passado para ela.

mysqli_connect_error(): string|null

Valor de retorno

• Uma string com a mensagem de erro legível por humanos da chamada mais recente a mysqli_connect() / mysqli_real_connect().
• null se nenhum erro ocorreu (a conexão foi bem-sucedida).

Como retorna null em caso de sucesso, você deve chamá-la apenas depois de confirmar que a conexão falhou.

Como usar mysqli_connect_error() (estilo procedural)

Na API procedural, mysqli_connect() retorna false quando a conexão falha. Verifique esse valor de retorno primeiro e, em seguida, leia a mensagem:

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

if (!$mysqli) {
    // Connection failed — mysqli_connect_error() now holds the reason
    echo "Failed to connect to MySQL: " . mysqli_connect_error();
    exit();
}

echo "Connected successfully";

// ... run your queries here ...

mysqli_close($mysqli);
?>

Se as credenciais estiverem incorretas, você verá algo como:

Failed to connect to MySQL: Access denied for user 'username'@'localhost' (using password: YES)

Estilo orientado a objetos: connect_error vs connect_errno

Ao criar a conexão com new mysqli(...), o procedural mysqli_connect_error() ainda funciona, mas é mais idiomático ler as propriedades correspondentes no objeto:

• $mysqli->connect_error — a mensagem de erro (string, ou null em caso de sucesso).
• $mysqli->connect_errno — o número do erro (um código inteiro, 0 em caso de sucesso).

O número é útil para ramificar em uma falha específica; a mensagem é para humanos e logs.

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

$mysqli->close();
?>

Para uma análise completa do código numérico, consulte mysqli_connect_errno().

Recomendado: deixar o MySQLi lançar exceções

Verificar manualmente o valor de retorno após cada conexão é fácil de esquecer. Desde o PHP 8.1, o MySQLi lança uma mysqli_sql_exception em caso de falha por padrão, permitindo tratar erros com um bloco try/catch normal. Este é o padrão recomendado para código novo:

<?php
// Enable exception mode explicitly (the default since PHP 8.1)
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

try {
    $mysqli = new mysqli("localhost", "username", "password", "database");
    echo "Connected successfully";
    $mysqli->close();
} catch (mysqli_sql_exception $e) {
    // $e->getMessage() carries the same text connect_error would return
    echo "Failed to connect to MySQL: " . $e->getMessage();
    exit();
}
?>

Com o modo de exceção ativado, connect_error raramente é lido diretamente — a mensagem é transportada dentro da exceção.

Armadilhas comuns

• Não o chame no objeto de conexão que você não conseguiu obter. Em uma conexão procedural malsucedida, $mysqli é false, portanto $mysqli->connect_error geraria um erro. Use o standalone mysqli_connect_error() (sem argumento) nesse caso.
• Ele reflete a última tentativa. Se você abrir várias conexões, o valor pertence à chamada de conexão mais recente, não a um handle específico.
• Nunca exiba erros brutos para usuários finais em produção. Mensagens de conexão podem vazar nomes de host e nomes de usuário — registre-os em log e exiba uma mensagem genérica.

Conclusão

mysqli_connect_error() é uma ferramenta de depuração pequena, mas essencial: ela informa exatamente por que uma conexão MySQLi falhou. Use-a junto com mysqli_connect_errno() quando precisar do código numérico, prefira as propriedades OO connect_error/connect_errno ao conectar com new mysqli(), e para novos projetos opte pelo tratamento de erros baseado em exceções. Para saber mais sobre como abrir conexões, consulte mysqli_connect() e a visão geral do MySQLi.

Prática