MySQL Connector/J 5.1 Developer Guide
This section explains the syntax of the URLs for connecting to MySQL.
This is the generic format of the connection URL:
protocol
//[hosts
][/database
][?properties
]
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
encoded.
protocol
There are three possible protocols for a connection:
jdbc:mysql:
is for ordinary and basic
failover connections.
jdbc:mysql:loadbalance:
is for
configuring load balancing. See
Section 8.2, “Configuring Load Balancing with Connector/J”
for details.
jdbc:mysql:replication:
is for
configuring a replication setup. See
Section 8.3, “Configuring Source/Replica Replication with Connector/J”
for details.
hosts
Depending on the situation, the host
s
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.
Single-host connections without adding 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:
jdbc:mysql://host1:33060/sakila
When host
is not
specified, the default value of
localhost
is used.
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. If
port
is not specified,
the default value is used.
Single-host connections adding host-specific properties:
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, and they
are preceded by
“key
=value
address=
”:
address=(host=host_or_ip
)(port=port
)(key1
=value1
)(key2
=value2
)...(keyN
=valueN
)
Here is a sample URL:
jdbc:mysql://address=(host=myhost)(port=1111)(key1=value1)/db
This is the mandatory format for iPv6 addresses, but it also supports the iPv4 addresses.
The host and the port are identified by the keys
host
and
port
. The description of
the default values of
host
and
port
in
Single host without host-specific properties
above also applies here.
Other keys that can be added include
user
,
password
,
protocol
, and so on. They
override the global values set in the
properties
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
is case-sensitive.
Two keys differing in case only are considered
conflicting, and there are no guarantees on which
one will be used.
Specify multiple hosts by listing them in a comma-separated list:
host1
,host2
,...,hostN
Each host can be specified in any of the two 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://myhost1:1111,address=(host=myhost2)(port=2222)(key2=value2)/db
User credentials
User credentials can be set outside of the connection
URL—for example, as arguments when getting a
connection from the
java.sql.DriverManager
(see
Section 5.3, “Configuration Properties for Connector/J”
for details). When set with the connection URL, use the keys
user
and password
to
specify credentials for each host:
(user=sandy)(password=mypass)
For example:
jdbc:mysql://address=(host=myhost1)(port=1111)(user=sandy)(password=secret),address=(host=myhost2)(port=2222)(user=finn)(password=secret)/db
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.
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
) 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.
dbname
.tablename
.colname
FROM dbname.tablename...
Always use the Connection.setCatalog()
method to specify the desired database in JDBC applications,
rather than the USE
statement.
database
properties
A succession of global properties applying to all hosts,
preceded by “?
” and written as
pairs separated by the symbol
“key
=value
&.
” 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.
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.