Skip to content

Latest commit

 

History

History
265 lines (169 loc) · 13.3 KB

6.2_Connection_URL_Syntax.md

File metadata and controls

265 lines (169 loc) · 13.3 KB

6.2 Connection URL Syntax

6.2 Connection URL的格式

This section explains the syntax of the URLs for connecting to MySQL.

本节主要介绍JDBC连接MySQL数据库的URL格式.

This is the generic format of the connection URL:

通用的connection URL格式如下:

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

The URL consists of the following parts:

包含以下部分:

Important

提示

Any reserved characters for URLs (for example, /, :, @, (, ), [, ], &, #, =, ?, and space) that appear in any part of the connection URL must be percent encoded.

在Connection URL的各部分中, 所有保留字符都必须进行百分号转码(percent encoded), 例如, /, :, @, (, ), [, ], &, #, =, ?, 以及英文空格).

protocol

There are four possible protocols for a connection:

MySQL-JDBC支持4种协议:

  • jdbc:mysql: is for ordinary and basic failover connections.

  • jdbc:mysql:loadbalance: is for configuring load balancing.

  • jdbc:mysql:replication: is for configuring a replication setup.

  • mysqlx: is for connections using the X Protocol.

  • jdbc:mysql: 最基本的连接方式

  • jdbc:mysql:loadbalance: 用于配置负载均衡.

  • jdbc:mysql:replication: 用于设置主从(replication).

  • mysqlx: 扩展协议(X Protocol)连接使用的协议.

hosts

Depending on the situation, the hosts part may consist simply of a host name, or it can be a complex structure consisting of various elements like multiple host names, port numbers, host-specific properties, and user credentials.

根据具体情况确定, hosts 部分可以是简单的主机名称; 也可能是包含多个元素的组合, 比如多个主机名端口号,特定属性的字符串,以及用户认证信息等。

Single host:

单服务器(host)的情况:

  • Single-host connections without adding host-specific properties:

  • 单服务器(Single-host)连接, 不指定特定属性(host-specific properties)的情况:

    • The hosts part is written in the format of host:port. This is an example of a simple single-host connection URL:

    • hosts部分的格式为 host:port. 例如:

      jdbc:mysql://host1:33060/sakila

    • host can be an IPv4 or an IPv6 host name string, and in the latter case it must be put inside square brackets, for example “[1000:2000::abcd].” When host is not specified, the default value of localhost is used.

    • host 可以是域名, IPv4地址, 或者IPv6地址（以方括号括起来,如 [1000:2000::abcd]之类.） 如果不指定 host, 则使用默认值 localhost.

    • port is a standard port number, i.e., an integer between 1 and 65535. The default port number for an ordinary MySQL connection is 3306, and it is 33060 for a connection using the X Protocol. If port is not specified, the corresponding default is used.

    • port 就是TCP端口号, 取值范围从1 到 65535. MySQL的默认端口是 3306, 如果使用X Protocol, 则默认端口是 33060. 如果不指定端口, 则使用相应的默认值. ​

  • Single-host connections adding host-specific properties:

  • 单服务器(Single-host)连接, 指定特定属性(host-specific properties)的情况:

    • In this case, the host is defined as a succession of key=value pairs. Keys are used to identify the host, the port, as well as any host-specific properties. There are two alternate formats for specifying keys:

    • 这时候host部分由多个key=value对组成. Key用来指定host, port,以及属性名. 支持两种格式:

      • The “address-equals” form:

      • 1.“address-equals”方式:

        address=(host=host_or_ip)(port=port)(key1=value1)(key2=value2)...(keyN=valueN)

        Here is a sample URL using the“address-equals” form : 示例:

        jdbc:mysql://address=(host=localhost)(port=3306)(user=root)/test

      • The “key-value” form:

      • 2.“key-value” 方式:

        (host=host,port=port,key1=value1,key2=value2,...,keyN=valueN)

        Here is a sample URL using the “key-value” form : 示例:

        jdbc:mysql://(host=localhost,port=3306,user=root)/test

​

  • The host and the port are identified by the keys host and port. The descriptions of the format and default values ofhost and port in Single host without host-specific properties above also apply here.

  • 主机名和端口号对应的key是host 和 port;

  • Other keys that can be added include user, password, protocol, and so on. They override the global values set in theproperties part of the URL. Limit the overrides to user, password, network timeouts, and statement and metadata cache sizes; the effects of other per-host overrides are not defined.

  • 其他可填写的key包括user, password, protocol等等, 详细信息后面会介绍。

  • Different protocols may require different keys. For example, the mysqlx: scheme uses two special keys, address and priority. address is a host:port pair and priority an integer. For example:

  • 协议不同, 则key也可能不同, 例如 mysqlx: 协议中就是address=host:port,以及priority=数字, 示例:

    mysqlx://(address=localhost:33060,priority=1,user=root)/db

  • key is case-sensitive. Two keys differing in case only are considered conflicting, and there are no guarantees on which one will be used.

  • key 属性名是区分大小写的, 但如果两个key的名称相同则算冲突, 不保证哪个会生效。

Multiple hosts

多服务器(host)的情况:

There are two formats for specifying multiple hosts:

多服务器的Connection URL,支持两种格式:

  • List hosts in a comma-separated list:

  • 使用英文逗号分隔服务器列表:

    host1,host2,...,hostN

    Each host can be specified in any of the three ways described in Single host above. Here are some examples:

    其中每个服务器都可以使用前面提到的3种格式, 示例如下:

    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

  • List hosts in a comma-separated list, and then encloses the list by square brackets:

  • 使用英文逗号分隔服务器列表,再加上英文中括号括起来:

    [host1,host2,...,hostN]

    This is called the host sublist form, which allows sharing of the user credentials by all hosts in the list as if they are a single host. Each host in the list can be specified in any of the three ways described in Single host above. Here are some examples:

    这种方式叫做主机子列表, 意思是支持使用相同的用户名密码信息. 其中每个服务器都可以使用前面提到的3种格式, 示例如下:

    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

    While it is not possible to write host sublists recursively, a host list may contain host sublists as its member hosts.

    服务器列表中的某个元素, 可以由一个sublist组成, 所以不能递归地编写主机子列表。

User credentials

用户认证

User credentials can be set outside of the connection URL—for example, as arguments when getting a connection from thejava.sql.DriverManager (see Section 6.3, “Configuration Properties” for details). When set with the connection URL, there are several ways to specify them:

用户认证信息, 可以放在Connection URL部分, 也可以放在参数部分(参考下文).

如果放在Connection URL中, 支持以下几种方式:

  • Prefix the a single host, a host sublist (see Multiple hosts), or any host in a list of hosts with the user credentials with an @:

  • 放在服务器信息的前面, 以 @ 符号分隔:

    user:password@host_or_host_sublist

    For example:

    示例

    mysqlx://sandy:secret@[(address=host1:1111,priority=1,key1=value1),(address=host2:2222,priority=2,key2=value2))]/db

  • Use the keys user and password to specify credentials for each host:

  • 为每个服务器分别指定用户名和密码:

    (user=sandy)(password=mypass)

    For example:

    例如:

    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

    In both forms, when multiple user credentials are specified, the one to the left takes precedence—that is, going from left to right in the connection string, the first one found that is applicable to a host is the one that is used.

    不管用哪种方式, 如果不小心指定多个用户密码, 因为是从左到右扫描, 所以先扫描到的才生效。

    Inside a host sublist, no host can have user credentials in the @ format, but individual host can have user credentials specified in the key format.

    注意: @ 格式的host sublist不能单独指定用户密码, 但key方式支持指定单独的密码。

database

The default database or catalog to open. If the database is not specified, the connection is made with no default database. In this case, either call the setCatalog() method on the Connection instance, or specify table names using the database name (that is, SELECT *dbname*.*tablename*.*colname* FROM dbname.tablename...) in your SQL statements. Opening a connection without specifying the database to use is, in general, only useful when building tools that work with multiple databases, such as GUI database managers.

指定默认打开的数据库(database)或目录(catalog)。 如果不指定则没有默认数据库, 这时候, 需要先调用Connection对象的setCatalog()方法, 或者直接在SQL语句中指定数据库名称(如 SELECT dbname.tablename.colname FROM dbname.tablename ...)。 一般来说,只有需要操纵多个数据库的工具才会不指定默认数据库, 比如GUI界面的数据库管理程序。

Note

Always use the Connection.setCatalog() method to specify the desired database in JDBC applications, rather than the USE *database* statement.

注意:

在JDBC程序中, 如果要切换数据库, 应该使用 Connection.setCatalog(); 而不是 USE db_xxx 语句。

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:

应用到所有host的全局属性, 类似于Http的URL参数, 在英文问号 ? 后面以 key=value 对的形式指定, 用 “&” 号(读音[与号])分隔:

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.
  • Any host-specific values specified with key-value pairs as explained in Single host with host-specific properties and Multiple hosts above override the global values set here.

下面是一些说明:

  • key和value都是字符串。在Connector/J内部会进行相应的类型转换和验证。
  • key区分大小写。如果两个key的大小写不同会被认为是冲突, 具体哪个生效并不确定。
  • 针对特定服务器的属性(包括单主机和多主机, 参考上文), 会覆盖此处介绍的全局属性值。

See Section 6.3, “Configuration Properties” for details about the configuration properties.

更多配置属性,请参考下一节。

https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-jdbc-url-format.html