3.5.2 连接 URL 语法_连接器和 API 手册

连接器和 API 手册 / 第 3 章 MySQL Connector/J 开发人员指南 / 3.5 连接器/J 参考 / 3.5.2 连接 URL 语法

3.5.2 连接 URL 语法

本节解释用于连接到 MySQL 的 URL 的语法。

这是连接 URL 的通用格式：

protocol//[hosts][/database][?properties]

URL由以下部分组成：

重要的

出现在连接 URL 任何部分的 URL 的任何保留字符（例如，、、、、、和空格 /）都必须进行百分比编码。:@([]&#=?

`protocol`

有可能的连接协议：

jdbc:mysql:用于普通和基本的 JDBC 故障转移连接。
jdbc:mysql:loadbalance:用于负载平衡 JDBC 连接。有关详细信息，请参阅第 3.8.3 节，“使用连接器/J 配置负载平衡” 。
jdbc:mysql:replication:用于 JDBC 复制连接。有关详细信息，请参阅第 3.8.4 节，“使用连接器/J 配置源/副本复制” 。
mysqlx:用于 X DevAPI 连接。
jdbc:mysql+srv:适用于使用 DNS SRV 记录的普通和基本故障转移 JDBC 连接。
jdbc:mysql+srv:loadbalance:用于使用 DNS SRV 记录的负载平衡 JDBC 连接。
jdbc:mysql+srv:replication:用于使用 DNS SRV 记录的复制 JDBC 连接。
mysqlx+srv:适用于使用 DNS SRV 记录的 X DevAPI 连接。

`hosts`

根据情况的不同，hosts 部分可能只包含一个主机名，也可能是由各种元素组成的复杂结构，例如多个主机名、端口号、特定于主机的属性和用户凭据。

单主机：
- 不添加主机特定属性的单主机连接：
  - 该部分以:hosts的格式编写。这是一个简单的单主机连接 URL 的示例： hostport
    jdbc:mysql://host1:33060/sakila
  - host可以是 IPv4 或 IPv6 主机名字符串，在后一种情况下，它必须放在方括号内，例如 “ [1000:2000::abcd]”。”host未指定时，使用默认值 localhost 。
  - port是一个标准端口号，即1到65535之间的整数。普通MySQL连接的默认端口号是3306，使用X协议的连接是33060。如果 port未指定，则使用相应的默认值。
- 添加主机特定属性的单主机连接：
  - 在这种情况下，主机被定义为一连串的对。密钥用于识别主机、端口以及任何特定于主机的属性。有两种指定键的替代格式： key=value
    
    “地址等于”形式：
    address=(host=host_or_ip)(port=port)(key1=value1)(key2=value2)...(keyN=valueN)
    这是一个使用“ address-equals ”形式的示例 URL ：
    jdbc:mysql://address=(host=myhost)(port=1111)(key1=value1)/db
    “键值”形式：
    (host=host,port=port,key1=value1,key2=value2,...,keyN=valueN)
    这是一个使用“键值”形式的示例 URL ：
    jdbc:mysql://(host=myhost,port=1111,key1=value1)/db
  - 主机和端口由键 host和标识port。上面关于 Single host without host-specific propertieshost的格式和默认值的描述也适用于这里。 port
  - 可以添加的其他键包括 user、 password、 protocol等。properties 它们覆盖了 URL 部分中设置的全局值。将覆盖限制为用户、密码、网络超时以及语句和元数据缓存大小；其他每个主机覆盖的影响未定义。
  - 不同的协议可能需要不同的密钥。例如，该mysqlx:方案使用两个特殊键，address 和priority。 address是一个 host:port 对和priority一个整数。例如：
    mysqlx://(address=host:1111,priority=1,key1=value1)/db
  - key区分大小写。仅大小写不同的两个密钥被认为是冲突的，并且不能保证将使用哪一个。

多个主机

指定多个主机有两种格式：

在逗号分隔列表中列出主机：

host1,host2,...,hostN

每个主机都可以用上面单一主机中描述的三种方式中的任何一种来指定。这里有些例子：

jdbc:mysql://myhost1:1111,myhost2:2222/db
jdbc:mysql://address=(host=myhost1)(port=1111)(key1=value1),address=(host=myhost2)(port=2222)(key2=value2)/db
jdbc:mysql://(host=myhost1,port=1111,key1=value1),(host=myhost2,port=2222,key2=value2)/db
jdbc:mysql://myhost1:1111,(host=myhost2,port=2222,key2=value2)/db
mysqlx://(address=host1:1111,priority=1,key1=value1),(address=host2:2222,priority=2,key2=value2)/db

在逗号分隔的列表中列出主机，然后用方括号将列表括起来：
```
[host1,host2,...,hostN]
```
这称为主机子列表形式，它允许列表中的所有主机共享用户凭据，就好像它们是单个主机一样。列表中的每个主机都可以用上面单个主机中描述的三种方式中的任何一种来指定。这里有些例子：
```
jdbc:mysql://sandy:secret@[myhost1:1111,myhost2:2222]/db
jdbc:mysql://sandy:secret@[address=(host=myhost1)(port=1111)(key1=value1),address=(host=myhost2)(port=2222)(key2=value2)]/db
jdbc:mysql://sandy:secret@[myhost1:1111,address=(host=myhost2)(port=2222)(key2=value2)]/db
```
虽然不可能递归地编写主机子列表，但主机列表可以包含主机子列表作为其成员主机。

用户凭据
用户凭证可以在连接 URL 之外设置——例如，作为从获取连接时的参数 java.sql.DriverManager（有关详细信息，请参见第 3.5.3 节“配置属性” ）。当使用连接 URL 设置时，有几种方法可以指定它们：
- 在单个主机、主机子列表（请参阅多个主机）或具有用户凭据的主机列表中的任何主机前加上@：
```
 user:password@host_or_host_sublist
```
  例如：
```
mysqlx://sandy:secret@[(address=host1:1111,priority=1,key1=value1),(address=host2:2222,priority=2,key2=value2))]/db
```
- 使用密钥user和 password为每个主机指定凭据：
```
(user=sandy)(password=mypass)
```
  例如：
```
jdbc:mysql://[(host=myhost1,port=1111,user=sandy,password=secret),(host=myhost2,port=2222,user=finn,password=secret)]/db
jdbc:mysql://address=(host=myhost1)(port=1111)(user=sandy)(password=secret),address=(host=myhost2)(port=2222)(user=finn)(password=secret)/db
```
在这两种形式中，当指定多个用户凭据时，左边的凭据优先——也就是说，在连接字符串中从左到右，找到的第一个适用于主机的就是被使用的凭据。
在主机子列表中，任何主机都不能具有 @ 格式的用户凭据，但单个主机可以具有以密钥格式指定的用户凭据。

`database`

要打开的默认数据库或目录。如果未指定数据库，则不使用默认数据库建立连接。在这种情况下，要么调用实例setCatalog() 上的方法，要么在 SQL 语句中Connection使用数据库名称（即）指定表名称。在不指定要使用的数据库的情况下打开连接通常仅在构建使用多个数据库的工具（例如 GUI 数据库管理器）时有用。 SELECT dbname.tablename.colname FROM dbname.tablename...

笔记

在 JDBC 应用程序中始终使用Connection.setCatalog() 方法来指定所需的数据库，而不是语句。 USE database

`properties`

A succession of global properties applying to all hosts, preceded by ? and written as key=value pairs separated by the symbol “&.” Here are some examples:

jdbc:mysql://(host=myhost1,port=1111),(host=myhost2,port=2222)/db?key1=value1&key2=value2&key3=value3

The following are true for the key-value pairs:

key and value are just strings. Proper type conversion and validation are performed internally in Connector/J.
key is case-sensitive. Two keys differing in case only are considered conflicting, and it is uncertain which one will be used.
如上面的具有主机特定属性的单个主机和多个主机中所述，使用键值对指定的任何主机特定值会覆盖此处设置的全局值。

有关配置属性的详细信息，请参见第 3.5.3 节“配置属性” 。