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.