5.4.58 mysql_real_connect()

MYSQL *
mysql_real_connect(MYSQL *mysql,
                   const char *host,
                   const char *user,
                   const char *passwd,
                   const char *db,
                   unsigned int port,
                   const char *unix_socket,
                   unsigned long client_flag)

Описание

Примечание

mysql_real_connect() — это синхронная функция. Её асинхронный аналог — mysql_real_connect_nonblocking(), предназначенный для приложений, требующих асинхронного взаимодействия с сервером. См. Главу 7, C API Асинхронный интерфейс.

Для подключения с использованием записи DNS SRV используйте mysql_real_connect_dns_srv(). См. Раздел 5.4.59, «mysql_real_connect_dns_srv()».

mysql_real_connect() пытается установить соединение с сервером MySQL, работающим на host. Программы-клиенты должны успешно подключиться к серверу перед выполнением любых других функций API, требующих корректного обработчика соединения MYSQL.

Укажите аргументы следующим образом:

В качестве первого аргумента укажите адрес существующей структуры MYSQL. Перед вызовом mysql_real_connect() вызовите mysql_init() для инициализации структуры MYSQL. Вы можете изменить множество параметров подключения с помощью вызова mysql_options(). См. Раздел 5.4.54, «mysql_options()».
Значение host может быть именем хоста или IP-адресом. Клиент пытается подключиться следующим образом:
- Если host равно NULL или строке "localhost", предполагается подключение к локальному хосту:
  - В Windows клиент подключается с использованием соединения с общей памятью, если сервер поддерживает соединения с общей памятью.
  - В Unix клиент подключается с использованием файла сокета Unix. Имя сокета можно указать с помощью аргумента unix_socket или переменной окружения MYSQL_UNIX_PORT.
- В Windows, если host равно ".", или TCP/IP не включен и не указан unix_socket или хост пуст, клиент подключается через именованную трубу, если сервер поддерживает именованные соединения через трубы. Если они не поддерживаются, произойдёт ошибка.
- В противном случае используется TCP/IP.
Вы также можете повлиять на тип соединения с помощью параметров MYSQL_OPT_PROTOCOL или MYSQL_OPT_NAMED_PIPE для mysql_options(). Тип соединения должен поддерживаться сервером.
Аргумент user содержит идентификатор пользователя MySQL. Если user равно NULL или пустой строке "", предполагается текущий пользователь. В Unix это текущее имя входа. В Windows ODBC текущее имя пользователя нужно указать явно. См. раздел Connector/ODBC.
Аргумент passwd содержит пароль для user. Если passwd равно NULL, проверяются только записи в таблице user для пользователя, у которого поле пароля пустое. Это позволяет администратору базы данных настроить систему привилегий MySQL таким образом, что пользователи получают разные права в зависимости от того, указан ли пароль.

Примечание

Не пытайтесь зашифровать пароль перед вызовом mysql_real_connect(); шифрование пароля выполняется автоматически API-клиентом.
Аргументы user и passwd используют кодировку символов, настроенную для объекта MYSQL. По умолчанию это utf8mb4, но может быть изменено вызовом mysql_options(mysql, MYSQL_SET_CHARSET_NAME, "charset_name") до подключения.
db — имя базы данных. Если db не равно NULL, подключение устанавливает базу данных по умолчанию на это значение.
Если port не равно 0, значение используется в качестве номера порта для TCP/IP соединения. Обратите внимание, что аргумент host определяет тип соединения.
Если unix_socket не равно NULL, строка указывает сокет или именованную трубу для использования. Обратите внимание, что аргумент host определяет тип соединения.
Значение client_flag обычно равно 0, но может быть установлено в комбинацию флагов для активации определённых функций:
- CAN_HANDLE_EXPIRED_PASSWORDS: Клиент может обрабатывать истекшие пароли. Для получения дополнительной информации см.
- CLIENT_COMPRESS: Использовать сжатие в протоколе клиент/сервер.
- CLIENT_FOUND_ROWS: Возвратить количество найденных (совпавших) строк, а не изменённых.
- CLIENT_IGNORE_SIGPIPE: Препятствует установке обработчика сигналов SIGPIPE библиотекой клиента. Это может быть использовано для предотвращения конфликтов с обработчиком, уже установленным приложением.
- CLIENT_IGNORE_SPACE: Разрешить пробелы после имён функций. Делает все имена функций зарезервированными словами.
- CLIENT_INTERACTIVE: Разрешить секунд бездействия (вместо секунд) перед закрытием соединения. Переменная сессии клиента устанавливается в значение переменной сессии.
- CLIENT_LOCAL_FILES: Включить обработку.
- CLIENT_MULTI_RESULTS: Сообщить серверу, что клиент может обрабатывать несколько наборов результатов при выполнении нескольких инструкций или хранимых процедур. Этот флаг автоматически включается, если включен CLIENT_MULTI_STATEMENTS. См. примечание после этой таблицы для получения дополнительной информации об этом флаге.
- CLIENT_MULTI_STATEMENTS: Сообщить серверу, что клиент может отправлять несколько инструкций в одной строке (разделенные ; символами). Если этот флаг не установлен, выполнение нескольких инструкций отключено. См. примечание после этой таблицы для получения дополнительной информации об этом флаге.
- CLIENT_NO_SCHEMA: Не разрешать синтаксис db_name.tbl_name.col_name. Это для ODBC. Приводит к ошибке парсера, если используется этот синтаксис, что полезно для отладки некоторых программ ODBC.
  
  Начиная с MySQL 8.0.32, флаг CLIENT_NO_SCHEMA устарел. Программы-клиенты могут опустить этот флаг и аргумент db, чтобы подключение установило значение базы данных на текущую (или по умолчанию).
- CLIENT_ODBC: Не используется.
- CLIENT_OPTIONAL_RESULTSET_METADATA: Этот флаг делает метаданные набора результатов необязательными. Подавление передачи метаданных может улучшить производительность, особенно для сеансов, выполняющих много запросов, каждый из которых возвращает мало строк. Подробнее о управлении передачей метаданных набора результатов см. Раздел 3.6.7, «Необязательные метаданные набора результатов».
- CLIENT_SSL: Использовать SSL (зашифрованный протокол). Не устанавливайте этот параметр в программе-приложении; он устанавливается внутри библиотеки клиента. Вместо этого используйте mysql_options() перед вызовом mysql_real_connect().
- CLIENT_REMEMBER_OPTIONS: Запомнить параметры, указанные в вызовах mysql_options(). Без этого флага, если mysql_real_connect() завершится неудачно, необходимо повторить вызовы mysql_options() перед повторной попыткой подключения. С этим флагом вызовы mysql_options() повторять не нужно.

Если ваша программа использует инструкции для выполнения хранимых процедур, флаг CLIENT_MULTI_RESULTS должен быть включён. Это потому, что каждая возвращает результат, указывающий статус вызова, помимо любых наборов результатов, которые могут быть возвращены инструкциями, выполняемыми внутри процедуры. Поскольку может возвращать несколько результатов, обрабатывайте их с помощью цикла, вызывающего mysql_next_result(), чтобы определить, есть ли ещё результаты.

CLIENT_MULTI_RESULTS может быть включено при вызове mysql_real_connect(), как явно, передавая флаг CLIENT_MULTI_RESULTS, так и неявно, передавая CLIENT_MULTI_STATEMENTS (что также включает CLIENT_MULTI_RESULTS). CLIENT_MULTI_RESULTS включен по умолчанию.

Если включены CLIENT_MULTI_STATEMENTS или CLIENT_MULTI_RESULTS, обрабатывайте результат для каждого вызова mysql_real_query() или mysql_query(), используя цикл, вызывающий mysql_next_result(), чтобы определить, есть ли ещё результаты. Пример см. в Разделе 3.6.3, «Поддержка выполнения нескольких инструкций».

Для некоторых аргументов возможно использование значения из файла параметров вместо явного значения в вызове mysql_real_connect(). Для этого вызовите mysql_options() с параметром MYSQL_READ_DEFAULT_FILE или MYSQL_READ_DEFAULT_GROUP перед вызовом mysql_real_connect(). Затем в вызове mysql_real_connect() укажите значение “no-value” для каждого аргумента, который должен быть прочитан из файла параметров:

Для host, укажите значение NULL или пустую строку ("").
Для user, укажите значение NULL или пустую строку.
Для passwd, укажите значение NULL. (Для пароля, значение пустой строки в вызове mysql_real_connect() не может быть переопределено в файле параметров, так как пустая строка явно указывает, что у учётной записи MySQL должен быть пустой пароль.)
Для db, укажите значение NULL или пустую строку.
Для port, укажите значение 0.
Для unix_socket, укажите значение NULL.

Если в файле параметров не найдено значение для аргумента, используется его значение по умолчанию, как указано в описаниях ранее в этом разделе.

Значения возврата

Обработчик соединения MYSQL*, если подключение было успешным, NULL, если подключение не удалось. Для успешного подключения возвращаемое значение равно значению первого аргумента.

Ошибки

Не удалось подключиться к серверу MySQL.
Не удалось подключиться к локальному серверу MySQL.
Не удалось создать IP-сокет.
Нет памяти.
Не удалось создать Unix-сокет.
Не удалось найти IP-адрес для имени хоста.
Произошел несоответствие протокола в результате попытки подключения к серверу с библиотекой клиента, которая использует другую версию протокола.
Не удалось создать именованную трубу в Windows.
Не удалось дождаться именованной трубы в Windows.
Не удалось получить обработчик трубы в Windows.
Если > 0 и подключение к серверу заняло больше чем секунд или сервер вышел из строя во время выполнения init-command.
Обработчик соединения MYSQL уже подключен.

Пример

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&mysql));
}

Используя mysql_options(), библиотека клиента MySQL читает секции [client] и [your_prog_name] в файле my.cnf. Это позволяет добавить параметры в секцию [your_prog_name], чтобы обеспечить работу программы даже в случае нестандартной настройки MySQL.