connect_error

Функция mysqli_connect_error() возвращает string с описанием последней ошибки подключения, возникшей в MySQLi. Это первое, к чему нужно обратиться, когда mysqli_connect() завершается неудачей и нужно понять почему — неверный хост, неправильные учётные данные, отсутствующая база данных или недоступный сервер. На этой странице объясняется, что возвращает функция, чем она отличается от связанной mysqli_connect_errno(), и как правильно использовать её как в процедурном, так и в объектно-ориентированном API MySQLi.

Синтаксис

mysqli_connect_error() не принимает аргументов, потому что при неудачной попытке подключения не создаётся рабочий объект MySQLi — передавать нечего.

mysqli_connect_error(): string|null

Возвращаемое значение

• string с удобочитаемым сообщением об ошибке последнего вызова mysqli_connect() / mysqli_real_connect().
• null, если ошибки не было (подключение прошло успешно).

Поскольку при успехе возвращается null, вызывать функцию следует только после того, как подтверждено, что подключение не удалось.

Как использовать mysqli_connect_error() (процедурный стиль)

В процедурном API mysqli_connect() возвращает false при неудачном подключении. Сначала проверьте это возвращаемое значение, затем прочитайте сообщение:

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

Если учётные данные неверны, вы увидите что-то вроде:

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

Объектно-ориентированный стиль: connect_error и connect_errno

При создании подключения с помощью new mysqli(...) процедурный mysqli_connect_error() по-прежнему работает, однако более идиоматично читать соответствующие свойства объекта:

• $mysqli->connect_error — сообщение об ошибке (string или null при успехе).
• $mysqli->connect_errno — числовой код ошибки (целое число, 0 при успехе).

Числовой код удобен для ветвления по конкретному типу сбоя; сообщение предназначено для людей и журналов.

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

Подробное описание числового кода см. в mysqli_connect_errno().

Рекомендация: использовать исключения MySQLi

Проверять возвращаемое значение после каждого подключения вручную легко забыть. Начиная с PHP 8.1, MySQLi по умолчанию выбрасывает исключение mysqli_sql_exception при сбое, что позволяет обрабатывать ошибки обычным блоком try/catch. Это рекомендуемый подход для нового кода:

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

При включённом режиме исключений connect_error редко читается напрямую — сообщение передаётся внутри исключения.

Распространённые ошибки

• Не обращайтесь к свойству объекта подключения, который не удалось получить. При неудачном процедурном подключении $mysqli равен false, поэтому $mysqli->connect_error вызовет ошибку. Используйте в таком случае самостоятельную функцию mysqli_connect_error() (без аргументов).
• Отражается последняя попытка. Если открывается несколько подключений, значение относится к самому последнему вызову connect, а не к конкретному дескриптору.
• Никогда не выводите сырые ошибки конечным пользователям в продакшене. Сообщения о подключении могут раскрывать имена хостов и пользователей — записывайте их в журнал и показывайте пользователю обобщённое сообщение.

Заключение

mysqli_connect_error() — небольшой, но незаменимый инструмент отладки: он точно сообщает, почему не удалось подключиться к MySQLi. Используйте его вместе с mysqli_connect_errno(), когда нужен числовой код; предпочитайте свойства OO connect_error/connect_errno при подключении через new mysqli(); в новых проектах выбирайте обработку ошибок на основе исключений. Подробнее об открытии подключений см. в mysqli_connect() и обзоре MySQLi.

Практика