Pre-General Availability Draft: 2018-03-21
This section explains the syntax of the URLs for connecting to MySQL.
This is the generic format of the connection URL:
The URL consists of the following parts:
Any reserved characters for URLs (for example,
?, and space) that
appear in any part of the connection URL must be percent
There are four possible protocols for a connection:
jdbc:mysql:is for ordinary and basic failover connections.
jdbc:mysql:loadbalance:is for configuring load balancing. See Section 9.3, “Configuring Load Balancing with Connector/J” for details.
jdbc:mysql:replication:is for configuring a replication setup. See Section 9.4, “Configuring Master/Slave Replication with Connector/J” for details.
mysqlx:is for connections using the X Protocol.
Depending on the situation, the
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
hostspart is written in the format of
port. This is an example of a simple single-host connection URL:
hostcan 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
hostis not specified, the default value of
portis 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
portis not specified, the corresponding default is used.
In this case, the host is defined as a succession of
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:
The “address-equals” form:
Here is a sample URL using the“address-equals” form :
The “key-value” form:
Here is a sample URL using the “key-value” form :
The host is identified by the keys
port. The descriptions of the format and default values of
portin Single host without host-specific properties above also apply here.
Other keys that can be added include
protocol, and so on. They override the global values set in the
propertiespart 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.
Different protocols may require different keys. For example, the
mysqlx:scheme uses two special keys,
priorityan integer. For example:
keyis case-sensitive. Two keys differing in case only are considered conflicting, and there are no guarantees on which one will be used.
There are two formats for specifying multiple hosts:
List hosts in a comma-separated list:
Each host can be specified in any of the three ways described in Single host above. Here are some examples:
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:
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:
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.
User credentials can be set outside of the connection URL in, for example, as arguments when getting a connection from the
java.sql.DriverManager. When set with the connection URL, there are several ways to specify them:
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
Use the keys
passwordto specify credentials for each host:
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.
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
method on the
Connection instance, or specify
table names using the database name (that is,
) 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.
Always use the
method to specify the desired database in JDBC applications,
rather than the
A succession of global properties applying to all hosts, written
and separated by the symbol
&.” Here are some examples:
The following are true for the key-value pairs:
valueare just strings. Proper type conversion and validation are performed internally in Connector/J.
keyis case-sensitive. Two keys differing in case only are considered conflicting, and it is uncertain which one will be used.