Documentation Home
Connectors and APIs Manual
Download this Manual
PDF (US Ltr) - 4.5Mb
PDF (A4) - 4.5Mb


3.5.2 Connection URL Syntax

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

This is the generic format of the connection URL:

Press CTRL+C to copy
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.

protocol

There are the possible protocols for a connection:

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

  • jdbc:mysql:loadbalance: is for load-balancing JDBC connections. See Section 3.8.3, “Configuring Load Balancing with Connector/J” for details.

  • jdbc:mysql:replication: is for JDBC replication connections. See Section 3.8.4, “Configuring Source/Replica Replication with Connector/J” for details.

  • mysqlx: is for X DevAPI connections.

  • jdbc:mysql+srv: is for ordinary and basic failover JDBC connections that make use of DNS SRV records.

  • jdbc:mysql+srv:loadbalance: is for load-balancing JDBC connections that make use of DNS SRV records.

  • jdbc:mysql+srv:replication: is for replication JDBC connections that make use of DNS SRV records.

  • mysqlx+srv: is for X DevAPI connections that make use of DNS SRV records.

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.

  • Single host:

    • 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:

        Press CTRL+C to copy
        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.

      • 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.

    • Single-host connections adding 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:

        • The address-equals form:

          Press CTRL+C to copy
          address=(host=host_or_ip)(port=port)(key1=value1)(key2=value2)...(keyN=valueN)

          Here is a sample URL using theaddress-equals form :

          Press CTRL+C to copy
          jdbc:mysql://address=(host=myhost)(port=1111)(key1=value1)/db
        • The key-value form:

          Press CTRL+C to copy
          (host=host,port=port,key1=value1,key2=value2,...,keyN=valueN)

          Here is a sample URL using the key-value form :

          Press CTRL+C to copy
          jdbc:mysql://(host=myhost,port=1111,key1=value1)/db

      • The host and the port are identified by the keys host and port. The descriptions of the format and default values of host and port in Single host without host-specific properties above also apply 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.

      • 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:

        Press CTRL+C to copy
        mysqlx://(address=host:1111,priority=1,key1=value1)/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.

  • Multiple hosts

    There are two formats for specifying multiple hosts:

    • List hosts in a comma-separated list:

      Press CTRL+C to copy
      host1,host2,...,hostN

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

      Press CTRL+C to copy
      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:

      Press CTRL+C to copy
      [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:

      Press CTRL+C to copy
      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

    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 3.5.3, “Configuration Properties” for details). 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 @:

      Press CTRL+C to copy
      user:password@host_or_host_sublist

      For example:

      Press CTRL+C to copy
      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:

      Press CTRL+C to copy
      (user=sandy)(password=mypass)

      For example:

      Press CTRL+C to copy
      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.

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.

Note

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

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:

Press CTRL+C to copy
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.

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