6.2.5 Connecting to the Server Using URI-Like Strings or Key-Value Pairs — MySQL 8.4

6.2.5 Подключение к серверу с использованием строк URI или пар «ключ-значение»

В этом разделе описывается использование строк подключения в формате URI или пар «ключ-значение» для указания параметров подключения к серверу MySQL, например, для клиентов, таких как MySQL Shell. Сведения о подключении с помощью параметров командной строки, например, для клиентов mysql или mysqldump, см. в разделе 6.2.4 «Подключение к серверу MySQL с использованием параметров командной строки». Дополнительную информацию о проблемах подключения см. в разделе 8.2.22 «Устранение неполадок при подключении к MySQL».

Примечание

Термин «“похожие на URI”» указывает на синтаксис строки подключения, который похож, но не идентичен синтаксису URI (унифицированного идентификатора ресурса), определенному в RFC 3986.

Следующие клиенты MySQL поддерживают подключение к серверу MySQL с использованием строки подключения в формате URI или пар «ключ-значение»:

MySQL Shell
Подключатели MySQL, реализующие X DevAPI

В этом разделе документированы все допустимые параметры подключения в формате строки URI и пар «ключ-значение», многие из которых аналогичны параметрам, задаваемым с помощью параметров командной строки:

Параметры, задаваемые строкой в формате URI, используют синтаксис, такой как myuser@example.com:3306/main-schema. Полный синтаксис см. в разделе «Подключение с использованием строк подключения в формате URI».
Параметры, задаваемые парами «ключ-значение», используют синтаксис, такой как {user:'myuser', host:'example.com', port:3306, schema:'main-schema'}. Полный синтаксис см. в разделе «Подключение с использованием пар „ключ-значение“».

Параметры подключения нечувствительны к регистру. Каждый параметр, если он задан, может быть указан только один раз. Если параметр задан более одного раза, возникает ошибка.

В этом разделе рассматриваются следующие темы:

Основные параметры подключения

Ниже описаны параметры, доступные при указании подключения к MySQL. Эти параметры можно задать, используя строку, соответствующую основному синтаксису URI (см. раздел «Подключение с использованием строк подключения в формате URI»), или в виде пар «ключ-значение» (см. раздел «Подключение с использованием пар „ключ-значение“»).

scheme: Протокол транспорта. Используйте mysqlx для подключений X Protocol и mysql для подключений к классическому протоколу MySQL. Если протокол не указан, сервер пытается определить протокол. Подключатели, поддерживающие DNS SRV, могут использовать схему mysqlx+srv (см. ).
user: Пользовательская учётная запись MySQL для процесса аутентификации.
password: Пароль для процесса аутентификации.

Предупреждение

Указание явного пароля в спецификации подключения небезопасно и не рекомендуется. Более позднее обсуждение покажет, как вызвать интерактивный запрос пароля.
host: Хост, на котором работает экземпляр сервера. Значение может быть именем хоста, IPv4-адресом или IPv6-адресом. Если хост не указан, значение по умолчанию — localhost.
port: TCP/IP-порт сети, на котором целевой сервер MySQL прослушивает подключения. Если порт не указан, значение по умолчанию — 33060 для подключений X Protocol и 3306 для подключений к классическому протоколу MySQL.
socket: Путь к файлу Unix-сокету или имя именованной трубы Windows. Значения — это локальные пути к файлам. В строках в формате URI они должны быть закодированы, используя либо кодировку процентов, либо заключая путь в скобки. Скобки устраняют необходимость в кодировке процентов таких символов, как разделитель каталогов /. Например, для подключения как root@localhost с использованием Unix-сокету /tmp/mysql.sock, укажите путь с кодировкой процентов как root@localhost?socket=%2Ftmp%2Fmysql.sock или с помощью скобок как root@localhost?socket=(/tmp/mysql.sock).
schema: База данных по умолчанию для подключения. Если база данных не указана, подключение не имеет базы данных по умолчанию.

Обработка localhost в Unix зависит от типа протокола транспорта. Подключения с использованием классического протокола MySQL обрабатывают localhost так же, как и другие клиенты MySQL, что означает, что localhost предполагается для подключений на основе сокетов. Для подключений с использованием протокола X, поведение localhost отличается тем, что оно предполагается для адреса обратной связи, например, IPv4-адрес 127.0.0.1.

Дополнительные параметры подключения

Вы можете указать параметры подключения, либо в качестве атрибутов в строке в формате URI, добавив ?attribute=value, либо в виде пар «ключ-значение». Доступны следующие параметры:

END_OF_DOCUMENT_MARKER

ssl-mode: Требуемое состояние безопасности для подключения. Допустимы следующие режимы:
- DISABLED
- PREFERRED
- REQUIRED
- VERIFY_CA
- VERIFY_IDENTITY
Важно

VERIFY_CA и VERIFY_IDENTITY являются лучшими вариантами, чем по умолчанию PREFERRED, поскольку они помогают предотвратить атаки «человек посередине».

Подробнее об этих режимах см. описание параметра --ssl-mode в Параметрах команд для зашифрованных подключений.
ssl-ca: Путь к файлу авторитетного центра сертификации X.509 в формате PEM.
ssl-capath: Путь к каталогу, содержащему файлы авторитетных центров сертификации X.509 в формате PEM.
ssl-cert: Путь к файлу сертификата X.509 в формате PEM.
ssl-cipher: Шифр шифрования, который следует использовать для подключений, использующих протоколы TLS до TLSv1.2 включительно.
ssl-crl: Путь к файлу, содержащему списки отзыва сертификатов в формате PEM.
ssl-crlpath: Путь к каталогу, содержащему файлы списков отзыва сертификатов в формате PEM.
ssl-key: Путь к файлу ключа X.509 в формате PEM.
tls-version: Протоколы TLS, разрешённые для зашифрованных подключений протокола MySQL. Этот параметр поддерживается только MySQL Shell. Значение tls-version (единственное число) представляет собой список, разделённый запятыми, например, TLSv1.2,TLSv1.3. Подробнее см. раздел 8.3.2, «Зашифрованные соединения TLS-протоколы и шифры». Этот параметр зависит от того, что параметр ssl-mode не установлен в DISABLED.
tls-versions: Разрешённые протоколы TLS для зашифрованных подключений X Protocol. Значение tls-versions (множественное число) представляет собой массив, например, [TLSv1.2,TLSv1.3]. Подробнее см. раздел 8.3.2, «Зашифрованные соединения TLS-протоколы и шифры». Этот параметр зависит от того, что параметр ssl-mode не установлен в DISABLED.
tls-ciphersuites: Разрешённые наборы шифров TLS. Значение tls-ciphersuites представляет собой список имён наборов шифров IANA, как указано в TLS Ciphersuites. Подробнее см. раздел 8.3.2, «Зашифрованные соединения TLS-протоколы и шифры». Этот параметр зависит от того, что параметр ssl-mode не установлен в DISABLED.
auth-method: Метод аутентификации, используемый для подключения. По умолчанию используется AUTO, что означает, что сервер пытается угадать. Допустимые методы:
- AUTO
- MYSQL41
- SHA256_MEMORY
- FROM_CAPABILITIES
- FALLBACK
- PLAIN
Для подключений X Protocol любой настроенный auth-method перезаписывается на эту последовательность методов аутентификации: MYSQL41, SHA256_MEMORY, PLAIN.
get-server-public-key: Запрос у сервера открытого ключа, необходимого для обмена паролем на основе пары ключей RSA. Используйте при подключении к серверам MySQL 8+ по классическому протоколу MySQL с режимом SSL DISABLED. В этом случае необходимо указать протокол. Например:
```
mysql://user@localhost:3306?get-server-public-key=true
```
Этот параметр применяется к клиентам, которые выполняют аутентификацию с помощью плагина аутентификации caching_sha2_password. Для этого плагина сервер не отправляет открытый ключ, если его не запросить. Этот параметр игнорируется для учётных записей, которые не выполняют аутентификацию с этим плагином. Он также игнорируется, если обмен паролем на основе RSA не используется, как в случае, когда клиент подключается к серверу с помощью защищённого соединения.

Если server-public-key-path=file_name указан и указывает на действительный файл открытого ключа, он имеет приоритет над get-server-public-key.

Подробнее о плагине caching_sha2_password см. в разделе 8.4.1.2, «Плагины аутентификации с кэшированием SHA-2».
server-public-key-path: Имя пути к файлу в формате PEM, содержащему копию клиентского открытого ключа, необходимую серверу для обмена паролем на основе пары ключей RSA. Используйте при подключении к серверам MySQL 8+ по классическому протоколу MySQL с режимом SSL DISABLED.

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

Если server-public-key-path=file_name указан и указывает на действительный файл открытого ключа, он имеет приоритет над get-server-public-key.

Подробнее об устаревшем плагине sha256_password и плагине caching_sha2_password см. в разделе 8.4.1.3, «Плагин аутентификации SHA-256» и разделе 8.4.1.2, «Плагины аутентификации с кэшированием SHA-2».
ssh: URI для подключения к SSH-серверу для доступа к экземпляру MySQL-сервера с помощью туннелирования SSH. Формат URI: [user@]host[:port]. Используйте параметр uri для указания URI целевого экземпляра MySQL-сервера. Подробнее о подключении через SSH-туннель из MySQL Shell см. .
uri: URI экземпляра MySQL-сервера, к которому необходимо получить доступ через SSH-туннель от сервера, указанного параметром ssh. Формат URI: [scheme://][user@]host[:port]. Не используйте базовые параметры подключения (scheme, user, host, port) для указания подключения к MySQL-серверу для туннелирования SSH, используйте только параметр uri.
ssh-password: Пароль для подключения к SSH-серверу.

Предупреждение

Указание явного пароля в спецификации подключения небезопасно и не рекомендуется. MySQL Shell запрашивает пароль интерактивно, когда он необходим.
ssh-config-file: Файл конфигурации SSH для подключения к SSH-серверу. Вы можете использовать параметр конфигурации MySQL Shell ssh.configFile для установки настраиваемого файла по умолчанию, если этот параметр не указан. Если ssh.configFile не установлен, по умолчанию используется стандартный файл конфигурации SSH ~/.ssh/config.
ssh-identity-file: Файл идентификации, который нужно использовать для подключения к SSH-серверу. По умолчанию, если этот параметр не указан, это любой файл идентификации, настроенный в агенте SSH (если используется), или в файле конфигурации SSH, или стандартный файл закрытого ключа в папке конфигурации SSH (~/.ssh/id_rsa).
ssh-identity-pass: Пароль к файлу идентификации, указанному параметром ssh-identity-file.

Предупреждение

Указание явного пароля в спецификации подключения небезопасно и не рекомендуется. MySQL Shell запрашивает пароль интерактивно, когда он необходим.
connect-timeout: Целочисленное значение, используемое для настройки количества секунд, в течение которых клиенты, такие как MySQL Shell, ожидают, прежде чем прекратить попытки подключения к неоткликающемуся MySQL-серверу.
compression: Этот параметр запрашивает или отключает сжатие для подключения.

Доступные значения для этого параметра: required, которое запрашивает сжатие и завершается ошибкой, если сервер его не поддерживает; preferred, которое запрашивает сжатие и переходит к несжатому подключению; и disabled, которое запрашивает несжатое подключение и завершается ошибкой, если сервер его не допускает. preferred является по умолчанию для подключений X Protocol, а disabled является по умолчанию для подключений по классическому протоколу MySQL. Подробнее о управлении сжатием подключений X Plugin см. в разделе 22.5.5, «Сжатие подключений с X Plugin».

Примечание

Разные MySQL-клиенты по-разному реализуют поддержку сжатия подключений. Обратитесь к документации вашего клиента для получения подробностей.
compression-algorithms и compression-level: Эти параметры доступны в MySQL Shell для большего контроля над сжатием подключения. Вы можете указать их для выбора алгоритма сжатия, используемого для подключения, и числового уровня сжатия, используемого с этим алгоритмом. Вы также можете использовать compression-algorithms вместо compression для запроса сжатия подключения. Подробнее о управлении сжатием подключений MySQL Shell см. .

connection-attributes: Управляет парами «ключ-значение», которые приложению передаются на сервер во время подключения. Дополнительную информацию об атрибутах подключения см. в разделе 29.12.9, «Таблицы атрибутов подключения Performance Schema». Клиенты обычно определяют набор атрибутов по умолчанию, который можно отключать или включать. Например:
```
mysqlx://user@host?connection-attributes
mysqlx://user@host?connection-attributes=true
mysqlx://user@host?connection-attributes=false
```
По умолчанию отправляется набор атрибутов по умолчанию. Приложения могут указать атрибуты, которые будут переданы дополнительно к атрибутам по умолчанию. Дополнительные атрибуты подключения указываются как параметр connection-attributes в строке подключения. Значение параметра connection-attributes должно быть пустым (что эквивалентно указанию true), значением Boolean (true или false для включения или выключения набора атрибутов по умолчанию) или списком из нуля или более key=value спецификаторов, разделенных запятыми (которые будут отправлены дополнительно к атрибутам по умолчанию). В списке отсутствующее значение ключа интерпретируется как пустая строка. Дополнительные примеры:
```
mysqlx://user@host?connection-attributes=[attr1=val1,attr2,attr3=]
mysqlx://user@host?connection-attributes=[]
```
Имена атрибутов, определенных приложением, не могут начинаться с _, так как такие имена зарезервированы для внутренних атрибутов.

Подключение с использованием строк подключения, похожих на URI

Вы можете указать подключение к MySQL Server с помощью строки подключения, похожей на URI. Такие строки можно использовать с MySQL Shell с опцией команды, командой MySQL Shell \connect и MySQL Connectors, которые реализуют X DevAPI.

Примечание

Термин “похожая на URI” означает синтаксис строки подключения, который аналогичен, но не идентичен синтаксису URI (унифицированного идентификатора ресурса), определённому в RFC 3986.

Строка подключения, похожая на URI, имеет следующий синтаксис:

[scheme://][user[:[password]]@]host[:port][/schema][?attribute1=value1&attribute2=value2...

Важно

Для зарезервированных символов в элементах строки подключения, похожей на URI, необходимо использовать кодировку процентов. Например, если вы указываете строку, содержащую символ @, этот символ необходимо заменить на %40. Если вы включаете идентификатор зоны в адрес IPv6, символ %, используемый в качестве разделителя, необходимо заменить на %25.

Параметры, которые можно использовать в строке подключения, похожей на URI, описаны в разделе «Базовые параметры подключения».

Методы MySQL Shell shell.parseUri() и shell.unparseUri() могут использоваться для разбора и сборки строки подключения, похожей на URI. Для строки подключения, похожей на URI, shell.parseUri() возвращает словарь, содержащий каждый элемент, найденный в строке. shell.unparseUri() преобразует словарь компонентов URI и параметров подключения в корректную строку подключения, похожую на URI, для подключения к MySQL, которую можно использовать в MySQL Shell или MySQL Connectors, реализующих X DevAPI.

Если пароль не указан в строке подключения, похожей на URI (что рекомендуется), интерактивные клиенты запрашивают пароль. Следующие примеры показывают, как указать строки подключения, похожие на URI, с именем пользователя user_name. В каждом случае пароль запрашивается.

Подключение по протоколу X к локальному экземпляру сервера, слушающему на порту 33065.
```
mysqlx://user_name@localhost:33065
```
Подключение по классическому протоколу MySQL к локальному экземпляру сервера, слушающему на порту 3333.
```
mysql://user_name@localhost:3333
```
Подключение по протоколу X к удалённому экземпляру сервера, используя имя хоста, IPv4-адрес и IPv6-адрес.
```
mysqlx://user_name@server.example.com/
mysqlx://user_name@198.51.100.14:123
mysqlx://user_name@[2001:db8:85a3:8d3:1319:8a2e:370:7348]
```
Подключение по протоколу X с использованием сокета, с путём, заданным с использованием кодировки процентов или скобок.
```
mysqlx://user_name@/path%2Fto%2Fsocket.sock
mysqlx://user_name@(/path/to/socket.sock)
```

Можно указать необязательный путь, который представляет базу данных.

# use 'world' as the default database
mysqlx://user_name@198.51.100.1/world

# use 'world_x' as the default database, encoding _ as %5F
mysqlx://user_name@198.51.100.2:33060/world%5Fx

Можно указать необязательный запрос, состоящий из значений, каждое из которых задано как пара «ключ-значение» или как одно key. Для указания нескольких значений разделяйте их символами ,. Разрешено смешивание значений key=value и key. Значения могут быть типа список, упорядоченного по порядку появления. Строки должны быть либо закодированы по процентам, либо заключены в скобки. Следующие варианты эквивалентны.
```
ssluser@127.0.0.1?ssl-ca=%2Froot%2Fclientcert%2Fca-cert.pem\
&ssl-cert=%2Froot%2Fclientcert%2Fclient-cert.pem\
&ssl-key=%2Froot%2Fclientcert%2Fclient-key

ssluser@127.0.0.1?ssl-ca=(/root/clientcert/ca-cert.pem)\
&ssl-cert=(/root/clientcert/client-cert.pem)\
&ssl-key=(/root/clientcert/client-key)
```

Для указания версии TLS и набора шифров для использования при зашифрованных подключениях:

mysql://user_name@198.51.100.2:3306/world%5Fx?\
tls-versions=[TLSv1.2,TLSv1.3]&tls-ciphersuites=[TLS_DHE_PSK_WITH_AES_128_\
GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256]

В предыдущих примерах предполагается, что для подключения требуется пароль. При использовании интерактивных клиентов пароль указанного пользователя запрашивается при входе в систему. Если у учётной записи пользователя нет пароля (что небезопасно и не рекомендуется), или если используется аутентификация сокета с проверкой подлинности (например, при подключениях к Unix-сокетам), вы должны явно указать в строке подключения, что пароль не предоставляется, и запрос пароля не требуется. Для этого разместите : после user_name в строке, но не указывайте пароль после неё. Например:

mysqlx://user_name:@localhost

Подключение с использованием пар «ключ-значение»

В MySQL Shell и некоторых MySQL Connectors, которые реализуют X DevAPI, вы можете указать подключение к MySQL Server с использованием пар «ключ-значение», представленных в естественных для языка конструкциях реализации. Например, вы можете передать параметры подключения с помощью пар «ключ-значение» как объект JSON в JavaScript или как словарь в Python. Независимо от способа передачи пар «ключ-значение», концепция остается неизменной: ключи, описанные в этом разделе, могут быть назначены значения, используемые для указания подключения. Вы можете указать подключения с использованием пар «ключ-значение» в методе MySQL Shell shell.connect() или методе InnoDB Cluster dba.createCluster(), а также в некоторых MySQL Connectors, которые реализуют X DevAPI.

Обычно пары «ключ-значение» заключены в символы { и }, а символ , используется в качестве разделителя между парами «ключ-значение». Символ : используется между ключом и значением, а строки должны быть ограничены (например, с помощью символа '). В отличие от строк подключения, похожих на URI, нет необходимости в кодировании процентов.

Подключение, заданное как пары «ключ-значение», имеет следующий формат:

{ key: value, key: value, ...}

Параметры, которые можно использовать в качестве ключей для подключения, описаны в разделе «Базовые параметры подключения».

Если пароль не указан в парах «ключ-значение» (что рекомендуется), интерактивные клиенты запрашивают пароль. Следующие примеры показывают, как указать подключения с использованием пар «ключ-значение» с именем пользователя 'user_name'. В каждом случае пароль запрашивается.

Подключение по протоколу X к локальному экземпляру сервера, слушающему на порту 33065.
```
{user:'user_name', host:'localhost', port:33065}
```
Подключение по классическому протоколу MySQL к локальному экземпляру сервера, слушающему на порту 3333.
```
{user:'user_name', host:'localhost', port:3333}
```
Подключение по протоколу X к удаленному экземпляру сервера, используя имя хоста, IPv4-адрес и IPv6-адрес.
```
{user:'user_name', host:'server.example.com'}
{user:'user_name', host:198.51.100.14:123}
{user:'user_name', host:[2001:db8:85a3:8d3:1319:8a2e:370:7348]}
```
Подключение по протоколу X с использованием сокета.
```
{user:'user_name', socket:'/path/to/socket/file'}
```
Можно указать необязательную схему, представляющую базу данных.
```
{user:'user_name', host:'localhost', schema:'world'}
```

В предыдущих примерах предполагается, что для подключения требуется пароль. При использовании интерактивных клиентов пароль указанного пользователя запрашивается при входе в систему. Если у учётной записи пользователя нет пароля (что небезопасно и не рекомендуется), или если используется аутентификация сокета с проверкой подлинности (например, при подключениях к Unix-сокетам), вы должны явно указать, что пароль не предоставляется, и запрос пароля не требуется. Для этого укажите пустую строку с помощью '' после ключа password. Например:

{user:'user_name', password:'', host:'localhost'}