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

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. Значение 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 все настроенные 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.1, «Плагин аутентификации Caching 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.2, «Плагин аутентификации SHA-256» и разделе 8.4.1.1, «Плагин аутентификации Caching 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, а disabled — значение по умолчанию для подключений по классическому протоколу MySQL. Подробнее о контроле сжатия подключений с помощью плагина X см. в разделе 22.5.5, «Сжатие подключений с помощью плагина X».

Примечание

Разные клиенты 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'}