Chapter 4 Connector/J Installation

Table of Contents

4.1 Installing Connector/J from a Binary Distribution
4.2 Installing the Driver and Configuring the CLASSPATH
4.3 Upgrading from an Older Version
4.3.1 Upgrading to MySQL Connector/J 8.0
4.4 Installing from the Development Source Tree
4.5 Testing Connector/J

MySQL Connector/J is distributed as a .zip or .tar.gz archive, available for download from the Connector/J Download page. The archive contains the sources and the JAR archive named mysql-connector-java-version.jar.

You can install the Connector/J package using either the binary or source distribution. The binary distribution provides the easiest method for installation; the source distribution lets you customize your installation further. With either solution, you manually add the Connector/J location to your Java CLASSPATH.

If you are upgrading from a previous version, read the upgrade information in Section 4.3, “Upgrading from an Older Version” before continuing.

Connector/J is also available as part of the Maven project. For more information and to download the Connector/J JAR files, see the Maven repository.

Important

You may also need to install the following third-party libraries on your system for Connector/J 8.0 to work:

  • Protocol Buffers (required for using X DevAPI and for building Connector/J 8.0 from source)

  • Javassist (only required for building Connector/J 8.0 from source)

4.1 Installing Connector/J from a Binary Distribution

For the easiest method of installation, use the binary distribution of the Connector/J package. Extract the JAR archive from the tar/gzip or zip archive to a suitable location, then optionally make the information about the JAR archive available by changing your CLASSPATH (see Section 4.2, “Installing the Driver and Configuring the CLASSPATH).

Use the appropriate graphical or command-line utility to extract the distribution (for example, WinZip for the .zip archive, and tar for the .tar.gz archive). Because there are potentially long file names in the distribution, we use the GNU tar archive format. Use GNU tar (or an application that understands the GNU tar archive format) to unpack the .tar.gz variant of the distribution.

You can also use Maven dependencies as an alternative installation method. In that case, the Connector/J binaries are automatically downloaded from The Maven Central Repository by default and managed locally by your Maven tool

4.2 Installing the Driver and Configuring the CLASSPATH

Once you have extracted the distribution archive, you can install the driver by placing mysql-connector-java-version.jar in your classpath, either by adding the full path to it to your CLASSPATH environment variable, or by directly specifying it with the command line switch -cp when starting the JVM.

To use the driver with the JDBC DriverManager, use com.mysql.cj.jdbc.Driver as the class that implements java.sql.Driver.

You can set the CLASSPATH environment variable under Unix, Linux, or OS X either locally for a user within the user's .profile, .login or other login file, or you can also set it globally by editing the global /etc/profile file.

For example, add the Connector/J driver to your CLASSPATH using one of the following forms, depending on your command shell:

# Bourne-compatible shell (sh, ksh, bash, zsh):
shell> export CLASSPATH=/path/mysql-connector-java-ver.jar:$CLASSPATH

# C shell (csh, tcsh):
shell> setenv CLASSPATH /path/mysql-connector-java-ver.jar:$CLASSPATH

For Windows platforms, you set the environment variable through the System Control Panel.

To use the X DevAPI features in Connector/J, you also need the external library protobuf-java-3.6.1.jar, which you can download from, for exmaple, the official Maven repository at https://repo1.maven.org/maven2/com/google/protobuf/protobuf-java/3.6.1/, and add it to the CLASSPATH.

If you prefer, you can use Maven dependencies manager to install and configure the Connector/J library in your project. Connector/J is published in The Maven Central Repository with "GroupId: mysql" and "ArtifactId: mysql-connector-java," and can be linked to your project by adding the following dependency in your pom.xml file:

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>x.y.z</version>
</dependency>

Note that if you choose use Maven to manage your project dependencies, you do not need to explicitly refer to the library protobuf-java as it is resolved by dependency transitivity. However, if you do not want to use the X DevAPI features, you may also want to add a dependency exclusion to avoid linking the unneeded sub-library. For example:

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>x.y.z</version>
    <exclusions>
        <exclusion>
            <groupId>com.google.protobuf</groupId>
            <artifactId>protobuf-java</artifactId>
        </exclusion>
    </exclusions> 
</dependency>

To use MySQL Connector/J with an application server such as GlassFish, Tomcat, or JBoss, read your vendor's documentation for more information on how to configure third-party class libraries, as most application servers ignore the CLASSPATH environment variable. For configuration examples for some J2EE application servers, see Chapter 8, Connection Pooling with Connector/J, Section 9.3, “Configuring Load Balancing with Connector/J”, and Section 9.5, “Advanced Load-balancing and Failover Configuration”. However, the authoritative source for JDBC connection pool configuration information for your particular application server is the documentation for that application server.

If you are developing servlets or JSPs, and your application server is J2EE-compliant, you can put the driver's .jar file in the WEB-INF/lib subdirectory of your webapp, as this is a standard location for third party class libraries in J2EE web applications.

You can also use the MysqlDataSource or MysqlConnectionPoolDataSource classes in the com.mysql.cj.jdbc package, if your J2EE application server supports or requires them. The javax.sql.XADataSource interface is implemented using the com.mysql.cj.jdbc.MysqlXADataSource class, which supports XA distributed transactions.

The various MysqlDataSource classes support the following parameters (through standard set mutators):

  • user

  • password

  • serverName (see the previous section about failover hosts)

  • databaseName

  • port

4.3 Upgrading from an Older Version

This section has information for users who are upgrading from one version of Connector/J to another, or to a new version of the MySQL server that supports a more recent level of JDBC. A newer version of Connector/J might include changes to support new features, improve existing functionality, or comply with new standards.

4.3.1 Upgrading to MySQL Connector/J 8.0

Upgrading an application developed for Connector/J 5.1 to use Connector/J 8.0 might require certain changes to your code or the environment in which it runs. Here are some changes for Connector/J going from 5.1 to 8.0, for which adjustments might be required:

4.3.1.1 Running on the Java 8 Platform

Connector/J 8.0 is created specifically to run on the Java 8 platform. While Java 8 is known to be strongly compatible with earlier Java versions, incompatibilities do exist, and code designed to work on Java 7 might need to be adjusted before being run on Java 8. Developers should refer to the incompatibility information provided by Oracle.

4.3.1.2 Changes in Connection Properties

A complete list of Connector/J 8.0 connection properties are available in connector-j-reference-set-config. The following are connection properties that have been changed (removed, added, have their names changed, or have their default values changed) going from Connector/J 5.1 to 8.0.

Properties that have been removed (do not use them during connection):

  • useDynamicCharsetInfo

  • useBlobToStoreUTF8OutsideBMP , utf8OutsideBmpExcludedColumnNamePattern, and utf8OutsideBmpIncludedColumnNamePattern: MySQL 5.5 and later supports the utf8mb4 character set, which is the character set that should be used by Connector/J applications for supporting characters beyond the Basic Multilingual Plane (BMP) of Unicode Version 3.

  • useJvmCharsetConverters: JVM character set conversion is now used in all cases

  • The following date and time properties:

    • dynamicCalendars

    • noTzConversionForTimeType

    • noTzConversionForDateType

    • cacheDefaultTimezone

    • useFastIntParsing

    • useFastDateParsing

    • useJDBCCompliantTimezoneShift

    • useLegacyDatetimeCode

    • useSSPSCompatibleTimezoneShift

    • useTimezone

    • useGmtMillisForDatetimes

  • dumpMetadataOnColumnNotFound

  • relaxAutoCommit

  • strictFloatingPoint

  • runningCTS13

  • retainStatementAfterResultSetClose

  • nullNamePatternMatchesAll (removed since release 8.0.9)

Properties that have been added:

  • mysqlx.useAsyncProtocol

Property that has its name changed:

  • com.mysql.jdbc.faultInjection.serverCharsetIndex changed to com.mysql.cj.testsuite.faultInjection.serverCharsetIndex

  • loadBalanceEnableJMX to ha.enableJMX

  • replicationEnableJMX to ha.enableJMX

Properties that have their default values changed:

  • nullCatalogMeansCurrent is now false by default

4.3.1.3 Changes in the Connector/J API

This section describes the changes to the Connector/J API going from version 5.1 to 8.0. You might need to adjust your API calls accordingly:

  • The name of the class that implements java.sql.Driver in MySQL Connector/J has changed from com.mysql.jdbc.Driver to com.mysql.cj.jdbc.Driver. The old class name has been deprecated.

  • The names of these commonly-used interfaces have also been changed:

    • ExceptionInterceptor: from com.mysql.jdbc.ExceptionInterceptor to com.mysql.cj.exceptions.ExceptionInterceptor

    • StatementInterceptor: from com.mysql.jdbc.StatementInterceptorV2 to com.mysql.cj.interceptors.QueryInterceptor

    • ConnectionLifecycleInterceptor: from com.mysql.jdbc.ConnectionLifecycleInterceptor to com.mysql.cj.jdbc.interceptors.ConnectionLifecycleInterceptor

    • AuthenticationPlugin: from com.mysql.jdbc.AuthenticationPlugin to com.mysql.cj.protocol.AuthenticationPlugin

    • BalanceStrategy: from com.mysql.jdbc.BalanceStrategy to com.mysql.cj.jdbc.ha.BalanceStrategy.

4.3.1.4 Changes for Build Properties

A number of Ant properties for building Connector/J from source have been renamed; see Table 4.1, “Changes with the Build Properties from Connector/J 5.1 to 8.0”

Table 4.1 Changes with the Build Properties from Connector/J 5.1 to 8.0

Old name New name
com.mysql.jdbc.extra.libs com.mysql.cj.extra.libs
com.mysql.jdbc.jdk com.mysql.cj.build.jdk
debug.enable com.mysql.cj.build.addDebugInfo
com.mysql.jdbc.noCleanBetweenCompiles com.mysql.cj.build.noCleanBetweenCompiles
com.mysql.jdbc.commercialBuild com.mysql.cj.build.commercial
com.mysql.jdbc.filterLicense com.mysql.cj.build.filterLicense
com.mysql.jdbc.noCryptoBuild com.mysql.cj.build.noCrypto
com.mysql.jdbc.noSources com.mysql.cj.build.noSources
com.mysql.jdbc.noMavenSources com.mysql.cj.build.noMavenSources
major_version com.mysql.cj.build.driver.version.major
minor_version com.mysql.cj.build.driver.version.minor
subminor_version com.mysql.cj.build.driver.version.subminor
version_status com.mysql.cj.build.driver.version.status
extra.version com.mysql.cj.build.driver.version.extra
snapshot.version com.mysql.cj.build.driver.version.snapshot
version com.mysql.cj.build.driver.version
full.version com.mysql.cj.build.driver.version.full
prodDisplayName com.mysql.cj.build.driver.displayName
prodName com.mysql.cj.build.driver.name
fullProdName com.mysql.cj.build.driver.fullName
buildDir com.mysql.cj.build.dir
buildDriverDir com.mysql.cj.build.dir.driver
mavenUploadDir com.mysql.cj.build.dir.maven
distDir com.mysql.cj.dist.dir
toPackage com.mysql.cj.dist.dir.prepare
packageDest com.mysql.cj.dist.dir.package
com.mysql.jdbc.docs.sourceDir com.mysql.cj.dist.dir.prebuilt.docs

4.3.1.5 Change for Test Properties

A number of Ant properties for testing Connector/J have been renamed or removed; see Table 4.2, “Changes with the Test Properties from Connector/J 5.1 to 8.0”

Table 4.2 Changes with the Test Properties from Connector/J 5.1 to 8.0

Old name New name
buildTestDir com.mysql.cj.testsuite.build.dir
junit.results com.mysql.cj.testsuite.junit.results
com.mysql.jdbc.testsuite.jvm com.mysql.cj.testsuite.jvm
test com.mysql.cj.testsuite.test.class
methods com.mysql.cj.testsuite.test.methods
com.mysql.jdbc.testsuite.url com.mysql.cj.testsuite.url
com.mysql.jdbc.testsuite.admin-url com.mysql.cj.testsuite.url.admin
com.mysql.jdbc.testsuite.ClusterUrl com.mysql.cj.testsuite.url.cluster
com.mysql.jdbc.testsuite.url.sha256default com.mysql.cj.testsuite.url.openssl
com.mysql.jdbc.testsuite.cantGrant com.mysql.cj.testsuite.cantGrant
com.mysql.jdbc.testsuite.no-multi-hosts-tests com.mysql.cj.testsuite.disable.multihost.tests
com.mysql.jdbc.test.ds.host com.mysql.cj.testsuite.ds.host
com.mysql.jdbc.test.ds.port com.mysql.cj.testsuite.ds.port
com.mysql.jdbc.test.ds.db com.mysql.cj.testsuite.ds.db
com.mysql.jdbc.test.ds.user com.mysql.cj.testsuite.ds.user
com.mysql.jdbc.test.ds.password com.mysql.cj.testsuite.ds.password
com.mysql.jdbc.test.tabletype com.mysql.cj.testsuite.loadstoreperf.tabletype
com.mysql.jdbc.testsuite.loadstoreperf.useBigResults com.mysql.cj.testsuite.loadstoreperf.useBigResults
com.mysql.jdbc.testsuite.MiniAdminTest.runShutdown com.mysql.cj.testsuite.miniAdminTest.runShutdown
com.mysql.jdbc.testsuite.noDebugOutput com.mysql.cj.testsuite.noDebugOutput
com.mysql.jdbc.testsuite.retainArtifacts com.mysql.cj.testsuite.retainArtifacts
com.mysql.jdbc.testsuite.runLongTests com.mysql.cj.testsuite.runLongTests
com.mysql.jdbc.test.ServerController.basedir com.mysql.cj.testsuite.serverController.basedir
com.mysql.jdbc.ReplicationConnection.isSlave com.mysql.cj.testsuite.replicationConnection.isSlave
com.mysql.jdbc.test.isLocalHostnameReplacement Removed
com.mysql.jdbc.testsuite.driver Removed
com.mysql.jdbc.testsuite.url.default Removed. No longer needed, as multi-JVM tests have been removed from the test suite.

4.3.1.6 Changes for Exceptions

Some exceptions have been removed from Connector/J going from version 5.1 to 8.0. Applications that used to catch the removed exceptions should now catch the corresponding exceptions listed in Table 4.3 below.

Note

Some of these Connector/J 5.1 exceptions are duplicated in the com.mysql.jdbc.exception.jdbc4 package; that is indicated by [jdbc4.] in their names in Table 4.3.

Table 4.3 Changes for Exceptions from Connector/J 5.1 to 8.0

Removed Exception in Connector/J 5.1 Exception to Catch in Connector/J 8.0
com.mysql.jdbc.exceptions.jdbc4.CommunicationsException com.mysql.cj.jdbc.exceptions.CommunicationsException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLDataException java.sql.SQLDataException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLIntegrityConstraintViolationException java.sql.SQLIntegrityConstraintViolationException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLInvalidAuthorizationSpecException java.sql.SQLInvalidAuthorizationSpecException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLNonTransientConnectionException java.sql.SQLNonTransientConnectionException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLNonTransientException java.sql.SQLNonTransientException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLQueryInterruptedException com.mysql.cj.jdbc.exceptions.MySQLQueryInterruptedException
com.mysql.jdbc.exceptions.MySQLStatementCancelledException com.mysql.cj.jdbc.exceptions.MySQLStatementCancelledException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLSyntaxErrorException java.sql.SQLSyntaxErrorException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLTimeoutException java.sql.SQLTimeoutException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLTransactionRollbackException java.sql.SQLTransactionRollbackException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLTransientConnectionException java.sql.SQLTransientConnectionException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLTransientException java.sql.SQLTransientException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLIntegrityConstraintViolationException java.sql.SQLIntegrityConstraintViolationException

4.3.1.7 Other Changes

Here are other changes with Connector/J 8.0:

  • Removed ReplicationDriver. Instead of using a separate driver, you can now obtain a connection for a replication setup just by using the jdbc:mysql:replication:// scheme.

  • See Chapter 4, Connector/J Installation for third-party libraries required for Connector/J 8.0 to work.

  • Connector/J 8.0 always performs time offset adjustments on date-time values, and the adjustments require one of the following to be true:

    • The MySQL server is configured with a canonical time zone that is recognizable by Java (for example, Europe/Paris, Etc/GMT-5, UTC, etc.)

    • The server's time zone is overridden by setting the Connector/J connection property serverTimezone (for example, serverTimezone=Europe/Paris).

4.4 Installing from the Development Source Tree

Caution

Read this section only if you are interested in helping us test our new code. To just get MySQL Connector/J up and running on your system, use a standard binary release distribution.

To install MySQL Connector/J from the development source tree, make sure that you have the following software on your system:

To check out and compile MySQL Connector/J, follow these steps:

  1. Check out the code from the source code repository for MySQL Connector/J located on GitHub at https://github.com/mysql/mysql-connector-j. The latest release of the Connector/J 8.0 series is on the release/8.0 branch; use the following command to check it out:

    shell> git clone --branch release/8.0 https://github.com/mysql/mysql-connector-j.git
    

    Under the current directory, the commands create a mysql-connector-j subdirectory , which contains the code you want.

  2. Make sure that you have JDK 1.8.x installed.

  3. Place the required junit.jar, javaassist.jar, and protobuf-java-x.y.z.jar files in a separate directory—for example, /home/username/ant-extralibs.

  4. Change your current working directory to the mysql-connector-j directory created in step 1 above.

  5. In the directory, create a file named build.properties to indicate to Ant the locations of the root directories for your JDK 1.8.x installation, as well as the location of the extra libraries. The file should contain the following property settings, with the path_to_* parts replaced by the appropriate filepaths:

    com.mysql.cj.build.jdk=path_to_jdk_1.8
    com.mysql.cj.extra.libs=path_to_folder_for_extra_libraries
    

    Alternatively, you can set the values of those properties through the Ant -D options.

  6. Issue the following command to compile the driver and create a .jar file for Connector/J:

    shell> ant dist
    

    This creates a build directory in the current directory, where all the build output goes. A directory is created under the build directory, whose name includes the version number of the release you are building. That directory contains the sources, the compiled .class files, and a .jar file for deployment. For more information and other possible targets, including those that create a fully packaged distribution, issue the following command:

    shell> ant -projecthelp
    
  7. Install the newly created .jar file for the JDBC driver as you would install a binary .jar file you download from MySQL by following the instructions given in Section 4.2, “Installing the Driver and Configuring the CLASSPATH.

Note that a package containing both the binary and source code for Connector/J 8.0 can also be downloaded from the Connector/J Download page.

Note

Going from Connector/J 5.1 to 8.0, a number of Ant properties for building Connector/J have been renamed or removed; see Section 4.3.1.4, “Changes for Build Properties” for details.

4.5 Testing Connector/J

The Connector/J source code repository or packages that are shipped with source code include an extensive test suite, containing test cases that can be executed independently. The test cases are divided into the following categories:

  • Unit tests: They are methods located in packages aligning with the classes that they test.

  • Functional tests: Classes from the package testsuite.simple. Include test code for the main features of Connector/J.

  • Performance tests: Classes from the package testsuite.perf. Include test code to make measurements for the performance of Connector/J.

  • Regression tests: Classes from the package testsuite.regression. Includes code for testing bug and regression fixes.

  • X DevAPI and X Protocol tests: Classes from the package testsuite.x for testing X DevAPI and X Protocol functionality.

The bundled Ant build file contains targets like test, which can facilitate the process of running the Connector/J tests; see the target descriptions in the build file for details. Besides the requirements for building Connector/J from the source code described in Section 4.4, “Installing from the Development Source Tree”, a number of the tests also require the File System Service Provider 1.2 for the Java Naming and Directory Interface (JNDI), available at http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html)—place the jar files downloaded from there into the lib directory or in the directory pointed to by the property com.mysql.cj.extra.libs.

To run the test using Ant, in addition to the properties required for Section 4.4, “Installing from the Development Source Tree”, you must set the following properties in the build.properties file or through the Ant -D options:

After setting these parameters, run the tests with Ant in the following ways:

  • Building the test target with ant test runs all test cases by default on a single server instance. If you want to run a particular test case, put the test's fully qualified class names in the com.mysql.cj.testsuite.test.class variable; for example:

    shell > ant -Dcom.mysql.cj.testsuite.test.class=testsuite.simple.StringUtilsTest test

    You can also run individual tests in a test case by specifying the names of the corresponding methods in the com.mysql.cj.testsuite.test.methods variable, separating multiple methods by commas; for example:

    shell > ant -Dcom.mysql.cj.testsuite.test.class=testsuite.simple.StringUtilsTest \
    -Dcom.mysql.cj.testsuite.test.methods=testIndexOfIgnoreCase,testGetBytes test
    

While the test results are partially reported by the console, complete reports in HTML and XML formats are provided. View the HTML report by opening buildtest/junit/report/index.html. XML version of the reports are located in the folder buildtest/junit.

Note

Going from Connector/J 5.1 to 8.0, a number of Ant properties for testing Connector/J have been renamed or removed; see Section 4.3.1.5, “Change for Test Properties” for details.