10322 lines
503 KiB
HTML
10322 lines
503 KiB
HTML
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>MySQL Connector/J 5.1 Developer Guide</title><link rel="stylesheet" type="text/css" href="mvl.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
|
||
<script language="javascript" type="text/javascript">
|
||
function addOnload(theFunc)
|
||
{
|
||
var previous = window.onload;
|
||
if (typeof window.onload != 'function')
|
||
{
|
||
window.onload = theFunc;
|
||
}
|
||
else
|
||
{
|
||
window.onload = function()
|
||
{
|
||
previous();
|
||
theFunc();
|
||
}
|
||
}
|
||
}
|
||
|
||
addOnload(function()
|
||
{
|
||
var base = new Date(1459186953*1000);
|
||
var now = new Date();
|
||
var diff = ((now-base)/1000)/(24*3600);
|
||
|
||
if (diff > 90) {
|
||
var nodes = document.getElementsByClassName('titlepage');
|
||
nodes[0].innerHTML = '<p style="border: 5px #ff0000 solid; padding: 5px; margin 5px">' +
|
||
'This copy of the manual is more than 90 days old. We encourage you to download a ' +
|
||
'new version from <a href="http://dev.mysql.com">dev.mysql.com/doc</a>.</p>' + nodes[0].innerHTML;
|
||
}
|
||
});
|
||
</script>
|
||
<noscript></noscript>
|
||
</head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j"></a>MySQL Connector/J 5.1 Developer Guide</h1></div><div><div class="abstract"><p class="title"><b>Abstract</b></p><p>
|
||
This manual describes how to install, configure, and develop
|
||
database applications using MySQL Connector/J, the JDBC driver
|
||
for communicating with MySQL servers.
|
||
</p><p>
|
||
For notes detailing the changes in each release of Connector/J,
|
||
see <a class="ulink" href="http://dev.mysql.com/doc/relnotes/connector-j/en/" target="_top">MySQL
|
||
Connector/J Release Notes</a>.
|
||
</p><p>
|
||
For legal information, see the <a class="link" href="#legalnotice" title="Legal Notices">Legal
|
||
Notices</a>.
|
||
</p><p>
|
||
For help with using MySQL, please visit either the
|
||
<a class="ulink" href="http://forums.mysql.com" target="_top">MySQL Forums</a> or
|
||
<a class="ulink" href="http://lists.mysql.com" target="_top">MySQL Mailing Lists</a>,
|
||
where you can discuss your issues with other MySQL users.
|
||
|
||
</p><p>
|
||
For additional documentation on MySQL products, including
|
||
translations of the documentation into other languages, and
|
||
downloadable versions in variety of formats, including HTML and PDF
|
||
formats, see the <a class="ulink" href="http://dev.mysql.com/doc" target="_top">MySQL
|
||
Documentation Library</a>.
|
||
</p><p><b>Licensing information. </b>
|
||
This product may include third-party software, used under
|
||
license. If you are using a <span class="emphasis"><em>Commercial</em></span>
|
||
release of MySQL Connector/J 5.1, see
|
||
<a class="ulink" href="http://downloads.mysql.com/docs/licenses/connector-j-5.1-com-en.pdf" target="_top">this
|
||
document</a> for licensing information, including
|
||
licensing information relating to third-party software that
|
||
may be included in this Commercial release. If you are using a
|
||
<span class="emphasis"><em>Community</em></span> release of MySQL Connector/J
|
||
5.1, see
|
||
<a class="ulink" href="http://downloads.mysql.com/docs/licenses/connector-j-5.1-gpl-en.pdf" target="_top">this
|
||
document</a> for licensing information, including
|
||
licensing information relating to third-party software that
|
||
may be included in this Community release.
|
||
</p><p>
|
||
Document generated on:
|
||
|
||
2016-03-28
|
||
|
||
|
||
|
||
(revision: 47177)
|
||
</p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="preface"><a href="#preface">Preface and Legal Notices</a></span></dt><dt><span class="chapter"><a href="#connector-j-overview">1 Overview of MySQL Connector/J</a></span></dt><dt><span class="chapter"><a href="#connector-j-versions">2 Connector/J Versions</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-change-history">2.1 Connector/J Release Notes and Change History</a></span></dt><dt><span class="section"><a href="#connector-j-versions-java">2.2 Java Versions Supported</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-installing">3 Connector/J Installation</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-binary-installation">3.1 Installing Connector/J from a Binary Distribution</a></span></dt><dt><span class="section"><a href="#connector-j-installing-classpath">3.2 Installing the Driver and Configuring the <code class="literal">CLASSPATH</code></a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading">3.3 Upgrading from an Older Version</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-installing-upgrading-5-1">3.3.1 Upgrading to MySQL Connector/J 5.1.x</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-issues">3.3.2 JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-3-0-to-3-1">3.3.3 Upgrading from MySQL Connector/J 3.0 to 3.1</a></span></dt></dl></dd><dt><span class="section"><a href="#connector-j-installing-source">3.4 Installing from Source</a></span></dt><dt><span class="section"><a href="#connector-j-testing">3.5 Testing Connector/J</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-examples">4 Connector/J Examples</a></span></dt><dt><span class="chapter"><a href="#connector-j-reference">5 Connector/J (JDBC) Reference</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-reference-configuration-properties">5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties
|
||
for Connector/J</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-useconfigs">5.1.1 Properties Files for the <code class="literal">useConfigs</code> Option</a></span></dt></dl></dd><dt><span class="section"><a href="#connector-j-reference-implementation-notes">5.2 JDBC API Implementation Notes</a></span></dt><dt><span class="section"><a href="#connector-j-reference-type-conversions">5.3 Java, JDBC and MySQL Types</a></span></dt><dt><span class="section"><a href="#connector-j-reference-charsets">5.4 Using Character Sets and Unicode</a></span></dt><dt><span class="section"><a href="#connector-j-reference-using-ssl">5.5 Connecting Securely Using SSL</a></span></dt><dt><span class="section"><a href="#connector-j-using-pam">5.6 Connecting Using PAM Authentication</a></span></dt><dt><span class="section"><a href="#connector-j-reference-replication-connection">5.7 Using Master/Slave Replication with ReplicationConnection</a></span></dt><dt><span class="section"><a href="#connector-j-reference-error-sqlstates">5.8 Mapping MySQL Error Numbers to JDBC SQLState Codes</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-usagenotes-basic">6 JDBC Concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-usagenotes-connect-drivermanager">6.1 Connecting to MySQL Using the JDBC <code class="literal">DriverManager</code>
|
||
Interface</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-statements">6.2 Using JDBC <code class="literal">Statement</code> Objects to Execute SQL</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-statements-callable">6.3 Using JDBC <code class="literal">CallableStatements</code> to Execute Stored
|
||
Procedures</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-last-insert-id">6.4 Retrieving <code class="literal">AUTO_INCREMENT</code> Column Values through JDBC</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-usagenotes-j2ee-concepts-connection-pooling">7 Connection Pooling with Connector/J</a></span></dt><dt><span class="chapter"><a href="#connector-j-multi-host-connections">8 Multi-Host Connections</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-config-failover">8.1 Configuring Server Failover</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections">8.2 Configuring Load Balancing with Connector/J</a></span></dt><dt><span class="section"><a href="#connector-j-master-slave-replication-connection">8.3 Configuring Master/Slave Replication with Connector/J</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-j2ee-concepts-load-balancing-failover">8.4 Advanced Load-balancing and Failover Configuration</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-interceptors">9 Using the Connector/J Interceptor Classes</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-tomcat">10 Using Connector/J with Tomcat</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-jboss">11 Using Connector/J with JBoss</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-spring-config">12 Using Connector/J with Spring</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-jdbctemplate">12.1 Using <code class="classname">JdbcTemplate</code></a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-transactional">12.2 Transactional JDBC Access</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-connpooling">12.3 Connection Pooling with Spring</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-usagenotes-glassfish-config">13 Using Connector/J with GlassFish</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-usagenotes-glassfish-config-jsp">13.1 A Simple JSP Application with GlassFish, Connector/J and MySQL</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-glassfish-config-servlet">13.2 A Simple Servlet with GlassFish, Connector/J and MySQL</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-j-usagenotes-fabric">14 Using Connector/J with MySQL Fabric</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-troubleshooting">15 Troubleshooting Connector/J Applications</a></span></dt><dt><span class="chapter"><a href="#connector-j-usagenotes-known-issues-limitations">16 Known Issues and Limitations</a></span></dt><dt><span class="chapter"><a href="#connector-j-support">17 Connector/J Support</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-support-community">17.1 Connector/J Community Support</a></span></dt><dt><span class="section"><a href="#connector-j-support-bug-report">17.2 How to Report Connector/J Bugs or Problems</a></span></dt></dl></dd></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a name="preface"></a>Preface and Legal Notices</h1></div></div></div><p>
|
||
This manual describes how to install, configure, and develop
|
||
database applications using MySQL Connector/J, the JDBC driver for
|
||
communicating with MySQL servers.
|
||
</p><div class="simplesect"><div class="titlepage"><div><div class="simple"><h2 class="title" style="clear: both"><a name="legalnotice"></a>Legal Notices</h2></div></div></div><p>
|
||
Copyright © 1998, 2016, Oracle and/or its affiliates. All
|
||
rights reserved.
|
||
</p><p>
|
||
This software and related documentation are provided under a license
|
||
agreement containing restrictions on use and disclosure and are
|
||
protected by intellectual property laws. Except as expressly
|
||
permitted in your license agreement or allowed by law, you may not
|
||
use, copy, reproduce, translate, broadcast, modify, license,
|
||
transmit, distribute, exhibit, perform, publish, or display any
|
||
part, in any form, or by any means. Reverse engineering,
|
||
disassembly, or decompilation of this software, unless required by
|
||
law for interoperability, is prohibited.
|
||
</p><p>
|
||
The information contained herein is subject to change without notice
|
||
and is not warranted to be error-free. If you find any errors,
|
||
please report them to us in writing.
|
||
</p><p>
|
||
If this is software or related documentation that is delivered to
|
||
the U.S. Government or anyone licensing it on behalf of the U.S.
|
||
Government, then the following notice is applicable:
|
||
</p><p>
|
||
U.S. GOVERNMENT END USERS: Oracle programs, including any operating
|
||
system, integrated software, any programs installed on the hardware,
|
||
and/or documentation, delivered to U.S. Government end users are
|
||
"commercial computer software" pursuant to the applicable Federal
|
||
Acquisition Regulation and agency-specific supplemental regulations.
|
||
As such, use, duplication, disclosure, modification, and adaptation
|
||
of the programs, including any operating system, integrated
|
||
software, any programs installed on the hardware, and/or
|
||
documentation, shall be subject to license terms and license
|
||
restrictions applicable to the programs. No other rights are granted
|
||
to the U.S. Government.
|
||
</p><p>
|
||
This software or hardware is developed for general use in a variety
|
||
of information management applications. It is not developed or
|
||
intended for use in any inherently dangerous applications, including
|
||
applications that may create a risk of personal injury. If you use
|
||
this software or hardware in dangerous applications, then you shall
|
||
be responsible to take all appropriate fail-safe, backup,
|
||
redundancy, and other measures to ensure its safe use. Oracle
|
||
Corporation and its affiliates disclaim any liability for any
|
||
damages caused by use of this software or hardware in dangerous
|
||
applications.
|
||
</p><p>
|
||
Oracle and Java are registered trademarks of Oracle and/or its
|
||
affiliates. Other names may be trademarks of their respective
|
||
owners.
|
||
</p><p>
|
||
Intel and Intel Xeon are trademarks or registered trademarks of
|
||
Intel Corporation. All SPARC trademarks are used under license and
|
||
are trademarks or registered trademarks of SPARC International, Inc.
|
||
AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks
|
||
or registered trademarks of Advanced Micro Devices. UNIX is a
|
||
registered trademark of The Open Group.
|
||
</p><p>
|
||
This software or hardware and documentation may provide access to or
|
||
information about content, products, and services from third
|
||
parties. Oracle Corporation and its affiliates are not responsible
|
||
for and expressly disclaim all warranties of any kind with respect
|
||
to third-party content, products, and services unless otherwise set
|
||
forth in an applicable agreement between you and Oracle. Oracle
|
||
Corporation and its affiliates will not be responsible for any loss,
|
||
costs, or damages incurred due to your access to or use of
|
||
third-party content, products, or services, except as set forth in
|
||
an applicable agreement between you and Oracle.
|
||
</p><p class="legal-head">Documentation Accessibility</p><p>
|
||
For information about Oracle's commitment to accessibility, visit
|
||
the Oracle Accessibility Program website at
|
||
|
||
|
||
|
||
<a class="ulink" href="http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc" target="_top">http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc</a>.
|
||
</p><p class="legal-subhead">Access to Oracle Support</p><p>
|
||
Oracle customers that have purchased support have access to
|
||
electronic support through My Oracle Support. For information,
|
||
visit
|
||
|
||
|
||
|
||
<a class="ulink" href="http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info" target="_top">http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info</a>
|
||
or visit
|
||
<a class="ulink" href="http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs" target="_top">http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs</a>
|
||
if you are hearing impaired.
|
||
</p><p>
|
||
This documentation is NOT distributed under a GPL license. Use of
|
||
this documentation is subject to the following terms:
|
||
</p><p>
|
||
You may create a printed copy of this documentation solely for your
|
||
own personal use. Conversion to other formats is allowed as long as
|
||
the actual content is not altered or edited in any way. You shall
|
||
not publish or distribute this documentation in any form or on any
|
||
media, except if you distribute the documentation in a manner
|
||
similar to how Oracle disseminates it (that is, electronically for
|
||
download on a Web site with the software) or on a CD-ROM or similar
|
||
medium, provided however that the documentation is disseminated
|
||
together with the software on the same medium. Any other use, such
|
||
as any dissemination of printed copies or use of this documentation,
|
||
in whole or in part, in another publication, requires the prior
|
||
written consent from an authorized representative of Oracle. Oracle
|
||
and/or its affiliates reserve any and all rights to this
|
||
documentation not expressly granted above.
|
||
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-overview"></a>Chapter 1 Overview of MySQL Connector/J</h1></div></div></div><a class="indexterm" name="idm140266693398656"></a><p>
|
||
MySQL provides connectivity for client applications developed in
|
||
the Java programming language with MySQL Connector/J, a driver
|
||
that implements the
|
||
<a class="ulink" href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html" target="_top">Java
|
||
Database Connectivity (JDBC) API</a>.
|
||
</p><p>
|
||
MySQL Connector/J is a JDBC Type 4 driver. Different versions are
|
||
available that are compatible with the JDBC 3.0 and JDBC 4.x
|
||
specifications (see <a class="xref" href="#connector-j-versions" title="Chapter 2 Connector/J Versions">Chapter 2, <i>Connector/J Versions</i></a>). The
|
||
Type 4 designation means that the driver is a pure Java
|
||
implementation of the MySQL protocol and does not rely on the
|
||
MySQL client libraries.
|
||
</p><p>
|
||
For large-scale programs that use common design patterns of data
|
||
access, consider using one of the popular persistence frameworks
|
||
such as <a class="ulink" href="http://www.hibernate.org/" target="_top">Hibernate</a>,
|
||
<a class="ulink" href="http://www.springframework.org/" target="_top">Spring's JDBC
|
||
templates</a> or <a class="ulink" href="http://ibatis.apache.org/" target="_top">Ibatis
|
||
SQL Maps</a> to reduce the amount of JDBC code for you to
|
||
debug, tune, secure, and maintain.
|
||
</p><h2><a name="idm140266693564400"></a>Key Topics</h2><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
For help with connection strings, connection options, and
|
||
setting up your connection through JDBC, see
|
||
<a class="xref" href="#connector-j-reference-configuration-properties" title="5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
|
||
for Connector/J”</a>.
|
||
</p></li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-versions"></a>Chapter 2 Connector/J Versions</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-change-history">2.1 Connector/J Release Notes and Change History</a></span></dt><dt><span class="section"><a href="#connector-j-versions-java">2.2 Java Versions Supported</a></span></dt></dl></div><a class="indexterm" name="idm140266693560592"></a><p>
|
||
There are currently four versions of MySQL Connector/J available:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
Connector/J 5.1 is a Type 4 pure Java JDBC driver, which
|
||
conforms to the JDBC 3.0, 4.0, 4.1, and 4.2 specifications. It
|
||
provides compatibility with all the functionality of MySQL,
|
||
including 4.1, 5.0, 5.1, 5.5, 5.6, and 5.7. Connector/J 5.1
|
||
provides ease of development features, including
|
||
auto-registration with the Driver Manager, standardized
|
||
validity checks, categorized SQLExceptions, support for large
|
||
update counts, support for local and offset date-time variants
|
||
from the <code class="literal">java.time</code> package, support for
|
||
JDBC-4.x XML processing, support for per connection client
|
||
information, and support for the
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/char.html" target="_top"><code class="literal">NCHAR</code></a>,
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/char.html" target="_top"><code class="literal">NVARCHAR</code></a> and
|
||
<code class="literal">NCLOB</code> data types. This release also
|
||
includes all bug fixes up to and including Connector/J 5.0.6.
|
||
</p></li><li class="listitem"><p>
|
||
Connector/J 5.0 provides support for all the functionality
|
||
offered by Connector/J 3.1 and includes distributed
|
||
transaction (XA) support.
|
||
</p></li><li class="listitem"><p>
|
||
Connector/J 3.1 was designed for connectivity to MySQL 4.1 and
|
||
MySQL 5.0 servers and provides support for all the
|
||
functionality in MySQL 5.0 except distributed transaction (XA)
|
||
support.
|
||
</p></li><li class="listitem"><p>
|
||
Connector/J 3.0 provides core functionality and was designed
|
||
for connectivity to MySQL 3.x or MySQL 4.1 servers, although
|
||
it provides basic compatibility with later versions of MySQL.
|
||
Connector/J 3.0 does not support server-side prepared
|
||
statements, and does not support any of the features in
|
||
versions of MySQL later than 4.1.
|
||
</p></li></ul></div><p>
|
||
The following table summarizes the Connector/J versions available,
|
||
along with the details of JDBC driver type, what version of the
|
||
JDBC API it supports, what versions of MySQL Server it works with,
|
||
and whether it is currently supported or not:
|
||
</p><p>
|
||
</p><div class="table"><a name="idm140266693549040"></a><p class="title"><b>Table 2.1 Summary of Connector/J Versions</b></p><div class="table-contents"><table class="table" summary="Summary of Connector/J Versions" border="1"><colgroup><col><col><col><col><col></colgroup><thead><tr><th scope="col">Connector/J version</th><th scope="col">Driver Type</th><th scope="col">JDBC version</th><th scope="col">MySQL Server version</th><th scope="col">Status</th></tr></thead><tbody><tr><td scope="row">5.1</td><td>4</td><td>3.0, 4.0, 4.1, 4.2</td><td>4.1, 5.0, 5.1, 5.5, 5.6, 5.7</td><td>Recommended version</td></tr><tr><td scope="row">5.0</td><td>4</td><td>3.0</td><td>4.1, 5.0</td><td>Released version</td></tr><tr><td scope="row">3.1</td><td>4</td><td>3.0</td><td>4.1, 5.0</td><td>Obsolete</td></tr><tr><td scope="row">3.0</td><td>4</td><td>3.0</td><td>3.x, 4.1</td><td>Obsolete</td></tr></tbody></table></div></div><p><br class="table-break">
|
||
</p><p>
|
||
The current recommended version for Connector/J is 5.1. This guide
|
||
covers all four connector versions, with specific notes given
|
||
where a setting applies to a specific option.
|
||
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-change-history"></a>2.1 Connector/J Release Notes and Change History</h2></div></div></div><p>
|
||
For details of new features and bug fixes in each Connector/J
|
||
release, see the
|
||
<a class="ulink" href="http://dev.mysql.com/doc/relnotes/connector-j/en/" target="_top">MySQL
|
||
Connector/J Release Notes</a>.
|
||
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-versions-java"></a>2.2 Java Versions Supported</h2></div></div></div><p>
|
||
The following table summarizes what version of JRE is required
|
||
to use Connector/J with Java applications, and what version of
|
||
JDK is required to build Connector/J source code:
|
||
</p><p>
|
||
</p><div class="table"><a name="idm140266687991728"></a><p class="title"><b>Table 2.2 Summary of Java Versions Required by Connector/J</b></p><div class="table-contents"><table class="table" summary="Summary of Java Versions Required by Connector/J" border="1"><colgroup><col><col><col></colgroup><thead><tr><th scope="col">Connector/J version</th><th scope="col">JRE Supported</th><th scope="col">JDK required (to build source code)</th></tr></thead><tbody><tr><td scope="row">5.1</td><td>1.5.x, 1.6.x, 1.7.x, 1.8.x</td><td>1.6.x and 1.5.x</td></tr><tr><td scope="row">5.0</td><td>1.3.x, 1.4.x, 1.5.x, 1.6.x</td><td>1.4.2, 1.5.x, 1.6.x</td></tr><tr><td scope="row">3.1</td><td>1.2.x, 1.3.x, 1.4.x, 1.5.x, 1.6.x</td><td>1.4.2, 1.5.x, 1.6.x</td></tr><tr><td scope="row">3.0</td><td>1.2.x, 1.3.x, 1.4.x, 1.5.x, 1.6.x</td><td>1.4.2, 1.5.x, 1.6.x</td></tr></tbody></table></div></div><p><br class="table-break">
|
||
</p><p>
|
||
If you are building Connector/J from source code using the
|
||
source distribution (see
|
||
<a class="xref" href="#connector-j-installing-source" title="3.4 Installing from Source">Section 3.4, “Installing from Source”</a>), you must use
|
||
JDK 1.4.2 or newer to compile the package for Connector/J 5.0 or
|
||
earlier. For Connector/J 5.1, you must have both JDK-1.6.x
|
||
<span class="emphasis"><em>AND</em></span> JDK-1.5.x installed to be able to build
|
||
the source code.
|
||
</p><p>
|
||
JRE 1.7 support requires Connector/J 5.1.21 and higher.
|
||
</p><p>
|
||
JRE 1.8 is required for Connector/J 5.1 to connect to MySQL
|
||
5.6.27 and later and 5.7 with SSL/TLS when using some cipher
|
||
suites.
|
||
</p><p>
|
||
Several JDBC 4.1 methods were implemented for the first time in
|
||
Connector/J 5.1.21.
|
||
</p><p>
|
||
Because of the implementation of
|
||
<code class="classname">java.sql.Savepoint</code>, Connector/J 3.1.0 and
|
||
newer will not run on a Java runtime older than 1.4 unless the
|
||
class verifier is turned off (by setting the
|
||
<code class="option">-Xverify:none</code> option to the Java runtime). This
|
||
is because the class verifier will try to load the class
|
||
definition for <code class="classname">java.sql.Savepoint</code> even
|
||
though it is not accessed by the driver unless you actually use
|
||
savepoint functionality.
|
||
</p><p>
|
||
Caching functionality provided by Connector/J 3.1.0 or newer is
|
||
also not available on JVMs older than 1.4.x, as it relies on
|
||
<code class="classname">java.util.LinkedHashMap</code>, which was first
|
||
available in JDK-1.4.0.
|
||
</p><p>
|
||
MySQL Connector/J does not support JDK-1.1.x or JDK-1.0.x.
|
||
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-installing"></a>Chapter 3 Connector/J Installation</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-binary-installation">3.1 Installing Connector/J from a Binary Distribution</a></span></dt><dt><span class="section"><a href="#connector-j-installing-classpath">3.2 Installing the Driver and Configuring the <code class="literal">CLASSPATH</code></a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading">3.3 Upgrading from an Older Version</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-installing-upgrading-5-1">3.3.1 Upgrading to MySQL Connector/J 5.1.x</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-issues">3.3.2 JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-3-0-to-3-1">3.3.3 Upgrading from MySQL Connector/J 3.0 to 3.1</a></span></dt></dl></dd><dt><span class="section"><a href="#connector-j-installing-source">3.4 Installing from Source</a></span></dt><dt><span class="section"><a href="#connector-j-testing">3.5 Testing Connector/J</a></span></dt></dl></div><p>
|
||
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
|
||
<code class="literal">CLASSPATH</code>.
|
||
</p><p>
|
||
If you are upgrading from a previous version, read the upgrade
|
||
information in <a class="xref" href="#connector-j-installing-upgrading" title="3.3 Upgrading from an Older Version">Section 3.3, “Upgrading from an Older Version”</a>
|
||
before continuing.
|
||
</p><p>
|
||
Connector/J is also available as part of the Maven project. For
|
||
more information and to download the Connector/J JAR files, see
|
||
the
|
||
<a class="ulink" href="http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22mysql%22%20AND%20a%3A%22mysql-connector-java%22" target="_top">Maven
|
||
repository</a>.
|
||
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-binary-installation"></a>3.1 Installing Connector/J from a Binary Distribution</h2></div></div></div><p>
|
||
For the easiest method of installation, use the binary
|
||
distribution of the Connector/J package. The binary distribution
|
||
is available either as a tar/gzip or zip file. Extract it to a
|
||
suitable location, then optionally make the information about
|
||
the package available by changing your
|
||
<code class="literal">CLASSPATH</code> (see
|
||
<a class="xref" href="#connector-j-installing-classpath" title="3.2 Installing the Driver and Configuring the CLASSPATH">Section 3.2, “Installing the Driver and Configuring the <code class="literal">CLASSPATH</code>”</a>).
|
||
</p><p>
|
||
MySQL Connector/J is distributed as a <code class="literal">.zip</code> or
|
||
<code class="literal">.tar.gz</code> archive containing the sources, the
|
||
class files, and the JAR archive named
|
||
<code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin.jar</code>.
|
||
</p><p>
|
||
Starting with Connector/J 3.1.9, the <code class="filename">.class</code>
|
||
files that constitute the JAR files are only included as part of
|
||
the driver JAR file.
|
||
</p><p>
|
||
Starting with Connector/J 3.1.8, the archive also includes a
|
||
debug build of the driver in a file named
|
||
<code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin-g.jar</code>.
|
||
Do not use the debug build of the driver unless instructed to do
|
||
so when reporting a problem or a bug, as it is not designed to
|
||
be run in production environments, and will have adverse
|
||
performance impact when used. The debug binary also depends on
|
||
the Aspect/J runtime library, which is located in the
|
||
<code class="filename">src/lib/aspectjrt.jar</code> file that comes with
|
||
the Connector/J distribution.
|
||
</p><p>
|
||
Use the appropriate graphical or command-line utility to extract
|
||
the distribution (for example, WinZip for the .zip archive, and
|
||
<span class="command"><strong>tar</strong></span> 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.
|
||
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-installing-classpath"></a>3.2 Installing the Driver and Configuring the <code class="literal">CLASSPATH</code></h2></div></div></div><a class="indexterm" name="idm140266687956592"></a><p>
|
||
Once you have extracted the distribution archive, you can
|
||
install the driver by placing
|
||
<code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin.jar
|
||
</code>in your classpath, either by adding the full path to
|
||
it to your <code class="literal">CLASSPATH</code> environment variable, or
|
||
by directly specifying it with the command line switch
|
||
<code class="literal">-cp</code> when starting the JVM.
|
||
</p><p>
|
||
To use the driver with the JDBC
|
||
<code class="literal">DriverManager</code>, use
|
||
<code class="literal">com.mysql.jdbc.Driver</code> as the class that
|
||
implements <code class="classname">java.sql.Driver</code>.
|
||
</p><p>
|
||
You can set the <code class="literal">CLASSPATH</code> environment
|
||
variable under Unix, Linux, or OS X either locally for a user
|
||
within their <code class="literal">.profile</code>,
|
||
<code class="literal">.login</code> or other login file. You can also set
|
||
it globally by editing the global
|
||
<code class="literal">/etc/profile</code> file.
|
||
</p><p>
|
||
For example, add the Connector/J driver to your
|
||
<code class="literal">CLASSPATH</code> using one of the following forms,
|
||
depending on your command shell:
|
||
</p><pre class="programlisting">
|
||
# Bourne-compatible shell (sh, ksh, bash, zsh):
|
||
shell> export CLASSPATH=/path/mysql-connector-java-<em class="replaceable"><code>ver</code></em>-bin.jar:$CLASSPATH
|
||
|
||
# C shell (csh, tcsh):
|
||
shell> setenv CLASSPATH /path/mysql-connector-java-<em class="replaceable"><code>ver</code></em>-bin.jar:$CLASSPATH
|
||
</pre><p>
|
||
For Windows platforms, you set the environment variable through
|
||
the System Control Panel.
|
||
</p><p>
|
||
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
|
||
<code class="literal">CLASSPATH</code> environment variable. For
|
||
configuration examples for some J2EE application servers, see
|
||
<a class="xref" href="#connector-j-usagenotes-j2ee-concepts-connection-pooling" title="Chapter 7 Connection Pooling with Connector/J">Chapter 7, <i>Connection Pooling with Connector/J</i></a>,
|
||
<a class="xref" href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections" title="8.2 Configuring Load Balancing with Connector/J">Section 8.2, “Configuring Load Balancing with Connector/J”</a>,
|
||
and
|
||
<a class="xref" href="#connector-j-usagenotes-j2ee-concepts-load-balancing-failover" title="8.4 Advanced Load-balancing and Failover Configuration">Section 8.4, “Advanced Load-balancing and Failover Configuration”</a>.
|
||
|
||
|
||
|
||
However, the authoritative source for JDBC connection pool
|
||
configuration information for your particular application server
|
||
is the documentation for that application server.
|
||
</p><p>
|
||
If you are developing servlets or JSPs, and your application
|
||
server is J2EE-compliant, you can put the driver's
|
||
<code class="literal">.jar</code> file in the
|
||
<code class="filename">WEB-INF/lib</code> subdirectory of your webapp, as
|
||
this is a standard location for third party class libraries in
|
||
J2EE web applications.
|
||
</p><p>
|
||
You can also use the <code class="classname">MysqlDataSource</code> or
|
||
<code class="classname">MysqlConnectionPoolDataSource</code> classes in
|
||
the <code class="literal">com.mysql.jdbc.jdbc2.optional</code> package, if
|
||
your J2EE application server supports or requires them. Starting
|
||
with Connector/J 5.0.0, the
|
||
<code class="literal">javax.sql.XADataSource</code> interface is
|
||
implemented using the
|
||
<code class="literal">com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</code>
|
||
class, which supports XA distributed transactions when used in
|
||
combination with MySQL server version 5.0 and later.
|
||
</p><p>
|
||
The various <code class="classname">MysqlDataSource</code> classes
|
||
support the following parameters (through standard set
|
||
mutators):
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="literal">user</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">password</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">serverName</code> (see the previous section
|
||
about failover hosts)
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">databaseName</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">port</code>
|
||
</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-installing-upgrading"></a>3.3 Upgrading from an Older Version</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="#connector-j-installing-upgrading-5-1">3.3.1 Upgrading to MySQL Connector/J 5.1.x</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-issues">3.3.2 JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer</a></span></dt><dt><span class="section"><a href="#connector-j-installing-upgrading-3-0-to-3-1">3.3.3 Upgrading from MySQL Connector/J 3.0 to 3.1</a></span></dt></dl></div><p>
|
||
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.
|
||
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-j-installing-upgrading-5-1"></a>3.3.1 Upgrading to MySQL Connector/J 5.1.x</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
In Connector/J 5.0.x and earlier, the alias for a table in
|
||
a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/select.html" target="_top"><code class="literal">SELECT</code></a> statement is
|
||
returned when accessing the result set metadata using
|
||
<code class="function">ResultSetMetaData.getColumnName()</code>.
|
||
This behavior however is not JDBC compliant, and in
|
||
Connector/J 5.1, this behavior has been changed so that
|
||
the original table name, rather than the alias, is
|
||
returned.
|
||
</p><p>
|
||
The JDBC-compliant behavior is designed to let API users
|
||
reconstruct the DML statement based on the metadata within
|
||
<code class="literal">ResultSet</code> and
|
||
<code class="literal">ResultSetMetaData</code>.
|
||
</p><p>
|
||
You can get the alias for a column in a result set by
|
||
calling
|
||
<code class="function">ResultSetMetaData.getColumnLabel()</code>.
|
||
To use the old noncompliant behavior with
|
||
<code class="function">ResultSetMetaData.getColumnName()</code>,
|
||
use the <code class="option">useOldAliasMetadataBehavior</code>
|
||
option and set the value to <code class="literal">true</code>.
|
||
</p><p>
|
||
In Connector/J 5.0.x, the default value of
|
||
<code class="option">useOldAliasMetadataBehavior</code> was
|
||
<code class="literal">true</code>, but in Connector/J 5.1 this was
|
||
changed to a default value of <code class="literal">false</code>.
|
||
</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-j-installing-upgrading-issues"></a>3.3.2 JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or Newer</h3></div></div></div><a class="indexterm" name="idm140266687912096"></a><a class="indexterm" name="idm140266687910704"></a><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<span class="emphasis"><em>Using the UTF-8 Character Encoding</em></span> -
|
||
Prior to MySQL server version 4.1, the UTF-8 character
|
||
encoding was not supported by the server, however the JDBC
|
||
driver could use it, allowing storage of multiple
|
||
character sets in <code class="literal">latin1</code> tables on the
|
||
server.
|
||
</p><p>
|
||
Starting with MySQL-4.1, this functionality is deprecated.
|
||
If you have applications that rely on this functionality,
|
||
and can not upgrade them to use the official Unicode
|
||
character support in MySQL server version 4.1 or newer,
|
||
add the following property to your connection URL:
|
||
</p><p>
|
||
<code class="computeroutput">useOldUTF8Behavior=true</code>
|
||
</p></li><li class="listitem"><p>
|
||
<span class="emphasis"><em>Server-side Prepared Statements</em></span> -
|
||
Connector/J 3.1 will automatically detect and use
|
||
server-side prepared statements when they are available
|
||
(MySQL server version 4.1.0 and newer). If your
|
||
application encounters issues with server-side prepared
|
||
statements, you can revert to the older client-side
|
||
emulated prepared statement code that is still presently
|
||
used for MySQL servers older than 4.1.0 with the following
|
||
connection property:
|
||
</p><p>
|
||
<code class="computeroutput">useServerPrepStmts=false</code>
|
||
</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-j-installing-upgrading-3-0-to-3-1"></a>3.3.3 Upgrading from MySQL Connector/J 3.0 to 3.1</h3></div></div></div><p>
|
||
Connector/J 3.1 is designed to be backward-compatible with
|
||
Connector/J 3.0 as much as possible. Major changes are
|
||
isolated to new functionality exposed in MySQL-4.1 and newer,
|
||
which includes Unicode character sets, server-side prepared
|
||
statements, <code class="literal">SQLState</code> codes returned in
|
||
error messages by the server and various performance
|
||
enhancements that can be enabled or disabled using
|
||
configuration properties.
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<span class="bold"><strong>Unicode Character Sets</strong></span>:
|
||
See the next section, as well as
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/charset.html" target="_top">Character Set Support</a>, for information on this MySQL
|
||
feature. If you have something misconfigured, it will
|
||
usually show up as an error with a message similar to
|
||
<code class="literal">Illegal mix of collations</code>.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>Server-side Prepared
|
||
Statements</strong></span>: Connector/J 3.1 will automatically
|
||
detect and use server-side prepared statements when they
|
||
are available (MySQL server version 4.1.0 and newer).
|
||
</p><p>
|
||
Starting with version 3.1.7, the driver scans SQL you are
|
||
preparing using all variants of
|
||
<code class="literal">Connection.prepareStatement()</code> to
|
||
determine if it is a supported type of statement to
|
||
prepare on the server side, and if it is not supported by
|
||
the server, it instead prepares it as a client-side
|
||
emulated prepared statement. You can disable this feature
|
||
by passing
|
||
<code class="literal">emulateUnsupportedPstmts=false</code> in your
|
||
JDBC URL.
|
||
</p><p>
|
||
If your application encounters issues with server-side
|
||
prepared statements, you can revert to the older
|
||
client-side emulated prepared statement code that is still
|
||
presently used for MySQL servers older than 4.1.0 with the
|
||
connection property
|
||
<code class="literal">useServerPrepStmts=false</code>.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>Datetimes</strong></span> with all-zero
|
||
components (<code class="literal">0000-00-00 ...</code>): These
|
||
values cannot be represented reliably in Java. Connector/J
|
||
3.0.x always converted them to <code class="literal">NULL</code>
|
||
when being read from a ResultSet.
|
||
</p><p>
|
||
Connector/J 3.1 throws an exception by default when these
|
||
values are encountered, as this is the most correct
|
||
behavior according to the JDBC and SQL standards. This
|
||
behavior can be modified using the
|
||
<code class="literal">zeroDateTimeBehavior</code> configuration
|
||
property. The permissible values are:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
|
||
<code class="literal">exception</code> (the default), which
|
||
throws an SQLException with an SQLState of
|
||
<code class="literal">S1009</code>.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">convertToNull</code>, which returns
|
||
<code class="literal">NULL</code> instead of the date.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">round</code>, which rounds the date to the
|
||
nearest closest value which is
|
||
<code class="literal">0001-01-01</code>.
|
||
</p></li></ul></div><p>
|
||
Starting with Connector/J 3.1.7,
|
||
<code class="literal">ResultSet.getString()</code> can be decoupled
|
||
from this behavior using
|
||
<code class="literal">noDatetimeStringSync=true</code> (the default
|
||
value is <code class="literal">false</code>) so that you can
|
||
retrieve the unaltered all-zero value as a String. Note
|
||
that this also precludes using any time zone conversions,
|
||
therefore the driver will not allow you to enable
|
||
<code class="literal">noDatetimeStringSync</code> and
|
||
<code class="literal">useTimezone</code> at the same time.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>New SQLState Codes</strong></span>:
|
||
Connector/J 3.1 uses SQL:1999 SQLState codes returned by
|
||
the MySQL server (if supported), which are different from
|
||
the legacy X/Open state codes that Connector/J 3.0 uses.
|
||
If connected to a MySQL server older than MySQL-4.1.0 (the
|
||
oldest version to return SQLStates as part of the error
|
||
code), the driver will use a built-in mapping. You can
|
||
revert to the old mapping by using the configuration
|
||
property <code class="literal">useSqlStateCodes=false</code>.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong><code class="literal">ResultSet.getString()</code></strong></span>:
|
||
Calling <code class="literal">ResultSet.getString()</code> on a
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/blob.html" target="_top"><code class="literal">BLOB</code></a> column will now return
|
||
the address of the <code class="literal">byte[]</code> array that
|
||
represents it, instead of a <code class="literal">String</code>
|
||
representation of the <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/blob.html" target="_top"><code class="literal">BLOB</code></a>.
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/blob.html" target="_top"><code class="literal">BLOB</code></a> values have no
|
||
character set, so they cannot be converted to
|
||
<code class="literal">java.lang.String</code>s without data loss or
|
||
corruption.
|
||
</p><p>
|
||
To store strings in MySQL with LOB behavior, use one of
|
||
the <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/blob.html" target="_top"><code class="literal">TEXT</code></a> types, which the
|
||
driver will treat as a <code class="literal">java.sql.Clob</code>.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>Debug builds</strong></span>: Starting
|
||
with Connector/J 3.1.8 a debug build of the driver in a
|
||
file named
|
||
<code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin-g.jar</code>
|
||
is shipped alongside the normal binary jar file that is
|
||
named
|
||
<code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin.jar</code>.
|
||
</p><p>
|
||
Starting with Connector/J 3.1.9, we do not ship the
|
||
<code class="literal">.class</code> files unbundled, they are only
|
||
available in the JAR archives that ship with the driver.
|
||
</p><p>
|
||
Do not use the debug build of the driver unless instructed
|
||
to do so when reporting a problem or bug, as it is not
|
||
designed to be run in production environments, and will
|
||
have adverse performance impact when used. The debug
|
||
binary also depends on the Aspect/J runtime library, which
|
||
is located in the
|
||
<code class="filename">src/lib/aspectjrt.jar</code> file that comes
|
||
with the Connector/J distribution.
|
||
</p></li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-installing-source"></a>3.4 Installing from Source</h2></div></div></div><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Caution</div><p>
|
||
To just get MySQL Connector/J up and running on your system,
|
||
install Connector/J
|
||
<a class="link" href="#connector-j-binary-installation" title="3.1 Installing Connector/J from a Binary Distribution">using a
|
||
standard binary release distribution</a>. Instructions in
|
||
this section is only for users who, for various reasons, want
|
||
to compile Connector/J from source.
|
||
</p></div><p>
|
||
The requirements and steps for installing from source
|
||
Connector/J <a class="link" href="#connector-j-installing-5.1.37" title="Installing Connector/J 5.1.37 or later from source">5.1.37
|
||
or later</a>,
|
||
<a class="link" href="#connector-j-installing-5.1.34" title="Installing Connector/J 5.1.34 to 5.1.36 from source">5.1.34 to
|
||
5.1.36</a>, and
|
||
<a class="link" href="#connector-j-installing-5.1.33" title="Installing Connector/J 5.1.33 or earlier from the source tree">5.1.33 or
|
||
earlier</a> are different; check the section below that is
|
||
relevant for the version you want.
|
||
</p><p><a name="connector-j-installing-5.1.37"></a><b>Installing Connector/J 5.1.37 or later from source. </b>
|
||
To install MySQL Connector/J from its source tree on GitHub,
|
||
you need to have the following software on your system:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
A Git client, to check out the sources from our GitHub
|
||
repository (available from
|
||
<a class="ulink" href="http://git-scm.com/downloads" target="_top">http://git-scm.com/downloads</a>).
|
||
</p></li><li class="listitem"><p>
|
||
Apache Ant version 1.8.2 or newer (available from
|
||
<a class="ulink" href="http://ant.apache.org/" target="_top">http://ant.apache.org/</a>).
|
||
</p></li><li class="listitem"><p>
|
||
JDK 1.8.x <span class="emphasis"><em>AND</em></span> JDK 1.5.x.
|
||
</p></li><li class="listitem"><p>
|
||
JRE 1.6.x (optional)
|
||
</p></li><li class="listitem"><p>
|
||
JUnit libraries (available from
|
||
<a class="ulink" href="https://github.com/junit-team/junit/wiki/Download-and-Install" target="_top">https://github.com/junit-team/junit/wiki/Download-and-Install</a>).
|
||
</p></li><li class="listitem"><p>
|
||
The required <code class="filename">.jar</code> files from the
|
||
Hibernate ORM 4.1 or 4.2 Final release bundle, which is
|
||
available at
|
||
<a class="ulink" href="http://sourceforge.net/projects/hibernate/files/hibernate4/" target="_top">http://sourceforge.net/projects/hibernate/files/hibernate4/</a>.
|
||
</p></li></ul></div><p>
|
||
To check out and compile MySQL Connector/J, follow these steps:
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
Check out the code from the source code repository for MySQL
|
||
Connector/J located on GitHub at
|
||
<a class="ulink" href="https://github.com/mysql/mysql-connector-j" target="_top">https://github.com/mysql/mysql-connector-j</a>;
|
||
for the latest release of the Connector/J 5.1 series, use
|
||
the following command:
|
||
</p><pre class="programlisting">
|
||
shell> <strong class="userinput"><code>git clone https://github.com/mysql/mysql-connector-j.git</code></strong>
|
||
</pre><p>
|
||
To check out a release other than the latest one, use the
|
||
<code class="option">--branch</code> option to specify the revision tag
|
||
for it:
|
||
|
||
</p><pre class="programlisting">
|
||
shell> <strong class="userinput"><code>git clone --branch 5.1.<em class="replaceable"><code>xx</code></em> https://github.com/mysql/mysql-connector-j.git</code></strong>
|
||
</pre><p>
|
||
</p><p>
|
||
Under the current directory, the commands create a
|
||
<code class="filename">mysql-connector-j</code> subdirectory , which
|
||
contains the code you want.
|
||
</p></li><li class="listitem"><p>
|
||
Make sure that you have both JDK 1.8.x
|
||
<span class="emphasis"><em>AND</em></span> JDK 1.5.x installed. You need both
|
||
JDKs because besides supporting JDBC from 4.0 to 4.2,
|
||
Connector/J 5.1 also supports JDBC 3.0, which is an older
|
||
version and requires the older JDK 1.5.x.
|
||
</p></li><li class="listitem"><p>
|
||
Consider also having JRE 1.6.x installed. This is optional:
|
||
if JRE 1.6.x is not available or not supplied to Ant with
|
||
the property <code class="literal">com.mysql.jdbc.java6.rtjar</code>,
|
||
the Java 8 bootstrap classes will be used. A warning will be
|
||
returned, saying that the bootstrap class path was not set
|
||
with the option to compile sources written for Java 6.
|
||
</p></li><li class="listitem"><p>
|
||
Place the required <code class="filename">junit.jar</code> file in a
|
||
separate directory—for example,
|
||
<code class="filename">/home/username/ant-extralibs</code>.
|
||
</p></li><li class="listitem"><p>
|
||
In the same directory for extra libraries described in the
|
||
last step, create a directory named
|
||
<code class="filename">hibernate4</code>, and put under it all the
|
||
<code class="filename">.jar</code> files you can find under the
|
||
<code class="filename">/lib/required/</code> folder in the Hibernate
|
||
ORM 4 Final release bundle.
|
||
</p></li><li class="listitem"><p>
|
||
Change your current working directory to the
|
||
<code class="filename">mysql-connector-j</code> directory created in
|
||
step 1 above.
|
||
</p></li><li class="listitem"><p>
|
||
In the directory, create a file named
|
||
<code class="filename">build.properties</code> to indicate to Ant the
|
||
locations of the root directories for your JDK 1.8.x and JDK
|
||
1.5.x installations, the location of the
|
||
<code class="filename">rt.jar</code> of your JRE 1.6.x (optional),
|
||
and the location of the extra libraries. The file should
|
||
contain the following property settings, with the
|
||
<span class="quote">“<span class="quote"><em class="replaceable"><code>path_to_*</code></em></span>”</span> parts
|
||
replaced by the appropriate filepaths:
|
||
</p><pre class="programlisting">
|
||
com.mysql.jdbc.jdk8=<em class="replaceable"><code>path_to_jdk_1.8</code></em>
|
||
com.mysql.jdbc.jdk5=<em class="replaceable"><code>path_to_jdk_1.5</code></em>
|
||
com.mysql.jdbc.java6.rtjar=<em class="replaceable"><code>path_to_rt.jar_under_jre_1.6</code></em>/rt.jar
|
||
com.mysql.jdbc.extra.libs=<em class="replaceable"><code>path_to_folder_for_extra_libraries</code></em>
|
||
</pre><p>
|
||
Alternatively, you can set the values of those properties
|
||
through the Ant <code class="option">-D</code> options.
|
||
</p></li><li class="listitem"><p>
|
||
Issue the following command to compile the driver and create
|
||
a <code class="filename">.jar</code> file for Connector/J:
|
||
</p><pre class="programlisting">
|
||
shell> <strong class="userinput"><code>ant dist</code></strong>
|
||
</pre><p>
|
||
This creates a <code class="filename">build</code> directory in the
|
||
current directory, where all the build output goes. A
|
||
directory is created under the <code class="filename">build</code>
|
||
directory, whose name includes the version number of the
|
||
release you are building. That directory contains the
|
||
sources, the compiled <code class="filename">.class</code> files, and
|
||
a <code class="filename">.jar</code> file for deployment. For more
|
||
information and other possible targets, including those that
|
||
create a fully packaged distribution, issue the following
|
||
command:
|
||
</p><pre class="programlisting">
|
||
shell> <strong class="userinput"><code>ant -projecthelp</code></strong>
|
||
</pre></li><li class="listitem"><p>
|
||
Install the newly created <code class="filename">.jar</code> file for
|
||
the JDBC driver as you would install a binary
|
||
<code class="filename">.jar</code> file you download from MySQL by
|
||
following the instructions given in
|
||
<a class="xref" href="#connector-j-installing-classpath" title="3.2 Installing the Driver and Configuring the CLASSPATH">Section 3.2, “Installing the Driver and Configuring the <code class="literal">CLASSPATH</code>”</a>.
|
||
</p></li></ol></div><p>
|
||
Note that a package containing both the binary and source code
|
||
for Connector/J 5.1 can also be found at
|
||
<a class="ulink" href="http://dev.mysql.com/downloads/connector/j/5.1.html" target="_top">
|
||
Connector/J 5.1 Download</a>.
|
||
</p><p><a name="connector-j-installing-5.1.34"></a><b>Installing Connector/J 5.1.34 to 5.1.36 from source. </b>
|
||
To install MySQL Connector/J 5.1.34 to 5.1.36 from the
|
||
Connector/J source tree on GitHub, make sure that you have the
|
||
following software on your system:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
A Git client, to check out the sources from our GitHub
|
||
repository (available from
|
||
<a class="ulink" href="http://git-scm.com/downloads" target="_top">http://git-scm.com/downloads</a>).
|
||
</p></li><li class="listitem"><p>
|
||
Apache Ant version 1.8.2 or newer (available from
|
||
<a class="ulink" href="http://ant.apache.org/" target="_top">http://ant.apache.org/</a>).
|
||
</p></li><li class="listitem"><p>
|
||
JDK 1.6.x <span class="emphasis"><em>AND</em></span> JDK 1.5.x.
|
||
</p></li><li class="listitem"><p>
|
||
JUnit libraries (available from
|
||
<a class="ulink" href="https://github.com/junit-team/junit/wiki/Download-and-Install" target="_top">https://github.com/junit-team/junit/wiki/Download-and-Install</a>).
|
||
</p></li><li class="listitem"><p>
|
||
The required <code class="filename">.jar</code> files from the
|
||
Hibernate ORM 4.1 or 4.2 Final release bundle, which is
|
||
available at
|
||
<a class="ulink" href="http://sourceforge.net/projects/hibernate/files/hibernate4/" target="_top">http://sourceforge.net/projects/hibernate/files/hibernate4/</a>.
|
||
</p></li></ul></div><p>
|
||
To check out and compile MySQL Connector/J, follow these steps:
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
Check out the code from the source code repository for MySQL
|
||
Connector/J located on GitHub at
|
||
<a class="ulink" href="https://github.com/mysql/mysql-connector-j" target="_top">https://github.com/mysql/mysql-connector-j</a>,
|
||
using the <code class="option">--branch</code> option to specify the
|
||
revision tag for release 5.1.<em class="replaceable"><code>xx</code></em>:
|
||
|
||
</p><pre class="programlisting">
|
||
shell> <strong class="userinput"><code>git clone --branch 5.1.<em class="replaceable"><code>xx</code></em> https://github.com/mysql/mysql-connector-j.git</code></strong>
|
||
</pre><p>
|
||
</p><p>
|
||
Under the current directory, the commands create a
|
||
<code class="filename">mysql-connector-j</code> subdirectory , which
|
||
contains the code you want.
|
||
</p></li><li class="listitem"><p>
|
||
Make sure that you have both JDK 1.6.x
|
||
<span class="emphasis"><em>AND</em></span> JDK 1.5.x installed. You need both
|
||
JDKs because Connector/J 5.1 supports both JDBC 3.0 (which
|
||
has existed prior to JDK 1.6.x) and JDBC 4.0.
|
||
</p></li><li class="listitem"><p>
|
||
Place the required <code class="filename">junit.jar</code> file in a
|
||
separate directory—for example,
|
||
<code class="filename">/home/username/ant-extralibs</code>.
|
||
</p></li><li class="listitem"><p>
|
||
In the same directory for extra libraries described in the
|
||
last step, create a directory named
|
||
<code class="filename">hibernate4</code>, and put under it all the
|
||
<code class="filename">.jar</code> files you can find under the
|
||
<code class="filename">/lib/required/</code> folder in the Hibernate
|
||
ORM 4 Final release bundle.
|
||
</p></li><li class="listitem"><p>
|
||
Change your current working directory to the
|
||
<code class="filename">mysql-connector-j</code> directory created in
|
||
step 1 above.
|
||
</p></li><li class="listitem"><p>
|
||
In the directory, create a file named
|
||
<code class="filename">build.properties</code> to indicate to Ant the
|
||
locations of the root directories for your JDK 1.5.x and JDK
|
||
1.6.x installations, as well as the location of the extra
|
||
libraries. The file should contain the following property
|
||
settings, with the
|
||
<span class="quote">“<span class="quote"><em class="replaceable"><code>path_to_*</code></em></span>”</span> parts
|
||
replaced by the appropriate filepaths:
|
||
</p><pre class="programlisting">
|
||
com.mysql.jdbc.jdk5=<em class="replaceable"><code>path_to_jdk_1.5</code></em>
|
||
com.mysql.jdbc.jdk6=<em class="replaceable"><code>path_to_jdk_1.6</code></em>
|
||
com.mysql.jdbc.extra.libs=<em class="replaceable"><code>path_to_folder_for_extra_libraries</code></em>
|
||
</pre><p>
|
||
Alternatively, you can set the values of those properties
|
||
through the Ant <code class="option">-D</code> options.
|
||
</p></li><li class="listitem"><p>
|
||
Issue the following command to compile the driver and create
|
||
a <code class="filename">.jar</code> file for Connector/J:
|
||
</p><pre class="programlisting">
|
||
shell> <strong class="userinput"><code>ant dist</code></strong>
|
||
</pre><p>
|
||
This creates a <code class="filename">build</code> directory in the
|
||
current directory, where all the build output goes. A
|
||
directory is created under the <code class="filename">build</code>
|
||
directory, whose name includes the version number of the
|
||
release you are building. That directory contains the
|
||
sources, the compiled <code class="filename">.class</code> files, and
|
||
a <code class="filename">.jar</code> file for deployment. For more
|
||
information and other possible targets, including those that
|
||
create a fully packaged distribution, issue the following
|
||
command:
|
||
</p><pre class="programlisting">
|
||
shell> <strong class="userinput"><code>ant -projecthelp</code></strong>
|
||
</pre></li><li class="listitem"><p>
|
||
Install the newly created <code class="filename">.jar</code> file for
|
||
the JDBC driver as you would install a binary
|
||
<code class="filename">.jar</code> file you download from MySQL by
|
||
following the instructions given in
|
||
<a class="xref" href="#connector-j-installing-classpath" title="3.2 Installing the Driver and Configuring the CLASSPATH">Section 3.2, “Installing the Driver and Configuring the <code class="literal">CLASSPATH</code>”</a>.
|
||
</p></li></ol></div><p><a name="connector-j-installing-5.1.33"></a><b>Installing Connector/J 5.1.33 or earlier from the source tree. </b>
|
||
To install MySQL Connector/J 5.1.33 or earlier from the
|
||
Connector/J source tree on GitHub, make sure that you have the
|
||
following software on your system:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
A Git client, to check out the source code from our GitHub
|
||
repository (available from
|
||
<a class="ulink" href="http://git-scm.com/downloads" target="_top">http://git-scm.com/downloads</a>).
|
||
</p></li><li class="listitem"><p>
|
||
Apache Ant version 1.7 or newer (available from
|
||
<a class="ulink" href="http://ant.apache.org/" target="_top">http://ant.apache.org/</a>).
|
||
</p></li><li class="listitem"><p>
|
||
JDK 1.6.x <span class="emphasis"><em>AND</em></span> JDK 1.5.x. Refer to
|
||
<a class="xref" href="#connector-j-versions-java" title="2.2 Java Versions Supported">Section 2.2, “Java Versions Supported”</a> for the version
|
||
of Java you need to build or run any Connector/J release.
|
||
</p></li><li class="listitem"><p>
|
||
The Ant Contrib (version 1.03b is available from
|
||
<a class="ulink" href="http://sourceforge.net/projects/ant-contrib/files/ant-contrib/1.0b3/" target="_top">http://sourceforge.net/projects/ant-contrib/files/ant-contrib/1.0b3/</a>)
|
||
and JUnit (available from
|
||
<a class="ulink" href="https://github.com/junit-team/junit/wiki/Download-and-Install" target="_top">https://github.com/junit-team/junit/wiki/Download-and-Install</a>)
|
||
libraries.
|
||
</p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
The required <code class="filename">.jar</code> files from the
|
||
Hibernate ORM 4.1 or 4.2 Final release bundle, which is
|
||
available at
|
||
<a class="ulink" href="http://sourceforge.net/projects/hibernate/files/hibernate4/" target="_top">http://sourceforge.net/projects/hibernate/files/hibernate4/</a>.
|
||
</p></li></ul></div><p>
|
||
To check out and compile a specific branch of MySQL Connector/J,
|
||
follow these steps:
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
Check out the code from the source code repository for MySQL
|
||
Connector/J located on GitHub at
|
||
<a class="ulink" href="https://github.com/mysql/mysql-connector-j" target="_top">https://github.com/mysql/mysql-connector-j</a>,
|
||
using the <code class="option">--branch</code> option to specify the
|
||
revision tag for release 5.1.<em class="replaceable"><code>xx</code></em>:
|
||
|
||
</p><pre class="programlisting">
|
||
shell> <strong class="userinput"><code>git clone --branch 5.1.<em class="replaceable"><code>xx</code></em> https://github.com/mysql/mysql-connector-j.git</code></strong>
|
||
</pre><p>
|
||
</p><p>
|
||
Under the current directory, the commands create a
|
||
<code class="filename">mysql-connector-j</code> subdirectory , which
|
||
contains the code you want.
|
||
</p></li><li class="listitem"><p>
|
||
To build Connector/J 5.1, make sure that you have both JDK
|
||
1.6.x <span class="emphasis"><em>AND</em></span> JDK 1.5.x installed. You need
|
||
both JDKs because Connector/J 5.1 supports both JDBC 3.0
|
||
(which has existed prior to JDK 1.6.x) and JDBC 4.0. Set
|
||
your <code class="literal">JAVA_HOME</code> environment variable to
|
||
the path to the JDK 1.5.x installation.
|
||
</p></li><li class="listitem"><p>
|
||
Place the required <code class="filename">ant-contrib.jar</code> file
|
||
(in exactly that name, without the version number in it;
|
||
rename the <code class="filename">jar</code> file if needed) and
|
||
<code class="filename">junit.jar</code> file in a separate
|
||
directory—for example,
|
||
<code class="filename">/home/username/ant-extralibs</code>.
|
||
</p></li><li class="listitem"><p>
|
||
In the same directory for extra libraries described in the
|
||
last step, create a directory named
|
||
<code class="filename">hibernate4</code>, and put under it all the
|
||
<code class="filename">.jar</code> files you can find under the
|
||
<code class="filename">/lib/required/</code> folder in the Hibernate
|
||
ORM 4 Final release bundle.
|
||
</p></li><li class="listitem"><p>
|
||
Change your current working directory to the
|
||
<code class="filename">mysql-connector-j</code> directory created in
|
||
step 1 above.
|
||
</p></li><li class="listitem"><p>
|
||
In the directory, create a file named
|
||
<code class="filename">build.properties</code> to indicate to Ant the
|
||
locations of the Javac and <code class="filename">rt.jar</code> of
|
||
your JDK 1.6.x, as well as the location of the extra
|
||
libraries. The file should contain the following property
|
||
settings, with the
|
||
<span class="quote">“<span class="quote"><em class="replaceable"><code>path_to_*</code></em></span>”</span> parts
|
||
replaced by the appropriate filepaths:
|
||
</p><pre class="programlisting">
|
||
com.mysql.jdbc.java6.javac=<em class="replaceable"><code>path_to_javac_1.6</code></em>/javac
|
||
com.mysql.jdbc.java6.rtjar=<em class="replaceable"><code>path_to_rt.jar_under_jdk_1.6</code></em>/rt.jar
|
||
com.mysql.jdbc.extra.libs=<em class="replaceable"><code>path_to_folder_for_extra_libraries</code></em>
|
||
</pre><p>
|
||
Alternatively, you can set the values of those properties
|
||
through the Ant <code class="option">-D</code> options.
|
||
</p></li><li class="listitem"><p>
|
||
Issue the following command to compile the driver and create
|
||
a <code class="filename">.jar</code> file for Connector/J:
|
||
</p><pre class="programlisting">
|
||
shell> <strong class="userinput"><code>ant dist</code></strong>
|
||
</pre><p>
|
||
This creates a <code class="filename">build</code> directory in the
|
||
current directory, where all the build output goes. A
|
||
directory is created under the <code class="filename">build</code>
|
||
directory, whose name includes the version number of the
|
||
release you are building. That directory contains the
|
||
sources, the compiled <code class="filename">.class</code> files, and
|
||
a <code class="filename">.jar</code> file for deployment. For more
|
||
information and other possible targets, including those that
|
||
create a fully packaged distribution, issue the following
|
||
command:
|
||
</p><pre class="programlisting">
|
||
shell> <strong class="userinput"><code>ant -projecthelp</code></strong>
|
||
</pre></li><li class="listitem"><p>
|
||
Install the newly created <code class="filename">.jar</code> file for
|
||
the JDBC driver as you would install a binary
|
||
<code class="filename">.jar</code> file you download from MySQL by
|
||
following the instructions given in
|
||
<a class="xref" href="#connector-j-installing-classpath" title="3.2 Installing the Driver and Configuring the CLASSPATH">Section 3.2, “Installing the Driver and Configuring the <code class="literal">CLASSPATH</code>”</a>.
|
||
</p></li></ol></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-testing"></a>3.5 Testing Connector/J</h2></div></div></div><p>
|
||
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:
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<span class="emphasis"><em>Functional or unit tests:</em></span> Classes
|
||
from the package <code class="classname">testsuite.simple</code>.
|
||
Include test code for the main features of the
|
||
Connector/J.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="emphasis"><em>Performance tests:</em></span> Classes from the
|
||
package <code class="classname">testsuite.perf</code>. Include
|
||
test code to make measurements for the performance of
|
||
Connector/J.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="emphasis"><em>Fabric tests:</em></span> Classes from the
|
||
package <code class="classname">testsuite.fabric</code>. Includes
|
||
the code to test Fabric-specific features. These tests
|
||
require the setting of some special properties that are
|
||
not documented here. Consult the code or the
|
||
Fabric-related targets in the bundled Ant build file,
|
||
<code class="filename">build.xml</code>.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="emphasis"><em>Regression tests:</em></span> Classes from the
|
||
package <code class="classname">testsuite.regression</code>.
|
||
Includes code for testing bug and regression fixes.
|
||
</p></li></ul></div><p>
|
||
</p><p>
|
||
The bundled Ant build file contains targets like
|
||
<code class="literal">test</code> and <code class="literal">test-multijvm</code>,
|
||
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
|
||
<a class="xref" href="#connector-j-installing-source" title="3.4 Installing from Source">Section 3.4, “Installing from Source”</a>, a number of the
|
||
tests also require the File System Service Provider 1.2 for the
|
||
Java Naming and Directory Interface (JNDI), available at
|
||
<a class="ulink" href="http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html" target="_top">http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html</a>)—place
|
||
the jar files downloaded from there into the
|
||
<code class="filename">lib</code> directory or in the directory pointed
|
||
to by the property <code class="literal">com.mysql.jdbc.extra.libs</code>.
|
||
</p><p>
|
||
To run the test using Ant, in addition to the properties
|
||
required for <a class="xref" href="#connector-j-installing-source" title="3.4 Installing from Source">Section 3.4, “Installing from Source”</a>,
|
||
you must set the following properties in the
|
||
<code class="filename">build.properties</code> file or through the Ant
|
||
<code class="option">-D</code> options:
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="literal">com.mysql.jdbc.testsuite.url</code>: it
|
||
specifies the JDBC URL for connection to a MySQL test
|
||
server; see
|
||
<a class="xref" href="#connector-j-reference-configuration-properties" title="5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
|
||
for Connector/J”</a>.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">com.mysql.jdbc.testsuite.jvm</code>: the JVM
|
||
to be used for the tests. If the property is set, the
|
||
specified JVM will be used for all test cases except if it
|
||
points to a Java 5 directory, in which case any test cases
|
||
for JDBC 4.0 and later are run with the JVM supplied with
|
||
the property <code class="literal">com.mysql.jdbc.jdk8</code> (for
|
||
5.1.36 and earlier, supplied with the property
|
||
<code class="literal">com.mysql.jdbc.jdk6</code>). If the property
|
||
is not set, the JVM supplied with
|
||
<code class="literal">com.mysql.jdbc.jdk5</code> will be used to run
|
||
test cases for JDBC 3.0 and the one supplied with
|
||
<code class="literal">com.mysql.jdbc.jdk8</code> (for 5.1.36 and
|
||
earlier, supplied with the property
|
||
<code class="literal">com.mysql.jdbc.jdk6</code>) will be used to
|
||
run test cases for JDBC 4.0 and later.
|
||
</p></li></ul></div><p>
|
||
</p><p>
|
||
After setting these parameters, run the tests with Ant in the
|
||
following ways:
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
Building the <code class="literal">test</code> target with
|
||
<code class="literal">ant test</code> 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 <code class="literal">test</code> variable; for
|
||
example:
|
||
|
||
</p><pre class="programlisting">
|
||
shell > <strong class="userinput"><code>ant -Dtest=testsuite.simple.StringUtilsTest test</code></strong></pre><p>
|
||
|
||
You can also run individual tests in a test case by
|
||
specifying the names of the corresponding methods in the
|
||
<code class="literal">methods</code> variable, separating multiple
|
||
methods by commas; for example:
|
||
|
||
</p><pre class="programlisting">
|
||
shell > <strong class="userinput"><code>ant -Dtest=testsuite.simple.StringUtilsTest -Dmethods=testIndexOfIgnoreCase,testGetBytes test</code></strong>
|
||
</pre><p>
|
||
</p></li><li class="listitem"><p>
|
||
Building the <code class="literal">test-multijvm</code> target with
|
||
<code class="literal">ant test-multijvm</code> runs all the test
|
||
cases
|
||
|
||
|
||
using multiple JVMs of different versions on multiple
|
||
server instances. For example, if you want to run the
|
||
tests using a Java 7 and a Java 8 JVM on three server
|
||
instances with different configurations, you will need to
|
||
use the following properties:
|
||
|
||
</p><pre class="programlisting">
|
||
com.mysql.jdbc.testsuite.jvm.1=<strong class="userinput"><code>path_to_Java_7</code></strong>
|
||
com.mysql.jdbc.testsuite.jvm.2=<strong class="userinput"><code>path_to_Java_8</code></strong>
|
||
com.mysql.jdbc.testsuite.url.1=<strong class="userinput"><code>URL_to_1st_server</code></strong>
|
||
com.mysql.jdbc.testsuite.url.2=<strong class="userinput"><code>URL_to_2nd_server</code></strong>
|
||
com.mysql.jdbc.testsuite.url.3=<strong class="userinput"><code>URL_to_3rd_server</code></strong></pre><p>
|
||
</p><p>
|
||
Unlike the target <code class="literal">test</code>, the target
|
||
<code class="literal">test-multijvm</code> only recognizes the
|
||
properties
|
||
<code class="literal">com.mysql.jdbc.testsuite.jvm.<strong class="userinput"><code>N</code></strong></code>
|
||
and
|
||
<code class="literal">com.mysql.jdbc.testsuite.url.<strong class="userinput"><code>N</code></strong></code>,
|
||
where <strong class="userinput"><code>N</code></strong> is a numeric suffice; the
|
||
same properties without the suffices are ignored by
|
||
<code class="literal">test-multijvm</code>. As with the target
|
||
<code class="literal">test</code>, if any of the
|
||
<code class="literal">com.mysql.jdbc.testsuite.jvm.<strong class="userinput"><code>N</code></strong></code>
|
||
settings points to Java 5, then Ant relies on the property
|
||
<code class="literal">com.mysql.jdbc.jdk8</code> to run the tests
|
||
specific to JDBC 4.0 and later.
|
||
</p><p>
|
||
You can choose to run individual test cases or specific
|
||
tests by using the <code class="literal">test</code> or
|
||
<code class="literal">methods</code> property, as explained in the
|
||
last bullet for the target <code class="literal">test</code>. Each
|
||
test is run once per possible combination of JVMs and
|
||
server instances (that is, 6 times in total for in this
|
||
example).
|
||
</p><p>
|
||
When a test for a certain JVM-server combination has
|
||
failed, <code class="literal">test-multijvm</code> does not throw an
|
||
error, but moves on to the next combination, until all
|
||
tests for all combinations are finished.
|
||
</p></li></ul></div><p>
|
||
</p><p>
|
||
While the test results are partially reported by the console,
|
||
complete reports in HTML and XML formats are provided:
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
For results of <code class="literal">test</code>: view the HTML
|
||
report by opening
|
||
<code class="filename">build/junit/unitregress/report/index.html</code>.
|
||
XML version of the reports are located in the folder
|
||
<code class="filename">build/junit/unitregress</code>.
|
||
</p></li><li class="listitem"><p>
|
||
For results of <code class="literal">test-multijvm</code>: view the
|
||
HTML report for each JVM-server combination by opening
|
||
<code class="filename">build/junit/MySQL<em class="replaceable"><code>N</code></em>.<em class="replaceable"><code>server_version</code></em>/<em class="replaceable"><code>operating_system_version</code></em>/<em class="replaceable"><code>jvm-version</code></em>/unitregress/report/index.html</code>.
|
||
XML version of the reports are located in the folder
|
||
<code class="filename">build/junit/MySQL<em class="replaceable"><code>N</code></em>.<em class="replaceable"><code>server_version</code></em>/<em class="replaceable"><code>operating_system_version</code></em>/<em class="replaceable"><code>jvm-version</code></em>/unitregress</code>.
|
||
</p></li></ul></div><p>
|
||
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-examples"></a>Chapter 4 Connector/J Examples</h1></div></div></div><a class="indexterm" name="idm140266687654896"></a><p>
|
||
Examples of using Connector/J are located throughout this
|
||
document. This section provides a summary and links to these
|
||
examples.
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<a class="xref" href="#connector-j-examples-connection-drivermanager" title="Example 6.1 Connector/J: Obtaining a connection from the DriverManager">Example 6.1, “Connector/J: Obtaining a connection from the
|
||
<code class="literal">DriverManager</code>”</a>
|
||
</p></li><li class="listitem"><p>
|
||
<a class="xref" href="#connector-j-examples-execute-select" title="Example 6.2 Connector/J: Using java.sql.Statement to execute a SELECT query">Example 6.2, “Connector/J: Using java.sql.Statement to execute a
|
||
<code class="literal">SELECT</code> query”</a>
|
||
</p></li><li class="listitem"><p>
|
||
<a class="xref" href="#connector-j-examples-stored-procedure" title="Example 6.3 Connector/J: Calling Stored Procedures">Example 6.3, “Connector/J: Calling Stored Procedures”</a>
|
||
</p></li><li class="listitem"><p>
|
||
<a class="xref" href="#connector-j-examples-preparecall" title="Example 6.4 Connector/J: Using Connection.prepareCall()">Example 6.4, “Connector/J: Using <code class="literal">Connection.prepareCall()</code>”</a>
|
||
</p></li><li class="listitem"><p>
|
||
<a class="xref" href="#connector-j-examples-output-param" title="Example 6.5 Connector/J: Registering output parameters">Example 6.5, “Connector/J: Registering output parameters”</a>
|
||
</p></li><li class="listitem"><p>
|
||
<a class="xref" href="#connector-j-examples-callablestatement" title="Example 6.6 Connector/J: Setting CallableStatement input parameters">Example 6.6, “Connector/J: Setting <code class="literal">CallableStatement</code> input
|
||
parameters”</a>
|
||
</p></li><li class="listitem"><p>
|
||
<a class="xref" href="#connector-j-examples-retrieving-results-params" title="Example 6.7 Connector/J: Retrieving results and output parameter values">Example 6.7, “Connector/J: Retrieving results and output parameter values”</a>
|
||
</p></li><li class="listitem"><p>
|
||
<a class="xref" href="#connector-j-examples-autoincrement-getgeneratedkeys" title="Example 6.8 Connector/J: Retrieving AUTO_INCREMENT column values using Statement.getGeneratedKeys()">Example 6.8, “Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
|
||
using <code class="literal">Statement.getGeneratedKeys()</code>”</a>
|
||
</p></li><li class="listitem"><p>
|
||
<a class="xref" href="#connector-j-examples-autoincrement-select" title="Example 6.9 Connector/J: Retrieving AUTO_INCREMENT column values using SELECT LAST_INSERT_ID()">Example 6.9, “Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
|
||
using <code class="literal">SELECT LAST_INSERT_ID()</code>”</a>
|
||
</p></li><li class="listitem"><p>
|
||
<a class="xref" href="#connector-j-examples-autoincrement-updateable-resultsets" title="Example 6.10 Connector/J: Retrieving AUTO_INCREMENT column values in Updatable ResultSets">Example 6.10, “Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
|
||
in <code class="literal">Updatable ResultSets</code>”</a>
|
||
</p></li><li class="listitem"><p>
|
||
<a class="xref" href="#connector-j-examples-connectionpool-j2ee" title="Example 7.1 Connector/J: Using a connection pool with a J2EE application server">Example 7.1, “Connector/J: Using a connection pool with a J2EE application server”</a>
|
||
</p></li><li class="listitem"><p>
|
||
<a class="xref" href="#connector-j-examples-transaction-retry" title="Example 15.1 Connector/J: Example of transaction with retry logic">Example 15.1, “Connector/J: Example of transaction with retry logic”</a>
|
||
</p></li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-reference"></a>Chapter 5 Connector/J (JDBC) Reference</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-reference-configuration-properties">5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties
|
||
for Connector/J</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-j-useconfigs">5.1.1 Properties Files for the <code class="literal">useConfigs</code> Option</a></span></dt></dl></dd><dt><span class="section"><a href="#connector-j-reference-implementation-notes">5.2 JDBC API Implementation Notes</a></span></dt><dt><span class="section"><a href="#connector-j-reference-type-conversions">5.3 Java, JDBC and MySQL Types</a></span></dt><dt><span class="section"><a href="#connector-j-reference-charsets">5.4 Using Character Sets and Unicode</a></span></dt><dt><span class="section"><a href="#connector-j-reference-using-ssl">5.5 Connecting Securely Using SSL</a></span></dt><dt><span class="section"><a href="#connector-j-using-pam">5.6 Connecting Using PAM Authentication</a></span></dt><dt><span class="section"><a href="#connector-j-reference-replication-connection">5.7 Using Master/Slave Replication with ReplicationConnection</a></span></dt><dt><span class="section"><a href="#connector-j-reference-error-sqlstates">5.8 Mapping MySQL Error Numbers to JDBC SQLState Codes</a></span></dt></dl></div><p>
|
||
This section of the manual contains reference material for MySQL
|
||
Connector/J.
|
||
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-configuration-properties"></a>5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties
|
||
for Connector/J</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="#connector-j-useconfigs">5.1.1 Properties Files for the <code class="literal">useConfigs</code> Option</a></span></dt></dl></div><a class="indexterm" name="idm140266687634656"></a><a class="indexterm" name="idm140266687633264"></a><p>
|
||
The name of the class that implements
|
||
<code class="literal">java.sql.Driver</code> in MySQL Connector/J is
|
||
<code class="literal">com.mysql.jdbc.Driver</code>. The
|
||
<code class="literal">org.gjt.mm.mysql.Driver</code> class name is also
|
||
usable for backward compatibility with MM.MySQL, the predecessor
|
||
of Connector/J. Use this class name when registering the driver,
|
||
or when configuring a software to use MySQL Connector/J.
|
||
</p><h3><a name="connector-j-reference-url-format"></a>JDBC URL Format</h3><p>
|
||
The general format for a JDBC URL for connecting to a MySQL
|
||
server is as follows, with items in square brackets ([ ]) being
|
||
optional:
|
||
</p><pre class="programlisting">
|
||
jdbc:mysql://[<em class="replaceable"><code>host1</code></em>][:<em class="replaceable"><code>port1</code></em>][,[<em class="replaceable"><code>host2</code></em>][:<em class="replaceable"><code>port2</code></em>]]...[/[<em class="replaceable"><code>database</code></em>]] »
|
||
[?<em class="replaceable"><code>propertyName1</code></em>=<em class="replaceable"><code>propertyValue1</code></em>[&<em class="replaceable"><code>propertyName2</code></em>=<em class="replaceable"><code>propertyValue2</code></em>]...]
|
||
</pre><p>
|
||
Here is a simple example for a connection URL:
|
||
</p><pre class="programlisting">
|
||
jdbc:mysql://localhost:3306/sakila?profileSQL=true
|
||
</pre><p>
|
||
Supply multiple hosts for a server failover setup (see
|
||
<a class="xref" href="#connector-j-multi-host-connections" title="Chapter 8 Multi-Host Connections">Chapter 8, <i>Multi-Host Connections</i></a> for
|
||
details):
|
||
</p><pre class="programlisting">
|
||
# Connection URL for a server failover setup:
|
||
jdbc:mysql//primaryhost,secondaryhost1,secondaryhost2/test</pre><p>
|
||
There are specialized URL schemes for configuring Connector/J's
|
||
multi-host functions like load balancing and replication; here
|
||
are some examples (see
|
||
<a class="xref" href="#connector-j-multi-host-connections" title="Chapter 8 Multi-Host Connections">Chapter 8, <i>Multi-Host Connections</i></a> for
|
||
details):
|
||
|
||
</p><pre class="programlisting">
|
||
# Connection URL for load balancing:
|
||
jdbc:mysql:loadbalance://localhost:3306,localhost:3310/sakila
|
||
|
||
# Connection URL for server replication:
|
||
jdbc:mysql:replication://master,slave1,slave2,slave3/test
|
||
</pre><p>
|
||
</p><h3><a name="idm140266687619200"></a>Host and Port</h3><p>
|
||
If no hosts are not specified, the host name defaults to
|
||
<code class="literal">127.0.0.1</code>. If the port for a host is not
|
||
specified, it defaults to <code class="literal">3306</code>, the default
|
||
port number for MySQL servers.
|
||
</p><h3><a name="idm140266687616688"></a>Initial Database for Connection</h3><p>
|
||
If the database is not specified, the connection is made with no
|
||
default database. In this case, either call the
|
||
<code class="function">setCatalog()</code> method on the Connection
|
||
instance, or fully specify table names using the database name
|
||
(that is, <code class="literal">SELECT
|
||
<em class="replaceable"><code>dbname</code></em>.<em class="replaceable"><code>tablename</code></em>.<em class="replaceable"><code>colname</code></em>
|
||
FROM dbname.tablename...</code>) in your SQL. Opening a
|
||
connection without specifying the database to use is generally
|
||
only useful when building tools that work with multiple
|
||
databases, such as GUI database managers.
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
|
||
Always use the <code class="literal">Connection.setCatalog()</code>
|
||
method to specify the desired database in JDBC applications,
|
||
rather than the <code class="literal">USE
|
||
<em class="replaceable"><code>database</code></em></code> statement.
|
||
</p></div><h3><a name="connector-j-reference-ipv6-url"></a>IPv6 Connections</h3><a class="indexterm" name="idm140266687609504"></a><p>
|
||
For IPv6 connections, use this alternative syntax to specify
|
||
hosts in the URL (the same syntax can also be used for IPv4
|
||
connections):
|
||
|
||
</p><pre class="programlisting">
|
||
jdbc:mysql://address=(<em class="replaceable"><code>key1</code></em>=<em class="replaceable"><code>value</code></em>)[(<em class="replaceable"><code>key2</code></em>=<em class="replaceable"><code>value</code></em>)]...[,address=(key3=value)[(key4=value)]...]...[/[<em class="replaceable"><code>database</code></em>]]»
|
||
[?<em class="replaceable"><code>propertyName1</code></em>=<em class="replaceable"><code>propertyValue1</code></em>[&<em class="replaceable"><code>propertyName2</code></em>=<em class="replaceable"><code>propertyValue2</code></em>]...]
|
||
</pre><p>
|
||
|
||
Supported keys include:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="literal">(protocol=tcp)</code>, or
|
||
<code class="literal">(protocol=pipe)</code> for named pipes on
|
||
Windows.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">(path=<em class="replaceable"><code>path_to_pipe</code></em>)</code>
|
||
for named pipes.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">(host=<em class="replaceable"><code>hostname</code></em>)</code>
|
||
for TCP connections.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">(port=<em class="replaceable"><code>port_number</code></em>)</code>
|
||
for TCP connections.
|
||
</p></li></ul></div><p>
|
||
For example:
|
||
</p><pre class="programlisting">
|
||
jdbc:mysql://address=(protocol=tcp)(host=localhost)(port=3306)/db
|
||
</pre><p>
|
||
Keys other than the four mentioned above are treated as
|
||
host-specific configuration properties, which allow per-host
|
||
overrides of any configuration property set for multi-host
|
||
connections (that is, when using failover, load balancing, or
|
||
replication). For example:
|
||
|
||
</p><pre class="programlisting">
|
||
# IPv6 Connection URL for a server failover setup:
|
||
jdbc:mysql//address=(protocol=tcp)(host=primaryhost)(port=3306),»
|
||
address=(protocol=tcp)(host=secondaryhost1)(port=3310)(user=test2)/test
|
||
|
||
# IPv6 Connection URL for load balancing:
|
||
jdbc:mysql:loadbalance://address=(protocol=tcp)(host=localhost)(port=3306)(user=test1),»
|
||
address=(protocol=tcp)(host=localhost)(port=3310)(user=test2)/sakila
|
||
|
||
# IPv6 Connection URL for server replication:
|
||
jdbc:mysql:replication://address=(protocol=tcp)(host=master)(port=3306)(user=test1),»
|
||
address=(protocol=tcp)(host=slave1)(port=3310)(user=test2)/test
|
||
</pre><p>
|
||
|
||
Limit the overrides to user, password, network timeouts, and
|
||
statement and metadata cache sizes; the effects of other
|
||
per-host overrides are not defined.
|
||
</p><p>
|
||
The ways to set the other configuration properties are the same
|
||
for IPv6 and IPv4 URLs; see
|
||
<a class="xref" href="#connector-j-reference-set-config" title="Setting Configuration Properties">Setting Configuration Properties</a>.
|
||
</p><p></p><h3><a name="connector-j-reference-set-config"></a>Setting Configuration Properties</h3><p>
|
||
Configuration properties define how Connector/J will make a
|
||
connection to a MySQL server. Unless otherwise noted, properties
|
||
can be set for a <code class="literal">DataSource</code> object or for a
|
||
<code class="literal">Connection</code> object.
|
||
</p><p>
|
||
Configuration properties can be set in one of the following
|
||
ways:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
Using the <code class="literal">set*()</code> methods on MySQL
|
||
implementations of <code class="literal">java.sql.DataSource</code>
|
||
(which is the preferred method when using implementations of
|
||
<code class="literal">java.sql.DataSource</code>):
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
|
||
<code class="literal">com.mysql.jdbc.jdbc2.optional.MysqlDataSource</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource</code>
|
||
</p></li></ul></div></li><li class="listitem"><p>
|
||
As a key/value pair in the
|
||
<code class="literal">java.util.Properties</code> instance passed to
|
||
<code class="literal">DriverManager.getConnection()</code> or
|
||
<code class="literal">Driver.connect()</code>
|
||
</p></li><li class="listitem"><p>
|
||
As a JDBC URL parameter in the URL given to
|
||
<code class="literal">java.sql.DriverManager.getConnection()</code>,
|
||
<code class="literal">java.sql.Driver.connect()</code> or the MySQL
|
||
implementations of the
|
||
<code class="literal">javax.sql.DataSource</code>
|
||
<code class="function">setURL()</code> method. If you specify a
|
||
configuration property in the URL without providing a value
|
||
for it, nothing will be set; for example, adding
|
||
<code class="literal">useServerPrepStmts</code> alone to the URL does
|
||
not make Connector/J use server-side prepared statements;
|
||
you need to add <code class="literal">useServerPrepStmts=true</code>.
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
|
||
If the mechanism you use to configure a JDBC URL is
|
||
XML-based, use the XML character literal
|
||
<code class="literal">&amp;</code> to separate configuration
|
||
parameters, as the ampersand is a reserved character for
|
||
XML.
|
||
</p></div></li></ul></div><p>
|
||
The properties are listed in the following tables.
|
||
</p><p><b>Connection/Authentication. </b>
|
||
</p><div class="informaltable"><table class="informaltable" summary="This table lists Connector/J Connection/Authentication
|
||
connection properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
|
||
<span class="strong"><strong>user</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
The user to connect as
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: all versions
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>password</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
The password to use when connecting
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: all versions
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>socketFactory</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
The name of the class that the driver should use for
|
||
creating socket connections to the server. This class
|
||
must implement the interface
|
||
'com.mysql.jdbc.SocketFactory' and have public no-args
|
||
constructor.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: com.mysql.jdbc.StandardSocketFactory
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>connectTimeout</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Timeout for socket connect (in milliseconds), with 0
|
||
being no timeout. Only works on JDK-1.4 or newer.
|
||
Defaults to '0'.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 0
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>socketTimeout</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Timeout on network socket operations (0, the default
|
||
means no timeout).
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 0
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>connectionLifecycleInterceptors</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
A comma-delimited list of classes that implement
|
||
"com.mysql.jdbc.ConnectionLifecycleInterceptor" that
|
||
should notified of connection lifecycle events
|
||
(creation, destruction, commit, rollback, setCatalog
|
||
and setAutoCommit) and potentially alter the execution
|
||
of these commands. ConnectionLifecycleInterceptors are
|
||
"stackable", more than one interceptor may be
|
||
specified via the configuration property as a
|
||
comma-delimited list, with the interceptors executed
|
||
in order from left to right.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.4
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useConfigs</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Load the comma-delimited list of configuration
|
||
properties before parsing the URL or applying
|
||
user-specified properties. These configurations are
|
||
explained in the 'Configurations' of the
|
||
documentation.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.5
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>authenticationPlugins</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Comma-delimited list of classes that implement
|
||
com.mysql.jdbc.AuthenticationPlugin and which will be
|
||
used for authentication unless disabled by
|
||
"disabledAuthenticationPlugins" property.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.19
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>defaultAuthenticationPlugin</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Name of a class implementing
|
||
com.mysql.jdbc.AuthenticationPlugin which will be used
|
||
as the default authentication plugin (see below). It
|
||
is an error to use a class which is not listed in
|
||
"authenticationPlugins" nor it is one of the built-in
|
||
plugins. It is an error to set as default a plugin
|
||
which was disabled with
|
||
"disabledAuthenticationPlugins" property. It is an
|
||
error to set this value to null or the empty string
|
||
(i.e. there must be at least a valid default
|
||
authentication plugin specified for the connection,
|
||
meeting all constraints listed above).
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default:
|
||
com.mysql.jdbc.authentication.MysqlNativePasswordPlugin
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.19
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>disabledAuthenticationPlugins</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Comma-delimited list of classes implementing
|
||
com.mysql.jdbc.AuthenticationPlugin or mechanisms,
|
||
i.e. "mysql_native_password". The authentication
|
||
plugins or mechanisms listed will not be used for
|
||
authentication which will fail if it requires one of
|
||
them. It is an error to disable the default
|
||
authentication plugin (either the one named by
|
||
"defaultAuthenticationPlugin" property or the
|
||
hard-coded one if "defaultAuthenticationPlugin"
|
||
property is not set).
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.19
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>disconnectOnExpiredPasswords</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If "disconnectOnExpiredPasswords" is set to "false"
|
||
and password is expired then server enters "sandbox"
|
||
mode and sends ERR(08001, ER_MUST_CHANGE_PASSWORD) for
|
||
all commands that are not needed to set a new password
|
||
until a new password is set.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.23
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>interactiveClient</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Set the CLIENT_INTERACTIVE flag, which tells MySQL to
|
||
timeout connections based on INTERACTIVE_TIMEOUT
|
||
instead of WAIT_TIMEOUT
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>localSocketAddress</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Hostname or IP address given to explicitly configure
|
||
the interface that the driver will bind the client
|
||
side of the TCP/IP connection to when connecting.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.5
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>propertiesTransform</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
An implementation of
|
||
com.mysql.jdbc.ConnectionPropertiesTransform that the
|
||
driver will use to modify URL properties passed to the
|
||
driver before attempting a connection
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.4
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useCompression</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Use zlib compression when communicating with the
|
||
server (true/false)? Defaults to 'false'.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.17
|
||
</p></td></tr></tbody></table></div><p>
|
||
</p><p><b>Networking. </b>
|
||
</p><div class="informaltable"><table class="informaltable" summary="This table lists Connector/J Networking connection
|
||
properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
|
||
<span class="strong"><strong>socksProxyHost</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Name or IP address of SOCKS host to connect through.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.34
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>socksProxyPort</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Port of SOCKS server.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 1080
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.34
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>maxAllowedPacket</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Maximum allowed packet size to send to server. If not
|
||
set, the value of system variable 'max_allowed_packet'
|
||
will be used to initialize this upon connecting. This
|
||
value will not take effect if set larger than the
|
||
value of 'max_allowed_packet'. Also, due to an
|
||
internal dependency with the property
|
||
"blobSendChunkSize", this setting has a minimum value
|
||
of "8203" if "useServerPrepStmts" is set to "true".
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: -1
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.8
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>tcpKeepAlive</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If connecting using TCP/IP, should the driver set
|
||
SO_KEEPALIVE?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>tcpNoDelay</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If connecting using TCP/IP, should the driver set
|
||
SO_TCP_NODELAY (disabling the Nagle Algorithm)?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>tcpRcvBuf</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If connecting using TCP/IP, should the driver set
|
||
SO_RCV_BUF to the given value? The default value of
|
||
'0', means use the platform default value for this
|
||
property)
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 0
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>tcpSndBuf</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If connecting using TCP/IP, should the driver set
|
||
SO_SND_BUF to the given value? The default value of
|
||
'0', means use the platform default value for this
|
||
property)
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 0
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>tcpTrafficClass</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If connecting using TCP/IP, should the driver set
|
||
traffic class or type-of-service fields ?See the
|
||
documentation for java.net.Socket.setTrafficClass()
|
||
for more information.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 0
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.7
|
||
</p></td></tr></tbody></table></div><p>
|
||
</p><p><b>High Availability and Clustering. </b>
|
||
</p><div class="informaltable"><table class="informaltable" summary="This table lists Connector/J High Availability and
|
||
Clustering connection properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
|
||
<span class="strong"><strong>autoReconnect</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver try to re-establish stale and/or
|
||
dead connections? If enabled the driver will throw an
|
||
exception for a queries issued on a stale or dead
|
||
connection, which belong to the current transaction,
|
||
but will attempt reconnect before the next query
|
||
issued on the connection in a new transaction. The use
|
||
of this feature is not recommended, because it has
|
||
side effects related to session state and data
|
||
consistency when applications don't handle
|
||
SQLExceptions properly, and is only designed to be
|
||
used when you are unable to configure your application
|
||
to handle SQLExceptions resulting from dead and stale
|
||
connections properly. Alternatively, as a last option,
|
||
investigate setting the MySQL server variable
|
||
"wait_timeout" to a high value, rather than the
|
||
default of 8 hours.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 1.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>autoReconnectForPools</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Use a reconnection strategy appropriate for connection
|
||
pools (defaults to 'false')
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>failOverReadOnly</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
When failing over in autoReconnect mode, should the
|
||
connection be set to 'read-only'?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.12
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>maxReconnects</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Maximum number of reconnects to attempt if
|
||
autoReconnect is true, default is '3'.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 3
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 1.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>reconnectAtTxEnd</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If autoReconnect is set to true, should the driver
|
||
attempt reconnections at the end of every transaction?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.10
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>retriesAllDown</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
When using loadbalancing or failover, the number of
|
||
times the driver should cycle through available hosts,
|
||
attempting to connect. Between cycles, the driver will
|
||
pause for 250ms if no servers are available.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 120
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.6
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>initialTimeout</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If autoReconnect is enabled, the initial time to wait
|
||
between re-connect attempts (in seconds, defaults to
|
||
'2').
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 2
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 1.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>roundRobinLoadBalance</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
When autoReconnect is enabled, and failoverReadonly is
|
||
false, should we pick hosts to connect to on a
|
||
round-robin basis?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>queriesBeforeRetryMaster</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Number of queries to issue before falling back to the
|
||
primary host when failed over (when using multi-host
|
||
failover). Whichever condition is met first,
|
||
'queriesBeforeRetryMaster' or
|
||
'secondsBeforeRetryMaster' will cause an attempt to be
|
||
made to reconnect to the primary host. Setting both
|
||
properties to 0 disables the automatic fall back to
|
||
the primary host at transaction boundaries. Defaults
|
||
to 50.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 50
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>secondsBeforeRetryMaster</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
How long should the driver wait, when failed over,
|
||
before attempting to reconnect to the primary host?
|
||
Whichever condition is met first,
|
||
'queriesBeforeRetryMaster' or
|
||
'secondsBeforeRetryMaster' will cause an attempt to be
|
||
made to reconnect to the master. Setting both
|
||
properties to 0 disables the automatic fall back to
|
||
the primary host at transaction boundaries. Time in
|
||
seconds, defaults to 30
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 30
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>allowMasterDownConnections</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
By default, a replication-aware connection will fail
|
||
to connect when configured master hosts are all
|
||
unavailable at initial connection. Setting this
|
||
property to 'true' allows to establish the initial
|
||
connection, by failing over to the slave servers, in
|
||
read-only state. It won't prevent subsequent failures
|
||
when switching back to the master hosts i.e. by
|
||
setting the replication connection to read/write
|
||
state.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.27
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>allowSlaveDownConnections</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
By default, a replication-aware connection will fail
|
||
to connect when configured slave hosts are all
|
||
unavailable at initial connection. Setting this
|
||
property to 'true' allows to establish the initial
|
||
connection. It won't prevent failures when switching
|
||
to slaves i.e. by setting the replication connection
|
||
to read-only state. The property
|
||
'readFromMasterWhenNoSlaves' should be used for this
|
||
purpose.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.38
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>readFromMasterWhenNoSlaves</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Replication-aware connections distribute load by using
|
||
the master hosts when in read/write state and by using
|
||
the slave hosts when in read-only state. If, when
|
||
setting the connection to read-only state, none of the
|
||
slave hosts are available, an SQLExeception is thrown
|
||
back. Setting this property to 'true' allows to fail
|
||
over to the master hosts, while setting the connection
|
||
state to read-only, when no slave hosts are available
|
||
at switch instant.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.38
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>replicationEnableJMX</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Enables JMX-based management of load-balanced
|
||
connection groups, including live addition/removal of
|
||
hosts from load-balancing pool.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.27
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>selfDestructOnPingMaxOperations</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
=If set to a non-zero value, the driver will report
|
||
close the connection and report failure when
|
||
Connection.ping() or Connection.isValid(int) is called
|
||
if the connection's count of commands sent to the
|
||
server exceeds this value.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 0
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.6
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>selfDestructOnPingSecondsLifetime</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If set to a non-zero value, the driver will report
|
||
close the connection and report failure when
|
||
Connection.ping() or Connection.isValid(int) is called
|
||
if the connection's lifetime exceeds this value.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 0
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.6
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>resourceId</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
A globally unique name that identifies the resource
|
||
that this datasource or connection is connected to,
|
||
used for XAResource.isSameRM() when the driver can't
|
||
determine this value based on hostnames used in the
|
||
URL
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.1
|
||
</p></td></tr></tbody></table></div><p>
|
||
</p><p><b>Security. </b>
|
||
</p><div class="informaltable"><table class="informaltable" summary="This table lists Connector/J Security connection
|
||
properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
|
||
<span class="strong"><strong>allowMultiQueries</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Allow the use of ';' to delimit multiple queries
|
||
during one statement (true/false), defaults to
|
||
'false', and does not affect the addBatch() and
|
||
executeBatch() methods, which instead rely on
|
||
rewriteBatchStatements.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useSSL</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Use SSL when communicating with the server
|
||
(true/false), default is 'true' when connecting to
|
||
MySQL 5.5.45+, 5.6.26+ or 5.7.6+, otherwise default is
|
||
'false'
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>requireSSL</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Require server support of SSL connection if
|
||
useSSL=true? (defaults to 'false').
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>verifyServerCertificate</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If "useSSL" is set to "true", should the driver verify
|
||
the server's certificate? When using this feature, the
|
||
keystore parameters should be specified by the
|
||
"clientCertificateKeyStore*" properties, rather than
|
||
system properties. Default is 'false' when connecting
|
||
to MySQL 5.5.45+, 5.6.26+ or 5.7.6+ and "useSSL" was
|
||
not explicitly set to "true". Otherwise default is
|
||
'true'
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.6
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>clientCertificateKeyStoreUrl</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
URL to the client certificate KeyStore (if not
|
||
specified, use defaults)
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>clientCertificateKeyStoreType</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
KeyStore type for client certificates (NULL or empty
|
||
means use the default, which is "JKS". Standard
|
||
keystore types supported by the JVM are "JKS" and
|
||
"PKCS12", your environment may have more available
|
||
depending on what security products are installed and
|
||
available to the JVM.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: JKS
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>clientCertificateKeyStorePassword</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Password for the client certificates KeyStore
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>trustCertificateKeyStoreUrl</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
URL to the trusted root certificate KeyStore (if not
|
||
specified, use defaults)
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>trustCertificateKeyStoreType</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
KeyStore type for trusted root certificates (NULL or
|
||
empty means use the default, which is "JKS". Standard
|
||
keystore types supported by the JVM are "JKS" and
|
||
"PKCS12", your environment may have more available
|
||
depending on what security products are installed and
|
||
available to the JVM.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: JKS
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>trustCertificateKeyStorePassword</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Password for the trusted root certificates KeyStore
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>enabledSSLCipherSuites</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If "useSSL" is set to "true", overrides the cipher
|
||
suites enabled for use on the underlying SSL sockets.
|
||
This may be required when using external JSSE
|
||
providers or to specify cipher suites compatible with
|
||
both MySQL server and used JVM.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.35
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>allowLoadLocalInfile</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver allow use of 'LOAD DATA LOCAL
|
||
INFILE...' (defaults to 'true').
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>allowUrlInLocalInfile</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver allow URLs in 'LOAD DATA LOCAL
|
||
INFILE' statements?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.4
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>allowPublicKeyRetrieval</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Allows special handshake roundtrip to get server RSA
|
||
public key directly from server.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.31
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>paranoid</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Take measures to prevent exposure sensitive
|
||
information in error messages and clear data
|
||
structures holding sensitive data when possible?
|
||
(defaults to 'false')
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>passwordCharacterEncoding</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
What character encoding is used for passwords? Leaving
|
||
this set to the default value (null), uses the value
|
||
set in "characterEncoding" if there is one, otherwise
|
||
uses UTF-8 as default encoding. If the password
|
||
contains non-ASCII characters, the password encoding
|
||
must match what server encoding was set to when the
|
||
password was created. For passwords in other character
|
||
encodings, the encoding will have to be specified with
|
||
this property (or with "characterEncoding"), as it's
|
||
not possible for the driver to auto-detect this.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>serverRSAPublicKeyFile</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
File path to the server RSA public key file for
|
||
sha256_password authentication. If not specified, the
|
||
public key will be retrieved from the server.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.31
|
||
</p></td></tr></tbody></table></div><p>
|
||
</p><p><b>Performance Extensions. </b>
|
||
</p><div class="informaltable"><table class="informaltable" summary="This table lists Connector/J Performance Extensions
|
||
connection properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
|
||
<span class="strong"><strong>callableStmtCacheSize</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If 'cacheCallableStmts' is enabled, how many callable
|
||
statements should be cached?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 100
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>metadataCacheSize</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
The number of queries to cache ResultSetMetadata for
|
||
if cacheResultSetMetaData is set to 'true' (default
|
||
50)
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 50
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useLocalSessionState</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver refer to the internal values of
|
||
autocommit and transaction isolation that are set by
|
||
Connection.setAutoCommit() and
|
||
Connection.setTransactionIsolation() and transaction
|
||
state as maintained by the protocol, rather than
|
||
querying the database or blindly sending commands to
|
||
the database for commit() or rollback() method calls?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useLocalTransactionState</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver use the in-transaction state
|
||
provided by the MySQL protocol to determine if a
|
||
commit() or rollback() should actually be sent to the
|
||
database?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>prepStmtCacheSize</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If prepared statement caching is enabled, how many
|
||
prepared statements should be cached?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 25
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.10
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>prepStmtCacheSqlLimit</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If prepared statement caching is enabled, what's the
|
||
largest SQL the driver will cache the parsing for?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 256
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.10
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>parseInfoCacheFactory</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Name of a class implementing
|
||
com.mysql.jdbc.CacheAdapterFactory, which will be used
|
||
to create caches for the parsed representation of
|
||
client-side prepared statements.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: com.mysql.jdbc.PerConnectionLRUFactory
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>serverConfigCacheFactory</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Name of a class implementing
|
||
com.mysql.jdbc.CacheAdapterFactory<String,
|
||
Map<String, String>>, which will be used to
|
||
create caches for MySQL server configuration values
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: com.mysql.jdbc.PerVmServerConfigCacheFactory
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>alwaysSendSetIsolation</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver always communicate with the database
|
||
when Connection.setTransactionIsolation() is called?
|
||
If set to false, the driver will only communicate with
|
||
the database when the requested transaction isolation
|
||
is different than the whichever is newer, the last
|
||
value that was set via
|
||
Connection.setTransactionIsolation(), or the value
|
||
that was read from the server when the connection was
|
||
established. Note that useLocalSessionState=true will
|
||
force the same behavior as
|
||
alwaysSendSetIsolation=false, regardless of how
|
||
alwaysSendSetIsolation is set.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>maintainTimeStats</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver maintain various internal timers to
|
||
enable idle time calculations as well as more verbose
|
||
error messages when the connection to the server
|
||
fails? Setting this property to false removes at least
|
||
two calls to System.getCurrentTimeMillis() per query.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.9
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useCursorFetch</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If connected to MySQL > 5.0.2, and setFetchSize()
|
||
> 0 on a statement, should that statement use
|
||
cursor-based fetching to retrieve rows?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>blobSendChunkSize</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Chunk size to use when sending BLOB/CLOBs via
|
||
ServerPreparedStatements. Note that this value cannot
|
||
exceed the value of "maxAllowedPacket" and, if that is
|
||
the case, then this value will be corrected
|
||
automatically.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 1048576
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.9
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>cacheCallableStmts</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver cache the parsing stage of
|
||
CallableStatements
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>cachePrepStmts</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver cache the parsing stage of
|
||
PreparedStatements of client-side prepared statements,
|
||
the "check" for suitability of server-side prepared
|
||
and server-side prepared statements themselves?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.10
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>cacheResultSetMetadata</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver cache ResultSetMetaData for
|
||
Statements and PreparedStatements? (Req. JDK-1.4+,
|
||
true/false, default 'false')
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>cacheServerConfiguration</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver cache the results of 'SHOW
|
||
VARIABLES' and 'SHOW COLLATION' on a per-URL basis?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.5
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>defaultFetchSize</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
The driver will call setFetchSize(n) with this value
|
||
on all newly-created Statements
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 0
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.9
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>dontCheckOnDuplicateKeyUpdateInSQL</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Stops checking if every INSERT statement contains the
|
||
"ON DUPLICATE KEY UPDATE" clause. As a side effect,
|
||
obtaining the statement's generated keys information
|
||
will return a list where normally it wouldn't. Also be
|
||
aware that, in this case, the list of generated keys
|
||
returned may not be accurate. The effect of this
|
||
property is canceled if set simultaneously with
|
||
'rewriteBatchedStatements=true'.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.32
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>dontTrackOpenResources</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
The JDBC specification requires the driver to
|
||
automatically track and close resources, however if
|
||
your application doesn't do a good job of explicitly
|
||
calling close() on statements or result sets, this can
|
||
cause memory leakage. Setting this property to true
|
||
relaxes this constraint, and can be more memory
|
||
efficient for some applications. Also the automatic
|
||
closing of the Statement and current ResultSet in
|
||
Statement.closeOnCompletion() and
|
||
Statement.getMoreResults
|
||
([Statement.CLOSE_CURRENT_RESULT |
|
||
Statement.CLOSE_ALL_RESULTS]), respectively, ceases to
|
||
happen. This property automatically sets
|
||
holdResultsOpenOverStatementClose=true.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>dynamicCalendars</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver retrieve the default calendar when
|
||
required, or cache it per connection/session?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.5
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>elideSetAutoCommits</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If using MySQL-4.1 or newer, should the driver only
|
||
issue 'set autocommit=n' queries when the server's
|
||
state doesn't match the requested state by
|
||
Connection.setAutoCommit(boolean)?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>enableEscapeProcessing</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Sets the default escape processing behavior for
|
||
Statement objects. The method
|
||
Statement.setEscapeProcessing() can be used to specify
|
||
the escape processing behavior for an individual
|
||
Statement object. Default escape processing behavior
|
||
in prepared statements must be defined with the
|
||
property 'processEscapeCodesForPrepStmts'.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.37
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>enableQueryTimeouts</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
When enabled, query timeouts set via
|
||
Statement.setQueryTimeout() use a shared
|
||
java.util.Timer instance for scheduling. Even if the
|
||
timeout doesn't expire before the query is processed,
|
||
there will be memory used by the TimerTask for the
|
||
given timeout which won't be reclaimed until the time
|
||
the timeout would have expired if it hadn't been
|
||
cancelled by the driver. High-load environments might
|
||
want to consider disabling this functionality.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.6
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>holdResultsOpenOverStatementClose</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver close result sets on
|
||
Statement.close() as required by the JDBC
|
||
specification?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>largeRowSizeThreshold</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
What size result set row should the JDBC driver
|
||
consider "large", and thus use a more memory-efficient
|
||
way of representing the row internally?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 2048
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>loadBalanceStrategy</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If using a load-balanced connection to connect to SQL
|
||
nodes in a MySQL Cluster/NDB configuration (by using
|
||
the URL prefix "jdbc:mysql:loadbalance://"), which
|
||
load balancing algorithm should the driver use: (1)
|
||
"random" - the driver will pick a random host for each
|
||
request. This tends to work better than round-robin,
|
||
as the randomness will somewhat account for spreading
|
||
loads where requests vary in response time, while
|
||
round-robin can sometimes lead to overloaded nodes if
|
||
there are variations in response times across the
|
||
workload. (2) "bestResponseTime" - the driver will
|
||
route the request to the host that had the best
|
||
response time for the previous transaction.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: random
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.6
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>locatorFetchBufferSize</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If 'emulateLocators' is configured to 'true', what
|
||
size buffer should be used when fetching BLOB data for
|
||
getBinaryInputStream?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 1048576
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.2.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>readOnlyPropagatesToServer</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver issue appropriate statements to
|
||
implicitly set the transaction access mode on server
|
||
side when Connection.setReadOnly() is called? Setting
|
||
this property to 'true' enables InnoDB read-only
|
||
potential optimizations but also requires an extra
|
||
roundtrip to set the right transaction state. Even if
|
||
this property is set to 'false', the driver will do
|
||
its best effort to prevent the execution of
|
||
database-state-changing queries. Requires minimum of
|
||
MySQL 5.6.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.35
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>rewriteBatchedStatements</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver use multiqueries (irregardless of
|
||
the setting of "allowMultiQueries") as well as
|
||
rewriting of prepared statements for INSERT into
|
||
multi-value inserts when executeBatch() is called?
|
||
Notice that this has the potential for SQL injection
|
||
if using plain java.sql.Statements and your code
|
||
doesn't sanitize input correctly. Notice that for
|
||
prepared statements, server-side prepared statements
|
||
can not currently take advantage of this rewrite
|
||
option, and that if you don't specify stream lengths
|
||
when using PreparedStatement.set*Stream(), the driver
|
||
won't be able to determine the optimum number of
|
||
parameters per batch and you might receive an error
|
||
from the driver that the resultant packet is too
|
||
large. Statement.getGeneratedKeys() for these
|
||
rewritten statements only works when the entire batch
|
||
includes INSERT statements. Please be aware using
|
||
rewriteBatchedStatements=true with INSERT .. ON
|
||
DUPLICATE KEY UPDATE that for rewritten statement
|
||
server returns only one value as sum of all affected
|
||
(or found) rows in batch and it isn't possible to map
|
||
it correctly to initial statements; in this case
|
||
driver returns 0 as a result of each batch statement
|
||
if total count was 0, and the
|
||
Statement.SUCCESS_NO_INFO as a result of each batch
|
||
statement if total count was > 0.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.13
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useDirectRowUnpack</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Use newer result set row unpacking code that skips a
|
||
copy from network buffers to a MySQL packet instance
|
||
and instead reads directly into the result set row
|
||
data buffers.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useDynamicCharsetInfo</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver use a per-connection cache of
|
||
character set information queried from the server when
|
||
necessary, or use a built-in static mapping that is
|
||
more efficient, but isn't aware of custom character
|
||
sets or character sets implemented after the release
|
||
of the JDBC driver?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.6
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useFastDateParsing</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Use internal String->Date/Time/Timestamp conversion
|
||
routines to avoid excessive object creation? This is
|
||
part of the legacy date-time code, thus the property
|
||
has an effect only when "useLegacyDatetimeCode=true."
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.5
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useFastIntParsing</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Use internal String->Integer conversion routines to
|
||
avoid excessive object creation?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.4
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useJvmCharsetConverters</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Always use the character encoding routines built into
|
||
the JVM, rather than using lookup tables for
|
||
single-byte character sets?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useReadAheadInput</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Use newer, optimized non-blocking, buffered input
|
||
stream when reading from the server?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.5
|
||
</p></td></tr></tbody></table></div><p>
|
||
</p><p><b>Debugging/Profiling. </b>
|
||
</p><div class="informaltable"><table class="informaltable" summary="This table lists Connector/J Debugging/Profiling
|
||
connection properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
|
||
<span class="strong"><strong>logger</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
The name of a class that implements
|
||
"com.mysql.jdbc.log.Log" that will be used to log
|
||
messages to. (default is
|
||
"com.mysql.jdbc.log.StandardLogger", which logs to
|
||
STDERR)
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: com.mysql.jdbc.log.StandardLogger
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>gatherPerfMetrics</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver gather performance metrics, and
|
||
report them via the configured logger every
|
||
'reportMetricsIntervalMillis' milliseconds?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>profileSQL</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Trace queries and their execution/fetch times to the
|
||
configured logger (true/false) defaults to 'false'
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>profileSql</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Deprecated, use 'profileSQL' instead. Trace queries
|
||
and their execution/fetch times on STDERR (true/false)
|
||
defaults to 'false'
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 2.0.14
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>reportMetricsIntervalMillis</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If 'gatherPerfMetrics' is enabled, how often should
|
||
they be logged (in ms)?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 30000
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>maxQuerySizeToLog</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Controls the maximum length/size of a query that will
|
||
get logged when profiling or tracing
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 2048
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>packetDebugBufferSize</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
The maximum number of packets to retain when
|
||
'enablePacketDebug' is true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 20
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>slowQueryThresholdMillis</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If 'logSlowQueries' is enabled, how long should a
|
||
query (in ms) before it is logged as 'slow'?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 2000
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>slowQueryThresholdNanos</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If 'useNanosForElapsedTime' is set to true, and this
|
||
property is set to a non-zero value, the driver will
|
||
use this threshold (in nanosecond units) to determine
|
||
if a query was slow.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 0
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useUsageAdvisor</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver issue 'usage' warnings advising
|
||
proper and efficient usage of JDBC and MySQL
|
||
Connector/J to the log (true/false, defaults to
|
||
'false')?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>autoGenerateTestcaseScript</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver dump the SQL it is executing,
|
||
including server-side prepared statements to STDERR?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.9
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>autoSlowLog</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Instead of using slowQueryThreshold* to determine if a
|
||
query is slow enough to be logged, maintain statistics
|
||
that allow the driver to determine queries that are
|
||
outside the 99th percentile?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.4
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>clientInfoProvider</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
The name of a class that implements the
|
||
com.mysql.jdbc.JDBC4ClientInfoProvider interface in
|
||
order to support JDBC-4.0's
|
||
Connection.get/setClientInfo() methods
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: com.mysql.jdbc.JDBC4CommentClientInfoProvider
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>dumpMetadataOnColumnNotFound</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver dump the field-level metadata of a
|
||
result set into the exception message when
|
||
ResultSet.findColumn() fails?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.13
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>dumpQueriesOnException</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver dump the contents of the query sent
|
||
to the server in the message for SQLExceptions?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>enablePacketDebug</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
When enabled, a ring-buffer of 'packetDebugBufferSize'
|
||
packets will be kept, and dumped when exceptions are
|
||
thrown in key areas in the driver's code
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>explainSlowQueries</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If 'logSlowQueries' is enabled, should the driver
|
||
automatically issue an 'EXPLAIN' on the server and
|
||
send the results to the configured log at a WARN
|
||
level?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>includeInnodbStatusInDeadlockExceptions</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Include the output of "SHOW ENGINE INNODB STATUS" in
|
||
exception messages when deadlock exceptions are
|
||
detected?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>includeThreadDumpInDeadlockExceptions</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Include a current Java thread dump in exception
|
||
messages when deadlock exceptions are detected?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.15
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>includeThreadNamesAsStatementComment</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Include the name of the current thread as a comment
|
||
visible in "SHOW PROCESSLIST", or in Innodb deadlock
|
||
dumps, useful in correlation with
|
||
"includeInnodbStatusInDeadlockExceptions=true" and
|
||
"includeThreadDumpInDeadlockExceptions=true".
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.15
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>logSlowQueries</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should queries that take longer than
|
||
'slowQueryThresholdMillis' be logged?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>logXaCommands</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver log XA commands sent by
|
||
MysqlXaConnection to the server, at the DEBUG level of
|
||
logging?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.5
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>profilerEventHandler</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Name of a class that implements the interface
|
||
com.mysql.jdbc.profiler.ProfilerEventHandler that will
|
||
be used to handle profiling/tracing events.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default:
|
||
com.mysql.jdbc.profiler.LoggingProfilerEventHandler
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.6
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>resultSetSizeThreshold</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If the usage advisor is enabled, how many rows should
|
||
a result set contain before the driver warns that it
|
||
is suspiciously large?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 100
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.5
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>traceProtocol</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should trace-level network protocol be logged?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useNanosForElapsedTime</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
For profiling/debugging functionality that measures
|
||
elapsed time, should the driver try to use nanoseconds
|
||
resolution if available (JDK >= 1.5)?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.7
|
||
</p></td></tr></tbody></table></div><p>
|
||
</p><p><b>Miscellaneous. </b>
|
||
</p><div class="informaltable"><table class="informaltable" summary="This table lists Connector/J Miscellaneous connection
|
||
properties." border="1"><colgroup><col class="Properties"></colgroup><thead><tr><th scope="col"><span class="bold"><strong>Properties and Descriptions</strong></span></th></tr></thead><tbody><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useUnicode</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver use Unicode character encodings when
|
||
handling strings? Should only be used when the driver
|
||
can't determine the character set mapping, or you are
|
||
trying to 'force' the driver to use a character set
|
||
that MySQL either doesn't natively support (such as
|
||
UTF-8), true/false, defaults to 'true'
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 1.1g
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>characterEncoding</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If 'useUnicode' is set to true, what character
|
||
encoding should the driver use when dealing with
|
||
strings? (defaults is to 'autodetect')
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 1.1g
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>characterSetResults</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Character set to tell the server to return results as.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.13
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>connectionAttributes</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
A comma-delimited list of user-defined key:value pairs
|
||
(in addition to standard MySQL-defined key:value
|
||
pairs) to be passed to MySQL Server for display as
|
||
connection attributes in the
|
||
PERFORMANCE_SCHEMA.SESSION_CONNECT_ATTRS table.
|
||
Example usage:
|
||
connectionAttributes=key1:value1,key2:value2 This
|
||
functionality is available for use with MySQL Server
|
||
version 5.6 or later only. Earlier versions of MySQL
|
||
Server do not support connection attributes, causing
|
||
this configuration option to be ignored. Setting
|
||
connectionAttributes=none will cause connection
|
||
attribute processing to be bypassed, for situations
|
||
where Connection creation/initialization speed is
|
||
critical.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.25
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>connectionCollation</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If set, tells the server to use this collation via
|
||
'set collation_connection'
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.13
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useBlobToStoreUTF8OutsideBMP</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Tells the driver to treat [MEDIUM/LONG]BLOB columns as
|
||
[LONG]VARCHAR columns holding text encoded in UTF-8
|
||
that has characters outside the BMP (4-byte
|
||
encodings), which MySQL server can't handle natively.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>utf8OutsideBmpExcludedColumnNamePattern</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
When "useBlobToStoreUTF8OutsideBMP" is set to "true",
|
||
column names matching the given regex will still be
|
||
treated as BLOBs unless they match the regex specified
|
||
for "utf8OutsideBmpIncludedColumnNamePattern". The
|
||
regex must follow the patterns used for the
|
||
java.util.regex package.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>utf8OutsideBmpIncludedColumnNamePattern</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Used to specify exclusion rules to
|
||
"utf8OutsideBmpExcludedColumnNamePattern". The regex
|
||
must follow the patterns used for the java.util.regex
|
||
package.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>loadBalanceEnableJMX</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Enables JMX-based management of load-balanced
|
||
connection groups, including live addition/removal of
|
||
hosts from load-balancing pool.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.13
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>sessionVariables</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
A comma-separated list of name/value pairs to be sent
|
||
as SET SESSION ... to the server when the driver
|
||
connects.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.8
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useColumnNamesInFindColumn</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Prior to JDBC-4.0, the JDBC specification had a bug
|
||
related to what could be given as a "column name" to
|
||
ResultSet methods like findColumn(), or getters that
|
||
took a String property. JDBC-4.0 clarified "column
|
||
name" to mean the label, as given in an "AS" clause
|
||
and returned by ResultSetMetaData.getColumnLabel(),
|
||
and if no AS clause, the column name. Setting this
|
||
property to "true" will give behavior that is
|
||
congruent to JDBC-3.0 and earlier versions of the JDBC
|
||
specification, but which because of the specification
|
||
bug could give unexpected results. This property is
|
||
preferred over "useOldAliasMetadataBehavior" unless
|
||
you need the specific behavior that it provides with
|
||
respect to ResultSetMetadata.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>allowNanAndInf</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver allow NaN or +/- INF values in
|
||
PreparedStatement.setDouble()?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.5
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>autoClosePStmtStreams</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver automatically call .close() on
|
||
streams/readers passed as arguments via set*()
|
||
methods?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.12
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>autoDeserialize</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver automatically detect and
|
||
de-serialize objects stored in BLOB fields?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.5
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>blobsAreStrings</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver always treat BLOBs as Strings -
|
||
specifically to work around dubious metadata returned
|
||
by the server for GROUP BY clauses?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.8
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>cacheDefaultTimezone</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Caches client's default time zone. This results in
|
||
better performance when dealing with time zone
|
||
conversions in Date and Time data types, however it
|
||
won't be aware of time zone changes if they happen at
|
||
runtime.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.35
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>capitalizeTypeNames</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Capitalize type names in DatabaseMetaData? (usually
|
||
only useful when using WebObjects, true/false,
|
||
defaults to 'false')
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 2.0.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>clobCharacterEncoding</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
The character encoding to use for sending and
|
||
retrieving TEXT, MEDIUMTEXT and LONGTEXT values
|
||
instead of the configured connection characterEncoding
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>clobberStreamingResults</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
This will cause a 'streaming' ResultSet to be
|
||
automatically closed, and any outstanding data still
|
||
streaming from the server to be discarded if another
|
||
query is executed before all the data has been read
|
||
from the server.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.9
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>compensateOnDuplicateKeyUpdateCounts</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver compensate for the update counts of
|
||
"ON DUPLICATE KEY" INSERT statements (2 = 1, 0 = 1)
|
||
when using prepared statements?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>continueBatchOnError</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver continue processing batch commands
|
||
if one statement fails. The JDBC spec allows either
|
||
way (defaults to 'true').
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>createDatabaseIfNotExist</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Creates the database given in the URL if it doesn't
|
||
yet exist. Assumes the configured user has permissions
|
||
to create databases.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.9
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>detectCustomCollations</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver detect custom charsets/collations
|
||
installed on server (true/false, defaults to 'false').
|
||
If this option set to 'true' driver gets actual
|
||
charsets/collations from server each time connection
|
||
establishes. This could slow down connection
|
||
initialization significantly.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.29
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>emptyStringsConvertToZero</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver allow conversions from empty string
|
||
fields to numeric values of '0'?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.8
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>emulateLocators</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver emulate java.sql.Blobs with
|
||
locators? With this feature enabled, the driver will
|
||
delay loading the actual Blob data until the one of
|
||
the retrieval methods (getInputStream(), getBytes(),
|
||
and so forth) on the blob data stream has been
|
||
accessed. For this to work, you must use a column
|
||
alias with the value of the column to the actual name
|
||
of the Blob. The feature also has the following
|
||
restrictions: The SELECT that created the result set
|
||
must reference only one table, the table must have a
|
||
primary key; the SELECT must alias the original blob
|
||
column name, specified as a string, to an alternate
|
||
name; the SELECT must cover all columns that make up
|
||
the primary key.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>emulateUnsupportedPstmts</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver detect prepared statements that are
|
||
not supported by the server, and replace them with
|
||
client-side emulated versions?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>exceptionInterceptors</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Comma-delimited list of classes that implement
|
||
com.mysql.jdbc.ExceptionInterceptor. These classes
|
||
will be instantiated one per Connection instance, and
|
||
all SQLExceptions thrown by the driver will be allowed
|
||
to be intercepted by these interceptors, in a chained
|
||
fashion, with the first class listed as the head of
|
||
the chain.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.8
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>functionsNeverReturnBlobs</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver always treat data from functions
|
||
returning BLOBs as Strings - specifically to work
|
||
around dubious metadata returned by the server for
|
||
GROUP BY clauses?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.8
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>generateSimpleParameterMetadata</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver generate simplified parameter
|
||
metadata for PreparedStatements when no metadata is
|
||
available either because the server couldn't support
|
||
preparing the statement, or server-side prepared
|
||
statements are disabled?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.5
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>getProceduresReturnsFunctions</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Pre-JDBC4 DatabaseMetaData API has only the
|
||
getProcedures() and getProcedureColumns() methods, so
|
||
they return metadata info for both stored procedures
|
||
and functions. JDBC4 was extended with the
|
||
getFunctions() and getFunctionColumns() methods and
|
||
the expected behaviours of previous methods are not
|
||
well defined. For JDBC4 and higher, default 'true'
|
||
value of the option means that calls of
|
||
DatabaseMetaData.getProcedures() and
|
||
DatabaseMetaData.getProcedureColumns() return metadata
|
||
for both procedures and functions as before, keeping
|
||
backward compatibility. Setting this property to
|
||
'false' decouples Connector/J from its pre-JDBC4
|
||
behaviours for DatabaseMetaData.getProcedures() and
|
||
DatabaseMetaData.getProcedureColumns(), forcing them
|
||
to return metadata for procedures only.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.26
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>ignoreNonTxTables</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Ignore non-transactional table warning for rollback?
|
||
(defaults to 'false').
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.9
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>jdbcCompliantTruncation</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver throw java.sql.DataTruncation
|
||
exceptions when data is truncated as is required by
|
||
the JDBC specification when connected to a server that
|
||
supports warnings (MySQL 4.1.0 and newer)? This
|
||
property has no effect if the server sql-mode includes
|
||
STRICT_TRANS_TABLES.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>loadBalanceAutoCommitStatementRegex</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
When load-balancing is enabled for auto-commit
|
||
statements (via
|
||
loadBalanceAutoCommitStatementThreshold), the
|
||
statement counter will only increment when the SQL
|
||
matches the regular expression. By default, every
|
||
statement issued matches.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.15
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>loadBalanceAutoCommitStatementThreshold</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
When auto-commit is enabled, the number of statements
|
||
which should be executed before triggering
|
||
load-balancing to rebalance. Default value of 0 causes
|
||
load-balanced connections to only rebalance when
|
||
exceptions are encountered, or auto-commit is disabled
|
||
and transactions are explicitly committed or rolled
|
||
back.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 0
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.15
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>loadBalanceBlacklistTimeout</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Time in milliseconds between checks of servers which
|
||
are unavailable, by controlling how long a server
|
||
lives in the global blacklist.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 0
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>loadBalanceConnectionGroup</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Logical group of load-balanced connections within a
|
||
classloader, used to manage different groups
|
||
independently. If not specified, live management of
|
||
load-balanced connections is disabled.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.13
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>loadBalanceExceptionChecker</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Fully-qualified class name of custom exception
|
||
checker. The class must implement
|
||
com.mysql.jdbc.LoadBalanceExceptionChecker interface,
|
||
and is used to inspect SQLExceptions and determine
|
||
whether they should trigger fail-over to another host
|
||
in a load-balanced deployment.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default:
|
||
com.mysql.jdbc.StandardLoadBalanceExceptionChecker
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.13
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>loadBalancePingTimeout</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Time in milliseconds to wait for ping response from
|
||
each of load-balanced physical connections when using
|
||
load-balanced Connection.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 0
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.13
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>loadBalanceSQLExceptionSubclassFailover</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Comma-delimited list of classes/interfaces used by
|
||
default load-balanced exception checker to determine
|
||
whether a given SQLException should trigger failover.
|
||
The comparison is done using
|
||
Class.isInstance(SQLException) using the thrown
|
||
SQLException.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.13
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>loadBalanceSQLStateFailover</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Comma-delimited list of SQLState codes used by default
|
||
load-balanced exception checker to determine whether a
|
||
given SQLException should trigger failover. The
|
||
SQLState of a given SQLException is evaluated to
|
||
determine whether it begins with any value in the
|
||
comma-delimited list.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.13
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>loadBalanceValidateConnectionOnSwapServer</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the load-balanced Connection explicitly check
|
||
whether the connection is live when swapping to a new
|
||
physical connection at commit/rollback?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.13
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>maxRows</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
The maximum number of rows to return (0, the default
|
||
means return all rows).
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: -1
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: all versions
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>netTimeoutForStreamingResults</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
What value should the driver automatically set the
|
||
server setting 'net_write_timeout' to when the
|
||
streaming result sets feature is in use? (value has
|
||
unit of seconds, the value '0' means the driver will
|
||
not try and adjust this value)
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: 600
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>noAccessToProcedureBodies</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
When determining procedure parameter types for
|
||
CallableStatements, and the connected user can't
|
||
access procedure bodies through "SHOW CREATE
|
||
PROCEDURE" or select on mysql.proc should the driver
|
||
instead create basic metadata (all parameters reported
|
||
as IN VARCHARs, but allowing registerOutParameter() to
|
||
be called on them anyway) instead of throwing an
|
||
exception?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>noDatetimeStringSync</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Don't ensure that
|
||
ResultSet.getDatetimeType().toString().equals(ResultSet.getString())
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>noTimezoneConversionForDateType</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Don't convert DATE values using the server time zone
|
||
if 'useTimezone'='true' or
|
||
'useLegacyDatetimeCode'='false'
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.35
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>noTimezoneConversionForTimeType</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Don't convert TIME values using the server time zone
|
||
if 'useTimezone'='true'
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>nullCatalogMeansCurrent</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
When DatabaseMetadataMethods ask for a 'catalog'
|
||
parameter, does the value null mean use the current
|
||
catalog? (this is not JDBC-compliant, but follows
|
||
legacy behavior from earlier versions of the driver)
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.8
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>nullNamePatternMatchesAll</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should DatabaseMetaData methods that accept *pattern
|
||
parameters treat null the same as '%' (this is not
|
||
JDBC-compliant, however older versions of the driver
|
||
accepted this departure from the specification)
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.8
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>overrideSupportsIntegrityEnhancementFacility</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver return "true" for
|
||
DatabaseMetaData.supportsIntegrityEnhancementFacility()
|
||
even if the database doesn't support it to workaround
|
||
applications that require this method to return "true"
|
||
to signal support of foreign keys, even though the SQL
|
||
specification states that this facility contains much
|
||
more than just foreign key support (one such
|
||
application being OpenOffice)?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.12
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>padCharsWithSpace</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If a result set column has the CHAR type and the value
|
||
does not fill the amount of characters specified in
|
||
the DDL for the column, should the driver pad the
|
||
remaining characters with space (for ANSI compliance)?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.6
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>pedantic</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Follow the JDBC spec to the letter.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>pinGlobalTxToPhysicalConnection</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
When using XAConnections, should the driver ensure
|
||
that operations on a given XID are always routed to
|
||
the same physical connection? This allows the
|
||
XAConnection to support "XA START ... JOIN" after "XA
|
||
END" has been called
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>populateInsertRowWithDefaultValues</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
When using ResultSets that are CONCUR_UPDATABLE,
|
||
should the driver pre-populate the "insert" row with
|
||
default values from the DDL for the table used in the
|
||
query so those values are immediately available for
|
||
ResultSet accessors? This functionality requires a
|
||
call to the database for metadata each time a result
|
||
set of this type is created. If disabled (the
|
||
default), the default values will be populated by the
|
||
an internal call to refreshRow() which pulls back
|
||
default values and/or values changed by triggers.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.5
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>processEscapeCodesForPrepStmts</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver process escape codes in queries that
|
||
are prepared? Default escape processing behavior in
|
||
non-prepared statements must be defined with the
|
||
property 'enableEscapeProcessing'.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.12
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>queryTimeoutKillsConnection</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If the timeout given in Statement.setQueryTimeout()
|
||
expires, should the driver forcibly abort the
|
||
Connection instead of attempting to abort the query?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.9
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>relaxAutoCommit</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If the version of MySQL the driver connects to does
|
||
not support transactions, still allow calls to
|
||
commit(), rollback() and setAutoCommit() (true/false,
|
||
defaults to 'false')?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 2.0.13
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>retainStatementAfterResultSetClose</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver retain the Statement reference in a
|
||
ResultSet after ResultSet.close() has been called.
|
||
This is not JDBC-compliant after JDBC-4.0.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.11
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>rollbackOnPooledClose</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver issue a rollback() when the logical
|
||
connection in a pool is closed?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.15
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>runningCTS13</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Enables workarounds for bugs in Sun's JDBC compliance
|
||
testsuite version 1.3
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>sendFractionalSeconds</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Send fractional part from TIMESTAMP seconds. If set to
|
||
false, the nanoseconds value of TIMESTAMP values will
|
||
be truncated before sending any data to the server.
|
||
This option applies only to prepared statements,
|
||
callable statements or updatable result sets.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.37
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>serverTimezone</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Override detection/mapping of time zone. Used when
|
||
time zone from server doesn't map to Java time zone
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>statementInterceptors</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
A comma-delimited list of classes that implement
|
||
"com.mysql.jdbc.StatementInterceptor" that should be
|
||
placed "in between" query execution to influence the
|
||
results. StatementInterceptors are "chainable", the
|
||
results returned by the "current" interceptor will be
|
||
passed on to the next in in the chain, from
|
||
left-to-right order, as specified in this property.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.1
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>strictFloatingPoint</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Used only in older versions of compliance test
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>strictUpdates</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver do strict checking (all primary keys
|
||
selected) of updatable result sets (true, false,
|
||
defaults to 'true')?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.4
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>tinyInt1isBit</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver treat the datatype TINYINT(1) as the
|
||
BIT type (because the server silently converts BIT
|
||
-> TINYINT(1) when creating tables)?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.16
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>transformedBitIsBoolean</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If the driver converts TINYINT(1) to a different type,
|
||
should it use BOOLEAN instead of BIT for future
|
||
compatibility with MySQL-5.0, as MySQL-5.0 has a BIT
|
||
type?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.9
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>treatUtilDateAsTimestamp</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver treat java.util.Date as a TIMESTAMP
|
||
for the purposes of PreparedStatement.setObject()?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.5
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>ultraDevHack</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Create PreparedStatements for prepareCall() when
|
||
required, because UltraDev is broken and issues a
|
||
prepareCall() for _all_ statements? (true/false,
|
||
defaults to 'false')
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 2.0.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useAffectedRows</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Don't set the CLIENT_FOUND_ROWS flag when connecting
|
||
to the server (not JDBC-compliant, will break most
|
||
applications that rely on "found" rows vs. "affected
|
||
rows" for DML statements), but does cause "correct"
|
||
update counts from "INSERT ... ON DUPLICATE KEY
|
||
UPDATE" statements to be returned by the server.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.7
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useGmtMillisForDatetimes</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Convert between session time zone and GMT before
|
||
creating Date and Timestamp instances (value of
|
||
'false' leads to legacy behavior, 'true' leads to more
|
||
JDBC-compliant behavior)? This is part of the legacy
|
||
date-time code, thus the property has an effect only
|
||
when "useLegacyDatetimeCode=true."
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.12
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useHostsInPrivileges</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Add '@hostname' to users in
|
||
DatabaseMetaData.getColumn/TablePrivileges()
|
||
(true/false), defaults to 'true'.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useInformationSchema</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
When connected to MySQL-5.0.7 or newer, should the
|
||
driver use the INFORMATION_SCHEMA to derive
|
||
information used by DatabaseMetaData?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useJDBCCompliantTimezoneShift</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver use JDBC-compliant rules when
|
||
converting TIME/TIMESTAMP/DATETIME values' time zone
|
||
information for those JDBC arguments which take a
|
||
java.util.Calendar argument? This is part of the
|
||
legacy date-time code, thus the property has an effect
|
||
only when "useLegacyDatetimeCode=true."
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useLegacyDatetimeCode</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Use code for DATE/TIME/DATETIME/TIMESTAMP handling in
|
||
result sets and statements that consistently handles
|
||
time zone conversions from client to server and back
|
||
again, or use the legacy code for these datatypes that
|
||
has been in the driver for backwards-compatibility?
|
||
Setting this property to 'false' voids the effects of
|
||
"useTimezone," "useJDBCCompliantTimezoneShift,"
|
||
"useGmtMillisForDatetimes," and "useFastDateParsing."
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.1.6
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useOldAliasMetadataBehavior</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the driver use the legacy behavior for "AS"
|
||
clauses on columns and tables, and only return aliases
|
||
(if any) for ResultSetMetaData.getColumnName() or
|
||
ResultSetMetaData.getTableName() rather than the
|
||
original column/table name? In 5.0.x, the default
|
||
value was true.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.4
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useOldUTF8Behavior</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Use the UTF-8 behavior the driver did when
|
||
communicating with 4.0 and older servers
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.6
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useOnlyServerErrorMessages</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Don't prepend 'standard' SQLState error messages to
|
||
error messages returned by the server.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.15
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useSSPSCompatibleTimezoneShift</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
If migrating from an environment that was using
|
||
server-side prepared statements, and the configuration
|
||
property "useJDBCCompliantTimeZoneShift" set to
|
||
"true", use compatible behavior when not using
|
||
server-side prepared statements when sending TIMESTAMP
|
||
values to the MySQL server.
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 5.0.5
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useServerPrepStmts</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Use server-side prepared statements if the server
|
||
supports them?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.0
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useSqlStateCodes</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Use SQL Standard state codes instead of 'legacy'
|
||
X/Open/SQL state codes (true/false), default is 'true'
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.3
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useStreamLengthsInPrepStmts</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Honor stream length parameter in
|
||
PreparedStatement/ResultSet.setXXXStream() method
|
||
calls (true/false, defaults to 'true')?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useTimezone</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Convert time/date types between client and server time
|
||
zones (true/false, defaults to 'false')? This is part
|
||
of the legacy date-time code, thus the property has an
|
||
effect only when "useLegacyDatetimeCode=true."
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: false
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.2
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>useUnbufferedInput</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Don't use BufferedInputStream for reading data from
|
||
the server
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.0.11
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>yearIsDateType</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Should the JDBC driver treat the MySQL type "YEAR" as
|
||
a java.sql.Date, or as a SHORT?
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: true
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.9
|
||
</p></td></tr><tr><td scope="row"><p>
|
||
<span class="strong"><strong>zeroDateTimeBehavior</strong></span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
What should happen when the driver encounters DATETIME
|
||
values that are composed entirely of zeros (used by
|
||
MySQL to represent invalid dates)? Valid values are
|
||
"exception", "round" and "convertToNull".
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Default: exception
|
||
</p>
|
||
|
||
|
||
|
||
<p>
|
||
Since version: 3.1.4
|
||
</p></td></tr></tbody></table></div><p>
|
||
</p><p>
|
||
Connector/J also supports access to MySQL using named pipes on
|
||
Windows platforms with the
|
||
<code class="literal">NamedPipeSocketFactory</code> as a plugin-socket
|
||
factory. If you do not use a <code class="literal">namedPipePath</code>
|
||
property, the default of <code class="literal">'\\.\pipe\MySQL'</code> is
|
||
used. If you use the <code class="literal">NamedPipeSocketFactory</code>,
|
||
the host name and port number values in the JDBC URL are
|
||
ignored. To enable this feature, set the
|
||
<code class="literal">socketFactory</code> property:
|
||
|
||
</p><pre class="programlisting">
|
||
socketFactory=com.mysql.jdbc.NamedPipeSocketFactory
|
||
</pre><p>
|
||
</p><p>
|
||
Named pipes only work when connecting to a MySQL server on the
|
||
same physical machine where the JDBC driver is running. In
|
||
simple performance tests, named pipe access is between 30%-50%
|
||
faster than the standard TCP/IP access. However, this varies per
|
||
system, and named pipes are slower than TCP/IP in many Windows
|
||
configurations.
|
||
</p><p>
|
||
To create your own socket factories, follow the example code in
|
||
<code class="classname">com.mysql.jdbc.NamedPipeSocketFactory</code>, or
|
||
<code class="classname">com.mysql.jdbc.StandardSocketFactory</code>.
|
||
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-j-useconfigs"></a>5.1.1 Properties Files for the <code class="literal">useConfigs</code> Option</h3></div></div></div><a class="indexterm" name="idm140266686905232"></a><p>
|
||
The <code class="literal">useConfigs</code> connection option is
|
||
convenient shorthand for specifying combinations of options
|
||
for particular scenarios. The argument values you can use with
|
||
this option correspond to the names of
|
||
<code class="filename">.properties</code> files within the Connector/J
|
||
<code class="filename">mysql-connector-java-<em class="replaceable"><code>version</code></em>-bin.jar</code>
|
||
JAR file. For example, the Connector/J 5.1.9 driver includes
|
||
the following configuration properties files:
|
||
</p><pre class="programlisting">
|
||
$ unzip mysql-connector-java-5.1.19-bin.jar '*/configs/*'
|
||
Archive: mysql-connector-java-5.1.19-bin.jar
|
||
creating: com/mysql/jdbc/configs/
|
||
inflating: com/mysql/jdbc/configs/3-0-Compat.properties
|
||
inflating: com/mysql/jdbc/configs/5-0-Compat.properties
|
||
inflating: com/mysql/jdbc/configs/clusterBase.properties
|
||
inflating: com/mysql/jdbc/configs/coldFusion.properties
|
||
inflating: com/mysql/jdbc/configs/fullDebug.properties
|
||
inflating: com/mysql/jdbc/configs/maxPerformance.properties
|
||
inflating: com/mysql/jdbc/configs/solarisMaxPerformance.properties
|
||
</pre><p>
|
||
To specify one of these combinations of options, specify
|
||
<code class="literal">useConfigs=3-0-Compat</code>,
|
||
<code class="literal">useConfigs=maxPerformance</code>, and so on. The
|
||
following sections show the options that are part of each
|
||
<code class="literal">useConfigs</code> setting. For the details of why
|
||
each one is included, see the comments in the
|
||
<code class="filename">.properties</code> files.
|
||
</p><h4><a name="idm140266686896192"></a>3-0-Compat</h4><pre class="programlisting">
|
||
emptyStringsConvertToZero=true
|
||
jdbcCompliantTruncation=false
|
||
noDatetimeStringSync=true
|
||
nullCatalogMeansCurrent=true
|
||
nullNamePatternMatchesAll=true
|
||
transformedBitIsBoolean=false
|
||
dontTrackOpenResources=true
|
||
zeroDateTimeBehavior=convertToNull
|
||
useServerPrepStmts=false
|
||
autoClosePStmtStreams=true
|
||
processEscapeCodesForPrepStmts=false
|
||
useFastDateParsing=false
|
||
populateInsertRowWithDefaultValues=false
|
||
useDirectRowUnpack=false
|
||
</pre><h4><a name="idm140266686894512"></a>5-0-Compat</h4><pre class="programlisting">
|
||
useDirectRowUnpack=false
|
||
</pre><h4><a name="idm140266686893264"></a>clusterBase</h4><pre class="programlisting">
|
||
autoReconnect=true
|
||
failOverReadOnly=false
|
||
roundRobinLoadBalance=true
|
||
</pre><h4><a name="idm140266686891936"></a>coldFusion</h4><pre class="programlisting">
|
||
useDynamicCharsetInfo=false
|
||
alwaysSendSetIsolation=false
|
||
useLocalSessionState=true
|
||
autoReconnect=true
|
||
</pre><h4><a name="idm140266686890576"></a>fullDebug</h4><pre class="programlisting">
|
||
profileSQL=true
|
||
gatherPerfMetrics=true
|
||
useUsageAdvisor=true
|
||
logSlowQueries=true
|
||
explainSlowQueries=true
|
||
</pre><h4><a name="idm140266686889200"></a>maxPerformance</h4><pre class="programlisting">
|
||
cachePrepStmts=true
|
||
cacheCallableStmts=true
|
||
cacheServerConfiguration=true
|
||
useLocalSessionState=true
|
||
elideSetAutoCommits=true
|
||
alwaysSendSetIsolation=false
|
||
enableQueryTimeouts=false
|
||
</pre><h4><a name="idm140266686887760"></a>solarisMaxPerformance</h4><pre class="programlisting">
|
||
useUnbufferedInput=false
|
||
useReadAheadInput=false
|
||
maintainTimeStats=false
|
||
</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-implementation-notes"></a>5.2 JDBC API Implementation Notes</h2></div></div></div><a class="indexterm" name="idm140266686885280"></a><p>
|
||
MySQL Connector/J, as a rigorous implementation of the
|
||
<a class="ulink" href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html" target="_top">JDBC
|
||
API</a>, passes all of the tests in the publicly available
|
||
version of Oracle's JDBC compliance test suite. The JDBC
|
||
specification is flexible on how certain functionality should be
|
||
implemented. This section gives details on an
|
||
interface-by-interface level about implementation decisions that
|
||
might affect how you code applications with MySQL Connector/J.
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<span class="bold"><strong>BLOB</strong></span>
|
||
</p><p>
|
||
Starting with Connector/J version 3.1.0, you can emulate
|
||
BLOBs with locators by adding the property
|
||
<code class="literal">emulateLocators=true</code> to your JDBC URL.
|
||
Using this method, the driver will delay loading the actual
|
||
BLOB data until you retrieve the other data and then use
|
||
retrieval methods (<code class="function">getInputStream()</code>,
|
||
<code class="function">getBytes()</code>, and so forth) on the BLOB
|
||
data stream.
|
||
</p><p>
|
||
You must use a column alias with the value of the column to
|
||
the actual name of the BLOB, for example:
|
||
</p><pre class="programlisting">
|
||
SELECT id, 'data' as blob_data from blobtable
|
||
</pre><p>
|
||
You must also follow these rules:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
|
||
The <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/select.html" target="_top"><code class="literal">SELECT</code></a> must reference
|
||
only one table. The table must have a
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/glossary.html#glos_primary_key" target="_top">primary key</a>.
|
||
</p></li><li class="listitem"><p>
|
||
The <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/select.html" target="_top"><code class="literal">SELECT</code></a> must alias the
|
||
original BLOB column name, specified as a string, to an
|
||
alternate name.
|
||
</p></li><li class="listitem"><p>
|
||
The <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/select.html" target="_top"><code class="literal">SELECT</code></a> must cover all
|
||
columns that make up the primary key.
|
||
</p></li></ul></div><p>
|
||
The BLOB implementation does not allow in-place modification
|
||
(they are copies, as reported by the
|
||
<code class="literal">DatabaseMetaData.locatorsUpdateCopies()</code>
|
||
method). Because of this, use the corresponding
|
||
<code class="literal">PreparedStatement.setBlob()</code> or
|
||
<code class="literal">ResultSet.updateBlob()</code> (in the case of
|
||
updatable result sets) methods to save changes back to the
|
||
database.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>CallableStatement</strong></span>
|
||
</p><p>
|
||
Starting with Connector/J 3.1.1, stored procedures are
|
||
supported when connecting to MySQL version 5.0 or newer
|
||
using the <code class="classname">CallableStatement</code>
|
||
interface. Currently, the
|
||
<code class="function">getParameterMetaData()</code> method of
|
||
<code class="classname">CallableStatement</code> is not supported.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>CLOB</strong></span>
|
||
</p><p>
|
||
The CLOB implementation does not allow in-place modification
|
||
(they are copies, as reported by the
|
||
<code class="literal">DatabaseMetaData.locatorsUpdateCopies()</code>
|
||
method). Because of this, use the
|
||
<code class="literal">PreparedStatement.setClob()</code> method to
|
||
save changes back to the database. The JDBC API does not
|
||
have a <code class="literal">ResultSet.updateClob()</code> method.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>Connection</strong></span>
|
||
</p><p>
|
||
Unlike the pre-Connector/J JDBC driver
|
||
(<code class="literal">MM.MySQL</code>), the
|
||
<code class="function">isClosed()</code> method does not ping the
|
||
server to determine if it is available. In accordance with
|
||
the JDBC specification, it only returns true if
|
||
<code class="function">closed()</code> has been called on the
|
||
connection. If you need to determine if the connection is
|
||
still valid, issue a simple query, such as <code class="literal">SELECT
|
||
1</code>. The driver will throw an exception if the
|
||
connection is no longer valid.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>DatabaseMetaData</strong></span>
|
||
</p><p>
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/glossary.html#glos_foreign_key" target="_top">Foreign key</a>
|
||
information
|
||
(<code class="function">getImportedKeys()</code>/<code class="function">getExportedKeys()</code>
|
||
and <code class="function">getCrossReference()</code>) is only
|
||
available from <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/innodb-storage-engine.html" target="_top"><code class="literal">InnoDB</code></a> tables.
|
||
The driver uses <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/show-create-table.html" target="_top"><code class="literal">SHOW CREATE
|
||
TABLE</code></a> to retrieve this information, so if any
|
||
other storage engines add support for foreign keys, the
|
||
driver would transparently support them as well.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>PreparedStatement</strong></span>
|
||
</p><p>
|
||
PreparedStatements are implemented by the driver, as MySQL
|
||
does not have a prepared statement feature. Because of this,
|
||
the driver does not implement
|
||
<code class="function">getParameterMetaData()</code> or
|
||
<code class="function">getMetaData()</code> as it would require the
|
||
driver to have a complete SQL parser in the client.
|
||
</p><p>
|
||
Starting with version 3.1.0 MySQL Connector/J, server-side
|
||
prepared statements and binary-encoded result sets are used
|
||
when the server supports them.
|
||
</p><p>
|
||
Take care when using a server-side prepared statement with
|
||
<span class="bold"><strong>large</strong></span> parameters that are
|
||
set using <code class="function">setBinaryStream()</code>,
|
||
<code class="function">setAsciiStream()</code>,
|
||
<code class="function">setUnicodeStream()</code>,
|
||
<code class="function">setBlob()</code>, or
|
||
<code class="function">setClob()</code>. To re-execute the statement
|
||
with any large parameter changed to a nonlarge parameter,
|
||
call <code class="function">clearParameters()</code> and set all
|
||
parameters again. The reason for this is as follows:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
|
||
During both server-side prepared statements and
|
||
client-side emulation, large data is exchanged only when
|
||
<code class="literal">PreparedStatement.execute()</code> is
|
||
called.
|
||
</p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
|
||
Once that has been done, the stream used to read the
|
||
data on the client side is closed (as per the JDBC
|
||
spec), and cannot be read from again.
|
||
</p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
|
||
If a parameter changes from large to nonlarge, the
|
||
driver must reset the server-side state of the prepared
|
||
statement to allow the parameter that is being changed
|
||
to take the place of the prior large value. This removes
|
||
all of the large data that has already been sent to the
|
||
server, thus requiring the data to be re-sent, using the
|
||
<code class="function">setBinaryStream()</code>,
|
||
<code class="function">setAsciiStream()</code>,
|
||
<code class="function">setUnicodeStream()</code>,
|
||
<code class="function">setBlob()</code> or
|
||
<code class="function">setClob()</code> method.
|
||
</p></li></ul></div><p>
|
||
Consequently, to change the type of a parameter to a
|
||
nonlarge one, you must call
|
||
<code class="function">clearParameters()</code> and set all
|
||
parameters of the prepared statement again before it can be
|
||
re-executed.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>ResultSet</strong></span>
|
||
</p><p>
|
||
By default, ResultSets are completely retrieved and stored
|
||
in memory. In most cases this is the most efficient way to
|
||
operate and, due to the design of the MySQL network
|
||
protocol, is easier to implement. If you are working with
|
||
ResultSets that have a large number of rows or large values
|
||
and cannot allocate heap space in your JVM for the memory
|
||
required, you can tell the driver to stream the results back
|
||
one row at a time.
|
||
</p><p>
|
||
To enable this functionality, create a
|
||
<code class="literal">Statement</code> instance in the following
|
||
manner:
|
||
</p><pre class="programlisting">
|
||
stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
|
||
java.sql.ResultSet.CONCUR_READ_ONLY);
|
||
stmt.setFetchSize(Integer.MIN_VALUE);
|
||
</pre><p>
|
||
The combination of a forward-only, read-only result set,
|
||
with a fetch size of <code class="literal">Integer.MIN_VALUE</code>
|
||
serves as a signal to the driver to stream result sets
|
||
row-by-row. After this, any result sets created with the
|
||
statement will be retrieved row-by-row.
|
||
</p><p>
|
||
There are some caveats with this approach. You must read all
|
||
of the rows in the result set (or close it) before you can
|
||
issue any other queries on the connection, or an exception
|
||
will be thrown.
|
||
</p><p>
|
||
The earliest the locks these statements hold can be released
|
||
(whether they be <code class="literal">MyISAM</code> table-level locks
|
||
or row-level locks in some other storage engine such as
|
||
<code class="literal">InnoDB</code>) is when the statement completes.
|
||
</p><p>
|
||
If the statement is within scope of a transaction, then
|
||
locks are released when the transaction completes (which
|
||
implies that the statement needs to complete first). As with
|
||
most other databases, statements are not complete until all
|
||
the results pending on the statement are read or the active
|
||
result set for the statement is closed.
|
||
</p><p>
|
||
Therefore, if using streaming results, process them as
|
||
quickly as possible if you want to maintain concurrent
|
||
access to the tables referenced by the statement producing
|
||
the result set.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>ResultSetMetaData</strong></span>
|
||
</p><p>
|
||
The <code class="function">isAutoIncrement()</code> method only works
|
||
when using MySQL servers 4.0 and newer.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>Statement</strong></span>
|
||
</p><p>
|
||
When using versions of the JDBC driver earlier than 3.2.1,
|
||
and connected to server versions earlier than 5.0.3, the
|
||
<code class="function">setFetchSize()</code> method has no effect,
|
||
other than to toggle result set streaming as described
|
||
above.
|
||
</p><p>
|
||
Connector/J 5.0.0 and later include support for both
|
||
<code class="literal">Statement.cancel()</code> and
|
||
<code class="literal">Statement.setQueryTimeout()</code>. Both require
|
||
MySQL 5.0.0 or newer server, and require a separate
|
||
connection to issue the
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/kill.html" target="_top"><code class="literal">KILL QUERY</code></a>
|
||
statement. In the case of
|
||
<code class="function">setQueryTimeout()</code>, the implementation
|
||
creates an additional thread to handle the timeout
|
||
functionality.
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
|
||
Failures to cancel the statement for
|
||
<code class="function">setQueryTimeout()</code> may manifest
|
||
themselves as <code class="literal">RuntimeException</code> rather
|
||
than failing silently, as there is currently no way to
|
||
unblock the thread that is executing the query being
|
||
cancelled due to timeout expiration and have it throw the
|
||
exception instead.
|
||
</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
|
||
The MySQL statement
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/kill.html" target="_top"><code class="literal">KILL QUERY</code></a>
|
||
(which is what the driver uses to implement
|
||
<code class="literal">Statement.cancel()</code>) is
|
||
non-deterministic; thus, avoid the use of
|
||
<code class="literal">Statement.cancel()</code> if possible. If no
|
||
query is in process, the next query issued will be killed
|
||
by the server. This race condition is guarded against as
|
||
of Connector/J 5.1.18.
|
||
</p></div><p>
|
||
MySQL does not support SQL cursors, and the JDBC driver
|
||
doesn't emulate them, so <code class="literal">setCursorName()</code>
|
||
has no effect.
|
||
</p><p>
|
||
Connector/J 5.1.3 and later include two additional methods:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
|
||
<code class="function">setLocalInfileInputStream()</code> sets an
|
||
<code class="literal">InputStream</code> instance that will be
|
||
used to send data to the MySQL server for a
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/load-data.html" target="_top"><code class="literal">LOAD DATA
|
||
LOCAL INFILE</code></a> statement rather than a
|
||
<code class="literal">FileInputStream</code> or
|
||
<code class="literal">URLInputStream</code> that represents the
|
||
path given as an argument to the statement.
|
||
</p><p>
|
||
This stream will be read to completion upon execution of
|
||
a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/load-data.html" target="_top"><code class="literal">LOAD DATA
|
||
LOCAL INFILE</code></a> statement, and will automatically
|
||
be closed by the driver, so it needs to be reset before
|
||
each call to <code class="literal">execute*()</code> that would
|
||
cause the MySQL server to request data to fulfill the
|
||
request for
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/load-data.html" target="_top"><code class="literal">LOAD DATA
|
||
LOCAL INFILE</code></a>.
|
||
</p><p>
|
||
If this value is set to <code class="literal">NULL</code>, the
|
||
driver will revert to using a
|
||
<code class="literal">FileInputStream</code> or
|
||
<code class="literal">URLInputStream</code> as required.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="function">getLocalInfileInputStream()</code> returns
|
||
the <code class="literal">InputStream</code> instance that will be
|
||
used to send data in response to a
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/load-data.html" target="_top"><code class="literal">LOAD DATA
|
||
LOCAL INFILE</code></a> statement.
|
||
</p><p>
|
||
This method returns <code class="literal">NULL</code> if no such
|
||
stream has been set using
|
||
<code class="function">setLocalInfileInputStream()</code>.
|
||
</p></li></ul></div></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-type-conversions"></a>5.3 Java, JDBC and MySQL Types</h2></div></div></div><a class="indexterm" name="idm140266686786912"></a><p>
|
||
MySQL Connector/J is flexible in the way it handles conversions
|
||
between MySQL data types and Java data types.
|
||
</p><p>
|
||
In general, any MySQL data type can be converted to a
|
||
<code class="literal">java.lang.String</code>, and any numeric type can be
|
||
converted to any of the Java numeric types, although round-off,
|
||
overflow, or loss of precision may occur.
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
|
||
All <code class="literal">TEXT</code> types return
|
||
<code class="literal">Types.LONGVARCHAR</code> with different
|
||
<code class="literal">getPrecision()</code> values (65535, 255,
|
||
16777215, and 2147483647 respectively) with
|
||
<code class="literal">getColumnType()</code> returning
|
||
<code class="literal">-1</code>. This behavior is intentional even
|
||
though <code class="literal">TINYTEXT</code> does not fall, regarding to
|
||
its size, within the <code class="literal">LONGVARCHAR</code> category.
|
||
This is to avoid different handling inside the same base type.
|
||
And <code class="literal">getColumnType()</code> returns
|
||
<code class="literal">-1</code> because the internal server handling is
|
||
of type <code class="literal">TEXT</code>, which is similar to
|
||
<code class="literal">BLOB</code>.
|
||
</p><p>
|
||
Also note that <code class="literal">getColumnTypeName()</code> will
|
||
return <code class="literal">VARCHAR</code> even though
|
||
<code class="literal">getColumnType()</code> returns
|
||
<code class="literal">Types.LONGVARCHAR</code>, because
|
||
<code class="literal">VARCHAR</code> is the designated column
|
||
database-specific name for this type.
|
||
</p></div><p>
|
||
Starting with Connector/J 3.1.0, the JDBC driver issues warnings
|
||
or throws <code class="literal">DataTruncation</code> exceptions as is
|
||
required by the JDBC specification unless the connection was
|
||
configured not to do so by using the property
|
||
<code class="literal">jdbcCompliantTruncation</code> and setting it to
|
||
<code class="literal">false</code>.
|
||
</p><p>
|
||
The conversions that are always guaranteed to work are listed in
|
||
the following table. The first column lists one or more MySQL
|
||
data types, and the second column lists one or more Java types
|
||
to which the MySQL types can be converted.
|
||
</p><div class="table"><a name="idm140266686768544"></a><p class="title"><b>Table 5.1 Connection Properties - Miscellaneous</b></p><div class="table-contents"><table class="table" summary="Connection Properties - Miscellaneous" border="1"><colgroup><col><col></colgroup><thead><tr><th scope="col">These MySQL Data Types</th><th scope="col">Can always be converted to these Java types</th></tr></thead><tbody><tr><td scope="row"><code class="literal">CHAR, VARCHAR, BLOB, TEXT, ENUM, and SET</code></td><td><code class="literal">java.lang.String, java.io.InputStream, java.io.Reader,
|
||
java.sql.Blob, java.sql.Clob</code></td></tr><tr><td scope="row"><code class="literal">FLOAT, REAL, DOUBLE PRECISION, NUMERIC, DECIMAL, TINYINT,
|
||
SMALLINT, MEDIUMINT, INTEGER, BIGINT</code></td><td><code class="literal">java.lang.String, java.lang.Short, java.lang.Integer,
|
||
java.lang.Long, java.lang.Double,
|
||
java.math.BigDecimal</code></td></tr><tr><td scope="row"><code class="literal">DATE, TIME, DATETIME, TIMESTAMP</code></td><td><code class="literal">java.lang.String, java.sql.Date, java.sql.Timestamp</code></td></tr></tbody></table></div></div><br class="table-break"><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
|
||
Round-off, overflow or loss of precision may occur if you
|
||
choose a Java numeric data type that has less precision or
|
||
capacity than the MySQL data type you are converting to/from.
|
||
</p></div><p>
|
||
The <code class="classname">ResultSet.getObject()</code> method uses the
|
||
type conversions between MySQL and Java types, following the
|
||
JDBC specification where appropriate. The value returned by
|
||
<code class="classname">ResultSetMetaData.GetColumnClassName()</code> is
|
||
also shown below. For more information on the JDBC types, see
|
||
the reference on the
|
||
<a class="ulink" href="http://docs.oracle.com/javase/8/docs/api/java/sql/Types.html" target="_top">java.sql.Types</a>
|
||
class.
|
||
</p><div class="table"><a name="idm140266686755008"></a><p class="title"><b>Table 5.2 MySQL Types to Java Types for ResultSet.getObject()</b></p><div class="table-contents"><table class="table" summary="MySQL Types to Java Types for ResultSet.getObject()" border="1"><colgroup><col><col><col></colgroup><thead><tr><th scope="col">MySQL Type Name</th><th scope="col">Return value of <code class="literal">GetColumnClassName</code></th><th scope="col">Returned as Java Class</th></tr></thead><tbody><tr><td scope="row"><code class="literal">BIT(1)</code> (new in MySQL-5.0)</td><td><code class="literal">BIT</code></td><td><code class="classname">java.lang.Boolean</code></td></tr><tr><td scope="row"><code class="literal">BIT( > 1)</code> (new in MySQL-5.0)</td><td><code class="literal">BIT</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">TINYINT</code></td><td><code class="literal">TINYINT</code></td><td><code class="classname">java.lang.Boolean</code> if the configuration property
|
||
<code class="literal">tinyInt1isBit</code> is set to
|
||
<code class="literal">true</code> (the default) and the storage
|
||
size is 1, or <code class="classname">java.lang.Integer</code>
|
||
if not.</td></tr><tr><td scope="row"><code class="literal">BOOL</code>, <code class="literal">BOOLEAN</code></td><td><code class="literal">TINYINT</code></td><td>See <code class="literal">TINYINT</code>, above as these are aliases for
|
||
<code class="literal">TINYINT(1)</code>, currently.</td></tr><tr><td scope="row"><code class="literal">SMALLINT[(M)] [UNSIGNED]</code></td><td><code class="literal">SMALLINT [UNSIGNED]</code></td><td><code class="classname">java.lang.Integer</code> (regardless if
|
||
<code class="literal">UNSIGNED</code> or not)</td></tr><tr><td scope="row"><code class="literal">MEDIUMINT[(M)] [UNSIGNED]</code></td><td><code class="literal">MEDIUMINT [UNSIGNED]</code></td><td><code class="classname">java.lang.Integer,</code> if <code class="literal">UNSIGNED</code>
|
||
<code class="classname">java.lang.Long</code> (C/J 3.1 and
|
||
earlier), or <code class="classname">java.lang.Integer</code>
|
||
for C/J 5.0 and later</td></tr><tr><td scope="row"><code class="literal">INT,INTEGER[(M)] [UNSIGNED]</code></td><td><code class="literal">INTEGER [UNSIGNED]</code></td><td><code class="classname">java.lang.Integer</code>, if <code class="literal">UNSIGNED</code>
|
||
<code class="classname">java.lang.Long</code></td></tr><tr><td scope="row"><code class="literal">BIGINT[(M)] [UNSIGNED]</code></td><td><code class="literal">BIGINT [UNSIGNED]</code></td><td><code class="classname">java.lang.Long</code>, if UNSIGNED
|
||
<code class="classname">java.math.BigInteger</code></td></tr><tr><td scope="row"><code class="literal">FLOAT[(M,D)]</code></td><td><code class="literal">FLOAT</code></td><td><code class="classname">java.lang.Float</code></td></tr><tr><td scope="row"><code class="literal">DOUBLE[(M,B)]</code></td><td><code class="literal">DOUBLE</code></td><td><code class="classname">java.lang.Double</code></td></tr><tr><td scope="row"><code class="literal">DECIMAL[(M[,D])]</code></td><td><code class="literal">DECIMAL</code></td><td><code class="classname">java.math.BigDecimal</code></td></tr><tr><td scope="row"><code class="literal">DATE</code></td><td><code class="literal">DATE</code></td><td><code class="classname">java.sql.Date</code></td></tr><tr><td scope="row"><code class="literal">DATETIME</code></td><td><code class="literal">DATETIME</code></td><td><code class="classname">java.sql.Timestamp</code></td></tr><tr><td scope="row"><code class="literal">TIMESTAMP[(M)]</code></td><td><code class="literal">TIMESTAMP</code></td><td><code class="classname">java.sql.Timestamp</code></td></tr><tr><td scope="row"><code class="literal">TIME</code></td><td><code class="literal">TIME</code></td><td><code class="classname">java.sql.Time</code></td></tr><tr><td scope="row"><code class="literal">YEAR[(2|4)]</code></td><td><code class="literal">YEAR</code></td><td>If <code class="literal">yearIsDateType</code> configuration property is set to
|
||
<code class="literal">false</code>, then the returned object type
|
||
is <code class="classname">java.sql.Short</code>. If set to
|
||
<code class="literal">true</code> (the default), then the returned
|
||
object is of type <code class="classname">java.sql.Date</code>
|
||
with the date
|
||
|
||
|
||
set to January 1st, at midnight.</td></tr><tr><td scope="row"><code class="literal">CHAR(M)</code></td><td><code class="literal">CHAR</code></td><td><code class="classname">java.lang.String</code> (unless the character set for
|
||
the column is <code class="literal">BINARY</code>, then
|
||
<code class="classname">byte[]</code> is returned.</td></tr><tr><td scope="row"><code class="literal">VARCHAR(M) [BINARY]</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code> (unless the character set for
|
||
the column is <code class="literal">BINARY</code>, then
|
||
<code class="classname">byte[]</code> is returned.</td></tr><tr><td scope="row"><code class="literal">BINARY(M)</code></td><td><code class="literal">BINARY</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">VARBINARY(M)</code></td><td><code class="literal">VARBINARY</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">TINYBLOB</code></td><td><code class="literal">TINYBLOB</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">TINYTEXT</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">BLOB</code></td><td><code class="literal">BLOB</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">TEXT</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">MEDIUMBLOB</code></td><td><code class="literal">MEDIUMBLOB</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">MEDIUMTEXT</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">LONGBLOB</code></td><td><code class="literal">LONGBLOB</code></td><td><code class="classname">byte[]</code></td></tr><tr><td scope="row"><code class="literal">LONGTEXT</code></td><td><code class="literal">VARCHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">ENUM('value1','value2',...)</code></td><td><code class="literal">CHAR</code></td><td><code class="classname">java.lang.String</code></td></tr><tr><td scope="row"><code class="literal">SET('value1','value2',...)</code></td><td><code class="literal">CHAR</code></td><td><code class="classname">java.lang.String</code></td></tr></tbody></table></div></div><br class="table-break"></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-charsets"></a>5.4 Using Character Sets and Unicode</h2></div></div></div><a class="indexterm" name="idm140266686663696"></a><a class="indexterm" name="idm140266686662304"></a><a class="indexterm" name="idm140266686660912"></a><p>
|
||
All strings sent from the JDBC driver to the server are
|
||
converted automatically from native Java Unicode form to the
|
||
client character encoding, including all queries sent using
|
||
<code class="literal">Statement.execute()</code>,
|
||
<code class="literal">Statement.executeUpdate()</code>,
|
||
<code class="literal">Statement.executeQuery()</code> as well as all
|
||
<code class="interfacename">PreparedStatement</code> and
|
||
<code class="interfacename">CallableStatement</code> parameters with
|
||
the exclusion of parameters set using
|
||
<code class="function">setBytes()</code>,
|
||
<code class="function">setBinaryStream()</code>,
|
||
<code class="function">setAsciiStream()</code>,
|
||
<code class="function">setUnicodeStream()</code> and
|
||
<code class="function">setBlob()</code>.
|
||
</p><h3><a name="idm140266686653072"></a>Number of Encodings Per Connection</h3><p>
|
||
In MySQL Server 4.1 and higher, Connector/J supports a single
|
||
character encoding between client and server, and any number of
|
||
character encodings for data returned by the server to the
|
||
client in <code class="classname">ResultSets</code>.
|
||
</p><p>
|
||
Prior to MySQL Server 4.1, Connector/J supported a single
|
||
character encoding per connection, which could either be
|
||
automatically detected from the server configuration, or could
|
||
be configured by the user through the
|
||
<em class="parameter"><code>useUnicode</code></em> and
|
||
<em class="parameter"><code>characterEncoding</code></em> properties.
|
||
</p><h3><a name="idm140266686649536"></a>Setting the Character Encoding</h3><p>
|
||
The character encoding between client and server is
|
||
automatically detected upon connection. You specify the encoding
|
||
on the server using the
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_character_set_server" target="_top"><code class="literal">character_set_server</code></a> for server
|
||
versions 4.1.0 and newer, and <code class="literal">character_set</code>
|
||
system variable for server versions older than 4.1.0. The driver
|
||
automatically uses the encoding specified by the server. For
|
||
more information, see <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/charset-server.html" target="_top">Server Character Set and Collation</a>.
|
||
</p><p>
|
||
For example, to use 4-byte UTF-8 character sets with
|
||
Connector/J, configure the MySQL server with
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_character_set_server" target="_top"><code class="literal">character_set_server=utf8mb4</code></a>,
|
||
and leave <code class="literal">characterEncoding</code> out of the
|
||
Connector/J connection string. Connector/J will then autodetect
|
||
the UTF-8 setting.
|
||
</p><p>
|
||
To override the automatically detected encoding on the client
|
||
side, use the <em class="parameter"><code>characterEncoding</code></em> property
|
||
in the URL used to connect to the server.
|
||
</p><p>
|
||
To allow multiple character sets to be sent from the client, use
|
||
the UTF-8 encoding, either by configuring
|
||
<code class="literal">utf8</code> as the default server character set, or
|
||
by configuring the JDBC driver to use UTF-8 through the
|
||
<code class="literal">characterEncoding</code> property.
|
||
</p><p>
|
||
When specifying character encodings on the client side, use
|
||
Java-style names. The following table lists MySQL character set
|
||
names and the corresponding Java-style names:
|
||
</p><div class="table"><a name="idm140266686639616"></a><p class="title"><b>Table 5.3 MySQL to Java Encoding Name Translations</b></p><div class="table-contents"><table class="table" summary="MySQL to Java Encoding Name Translations" border="1"><colgroup><col><col></colgroup><thead><tr><th scope="col">MySQL Character Set Name</th><th scope="col">Java-Style Character Encoding Name</th></tr></thead><tbody><tr><td scope="row"><code class="literal">ascii</code></td><td><code class="literal">US-ASCII</code></td></tr><tr><td scope="row"><code class="literal">big5</code></td><td><code class="literal">Big5</code></td></tr><tr><td scope="row"><code class="literal">gbk</code></td><td><code class="literal">GBK</code></td></tr><tr><td scope="row"><code class="literal">sjis</code></td><td><code class="literal">SJIS (or Cp932 or MS932 for MySQL Server < 4.1.11)</code></td></tr><tr><td scope="row"><code class="literal">cp932</code></td><td><code class="literal">Cp932 or MS932 (MySQL Server > 4.1.11)</code></td></tr><tr><td scope="row"><code class="literal">gb2312</code></td><td><code class="literal">EUC_CN</code></td></tr><tr><td scope="row"><code class="literal">ujis</code></td><td><code class="literal">EUC_JP</code></td></tr><tr><td scope="row"><code class="literal">euckr</code></td><td><code class="literal">EUC_KR</code></td></tr><tr><td scope="row"><code class="literal">latin1</code></td><td><code class="literal">Cp1252</code></td></tr><tr><td scope="row"><code class="literal">latin2</code></td><td><code class="literal">ISO8859_2</code></td></tr><tr><td scope="row"><code class="literal">greek</code></td><td><code class="literal">ISO8859_7</code></td></tr><tr><td scope="row"><code class="literal">hebrew</code></td><td><code class="literal">ISO8859_8</code></td></tr><tr><td scope="row"><code class="literal">cp866</code></td><td><code class="literal">Cp866</code></td></tr><tr><td scope="row"><code class="literal">tis620</code></td><td><code class="literal">TIS620</code></td></tr><tr><td scope="row"><code class="literal">cp1250</code></td><td><code class="literal">Cp1250</code></td></tr><tr><td scope="row"><code class="literal">cp1251</code></td><td><code class="literal">Cp1251</code></td></tr><tr><td scope="row"><code class="literal">cp1257</code></td><td><code class="literal">Cp1257</code></td></tr><tr><td scope="row"><code class="literal">macroman</code></td><td><code class="literal">MacRoman</code></td></tr><tr><td scope="row"><code class="literal">macce</code></td><td><code class="literal">MacCentralEurope</code></td></tr><tr><td scope="row"><code class="literal">utf8</code></td><td><code class="literal">UTF-8</code></td></tr><tr><td scope="row"><code class="literal">ucs2</code></td><td><code class="literal">UnicodeBig</code></td></tr></tbody></table></div></div><br class="table-break"><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Warning</div><p>
|
||
Do not issue the query <code class="literal">set names</code> with
|
||
Connector/J, as the driver will not detect that the character
|
||
set has changed, and will continue to use the character set
|
||
detected during the initial connection setup.
|
||
</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-using-ssl"></a>5.5 Connecting Securely Using SSL</h2></div></div></div><a class="indexterm" name="idm140266686592864"></a><p>
|
||
SSL in MySQL Connector/J encrypts all data (other than the
|
||
initial handshake) between the JDBC driver and the server. There
|
||
is a performance penalty for enabling SSL, the severity of which
|
||
depends on multiple factors including (but not limited to) the
|
||
size of the query, the amount of data returned, the server
|
||
hardware, the SSL library used, the network bandwidth, and so
|
||
on.
|
||
</p><p>
|
||
For SSL support to work, you must have the following:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
A JDK that includes JSSE (Java Secure Sockets Extension),
|
||
like JDK-1.4.1 or newer. SSL does not currently work with a
|
||
JDK that you can add JSSE to, like JDK-1.2.x or JDK-1.3.x
|
||
due to the following JSSE bug:
|
||
<a class="ulink" href="http://bugs.java.com/bugdatabase/view_bug.do?bug_id=4273544" target="_top">http://bugs.java.com/bugdatabase/view_bug.do?bug_id=4273544</a>
|
||
</p></li><li class="listitem"><p>
|
||
A MySQL server that supports SSL and has been compiled and
|
||
configured to do so, which is MySQL 4.0.4 or later. For more
|
||
information, see
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/building-with-secure-connection-support.html" target="_top">Building MySQL with Support for Secure Connections</a>.
|
||
</p></li><li class="listitem"><p>
|
||
A client certificate (covered later in this section)
|
||
</p></li></ul></div><p>
|
||
The system works through two Java truststore files, one file
|
||
contains the certificate information for the server
|
||
(<code class="filename">truststore</code> in the examples below). The
|
||
other file contains the certificate for the client
|
||
(<code class="filename">keystore</code> in the examples below). All Java
|
||
truststore files are password protected by supplying a suitable
|
||
password to the <span class="command"><strong>keytool</strong></span> when you create the
|
||
files. You need the file names and associated passwords to
|
||
create an SSL connection.
|
||
</p><p>
|
||
You will first need to import the MySQL server CA Certificate
|
||
into a Java truststore. A sample MySQL server CA Certificate is
|
||
located in the <code class="filename">SSL</code> subdirectory of the
|
||
MySQL source distribution. This is what SSL will use to
|
||
determine if you are communicating with a secure MySQL server.
|
||
Alternatively, use the CA Certificate that you have generated or
|
||
been provided with by your SSL provider.
|
||
</p><p>
|
||
To use Java's <span class="command"><strong>keytool</strong></span> to create a truststore
|
||
in the current directory , and import the server's CA
|
||
certificate (<code class="filename">cacert.pem</code>), you can do the
|
||
following (assuming that <span class="command"><strong>keytool</strong></span> is in your
|
||
path. The <span class="command"><strong>keytool</strong></span> is typically located in the
|
||
<code class="filename">bin</code> subdirectory of your JDK or JRE):
|
||
</p><pre class="programlisting">
|
||
shell> keytool -import -alias mysqlServerCACert \
|
||
-file cacert.pem -keystore truststore
|
||
</pre><p>
|
||
Enter the password when prompted for the keystore file.
|
||
Interaction with <span class="command"><strong>keytool</strong></span> looks like this:
|
||
</p><pre class="programlisting">
|
||
Enter keystore password: *********
|
||
Owner: EMAILADDRESS=walrus@example.com, CN=Walrus,
|
||
O=My Company, L=Orenburg, ST=Some-State, C=RU
|
||
Issuer: EMAILADDRESS=walrus@example.com, CN=Walrus,
|
||
O=My Company, L=Orenburg, ST=Some-State, C=RU
|
||
Serial number: 0
|
||
Valid from:
|
||
Fri Aug 02 16:55:53 CDT 2002 until: Sat Aug 02 16:55:53 CDT 2003
|
||
Certificate fingerprints:
|
||
MD5: 61:91:A0:F2:03:07:61:7A:81:38:66:DA:19:C4:8D:AB
|
||
SHA1: 25:77:41:05:D5:AD:99:8C:14:8C:CA:68:9C:2F:B8:89:C3:34:4D:6C
|
||
Trust this certificate? [no]: yes
|
||
Certificate was added to keystore
|
||
</pre><p>
|
||
You then have two options: either import the client certificate
|
||
that matches the CA certificate you just imported, or create a
|
||
new client certificate.
|
||
</p><p>
|
||
Importing an existing certificate requires the certificate to be
|
||
in DER format. You can use <span class="command"><strong>openssl</strong></span> to convert
|
||
an existing certificate into the new format. For example:
|
||
</p><pre class="programlisting">
|
||
shell> openssl x509 -outform DER -in client-cert.pem -out client.cert
|
||
</pre><p>
|
||
Now import the converted certificate into your keystore using
|
||
<span class="command"><strong>keytool</strong></span>:
|
||
</p><pre class="programlisting">
|
||
shell> keytool -import -file client.cert -keystore keystore -alias mysqlClientCertificate
|
||
</pre><p>
|
||
To generate your own client certificate, use
|
||
<span class="command"><strong>keytool</strong></span> to create a suitable certificate and
|
||
add it to the <code class="filename">keystore</code> file:
|
||
</p><pre class="programlisting">
|
||
shell> keytool -genkey -keyalg rsa \
|
||
-alias mysqlClientCertificate -keystore keystore
|
||
</pre><p>
|
||
Keytool will prompt you for the following information, and
|
||
create a keystore named <code class="filename">keystore</code> in the
|
||
current directory.
|
||
</p><p>
|
||
Respond with information that is appropriate for your situation:
|
||
</p><pre class="programlisting">
|
||
Enter keystore password: *********
|
||
What is your first and last name?
|
||
[Unknown]: Matthews
|
||
What is the name of your organizational unit?
|
||
[Unknown]: Software Development
|
||
What is the name of your organization?
|
||
[Unknown]: My Company
|
||
What is the name of your City or Locality?
|
||
[Unknown]: Flossmoor
|
||
What is the name of your State or Province?
|
||
[Unknown]: IL
|
||
What is the two-letter country code for this unit?
|
||
[Unknown]: US
|
||
Is <CN=Matthews, OU=Software Development, O=My Company,
|
||
L=Flossmoor, ST=IL, C=US> correct?
|
||
[no]: y
|
||
|
||
Enter key password for <mysqlClientCertificate>
|
||
(RETURN if same as keystore password):
|
||
</pre><p>
|
||
Finally, to get JSSE to use the keystore and truststore that you
|
||
have generated, you need to set the following system properties
|
||
when you start your JVM, replacing
|
||
<em class="replaceable"><code>path_to_keystore_file</code></em> with the full
|
||
path to the keystore file you created,
|
||
<em class="replaceable"><code>path_to_truststore_file</code></em> with the path
|
||
to the truststore file you created, and using the appropriate
|
||
password values for each property. You can do this either on the
|
||
command line:
|
||
</p><pre class="programlisting">
|
||
-Djavax.net.ssl.keyStore=<em class="replaceable"><code>path_to_keystore_file</code></em>
|
||
-Djavax.net.ssl.keyStorePassword=<em class="replaceable"><code>password</code></em>
|
||
-Djavax.net.ssl.trustStore=<em class="replaceable"><code>path_to_truststore_file</code></em>
|
||
-Djavax.net.ssl.trustStorePassword=<em class="replaceable"><code>password</code></em>
|
||
</pre><p>
|
||
Or you can set the values directly within the application:
|
||
</p><pre class="programlisting">
|
||
System.setProperty("javax.net.ssl.keyStore","<em class="replaceable"><code>path_to_keystore_file</code></em>");
|
||
System.setProperty("javax.net.ssl.keyStorePassword","<em class="replaceable"><code>password</code></em>");
|
||
System.setProperty("javax.net.ssl.trustStore","<em class="replaceable"><code>path_to_truststore_file</code></em>");
|
||
System.setProperty("javax.net.ssl.trustStorePassword","<em class="replaceable"><code>password</code></em>");
|
||
</pre><p>
|
||
You will also need to set <code class="literal">useSSL</code> to
|
||
<code class="literal">true</code> in your connection parameters for MySQL
|
||
Connector/J, either by adding <code class="literal">useSSL=true</code> to
|
||
your URL, or by setting the property <code class="literal">useSSL</code>
|
||
to <code class="literal">true</code> in the
|
||
<code class="classname">java.util.Properties</code> instance you pass to
|
||
<code class="literal">DriverManager.getConnection()</code>.
|
||
</p><p>
|
||
You can test that SSL is working by turning on JSSE debugging
|
||
(as detailed below), and look for the following key events:
|
||
</p><pre class="programlisting">
|
||
...
|
||
*** ClientHello, v3.1
|
||
RandomCookie: GMT: 1018531834 bytes = { 199, 148, 180, 215, 74, 12, »
|
||
54, 244, 0, 168, 55, 103, 215, 64, 16, 138, 225, 190, 132, 153, 2, »
|
||
217, 219, 239, 202, 19, 121, 78 }
|
||
Session ID: {}
|
||
Cipher Suites: { 0, 5, 0, 4, 0, 9, 0, 10, 0, 18, 0, 19, 0, 3, 0, 17 }
|
||
Compression Methods: { 0 }
|
||
***
|
||
[write] MD5 and SHA1 hashes: len = 59
|
||
0000: 01 00 00 37 03 01 3D B6 90 FA C7 94 B4 D7 4A 0C ...7..=.......J.
|
||
0010: 36 F4 00 A8 37 67 D7 40 10 8A E1 BE 84 99 02 D9 6...7g.@........
|
||
0020: DB EF CA 13 79 4E 00 00 10 00 05 00 04 00 09 00 ....yN..........
|
||
0030: 0A 00 12 00 13 00 03 00 11 01 00 ...........
|
||
main, WRITE: SSL v3.1 Handshake, length = 59
|
||
main, READ: SSL v3.1 Handshake, length = 74
|
||
*** ServerHello, v3.1
|
||
RandomCookie: GMT: 1018577560 bytes = { 116, 50, 4, 103, 25, 100, 58, »
|
||
202, 79, 185, 178, 100, 215, 66, 254, 21, 83, 187, 190, 42, 170, 3, »
|
||
132, 110, 82, 148, 160, 92 }
|
||
Session ID: {163, 227, 84, 53, 81, 127, 252, 254, 178, 179, 68, 63, »
|
||
182, 158, 30, 11, 150, 79, 170, 76, 255, 92, 15, 226, 24, 17, 177, »
|
||
219, 158, 177, 187, 143}
|
||
Cipher Suite: { 0, 5 }
|
||
Compression Method: 0
|
||
***
|
||
%% Created: [Session-1, SSL_RSA_WITH_RC4_128_SHA]
|
||
** SSL_RSA_WITH_RC4_128_SHA
|
||
[read] MD5 and SHA1 hashes: len = 74
|
||
0000: 02 00 00 46 03 01 3D B6 43 98 74 32 04 67 19 64 ...F..=.C.t2.g.d
|
||
0010: 3A CA 4F B9 B2 64 D7 42 FE 15 53 BB BE 2A AA 03 :.O..d.B..S..*..
|
||
0020: 84 6E 52 94 A0 5C 20 A3 E3 54 35 51 7F FC FE B2 .nR..\ ..T5Q....
|
||
0030: B3 44 3F B6 9E 1E 0B 96 4F AA 4C FF 5C 0F E2 18 .D?.....O.L.\...
|
||
0040: 11 B1 DB 9E B1 BB 8F 00 05 00 ..........
|
||
main, READ: SSL v3.1 Handshake, length = 1712
|
||
...
|
||
</pre><p>
|
||
JSSE provides debugging (to <code class="literal">stdout</code>) when you
|
||
set the following system property:
|
||
<code class="literal">-Djavax.net.debug=all</code> This will tell you what
|
||
keystores and truststores are being used, as well as what is
|
||
going on during the SSL handshake and certificate exchange. It
|
||
will be helpful when trying to determine what is not working
|
||
when trying to get an SSL connection to happen.
|
||
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-using-pam"></a>5.6 Connecting Using PAM Authentication</h2></div></div></div><a class="indexterm" name="idm140266686546928"></a><p>
|
||
Java applications using Connector/J 5.1.21 and higher can
|
||
connect to MySQL servers that use the pluggable authentication
|
||
module (PAM) authentication scheme.
|
||
</p><p>
|
||
For PAM authentication to work, you must have the following:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
A MySQL server that supports PAM authentication: a
|
||
commercial distribution of MySQL 5.5.16 or higher. See
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/pam-authentication-plugin.html" target="_top">The PAM Authentication Plugin</a> for more
|
||
information. Connector/J implements the same cleartext
|
||
authentication method as in
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/cleartext-authentication-plugin.html" target="_top">The Cleartext Client-Side Authentication Plugin</a>.
|
||
</p></li><li class="listitem"><p>
|
||
SSL capability, as explained in
|
||
<a class="xref" href="#connector-j-reference-using-ssl" title="5.5 Connecting Securely Using SSL">Section 5.5, “Connecting Securely Using SSL”</a>. Because
|
||
the PAM authentication scheme sends the original password to
|
||
the server, the connection to the server must be encrypted.
|
||
</p></li></ul></div><p>
|
||
PAM authentication support is enabled by default in Connector/J
|
||
5.1.21 and up, so no extra configuration is needed.
|
||
</p><p>
|
||
To disable the PAM authentication feature, specify
|
||
<code class="literal">mysql_clear_password</code> (the method) or
|
||
<code class="literal">com.mysql.jdbc.authentication.MysqlClearPasswordPlugin</code>
|
||
(the class name) in the comma-separated list of arguments for
|
||
the <code class="literal">disabledAuthenticationPlugins</code> connection
|
||
option. See
|
||
<a class="xref" href="#connector-j-reference-configuration-properties" title="5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
|
||
for Connector/J”</a>
|
||
for details about that connection option.
|
||
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-replication-connection"></a>5.7 Using Master/Slave Replication with ReplicationConnection</h2></div></div></div><p>
|
||
See
|
||
<a class="xref" href="#connector-j-master-slave-replication-connection" title="8.3 Configuring Master/Slave Replication with Connector/J">Section 8.3, “Configuring Master/Slave Replication with Connector/J”</a>
|
||
for details on the topic.
|
||
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-reference-error-sqlstates"></a>5.8 Mapping MySQL Error Numbers to JDBC SQLState Codes</h2></div></div></div><a class="indexterm" name="idm140266686533536"></a><a class="indexterm" name="idm140266686532528"></a><a class="indexterm" name="idm140266686531520"></a><a class="indexterm" name="idm140266686530128"></a><a class="indexterm" name="idm140266686528736"></a><a class="indexterm" name="idm140266686527728"></a><a class="indexterm" name="idm140266686526720"></a><a class="indexterm" name="idm140266686525712"></a><a class="indexterm" name="idm140266686524704"></a><a class="indexterm" name="idm140266686523696"></a><a class="indexterm" name="idm140266686522688"></a><a class="indexterm" name="idm140266686521680"></a><a class="indexterm" name="idm140266686520672"></a><a class="indexterm" name="idm140266686519664"></a><a class="indexterm" name="idm140266686518656"></a><a class="indexterm" name="idm140266686517648"></a><a class="indexterm" name="idm140266686516640"></a><a class="indexterm" name="idm140266686515632"></a><a class="indexterm" name="idm140266686514624"></a><a class="indexterm" name="idm140266686513616"></a><a class="indexterm" name="idm140266686512608"></a><a class="indexterm" name="idm140266686511600"></a><a class="indexterm" name="idm140266686510592"></a><a class="indexterm" name="idm140266686509584"></a><a class="indexterm" name="idm140266686508576"></a><a class="indexterm" name="idm140266686507568"></a><a class="indexterm" name="idm140266686506560"></a><a class="indexterm" name="idm140266686505552"></a><a class="indexterm" name="idm140266686504544"></a><a class="indexterm" name="idm140266686503536"></a><a class="indexterm" name="idm140266686502528"></a><a class="indexterm" name="idm140266686501520"></a><a class="indexterm" name="idm140266686500512"></a><a class="indexterm" name="idm140266686499504"></a><a class="indexterm" name="idm140266686498496"></a><a class="indexterm" name="idm140266686497488"></a><a class="indexterm" name="idm140266686496480"></a><a class="indexterm" name="idm140266686495472"></a><a class="indexterm" name="idm140266686494464"></a><a class="indexterm" name="idm140266686493456"></a><a class="indexterm" name="idm140266686492448"></a><a class="indexterm" name="idm140266686491440"></a><a class="indexterm" name="idm140266686490432"></a><a class="indexterm" name="idm140266686489424"></a><a class="indexterm" name="idm140266686488416"></a><a class="indexterm" name="idm140266686487408"></a><a class="indexterm" name="idm140266686486400"></a><a class="indexterm" name="idm140266686485392"></a><a class="indexterm" name="idm140266686484384"></a><a class="indexterm" name="idm140266686483376"></a><a class="indexterm" name="idm140266686482368"></a><a class="indexterm" name="idm140266686481360"></a><a class="indexterm" name="idm140266686480352"></a><a class="indexterm" name="idm140266686479344"></a><a class="indexterm" name="idm140266686478336"></a><a class="indexterm" name="idm140266686477328"></a><a class="indexterm" name="idm140266686476320"></a><a class="indexterm" name="idm140266686475312"></a><a class="indexterm" name="idm140266686474304"></a><a class="indexterm" name="idm140266686473296"></a><a class="indexterm" name="idm140266686472288"></a><a class="indexterm" name="idm140266686471280"></a><a class="indexterm" name="idm140266686470272"></a><a class="indexterm" name="idm140266686469264"></a><a class="indexterm" name="idm140266686468256"></a><a class="indexterm" name="idm140266686467248"></a><a class="indexterm" name="idm140266686466240"></a><a class="indexterm" name="idm140266686465232"></a><a class="indexterm" name="idm140266686464224"></a><a class="indexterm" name="idm140266686463216"></a><a class="indexterm" name="idm140266686462208"></a><a class="indexterm" name="idm140266686461200"></a><a class="indexterm" name="idm140266686460192"></a><a class="indexterm" name="idm140266686459184"></a><a class="indexterm" name="idm140266686458176"></a><a class="indexterm" name="idm140266686457168"></a><a class="indexterm" name="idm140266686456160"></a><a class="indexterm" name="idm140266686455152"></a><a class="indexterm" name="idm140266686454144"></a><a class="indexterm" name="idm140266686453136"></a><a class="indexterm" name="idm140266686452128"></a><a class="indexterm" name="idm140266686451120"></a><a class="indexterm" name="idm140266686450112"></a><a class="indexterm" name="idm140266686449104"></a><a class="indexterm" name="idm140266686448096"></a><a class="indexterm" name="idm140266686447088"></a><a class="indexterm" name="idm140266686446080"></a><a class="indexterm" name="idm140266686445072"></a><a class="indexterm" name="idm140266686444064"></a><a class="indexterm" name="idm140266686443056"></a><a class="indexterm" name="idm140266686442048"></a><a class="indexterm" name="idm140266686441040"></a><a class="indexterm" name="idm140266686440032"></a><a class="indexterm" name="idm140266686439024"></a><a class="indexterm" name="idm140266686438016"></a><a class="indexterm" name="idm140266686437008"></a><a class="indexterm" name="idm140266686436000"></a><a class="indexterm" name="idm140266686434992"></a><a class="indexterm" name="idm140266686433984"></a><a class="indexterm" name="idm140266686432976"></a><a class="indexterm" name="idm140266686431968"></a><a class="indexterm" name="idm140266686430960"></a><a class="indexterm" name="idm140266686429952"></a><a class="indexterm" name="idm140266686428944"></a><a class="indexterm" name="idm140266686427936"></a><a class="indexterm" name="idm140266686426928"></a><a class="indexterm" name="idm140266686425920"></a><a class="indexterm" name="idm140266686424912"></a><a class="indexterm" name="idm140266686423904"></a><a class="indexterm" name="idm140266686422896"></a><a class="indexterm" name="idm140266686421888"></a><a class="indexterm" name="idm140266686420880"></a><a class="indexterm" name="idm140266686419872"></a><a class="indexterm" name="idm140266686418864"></a><a class="indexterm" name="idm140266686417856"></a><a class="indexterm" name="idm140266686416848"></a><a class="indexterm" name="idm140266686415840"></a><a class="indexterm" name="idm140266686414832"></a><a class="indexterm" name="idm140266686413824"></a><a class="indexterm" name="idm140266686412816"></a><a class="indexterm" name="idm140266686411808"></a><a class="indexterm" name="idm140266686410800"></a><a class="indexterm" name="idm140266686409792"></a><a class="indexterm" name="idm140266686408784"></a><a class="indexterm" name="idm140266686407776"></a><a class="indexterm" name="idm140266686406768"></a><a class="indexterm" name="idm140266686405760"></a><a class="indexterm" name="idm140266686404752"></a><a class="indexterm" name="idm140266686403744"></a><a class="indexterm" name="idm140266686402736"></a><a class="indexterm" name="idm140266686401728"></a><a class="indexterm" name="idm140266686400720"></a><a class="indexterm" name="idm140266686399712"></a><a class="indexterm" name="idm140266686398704"></a><a class="indexterm" name="idm140266686397696"></a><a class="indexterm" name="idm140266686396688"></a><a class="indexterm" name="idm140266686395680"></a><p>
|
||
The table below provides a mapping of the MySQL error numbers to
|
||
JDBC <code class="literal">SQLState</code> values.
|
||
</p><div class="table"><a name="idm140266686393568"></a><p class="title"><b>Table 5.4 Mapping of MySQL Error Numbers to SQLStates</b></p><div class="table-contents"><table class="table" summary="Mapping of MySQL Error Numbers to SQLStates" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th scope="col">MySQL Error Number</th><th scope="col">MySQL Error Name</th><th scope="col">Legacy (X/Open) SQLState</th><th scope="col">SQL Standard SQLState</th></tr></thead><tbody><tr><td scope="row">1022</td><td>ER_DUP_KEY</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1037</td><td>ER_OUTOFMEMORY</td><td>S1001</td><td>HY001</td></tr><tr><td scope="row">1038</td><td>ER_OUT_OF_SORTMEMORY</td><td>S1001</td><td>HY001</td></tr><tr><td scope="row">1040</td><td>ER_CON_COUNT_ERROR</td><td>08004</td><td>08004</td></tr><tr><td scope="row">1042</td><td>ER_BAD_HOST_ERROR</td><td>08004</td><td>08S01</td></tr><tr><td scope="row">1043</td><td>ER_HANDSHAKE_ERROR</td><td>08004</td><td>08S01</td></tr><tr><td scope="row">1044</td><td>ER_DBACCESS_DENIED_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1045</td><td>ER_ACCESS_DENIED_ERROR</td><td>28000</td><td>28000</td></tr><tr><td scope="row">1046</td><td>ER_NO_DB_ERROR</td><td>3D000</td><td>3D000</td></tr><tr><td scope="row">1047</td><td>ER_UNKNOWN_COM_ERROR</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1048</td><td>ER_BAD_NULL_ERROR</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1049</td><td>ER_BAD_DB_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1050</td><td>ER_TABLE_EXISTS_ERROR</td><td>42S01</td><td>42S01</td></tr><tr><td scope="row">1051</td><td>ER_BAD_TABLE_ERROR</td><td>42S02</td><td>42S02</td></tr><tr><td scope="row">1052</td><td>ER_NON_UNIQ_ERROR</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1053</td><td>ER_SERVER_SHUTDOWN</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1054</td><td>ER_BAD_FIELD_ERROR</td><td>S0022</td><td>42S22</td></tr><tr><td scope="row">1055</td><td>ER_WRONG_FIELD_WITH_GROUP</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1056</td><td>ER_WRONG_GROUP_FIELD</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1057</td><td>ER_WRONG_SUM_SELECT</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1058</td><td>ER_WRONG_VALUE_COUNT</td><td>21S01</td><td>21S01</td></tr><tr><td scope="row">1059</td><td>ER_TOO_LONG_IDENT</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1060</td><td>ER_DUP_FIELDNAME</td><td>S1009</td><td>42S21</td></tr><tr><td scope="row">1061</td><td>ER_DUP_KEYNAME</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1062</td><td>ER_DUP_ENTRY</td><td>S1009</td><td>23000</td></tr><tr><td scope="row">1063</td><td>ER_WRONG_FIELD_SPEC</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1064</td><td>ER_PARSE_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1065</td><td>ER_EMPTY_QUERY</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1066</td><td>ER_NONUNIQ_TABLE</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1067</td><td>ER_INVALID_DEFAULT</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1068</td><td>ER_MULTIPLE_PRI_KEY</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1069</td><td>ER_TOO_MANY_KEYS</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1070</td><td>ER_TOO_MANY_KEY_PARTS</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1071</td><td>ER_TOO_LONG_KEY</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1072</td><td>ER_KEY_COLUMN_DOES_NOT_EXITS</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1073</td><td>ER_BLOB_USED_AS_KEY</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1074</td><td>ER_TOO_BIG_FIELDLENGTH</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1075</td><td>ER_WRONG_AUTO_KEY</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1080</td><td>ER_FORCING_CLOSE</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1081</td><td>ER_IPSOCK_ERROR</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1082</td><td>ER_NO_SUCH_INDEX</td><td>S1009</td><td>42S12</td></tr><tr><td scope="row">1083</td><td>ER_WRONG_FIELD_TERMINATORS</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1084</td><td>ER_BLOBS_AND_NO_TERMINATED</td><td>S1009</td><td>42000</td></tr><tr><td scope="row">1090</td><td>ER_CANT_REMOVE_ALL_FIELDS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1091</td><td>ER_CANT_DROP_FIELD_OR_KEY</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1101</td><td>ER_BLOB_CANT_HAVE_DEFAULT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1102</td><td>ER_WRONG_DB_NAME</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1103</td><td>ER_WRONG_TABLE_NAME</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1104</td><td>ER_TOO_BIG_SELECT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1106</td><td>ER_UNKNOWN_PROCEDURE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1107</td><td>ER_WRONG_PARAMCOUNT_TO_PROCEDURE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1109</td><td>ER_UNKNOWN_TABLE</td><td>42S02</td><td>42S02</td></tr><tr><td scope="row">1110</td><td>ER_FIELD_SPECIFIED_TWICE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1112</td><td>ER_UNSUPPORTED_EXTENSION</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1113</td><td>ER_TABLE_MUST_HAVE_COLUMNS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1115</td><td>ER_UNKNOWN_CHARACTER_SET</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1118</td><td>ER_TOO_BIG_ROWSIZE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1120</td><td>ER_WRONG_OUTER_JOIN</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1121</td><td>ER_NULL_COLUMN_IN_INDEX</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1129</td><td>ER_HOST_IS_BLOCKED</td><td>08004</td><td>HY000</td></tr><tr><td scope="row">1130</td><td>ER_HOST_NOT_PRIVILEGED</td><td>08004</td><td>HY000</td></tr><tr><td scope="row">1131</td><td>ER_PASSWORD_ANONYMOUS_USER</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1132</td><td>ER_PASSWORD_NOT_ALLOWED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1133</td><td>ER_PASSWORD_NO_MATCH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1136</td><td>ER_WRONG_VALUE_COUNT_ON_ROW</td><td>21S01</td><td>21S01</td></tr><tr><td scope="row">1138</td><td>ER_INVALID_USE_OF_NULL</td><td>S1000</td><td>42000</td></tr><tr><td scope="row">1139</td><td>ER_REGEXP_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1140</td><td>ER_MIX_OF_GROUP_FUNC_AND_FIELDS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1141</td><td>ER_NONEXISTING_GRANT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1142</td><td>ER_TABLEACCESS_DENIED_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1143</td><td>ER_COLUMNACCESS_DENIED_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1144</td><td>ER_ILLEGAL_GRANT_FOR_TABLE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1145</td><td>ER_GRANT_WRONG_HOST_OR_USER</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1146</td><td>ER_NO_SUCH_TABLE</td><td>42S02</td><td>42S02</td></tr><tr><td scope="row">1147</td><td>ER_NONEXISTING_TABLE_GRANT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1148</td><td>ER_NOT_ALLOWED_COMMAND</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1149</td><td>ER_SYNTAX_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1152</td><td>ER_ABORTING_CONNECTION</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1153</td><td>ER_NET_PACKET_TOO_LARGE</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1154</td><td>ER_NET_READ_ERROR_FROM_PIPE</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1155</td><td>ER_NET_FCNTL_ERROR</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1156</td><td>ER_NET_PACKETS_OUT_OF_ORDER</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1157</td><td>ER_NET_UNCOMPRESS_ERROR</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1158</td><td>ER_NET_READ_ERROR</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1159</td><td>ER_NET_READ_INTERRUPTED</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1160</td><td>ER_NET_ERROR_ON_WRITE</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1161</td><td>ER_NET_WRITE_INTERRUPTED</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1162</td><td>ER_TOO_LONG_STRING</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1163</td><td>ER_TABLE_CANT_HANDLE_BLOB</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1164</td><td>ER_TABLE_CANT_HANDLE_AUTO_INCREMENT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1166</td><td>ER_WRONG_COLUMN_NAME</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1167</td><td>ER_WRONG_KEY_COLUMN</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1169</td><td>ER_DUP_UNIQUE</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1170</td><td>ER_BLOB_KEY_WITHOUT_LENGTH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1171</td><td>ER_PRIMARY_CANT_HAVE_NULL</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1172</td><td>ER_TOO_MANY_ROWS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1173</td><td>ER_REQUIRES_PRIMARY_KEY</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1176</td><td>ER_KEY_DOES_NOT_EXITS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1177</td><td>ER_CHECK_NO_SUCH_TABLE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1178</td><td>ER_CHECK_NOT_IMPLEMENTED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1179</td><td>ER_CANT_DO_THIS_DURING_AN_TRANSACTION</td><td>25000</td><td>25000</td></tr><tr><td scope="row">1184</td><td>ER_NEW_ABORTING_CONNECTION</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1189</td><td>ER_MASTER_NET_READ</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1190</td><td>ER_MASTER_NET_WRITE</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1203</td><td>ER_TOO_MANY_USER_CONNECTIONS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1205</td><td>ER_LOCK_WAIT_TIMEOUT</td><td>40001</td><td>40001</td></tr><tr><td scope="row">1207</td><td>ER_READ_ONLY_TRANSACTION</td><td>25000</td><td>25000</td></tr><tr><td scope="row">1211</td><td>ER_NO_PERMISSION_TO_CREATE_USER</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1213</td><td>ER_LOCK_DEADLOCK</td><td>40001</td><td>40001</td></tr><tr><td scope="row">1216</td><td>ER_NO_REFERENCED_ROW</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1217</td><td>ER_ROW_IS_REFERENCED</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1218</td><td>ER_CONNECT_TO_MASTER</td><td>08S01</td><td>08S01</td></tr><tr><td scope="row">1222</td><td>ER_WRONG_NUMBER_OF_COLUMNS_IN_SELECT</td><td>21000</td><td>21000</td></tr><tr><td scope="row">1226</td><td>ER_USER_LIMIT_REACHED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1227</td><td>ER_SPECIFIC_ACCESS_DENIED_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1230</td><td>ER_NO_DEFAULT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1231</td><td>ER_WRONG_VALUE_FOR_VAR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1232</td><td>ER_WRONG_TYPE_FOR_VAR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1234</td><td>ER_CANT_USE_OPTION_HERE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1235</td><td>ER_NOT_SUPPORTED_YET</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1239</td><td>ER_WRONG_FK_DEF</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1241</td><td>ER_OPERAND_COLUMNS</td><td>21000</td><td>21000</td></tr><tr><td scope="row">1242</td><td>ER_SUBQUERY_NO_1_ROW</td><td>21000</td><td>21000</td></tr><tr><td scope="row">1247</td><td>ER_ILLEGAL_REFERENCE</td><td>42S22</td><td>42S22</td></tr><tr><td scope="row">1248</td><td>ER_DERIVED_MUST_HAVE_ALIAS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1249</td><td>ER_SELECT_REDUCED</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1250</td><td>ER_TABLENAME_NOT_ALLOWED_HERE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1251</td><td>ER_NOT_SUPPORTED_AUTH_MODE</td><td>08004</td><td>08004</td></tr><tr><td scope="row">1252</td><td>ER_SPATIAL_CANT_HAVE_NULL</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1253</td><td>ER_COLLATION_CHARSET_MISMATCH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1261</td><td>ER_WARN_TOO_FEW_RECORDS</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1262</td><td>ER_WARN_TOO_MANY_RECORDS</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1263</td><td>ER_WARN_NULL_TO_NOTNULL</td><td>S1000</td><td>01000</td></tr><tr><td scope="row">1264</td><td>ER_WARN_DATA_OUT_OF_RANGE</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1265</td><td>ER_WARN_DATA_TRUNCATED</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1280</td><td>ER_WRONG_NAME_FOR_INDEX</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1281</td><td>ER_WRONG_NAME_FOR_CATALOG</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1286</td><td>ER_UNKNOWN_STORAGE_ENGINE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1292</td><td>ER_TRUNCATED_WRONG_VALUE</td><td>22007</td><td>22007</td></tr><tr><td scope="row">1303</td><td>ER_SP_NO_RECURSIVE_CREATE</td><td>S1000</td><td>2F003</td></tr><tr><td scope="row">1304</td><td>ER_SP_ALREADY_EXISTS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1305</td><td>ER_SP_DOES_NOT_EXIST</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1308</td><td>ER_SP_LILABEL_MISMATCH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1309</td><td>ER_SP_LABEL_REDEFINE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1310</td><td>ER_SP_LABEL_MISMATCH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1311</td><td>ER_SP_UNINIT_VAR</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1312</td><td>ER_SP_BADSELECT</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1313</td><td>ER_SP_BADRETURN</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1314</td><td>ER_SP_BADSTATEMENT</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1315</td><td>ER_UPDATE_LOG_DEPRECATED_IGNORED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1316</td><td>ER_UPDATE_LOG_DEPRECATED_TRANSLATED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1317</td><td>ER_QUERY_INTERRUPTED</td><td>S1000</td><td>70100</td></tr><tr><td scope="row">1318</td><td>ER_SP_WRONG_NO_OF_ARGS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1319</td><td>ER_SP_COND_MISMATCH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1320</td><td>ER_SP_NORETURN</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1321</td><td>ER_SP_NORETURNEND</td><td>S1000</td><td>2F005</td></tr><tr><td scope="row">1322</td><td>ER_SP_BAD_CURSOR_QUERY</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1323</td><td>ER_SP_BAD_CURSOR_SELECT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1324</td><td>ER_SP_CURSOR_MISMATCH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1325</td><td>ER_SP_CURSOR_ALREADY_OPEN</td><td>24000</td><td>24000</td></tr><tr><td scope="row">1326</td><td>ER_SP_CURSOR_NOT_OPEN</td><td>24000</td><td>24000</td></tr><tr><td scope="row">1327</td><td>ER_SP_UNDECLARED_VAR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1329</td><td>ER_SP_FETCH_NO_DATA</td><td>S1000</td><td>02000</td></tr><tr><td scope="row">1330</td><td>ER_SP_DUP_PARAM</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1331</td><td>ER_SP_DUP_VAR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1332</td><td>ER_SP_DUP_COND</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1333</td><td>ER_SP_DUP_CURS</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1335</td><td>ER_SP_SUBSELECT_NYI</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1336</td><td>ER_STMT_NOT_ALLOWED_IN_SF_OR_TRG</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1337</td><td>ER_SP_VARCOND_AFTER_CURSHNDLR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1338</td><td>ER_SP_CURSOR_AFTER_HANDLER</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1339</td><td>ER_SP_CASE_NOT_FOUND</td><td>S1000</td><td>20000</td></tr><tr><td scope="row">1365</td><td>ER_DIVISION_BY_ZERO</td><td>22012</td><td>22012</td></tr><tr><td scope="row">1367</td><td>ER_ILLEGAL_VALUE_FOR_TYPE</td><td>22007</td><td>22007</td></tr><tr><td scope="row">1370</td><td>ER_PROCACCESS_DENIED_ERROR</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1397</td><td>ER_XAER_NOTA</td><td>S1000</td><td>XAE04</td></tr><tr><td scope="row">1398</td><td>ER_XAER_INVAL</td><td>S1000</td><td>XAE05</td></tr><tr><td scope="row">1399</td><td>ER_XAER_RMFAIL</td><td>S1000</td><td>XAE07</td></tr><tr><td scope="row">1400</td><td>ER_XAER_OUTSIDE</td><td>S1000</td><td>XAE09</td></tr><tr><td scope="row">1401</td><td>ER_XA_RMERR</td><td>S1000</td><td>XAE03</td></tr><tr><td scope="row">1402</td><td>ER_XA_RBROLLBACK</td><td>S1000</td><td>XA100</td></tr><tr><td scope="row">1403</td><td>ER_NONEXISTING_PROC_GRANT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1406</td><td>ER_DATA_TOO_LONG</td><td>22001</td><td>22001</td></tr><tr><td scope="row">1407</td><td>ER_SP_BAD_SQLSTATE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1410</td><td>ER_CANT_CREATE_USER_WITH_GRANT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1413</td><td>ER_SP_DUP_HANDLER</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1414</td><td>ER_SP_NOT_VAR_ARG</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1415</td><td>ER_SP_NO_RETSET</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1416</td><td>ER_CANT_CREATE_GEOMETRY_OBJECT</td><td>22003</td><td>22003</td></tr><tr><td scope="row">1425</td><td>ER_TOO_BIG_SCALE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1426</td><td>ER_TOO_BIG_PRECISION</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1427</td><td>ER_M_BIGGER_THAN_D</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1437</td><td>ER_TOO_LONG_BODY</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1439</td><td>ER_TOO_BIG_DISPLAYWIDTH</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1440</td><td>ER_XAER_DUPID</td><td>S1000</td><td>XAE08</td></tr><tr><td scope="row">1441</td><td>ER_DATETIME_FUNCTION_OVERFLOW</td><td>22008</td><td>22008</td></tr><tr><td scope="row">1451</td><td>ER_ROW_IS_REFERENCED_2</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1452</td><td>ER_NO_REFERENCED_ROW_2</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1453</td><td>ER_SP_BAD_VAR_SHADOW</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1458</td><td>ER_SP_WRONG_NAME</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1460</td><td>ER_SP_NO_AGGREGATE</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1461</td><td>ER_MAX_PREPARED_STMT_COUNT_REACHED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1463</td><td>ER_NON_GROUPING_FIELD_USED</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1557</td><td>ER_FOREIGN_DUPLICATE_KEY</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1568</td><td>ER_CANT_CHANGE_TX_ISOLATION</td><td>S1000</td><td>25001</td></tr><tr><td scope="row">1582</td><td>ER_WRONG_PARAMCOUNT_TO_NATIVE_FCT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1583</td><td>ER_WRONG_PARAMETERS_TO_NATIVE_FCT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1584</td><td>ER_WRONG_PARAMETERS_TO_STORED_FCT</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1586</td><td>ER_DUP_ENTRY_WITH_KEY_NAME</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1613</td><td>ER_XA_RBTIMEOUT</td><td>S1000</td><td>XA106</td></tr><tr><td scope="row">1614</td><td>ER_XA_RBDEADLOCK</td><td>S1000</td><td>XA102</td></tr><tr><td scope="row">1630</td><td>ER_FUNC_INEXISTENT_NAME_COLLISION</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1641</td><td>ER_DUP_SIGNAL_SET</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1642</td><td>ER_SIGNAL_WARN</td><td>01000</td><td>01000</td></tr><tr><td scope="row">1643</td><td>ER_SIGNAL_NOT_FOUND</td><td>S1000</td><td>02000</td></tr><tr><td scope="row">1645</td><td>ER_RESIGNAL_WITHOUT_ACTIVE_HANDLER</td><td>S1000</td><td>0K000</td></tr><tr><td scope="row">1687</td><td>ER_SPATIAL_MUST_HAVE_GEOM_COL</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1690</td><td>ER_DATA_OUT_OF_RANGE</td><td>22003</td><td>22003</td></tr><tr><td scope="row">1698</td><td>ER_ACCESS_DENIED_NO_PASSWORD_ERROR</td><td>28000</td><td>28000</td></tr><tr><td scope="row">1701</td><td>ER_TRUNCATE_ILLEGAL_FK</td><td>42000</td><td>42000</td></tr><tr><td scope="row">1758</td><td>ER_DA_INVALID_CONDITION_NUMBER</td><td>35000</td><td>35000</td></tr><tr><td scope="row">1761</td><td>ER_FOREIGN_DUPLICATE_KEY_WITH_CHILD_INFO</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1762</td><td>ER_FOREIGN_DUPLICATE_KEY_WITHOUT_CHILD_INFO</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1792</td><td>ER_CANT_EXECUTE_IN_READ_ONLY_TRANSACTION</td><td>S1000</td><td>25006</td></tr><tr><td scope="row">1845</td><td>ER_ALTER_OPERATION_NOT_SUPPORTED</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1846</td><td>ER_ALTER_OPERATION_NOT_SUPPORTED_REASON</td><td>0A000</td><td>0A000</td></tr><tr><td scope="row">1859</td><td>ER_DUP_UNKNOWN_IN_INDEX</td><td>23000</td><td>23000</td></tr><tr><td scope="row">1873</td><td>ER_ACCESS_DENIED_CHANGE_USER_ERROR</td><td>28000</td><td>28000</td></tr><tr><td scope="row">1887</td><td>ER_GET_STACKED_DA_WITHOUT_ACTIVE_HANDLER</td><td>S1000</td><td>0Z002</td></tr><tr><td scope="row">1903</td><td>ER_INVALID_ARGUMENT_FOR_LOGARITHM</td><td>S1000</td><td>2201E</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-basic"></a>Chapter 6 JDBC Concepts</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-usagenotes-connect-drivermanager">6.1 Connecting to MySQL Using the JDBC <code class="literal">DriverManager</code>
|
||
Interface</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-statements">6.2 Using JDBC <code class="literal">Statement</code> Objects to Execute SQL</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-statements-callable">6.3 Using JDBC <code class="literal">CallableStatements</code> to Execute Stored
|
||
Procedures</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-last-insert-id">6.4 Retrieving <code class="literal">AUTO_INCREMENT</code> Column Values through JDBC</a></span></dt></dl></div><a class="indexterm" name="idm140266685944768"></a><p>
|
||
This section provides some general JDBC background.
|
||
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-connect-drivermanager"></a>6.1 Connecting to MySQL Using the JDBC <code class="literal">DriverManager</code>
|
||
Interface</h2></div></div></div><p>
|
||
When you are using JDBC outside of an application server, the
|
||
<code class="literal">DriverManager</code> class manages the establishment
|
||
of connections.
|
||
</p><p>
|
||
Specify to the <code class="literal">DriverManager</code> which JDBC
|
||
drivers to try to make Connections with. The easiest way to do
|
||
this is to use <code class="literal">Class.forName()</code> on the class
|
||
that implements the <code class="literal">java.sql.Driver</code>
|
||
interface. With MySQL Connector/J, the name of this class is
|
||
<code class="literal">com.mysql.jdbc.Driver</code>. With this method, you
|
||
could use an external configuration file to supply the driver
|
||
class name and driver parameters to use when connecting to a
|
||
database.
|
||
</p><p>
|
||
The following section of Java code shows how you might register
|
||
MySQL Connector/J from the <code class="function">main()</code> method of
|
||
your application. If testing this code, first read the
|
||
installation section at
|
||
<a class="xref" href="#connector-j-installing" title="Chapter 3 Connector/J Installation">Chapter 3, <i>Connector/J Installation</i></a>, to make sure you have
|
||
connector installed correctly and the
|
||
<code class="literal">CLASSPATH</code> set up. Also, ensure that MySQL is
|
||
configured to accept external TCP/IP connections.
|
||
</p><pre class="programlisting">
|
||
import java.sql.Connection;
|
||
import java.sql.DriverManager;
|
||
import java.sql.SQLException;
|
||
|
||
// Notice, do not import com.mysql.jdbc.*
|
||
// or you will have problems!
|
||
|
||
public class LoadDriver {
|
||
public static void main(String[] args) {
|
||
try {
|
||
// The newInstance() call is a work around for some
|
||
// broken Java implementations
|
||
|
||
Class.forName("com.mysql.jdbc.Driver").newInstance();
|
||
} catch (Exception ex) {
|
||
// handle the error
|
||
}
|
||
}
|
||
}
|
||
</pre><p>
|
||
After the driver has been registered with the
|
||
<code class="literal">DriverManager</code>, you can obtain a
|
||
<code class="literal">Connection</code> instance that is connected to a
|
||
particular database by calling
|
||
<code class="literal">DriverManager.getConnection()</code>:
|
||
</p><div class="example"><a name="connector-j-examples-connection-drivermanager"></a><p class="title"><b>Example 6.1 Connector/J: Obtaining a connection from the
|
||
<code class="literal">DriverManager</code></b></p><div class="example-contents"><p>
|
||
If you have not already done so, please review the portion of
|
||
<a class="xref" href="#connector-j-usagenotes-connect-drivermanager" title="6.1 Connecting to MySQL Using the JDBC DriverManager Interface">Section 6.1, “Connecting to MySQL Using the JDBC <code class="literal">DriverManager</code>
|
||
Interface”</a>
|
||
above before working with the example below.
|
||
</p><p>
|
||
This example shows how you can obtain a
|
||
<code class="literal">Connection</code> instance from the
|
||
<code class="literal">DriverManager</code>. There are a few different
|
||
signatures for the <code class="function">getConnection()</code>
|
||
method. Consult the API documentation that comes with your JDK
|
||
for more specific information on how to use them.
|
||
</p><pre class="programlisting">
|
||
import java.sql.Connection;
|
||
import java.sql.DriverManager;
|
||
import java.sql.SQLException;
|
||
|
||
Connection conn = null;
|
||
...
|
||
try {
|
||
conn =
|
||
DriverManager.getConnection("jdbc:mysql://localhost/test?" +
|
||
"user=minty&password=greatsqldb");
|
||
|
||
// Do something with the Connection
|
||
|
||
...
|
||
} catch (SQLException ex) {
|
||
// handle any errors
|
||
System.out.println("SQLException: " + ex.getMessage());
|
||
System.out.println("SQLState: " + ex.getSQLState());
|
||
System.out.println("VendorError: " + ex.getErrorCode());
|
||
}
|
||
</pre><p>
|
||
Once a <code class="classname">Connection</code> is established, it
|
||
can be used to create <code class="classname">Statement</code> and
|
||
<code class="classname">PreparedStatement</code> objects, as well as
|
||
retrieve metadata about the database. This is explained in the
|
||
following sections.
|
||
</p></div></div><br class="example-break"></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-statements"></a>6.2 Using JDBC <code class="literal">Statement</code> Objects to Execute SQL</h2></div></div></div><p>
|
||
<code class="classname">Statement</code> objects allow you to execute
|
||
basic SQL queries and retrieve the results through the
|
||
<code class="literal">ResultSet</code> class, which is described later.
|
||
</p><p>
|
||
To create a <code class="classname">Statement</code> instance, you call
|
||
the <code class="function">createStatement()</code> method on the
|
||
<code class="literal">Connection</code> object you have retrieved using
|
||
one of the <code class="literal">DriverManager.getConnection()</code> or
|
||
<code class="literal">DataSource.getConnection()</code> methods described
|
||
earlier.
|
||
</p><p>
|
||
Once you have a <code class="classname">Statement</code> instance, you
|
||
can execute a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/select.html" target="_top"><code class="literal">SELECT</code></a> query by
|
||
calling the <code class="function">executeQuery(String)</code> method
|
||
with the SQL you want to use.
|
||
</p><p>
|
||
To update data in the database, use the
|
||
<code class="function">executeUpdate(String SQL)</code> method. This
|
||
method returns the number of rows matched by the update
|
||
statement, not the number of rows that were modified.
|
||
</p><p>
|
||
If you do not know ahead of time whether the SQL statement will
|
||
be a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/select.html" target="_top"><code class="literal">SELECT</code></a> or an
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/update.html" target="_top"><code class="literal">UPDATE</code></a>/<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/insert.html" target="_top"><code class="literal">INSERT</code></a>,
|
||
then you can use the <code class="function">execute(String SQL)</code>
|
||
method. This method will return true if the SQL query was a
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/select.html" target="_top"><code class="literal">SELECT</code></a>, or false if it was an
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/update.html" target="_top"><code class="literal">UPDATE</code></a>,
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/insert.html" target="_top"><code class="literal">INSERT</code></a>, or
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/delete.html" target="_top"><code class="literal">DELETE</code></a> statement. If the
|
||
statement was a <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/select.html" target="_top"><code class="literal">SELECT</code></a> query, you
|
||
can retrieve the results by calling the
|
||
<code class="function">getResultSet()</code> method. If the statement was
|
||
an <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/update.html" target="_top"><code class="literal">UPDATE</code></a>,
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/insert.html" target="_top"><code class="literal">INSERT</code></a>, or
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/delete.html" target="_top"><code class="literal">DELETE</code></a> statement, you can
|
||
retrieve the affected rows count by calling
|
||
<code class="function">getUpdateCount()</code> on the
|
||
<code class="classname">Statement</code> instance.
|
||
</p><div class="example"><a name="connector-j-examples-execute-select"></a><p class="title"><b>Example 6.2 Connector/J: Using java.sql.Statement to execute a
|
||
<code class="literal">SELECT</code> query</b></p><div class="example-contents"><pre class="programlisting">
|
||
import java.sql.Connection;
|
||
import java.sql.DriverManager;
|
||
import java.sql.SQLException;
|
||
import java.sql.Statement;
|
||
import java.sql.ResultSet;
|
||
|
||
// assume that conn is an already created JDBC connection (see previous examples)
|
||
|
||
Statement stmt = null;
|
||
ResultSet rs = null;
|
||
|
||
try {
|
||
stmt = conn.createStatement();
|
||
rs = stmt.executeQuery("SELECT foo FROM bar");
|
||
|
||
// or alternatively, if you don't know ahead of time that
|
||
// the query will be a SELECT...
|
||
|
||
if (stmt.execute("SELECT foo FROM bar")) {
|
||
rs = stmt.getResultSet();
|
||
}
|
||
|
||
// Now do something with the ResultSet ....
|
||
}
|
||
catch (SQLException ex){
|
||
// handle any errors
|
||
System.out.println("SQLException: " + ex.getMessage());
|
||
System.out.println("SQLState: " + ex.getSQLState());
|
||
System.out.println("VendorError: " + ex.getErrorCode());
|
||
}
|
||
finally {
|
||
// it is a good idea to release
|
||
// resources in a finally{} block
|
||
// in reverse-order of their creation
|
||
// if they are no-longer needed
|
||
|
||
if (rs != null) {
|
||
try {
|
||
rs.close();
|
||
} catch (SQLException sqlEx) { } // ignore
|
||
|
||
rs = null;
|
||
}
|
||
|
||
if (stmt != null) {
|
||
try {
|
||
stmt.close();
|
||
} catch (SQLException sqlEx) { } // ignore
|
||
|
||
stmt = null;
|
||
}
|
||
}
|
||
</pre></div></div><br class="example-break"></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-statements-callable"></a>6.3 Using JDBC <code class="literal">CallableStatements</code> to Execute Stored
|
||
Procedures</h2></div></div></div><p>
|
||
Starting with MySQL server version 5.0 when used with
|
||
Connector/J 3.1.1 or newer, the
|
||
<code class="classname">java.sql.CallableStatement</code> interface is
|
||
fully implemented with the exception of the
|
||
<code class="function">getParameterMetaData()</code> method.
|
||
</p><p>
|
||
For more information on MySQL stored procedures, please refer to
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/stored-routines.html" target="_top">Using Stored Routines (Procedures and Functions)</a>.
|
||
</p><p>
|
||
Connector/J exposes stored procedure functionality through
|
||
JDBC's <code class="classname">CallableStatement</code> interface.
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
|
||
Current versions of MySQL server do not return enough
|
||
information for the JDBC driver to provide result set metadata
|
||
for callable statements. This means that when using
|
||
<code class="literal">CallableStatement</code>,
|
||
<code class="literal">ResultSetMetaData</code> may return
|
||
<code class="literal">NULL</code>.
|
||
</p></div><p>
|
||
The following example shows a stored procedure that returns the
|
||
value of <code class="varname">inOutParam</code> incremented by 1, and the
|
||
string passed in using <code class="varname">inputParam</code> as a
|
||
<code class="classname">ResultSet</code>:
|
||
|
||
</p><div class="example"><a name="connector-j-examples-stored-procedure"></a><p class="title"><b>Example 6.3 Connector/J: Calling Stored Procedures</b></p><div class="example-contents"><pre class="programlisting">
|
||
CREATE PROCEDURE demoSp(IN inputParam VARCHAR(255), \
|
||
INOUT inOutParam INT)
|
||
BEGIN
|
||
DECLARE z INT;
|
||
SET z = inOutParam + 1;
|
||
SET inOutParam = z;
|
||
|
||
SELECT inputParam;
|
||
|
||
SELECT CONCAT('zyxw', inputParam);
|
||
END
|
||
</pre></div></div><p><br class="example-break">
|
||
</p><p>
|
||
To use the <code class="literal">demoSp</code> procedure with Connector/J,
|
||
follow these steps:
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
Prepare the callable statement by using
|
||
<code class="literal">Connection.prepareCall()</code>.
|
||
</p><p>
|
||
Notice that you have to use JDBC escape syntax, and that the
|
||
parentheses surrounding the parameter placeholders are not
|
||
optional:
|
||
</p><div class="example"><a name="connector-j-examples-preparecall"></a><p class="title"><b>Example 6.4 Connector/J: Using <code class="literal">Connection.prepareCall()</code></b></p><div class="example-contents"><pre class="programlisting">
|
||
import java.sql.CallableStatement;
|
||
|
||
...
|
||
|
||
//
|
||
// Prepare a call to the stored procedure 'demoSp'
|
||
// with two parameters
|
||
//
|
||
// Notice the use of JDBC-escape syntax ({call ...})
|
||
//
|
||
|
||
CallableStatement cStmt = conn.prepareCall("{call demoSp(?, ?)}");
|
||
|
||
|
||
|
||
cStmt.setString(1, "abcdefg");
|
||
</pre></div></div><br class="example-break"><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
|
||
<code class="literal">Connection.prepareCall()</code> is an
|
||
expensive method, due to the metadata retrieval that the
|
||
driver performs to support output parameters. For
|
||
performance reasons, minimize unnecessary calls to
|
||
<code class="literal">Connection.prepareCall()</code> by reusing
|
||
<code class="classname">CallableStatement</code> instances in your
|
||
code.
|
||
</p></div></li><li class="listitem"><p>
|
||
Register the output parameters (if any exist)
|
||
</p><p>
|
||
To retrieve the values of output parameters (parameters
|
||
specified as <code class="literal">OUT</code> or
|
||
<code class="literal">INOUT</code> when you created the stored
|
||
procedure), JDBC requires that they be specified before
|
||
statement execution using the various
|
||
<code class="function">registerOutputParameter()</code> methods in
|
||
the <code class="classname">CallableStatement</code> interface:
|
||
|
||
</p><div class="example"><a name="connector-j-examples-output-param"></a><p class="title"><b>Example 6.5 Connector/J: Registering output parameters</b></p><div class="example-contents"><pre class="programlisting">
|
||
import java.sql.Types;
|
||
...
|
||
//
|
||
// Connector/J supports both named and indexed
|
||
// output parameters. You can register output
|
||
// parameters using either method, as well
|
||
// as retrieve output parameters using either
|
||
// method, regardless of what method was
|
||
// used to register them.
|
||
//
|
||
// The following examples show how to use
|
||
// the various methods of registering
|
||
// output parameters (you should of course
|
||
// use only one registration per parameter).
|
||
//
|
||
|
||
//
|
||
// Registers the second parameter as output, and
|
||
// uses the type 'INTEGER' for values returned from
|
||
// getObject()
|
||
//
|
||
|
||
cStmt.registerOutParameter(2, Types.INTEGER);
|
||
|
||
//
|
||
// Registers the named parameter 'inOutParam', and
|
||
// uses the type 'INTEGER' for values returned from
|
||
// getObject()
|
||
//
|
||
|
||
cStmt.registerOutParameter("inOutParam", Types.INTEGER);
|
||
...
|
||
</pre></div></div><p><br class="example-break">
|
||
</p></li><li class="listitem"><p>
|
||
Set the input parameters (if any exist)
|
||
</p><p>
|
||
Input and in/out parameters are set as for
|
||
<code class="classname">PreparedStatement</code> objects. However,
|
||
<code class="classname">CallableStatement</code> also supports
|
||
setting parameters by name:
|
||
|
||
</p><div class="example"><a name="connector-j-examples-callablestatement"></a><p class="title"><b>Example 6.6 Connector/J: Setting <code class="literal">CallableStatement</code> input
|
||
parameters</b></p><div class="example-contents"><pre class="programlisting">
|
||
...
|
||
|
||
//
|
||
// Set a parameter by index
|
||
//
|
||
|
||
cStmt.setString(1, "abcdefg");
|
||
|
||
//
|
||
// Alternatively, set a parameter using
|
||
// the parameter name
|
||
//
|
||
|
||
cStmt.setString("inputParameter", "abcdefg");
|
||
|
||
//
|
||
// Set the 'in/out' parameter using an index
|
||
//
|
||
|
||
cStmt.setInt(2, 1);
|
||
|
||
//
|
||
// Alternatively, set the 'in/out' parameter
|
||
// by name
|
||
//
|
||
|
||
cStmt.setInt("inOutParam", 1);
|
||
|
||
...
|
||
</pre></div></div><p><br class="example-break">
|
||
</p></li><li class="listitem"><p>
|
||
Execute the <code class="classname">CallableStatement</code>, and
|
||
retrieve any result sets or output parameters.
|
||
</p><p>
|
||
Although <code class="classname">CallableStatement</code> supports
|
||
calling any of the <code class="classname">Statement</code> execute
|
||
methods (<code class="function">executeUpdate()</code>,
|
||
<code class="function">executeQuery()</code> or
|
||
<code class="function">execute()</code>), the most flexible method to
|
||
call is <code class="function">execute()</code>, as you do not need
|
||
to know ahead of time if the stored procedure returns result
|
||
sets:
|
||
|
||
</p><div class="example"><a name="connector-j-examples-retrieving-results-params"></a><p class="title"><b>Example 6.7 Connector/J: Retrieving results and output parameter values</b></p><div class="example-contents"><pre class="programlisting">
|
||
...
|
||
|
||
boolean hadResults = cStmt.execute();
|
||
|
||
//
|
||
// Process all returned result sets
|
||
//
|
||
|
||
while (hadResults) {
|
||
ResultSet rs = cStmt.getResultSet();
|
||
|
||
// process result set
|
||
...
|
||
|
||
hadResults = cStmt.getMoreResults();
|
||
}
|
||
|
||
//
|
||
// Retrieve output parameters
|
||
//
|
||
// Connector/J supports both index-based and
|
||
// name-based retrieval
|
||
//
|
||
|
||
int outputValue = cStmt.getInt(2); // index-based
|
||
|
||
outputValue = cStmt.getInt("inOutParam"); // name-based
|
||
|
||
...
|
||
</pre></div></div><p><br class="example-break">
|
||
</p></li></ol></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-last-insert-id"></a>6.4 Retrieving <code class="literal">AUTO_INCREMENT</code> Column Values through JDBC</h2></div></div></div><p>
|
||
Before version 3.0 of the JDBC API, there was no standard way of
|
||
retrieving key values from databases that supported auto
|
||
increment or identity columns. With older JDBC drivers for
|
||
MySQL, you could always use a MySQL-specific method on the
|
||
<code class="classname">Statement</code> interface, or issue the query
|
||
<code class="literal">SELECT LAST_INSERT_ID()</code> after issuing an
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/insert.html" target="_top"><code class="literal">INSERT</code></a> to a table that had an
|
||
<code class="literal">AUTO_INCREMENT</code> key. Using the MySQL-specific
|
||
method call isn't portable, and issuing a
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/select.html" target="_top"><code class="literal">SELECT</code></a> to get the
|
||
<code class="literal">AUTO_INCREMENT</code> key's value requires another
|
||
round-trip to the database, which isn't as efficient as
|
||
possible. The following code snippets demonstrate the three
|
||
different ways to retrieve <code class="literal">AUTO_INCREMENT</code>
|
||
values. First, we demonstrate the use of the new JDBC 3.0 method
|
||
<code class="function">getGeneratedKeys()</code> which is now the
|
||
preferred method to use if you need to retrieve
|
||
<code class="literal">AUTO_INCREMENT</code> keys and have access to JDBC
|
||
3.0. The second example shows how you can retrieve the same
|
||
value using a standard <code class="literal">SELECT
|
||
LAST_INSERT_ID()</code> query. The final example shows how
|
||
updatable result sets can retrieve the
|
||
<code class="literal">AUTO_INCREMENT</code> value when using the
|
||
<code class="function">insertRow()</code> method.
|
||
</p><div class="example"><a name="connector-j-examples-autoincrement-getgeneratedkeys"></a><p class="title"><b>Example 6.8 Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
|
||
using <code class="literal">Statement.getGeneratedKeys()</code></b></p><div class="example-contents"><pre class="programlisting">
|
||
Statement stmt = null;
|
||
ResultSet rs = null;
|
||
|
||
try {
|
||
|
||
//
|
||
// Create a Statement instance that we can use for
|
||
// 'normal' result sets assuming you have a
|
||
// Connection 'conn' to a MySQL database already
|
||
// available
|
||
|
||
stmt = conn.createStatement();
|
||
|
||
//
|
||
// Issue the DDL queries for the table for this example
|
||
//
|
||
|
||
stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
|
||
stmt.executeUpdate(
|
||
"CREATE TABLE autoIncTutorial ("
|
||
+ "priKey INT NOT NULL AUTO_INCREMENT, "
|
||
+ "dataField VARCHAR(64), PRIMARY KEY (priKey))");
|
||
|
||
//
|
||
// Insert one row that will generate an AUTO INCREMENT
|
||
// key in the 'priKey' field
|
||
//
|
||
|
||
stmt.executeUpdate(
|
||
"INSERT INTO autoIncTutorial (dataField) "
|
||
+ "values ('Can I Get the Auto Increment Field?')",
|
||
Statement.RETURN_GENERATED_KEYS);
|
||
|
||
//
|
||
// Example of using Statement.getGeneratedKeys()
|
||
// to retrieve the value of an auto-increment
|
||
// value
|
||
//
|
||
|
||
int autoIncKeyFromApi = -1;
|
||
|
||
rs = stmt.getGeneratedKeys();
|
||
|
||
if (rs.next()) {
|
||
autoIncKeyFromApi = rs.getInt(1);
|
||
} else {
|
||
|
||
// throw an exception from here
|
||
}
|
||
|
||
System.out.println("Key returned from getGeneratedKeys():"
|
||
+ autoIncKeyFromApi);
|
||
} finally {
|
||
|
||
if (rs != null) {
|
||
try {
|
||
rs.close();
|
||
} catch (SQLException ex) {
|
||
// ignore
|
||
}
|
||
}
|
||
|
||
if (stmt != null) {
|
||
try {
|
||
stmt.close();
|
||
} catch (SQLException ex) {
|
||
// ignore
|
||
}
|
||
}
|
||
}
|
||
</pre></div></div><br class="example-break"><div class="example"><a name="connector-j-examples-autoincrement-select"></a><p class="title"><b>Example 6.9 Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
|
||
using <code class="literal">SELECT LAST_INSERT_ID()</code></b></p><div class="example-contents"><pre class="programlisting">
|
||
Statement stmt = null;
|
||
ResultSet rs = null;
|
||
|
||
try {
|
||
|
||
//
|
||
// Create a Statement instance that we can use for
|
||
// 'normal' result sets.
|
||
|
||
stmt = conn.createStatement();
|
||
|
||
//
|
||
// Issue the DDL queries for the table for this example
|
||
//
|
||
|
||
stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
|
||
stmt.executeUpdate(
|
||
"CREATE TABLE autoIncTutorial ("
|
||
+ "priKey INT NOT NULL AUTO_INCREMENT, "
|
||
+ "dataField VARCHAR(64), PRIMARY KEY (priKey))");
|
||
|
||
//
|
||
// Insert one row that will generate an AUTO INCREMENT
|
||
// key in the 'priKey' field
|
||
//
|
||
|
||
stmt.executeUpdate(
|
||
"INSERT INTO autoIncTutorial (dataField) "
|
||
+ "values ('Can I Get the Auto Increment Field?')");
|
||
|
||
//
|
||
// Use the MySQL LAST_INSERT_ID()
|
||
// function to do the same thing as getGeneratedKeys()
|
||
//
|
||
|
||
int autoIncKeyFromFunc = -1;
|
||
rs = stmt.executeQuery("SELECT LAST_INSERT_ID()");
|
||
|
||
if (rs.next()) {
|
||
autoIncKeyFromFunc = rs.getInt(1);
|
||
} else {
|
||
// throw an exception from here
|
||
}
|
||
|
||
System.out.println("Key returned from " +
|
||
"'SELECT LAST_INSERT_ID()': " +
|
||
autoIncKeyFromFunc);
|
||
|
||
} finally {
|
||
|
||
if (rs != null) {
|
||
try {
|
||
rs.close();
|
||
} catch (SQLException ex) {
|
||
// ignore
|
||
}
|
||
}
|
||
|
||
if (stmt != null) {
|
||
try {
|
||
stmt.close();
|
||
} catch (SQLException ex) {
|
||
// ignore
|
||
}
|
||
}
|
||
}
|
||
</pre></div></div><br class="example-break"><div class="example"><a name="connector-j-examples-autoincrement-updateable-resultsets"></a><p class="title"><b>Example 6.10 Connector/J: Retrieving <code class="literal">AUTO_INCREMENT</code> column values
|
||
in <code class="literal">Updatable ResultSets</code></b></p><div class="example-contents"><pre class="programlisting">
|
||
Statement stmt = null;
|
||
ResultSet rs = null;
|
||
|
||
try {
|
||
|
||
//
|
||
// Create a Statement instance that we can use for
|
||
// 'normal' result sets as well as an 'updatable'
|
||
// one, assuming you have a Connection 'conn' to
|
||
// a MySQL database already available
|
||
//
|
||
|
||
stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
|
||
java.sql.ResultSet.CONCUR_UPDATABLE);
|
||
|
||
//
|
||
// Issue the DDL queries for the table for this example
|
||
//
|
||
|
||
stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
|
||
stmt.executeUpdate(
|
||
"CREATE TABLE autoIncTutorial ("
|
||
+ "priKey INT NOT NULL AUTO_INCREMENT, "
|
||
+ "dataField VARCHAR(64), PRIMARY KEY (priKey))");
|
||
|
||
//
|
||
// Example of retrieving an AUTO INCREMENT key
|
||
// from an updatable result set
|
||
//
|
||
|
||
rs = stmt.executeQuery("SELECT priKey, dataField "
|
||
+ "FROM autoIncTutorial");
|
||
|
||
rs.moveToInsertRow();
|
||
|
||
rs.updateString("dataField", "AUTO INCREMENT here?");
|
||
rs.insertRow();
|
||
|
||
//
|
||
// the driver adds rows at the end
|
||
//
|
||
|
||
rs.last();
|
||
|
||
//
|
||
// We should now be on the row we just inserted
|
||
//
|
||
|
||
int autoIncKeyFromRS = rs.getInt("priKey");
|
||
|
||
System.out.println("Key returned for inserted row: "
|
||
+ autoIncKeyFromRS);
|
||
|
||
} finally {
|
||
|
||
if (rs != null) {
|
||
try {
|
||
rs.close();
|
||
} catch (SQLException ex) {
|
||
// ignore
|
||
}
|
||
}
|
||
|
||
if (stmt != null) {
|
||
try {
|
||
stmt.close();
|
||
} catch (SQLException ex) {
|
||
// ignore
|
||
}
|
||
}
|
||
}
|
||
</pre></div></div><br class="example-break"><p>
|
||
Running the preceding example code should produce the following
|
||
output:
|
||
</p><pre class="programlisting">
|
||
Key returned from getGeneratedKeys(): 1
|
||
Key returned from SELECT LAST_INSERT_ID(): 1
|
||
Key returned for inserted row: 1
|
||
</pre><p>
|
||
At times, it can be tricky to use the <code class="literal">SELECT
|
||
LAST_INSERT_ID()</code> query, as that function's value is
|
||
scoped to a connection. So, if some other query happens on the
|
||
same connection, the value is overwritten. On the other hand,
|
||
the <code class="function">getGeneratedKeys()</code> method is scoped by
|
||
the <code class="classname">Statement</code> instance, so it can be used
|
||
even if other queries happen on the same connection, but not on
|
||
the same <code class="classname">Statement</code> instance.
|
||
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-j2ee-concepts-connection-pooling"></a>Chapter 7 Connection Pooling with Connector/J</h1></div></div></div><a class="indexterm" name="idm140266685820560"></a><a class="indexterm" name="idm140266685819168"></a><p>
|
||
Connection pooling is a technique of creating and managing a pool
|
||
of connections that are ready for use by any
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/glossary.html#glos_thread" target="_top">thread</a> that needs them.
|
||
Connection pooling can greatly increase the performance of your
|
||
Java application, while reducing overall resource usage.
|
||
</p><h2><a name="idm140266685816832"></a>How Connection Pooling Works</h2><p>
|
||
Most applications only need a thread to have access to a JDBC
|
||
connection when they are actively processing a
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/glossary.html#glos_transaction" target="_top">transaction</a>, which often
|
||
takes only milliseconds to complete. When not processing a
|
||
transaction, the connection sits idle. Connection pooling enables
|
||
the idle connection to be used by some other thread to do useful
|
||
work.
|
||
</p><p>
|
||
In practice, when a thread needs to do work against a MySQL or
|
||
other database with JDBC, it requests a connection from the pool.
|
||
When the thread is finished using the connection, it returns it to
|
||
the pool, so that it can be used by any other threads.
|
||
</p><p>
|
||
When the connection is loaned out from the pool, it is used
|
||
exclusively by the thread that requested it. From a programming
|
||
point of view, it is the same as if your thread called
|
||
<code class="literal">DriverManager.getConnection()</code> every time it
|
||
needed a JDBC connection. With connection pooling, your thread may
|
||
end up using either a new connection or an already-existing
|
||
connection.
|
||
</p><h2><a name="idm140266685812608"></a>Benefits of Connection Pooling</h2><p>
|
||
The main benefits to connection pooling are:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
Reduced connection creation time.
|
||
</p><p>
|
||
Although this is not usually an issue with the quick
|
||
connection setup that MySQL offers compared to other
|
||
databases, creating new JDBC connections still incurs
|
||
networking and JDBC driver overhead that will be avoided if
|
||
connections are recycled.
|
||
</p></li><li class="listitem"><p>
|
||
Simplified programming model.
|
||
</p><p>
|
||
When using connection pooling, each individual thread can act
|
||
as though it has created its own JDBC connection, allowing you
|
||
to use straightforward JDBC programming techniques.
|
||
</p></li><li class="listitem"><p>
|
||
Controlled resource usage.
|
||
</p><p>
|
||
If you create a new connection every time a thread needs one
|
||
rather than using connection pooling, your application's
|
||
resource usage can be wasteful, and it could lead to
|
||
unpredictable behaviors for your application when it is under
|
||
a heavy load.
|
||
</p></li></ul></div><h2><a name="idm140266685806800"></a>Using Connection Pooling with Connector/J</h2><p>
|
||
The concept of connection pooling in JDBC has been standardized
|
||
through the JDBC 2.0 Optional interfaces, and all major
|
||
application servers have implementations of these APIs that work
|
||
with MySQL Connector/J.
|
||
</p><p>
|
||
Generally, you configure a connection pool in your application
|
||
server configuration files, and access it through the Java Naming
|
||
and Directory Interface (JNDI). The following code shows how you
|
||
might use a connection pool from an application deployed in a J2EE
|
||
application server:
|
||
|
||
</p><div class="example"><a name="connector-j-examples-connectionpool-j2ee"></a><p class="title"><b>Example 7.1 Connector/J: Using a connection pool with a J2EE application server</b></p><div class="example-contents"><pre class="programlisting">
|
||
import java.sql.Connection;
|
||
import java.sql.SQLException;
|
||
import java.sql.Statement;
|
||
|
||
import javax.naming.InitialContext;
|
||
import javax.sql.DataSource;
|
||
|
||
|
||
public class MyServletJspOrEjb {
|
||
|
||
public void doSomething() throws Exception {
|
||
/*
|
||
* Create a JNDI Initial context to be able to
|
||
* lookup the DataSource
|
||
*
|
||
* In production-level code, this should be cached as
|
||
* an instance or static variable, as it can
|
||
* be quite expensive to create a JNDI context.
|
||
*
|
||
* Note: This code only works when you are using servlets
|
||
* or EJBs in a J2EE application server. If you are
|
||
* using connection pooling in standalone Java code, you
|
||
* will have to create/configure datasources using whatever
|
||
* mechanisms your particular connection pooling library
|
||
* provides.
|
||
*/
|
||
|
||
InitialContext ctx = new InitialContext();
|
||
|
||
/*
|
||
* Lookup the DataSource, which will be backed by a pool
|
||
* that the application server provides. DataSource instances
|
||
* are also a good candidate for caching as an instance
|
||
* variable, as JNDI lookups can be expensive as well.
|
||
*/
|
||
|
||
DataSource ds =
|
||
(DataSource)ctx.lookup("java:comp/env/jdbc/MySQLDB");
|
||
|
||
/*
|
||
* The following code is what would actually be in your
|
||
* Servlet, JSP or EJB 'service' method...where you need
|
||
* to work with a JDBC connection.
|
||
*/
|
||
|
||
Connection conn = null;
|
||
Statement stmt = null;
|
||
|
||
try {
|
||
conn = ds.getConnection();
|
||
|
||
/*
|
||
* Now, use normal JDBC programming to work with
|
||
* MySQL, making sure to close each resource when you're
|
||
* finished with it, which permits the connection pool
|
||
* resources to be recovered as quickly as possible
|
||
*/
|
||
|
||
stmt = conn.createStatement();
|
||
stmt.execute("SOME SQL QUERY");
|
||
|
||
stmt.close();
|
||
stmt = null;
|
||
|
||
conn.close();
|
||
conn = null;
|
||
} finally {
|
||
/*
|
||
* close any jdbc instances here that weren't
|
||
* explicitly closed during normal code path, so
|
||
* that we don't 'leak' resources...
|
||
*/
|
||
|
||
if (stmt != null) {
|
||
try {
|
||
stmt.close();
|
||
} catch (sqlexception sqlex) {
|
||
// ignore, as we can't do anything about it here
|
||
}
|
||
|
||
stmt = null;
|
||
}
|
||
|
||
if (conn != null) {
|
||
try {
|
||
conn.close();
|
||
} catch (sqlexception sqlex) {
|
||
// ignore, as we can't do anything about it here
|
||
}
|
||
|
||
conn = null;
|
||
}
|
||
}
|
||
}
|
||
}
|
||
</pre></div></div><p><br class="example-break">
|
||
|
||
As shown in the example above, after obtaining the JNDI
|
||
<code class="literal">InitialContext</code>, and looking up the
|
||
<code class="literal">DataSource</code>, the rest of the code follows
|
||
familiar JDBC conventions.
|
||
</p><p>
|
||
When using connection pooling, always make sure that connections,
|
||
and anything created by them (such as statements or result sets)
|
||
are closed. This rule applies no matter what happens in your code
|
||
(exceptions, flow-of-control, and so forth). When these objects
|
||
are closed, they can be re-used; otherwise, they will be stranded,
|
||
which means that the MySQL server resources they represent (such
|
||
as buffers, locks, or sockets) are tied up for some time, or in
|
||
the worst case can be tied up forever.
|
||
</p><h2><a name="idm140266685794960"></a>Sizing the Connection Pool</h2><p>
|
||
Each connection to MySQL has overhead (memory, CPU, context
|
||
switches, and so forth) on both the client and server side. Every
|
||
connection limits how many resources there are available to your
|
||
application as well as the MySQL server. Many of these resources
|
||
will be used whether or not the connection is actually doing any
|
||
useful work! Connection pools can be tuned to maximize
|
||
performance, while keeping resource utilization below the point
|
||
where your application will start to fail rather than just run
|
||
slower.
|
||
</p><p>
|
||
The optimal size for the connection pool depends on anticipated
|
||
load and average database transaction time. In practice, the
|
||
optimal connection pool size can be smaller than you might expect.
|
||
If you take Oracle's Java Petstore blueprint application for
|
||
example, a connection pool of 15-20 connections can serve a
|
||
relatively moderate load (600 concurrent users) using MySQL and
|
||
Tomcat with acceptable response times.
|
||
</p><p>
|
||
To correctly size a connection pool for your application, create
|
||
load test scripts with tools such as Apache JMeter or The Grinder,
|
||
and load test your application.
|
||
</p><p>
|
||
An easy way to determine a starting point is to configure your
|
||
connection pool's maximum number of connections to be unbounded,
|
||
run a load test, and measure the largest amount of concurrently
|
||
used connections. You can then work backward from there to
|
||
determine what values of minimum and maximum pooled connections
|
||
give the best performance for your particular application.
|
||
</p><h2><a name="idm140266685791088"></a>Validating Connections</h2><p>
|
||
MySQL Connector/J can validate the connection by executing a
|
||
lightweight ping against a server. In the case of load-balanced
|
||
connections, this is performed against all active pooled internal
|
||
connections that are retained. This is beneficial to Java
|
||
applications using connection pools, as the pool can use this
|
||
feature to validate connections. Depending on your connection pool
|
||
and configuration, this validation can be carried out at different
|
||
times:
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
Before the pool returns a connection to the application.
|
||
</p></li><li class="listitem"><p>
|
||
When the application returns a connection to the pool.
|
||
</p></li><li class="listitem"><p>
|
||
During periodic checks of idle connections.
|
||
</p></li></ol></div><p>
|
||
To use this feature, specify a validation query in your connection
|
||
pool that starts with <code class="literal">/* ping */</code>. Note that the
|
||
syntax must be exactly as specified. This will cause the driver
|
||
send a ping to the server and return a dummy lightweight result
|
||
set. When using a <code class="literal">ReplicationConnection</code> or
|
||
<code class="literal">LoadBalancedConnection</code>, the ping will be sent
|
||
across all active connections.
|
||
</p><p>
|
||
It is critical that the syntax be specified correctly. The syntax
|
||
needs to be exact for reasons of efficiency, as this test is done
|
||
for every statement that is executed:
|
||
</p><pre class="programlisting">
|
||
|
||
protected static final String PING_MARKER = "/* ping */";
|
||
...
|
||
if (sql.charAt(0) == '/') {
|
||
if (sql.startsWith(PING_MARKER)) {
|
||
doPingInstead();
|
||
...
|
||
|
||
</pre><p>
|
||
None of the following snippets will work, because the ping syntax
|
||
is sensitive to whitespace, capitalization, and placement:
|
||
</p><pre class="programlisting">
|
||
sql = "/* PING */ SELECT 1";
|
||
sql = "SELECT 1 /* ping*/";
|
||
sql = "/*ping*/ SELECT 1";
|
||
sql = " /* ping */ SELECT 1";
|
||
sql = "/*to ping or not to ping*/ SELECT 1";
|
||
</pre><p>
|
||
All of the previous statements will issue a normal
|
||
<code class="literal">SELECT</code> statement and will
|
||
<span class="bold"><strong>not</strong></span> be transformed into the
|
||
lightweight ping. Further, for load-balanced connections, the
|
||
statement will be executed against one connection in the internal
|
||
pool, rather than validating each underlying physical connection.
|
||
This results in the non-active physical connections assuming a
|
||
stale state, and they may die. If Connector/J then re-balances, it
|
||
might select a dead connection, resulting in an exception being
|
||
passed to the application. To help prevent this, you can use
|
||
<code class="literal">loadBalanceValidateConnectionOnSwapServer</code> to
|
||
validate the connection before use.
|
||
</p><p>
|
||
If your Connector/J deployment uses a connection pool that allows
|
||
you to specify a validation query, take advantage of it, but
|
||
ensure that the query starts <span class="emphasis"><em>exactly</em></span> with
|
||
<code class="literal">/* ping */</code>. This is particularly important if
|
||
you are using the load-balancing or replication-aware features of
|
||
Connector/J, as it will help keep alive connections which
|
||
otherwise will go stale and die, causing problems later.
|
||
</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-multi-host-connections"></a>Chapter 8 Multi-Host Connections</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-config-failover">8.1 Configuring Server Failover</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections">8.2 Configuring Load Balancing with Connector/J</a></span></dt><dt><span class="section"><a href="#connector-j-master-slave-replication-connection">8.3 Configuring Master/Slave Replication with Connector/J</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-j2ee-concepts-load-balancing-failover">8.4 Advanced Load-balancing and Failover Configuration</a></span></dt></dl></div><a class="indexterm" name="idm140266685775024"></a><p>
|
||
The following sections discuss a number of topics that involve
|
||
multi-host connections, namely, server load-balancing, failover,
|
||
and replication.
|
||
</p><p>
|
||
Developers should know the following things about multi-host
|
||
connections that are managed through Connector/J:
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
Each multi-host connection is a wrapper of the underlying
|
||
physical connections.
|
||
</p></li><li class="listitem"><p>
|
||
Each of the underlying physical connections has its own
|
||
session. Sessions cannot be tracked, shared, or copied,
|
||
given the MySQL architecture.
|
||
</p></li><li class="listitem"><p>
|
||
Every switch between physical connections means a switch
|
||
between sessions.
|
||
</p></li><li class="listitem"><p>
|
||
Within a transaction boundary, there are no switches between
|
||
physical connections. Beyond a transaction boundary, there
|
||
is no guarantee that a switch does not occur.
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
|
||
If an application reuses session-scope data (for example,
|
||
variables, SSPs) beyond a transaction boundary, failures
|
||
are possible, as a switch between the physical connections
|
||
(which is also a switch between sessions) might occur.
|
||
Therefore, the application should re-prepare the session
|
||
data and also restart the last transaction in case of an
|
||
exception, or it should re-prepare session data for each
|
||
new transaction if it does not want to deal with exception
|
||
handling.
|
||
</p></div></li></ul></div><p>
|
||
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-config-failover"></a>8.1 Configuring Server Failover</h2></div></div></div><a class="indexterm" name="idm140266685766112"></a><p>
|
||
MySQL Connector/J supports server failover. A failover happens
|
||
when connection-related errors occur for an underlying, active
|
||
connection. The connection errors are, by default, propagated to
|
||
the client, which has to handle them by, for example, recreating
|
||
the working objects (<code class="literal">Statement</code>,
|
||
<code class="literal">ResultSet</code>, etc.) and restarting the
|
||
processes. Sometimes, the driver might eventually fall back to
|
||
the original host automatically before the client application
|
||
continues to run, in which case the host switch is transparent
|
||
and the client application will not even notice it.
|
||
</p><p>
|
||
</p><p>
|
||
A connection using failover support works just like a standard
|
||
connection: the client does not experience any disruptions in
|
||
the failover process. This means the client can rely on the same
|
||
connection instance even if two successive statements might be
|
||
executed on two different physical hosts. However, this does not
|
||
mean the client does not have to deal with the exception that
|
||
triggered the server switch.
|
||
</p><p>
|
||
The failover is configured at the initial setup stage of the
|
||
server connection by the connection URL (see explanations for
|
||
its format
|
||
<a class="link" href="#connector-j-reference-url-format" title="JDBC URL Format">here</a>):
|
||
|
||
</p><pre class="programlisting">
|
||
jdbc:mysql://[<em class="replaceable"><code>primary host</code></em>][:<em class="replaceable"><code>port</code></em>],[<em class="replaceable"><code>secondary host 1</code></em>][:<em class="replaceable"><code>port</code></em>][,[<em class="replaceable"><code>secondary host 2</code></em>][:<em class="replaceable"><code>port</code></em>]]...[/[<em class="replaceable"><code>database</code></em>]]»
|
||
[?<em class="replaceable"><code>propertyName1</code></em>=<em class="replaceable"><code>propertyValue1</code></em>[&<em class="replaceable"><code>propertyName2</code></em>=<em class="replaceable"><code>propertyValue2</code></em>]...]
|
||
</pre><p>
|
||
</p><p>
|
||
The host list in the connection URL comprises of two types of
|
||
hosts, the primary and the secondary. When starting a new
|
||
connection, the driver always tries to connect to the primary
|
||
host first and, if required, fails over to the secondary hosts
|
||
on the list sequentially when communication problems are
|
||
experienced. Even if the initial connection to the primary host
|
||
fails and the driver gets connected to a secondary host, the
|
||
primary host never loses its special status: for example, it can
|
||
be configured with an access mode distinct from those of the
|
||
secondary hosts, and it can be put on a higher priority when a
|
||
host is to be picked during a failover process.
|
||
</p><p>
|
||
The failover support is configured by the following connection
|
||
properties (their functions are explained in the paragraphs
|
||
below):
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="literal">failOverReadOnly</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">secondsBeforeRetryMaster</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">queriesBeforeRetryMaster</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">retriesAllDown</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">autoReconnect</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">autoReconnectForPools</code>
|
||
</p></li></ul></div><p>
|
||
</p><h3><a name="idm140266685744688"></a>Configuring Connection Access Mode</h3><p>
|
||
As with any standard connection, the initial connection to the
|
||
primary host is in read/write mode. However, if the driver fails
|
||
to establish the initial connection to the primary host and it
|
||
automatically switches to the next host on the list, the access
|
||
mode now depends on the value of the property
|
||
<code class="literal">failOverReadOnly</code>, which is
|
||
<span class="quote">“<span class="quote">true</span>”</span> by default. The same happens if the driver
|
||
is initially connected to the primary host and, because of some
|
||
connection failure, it fails over to a secondary host. Every
|
||
time the connection falls back to the primary host, its access
|
||
mode will be read/write, irrespective of whether or not the
|
||
primary host has been connected to before. The connection access
|
||
mode can be changed any time at runtime by calling the
|
||
method<code class="literal"> Connection.setReadOnly(boolean)</code>, which
|
||
partially overrides the property
|
||
<code class="literal">failOverReadOnly</code>. When
|
||
<code class="literal">failOverReadOnly=false</code> and the access mode is
|
||
explicitly set to either true or false, it becomes the mode for
|
||
every connection after a host switch, no matter what host type
|
||
are we connected to; but, if
|
||
<code class="literal">failOverReadOnly=true</code>, changing the access
|
||
mode to read/write is only possible if the driver is connecting
|
||
to the primary host; however, even if the access mode cannot be
|
||
changed for the current connection, the driver remembers the
|
||
client's last intention and, when falling back to the primary
|
||
host, that is the mode that will be used. For an illustration,
|
||
see the following successions of events with a two-host
|
||
connection.
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
Sequence A, with <code class="literal">failOverReadOnly=true</code>:
|
||
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
Connects to primary host in read/write mode
|
||
</p></li><li class="listitem"><p>
|
||
Sets
|
||
<code class="literal">Connection.setReadOnly(true)</code>;
|
||
primary host now in read-only mode
|
||
</p></li><li class="listitem"><p>
|
||
Failover event; connects to secondary host in
|
||
read-only mode
|
||
</p></li><li class="listitem"><p>
|
||
Sets
|
||
<code class="literal">Connection.setReadOnly(false)</code>;
|
||
secondary host remains in read-only mode
|
||
</p></li><li class="listitem"><p>
|
||
Falls back to primary host; connection now in
|
||
read/write mode
|
||
</p></li></ol></div><p>
|
||
</p></li><li class="listitem"><p>
|
||
Sequence B, with <code class="literal">failOverReadOnly=false</code>
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
Connects to primary host in read/write mode
|
||
</p></li><li class="listitem"><p>
|
||
Sets <code class="literal">Connection.setReadOnly(true)</code>;
|
||
primary host now in read-only mode
|
||
</p></li><li class="listitem"><p>
|
||
Failover event; connects to secondary host in
|
||
read-only mode
|
||
</p></li><li class="listitem"><p>
|
||
Set <code class="literal">Connection.setReadOnly(false)</code>;
|
||
connection to secondary host switches to read/write
|
||
mode
|
||
</p></li><li class="listitem"><p>
|
||
Falls back to primary host; connection now in
|
||
read/write mode
|
||
</p></li></ol></div></li></ul></div><p>
|
||
</p><p>
|
||
The difference between the two scenarios is in step 4: the
|
||
access mode for the secondary host in sequence A does not change
|
||
at that step, but the driver remembers and uses the set mode
|
||
when falling back to the primary host, which would be read-only
|
||
otherwise; but in sequence B, the access mode for the secondary
|
||
host changes immediately.
|
||
</p><h3><a name="idm140266685721520"></a>Configuring Fallback to Primary Host</h3><p>
|
||
As already mentioned, the primary host is special in the
|
||
failover arrangement when it comes to the host's access mode.
|
||
Additionally, the driver tries to fall back to the primary host
|
||
as soon as possible by default, even if no communication
|
||
exception occurs. Two properties,
|
||
<code class="literal">secondsBeforeRetryMaster</code> and
|
||
<code class="literal">queriesBeforeRetryMaster</code>, determine when the
|
||
driver is ready to retry a reconnection to the primary host (the
|
||
<code class="literal">Master</code> in the property names stands for the
|
||
primary host of our connection URL, which is not necessarily a
|
||
master host in a replication setup; the naming was maintained
|
||
for back compatibility with Connector/J versions prior to
|
||
5.1.35):
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="literal">secondsBeforeRetryMaster</code> determines how
|
||
much time the driver waits before trying to fall back to
|
||
the primary host
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">queriesBeforeRetryMaster</code> determines the
|
||
number of queries that are executed before the driver
|
||
tries to fall back to the primary host. Note that for the
|
||
driver, each call to a
|
||
<code class="literal">Statement.execute*()</code> method increments
|
||
the query execution counter; therefore, when calls are
|
||
made to <code class="literal">Statement.executeBatch()</code> or if
|
||
<code class="literal">allowMultiQueries</code> or
|
||
<code class="literal">rewriteBatchStatements</code> are enabled, the
|
||
driver may not have an accurate count of the actual number
|
||
of queries executed on the server. Also, the driver calls
|
||
the <code class="literal">Statement.execute*()</code> methods
|
||
internally in several occasions. All these mean you can
|
||
only use <code class="literal">queriesBeforeRetryMaster</code> only
|
||
as a coarse specification for when to fall back to the
|
||
primary host.
|
||
</p></li></ul></div><p>
|
||
|
||
In general, an attempt to fallback to the primary host is made
|
||
when at least one of the conditions specified by the two
|
||
properties is met, and the attempt always takes place at
|
||
transaction boundaries. However, if auto-commit is turned off,
|
||
the check happens only when the method
|
||
<code class="literal">Connection.commit()</code> or
|
||
<code class="literal">Connection.rollback()</code> is called. The
|
||
automatic fallback to the primary host can be turned off by
|
||
setting simultaneously
|
||
<code class="literal">secondsBeforeRetryMaster</code> and
|
||
<code class="literal">queriesBeforeRetryMaster</code> to <span class="quote">“<span class="quote">0</span>”</span>.
|
||
Setting only one of the properties to <span class="quote">“<span class="quote">0</span>”</span> only
|
||
disables one part of the check.
|
||
</p><h3><a name="connector-j-config-reconnect"></a>Configuring Reconnection Attempts</h3><p>
|
||
When establishing a new connection or when a failover event
|
||
occurs, the driver tries to connect successively to the next
|
||
candidate on the host list. When the end of the list has been
|
||
reached, it restarts all over again from the beginning of the
|
||
list; however, the primary host is skipped over, if (a) NOT all
|
||
the secondary hosts have already been tested at least once, AND
|
||
(b) the fallback conditions defined by
|
||
<code class="literal">secondsBeforeRetryMaster</code> and
|
||
<code class="literal">queriesBeforeRetryMaster</code> are not yet
|
||
fulfilled. Each run-through of the whole host list, (which is
|
||
not necessarily completed at the end of the host list) counts as
|
||
a single connection attempt. The driver tries as many connection
|
||
attempts as specified by the value of the property
|
||
<code class="literal">retriesAllDown</code>.
|
||
</p><h3><a name="idm140266685702368"></a>Seamless Reconnection</h3><p>
|
||
Although not recommended, you can make the driver perform
|
||
failovers without invalidating the active
|
||
<code class="literal">Statement</code> or <code class="literal">ResultSet</code>
|
||
instances by setting either the parameter
|
||
<code class="literal">autoReconnect</code> or
|
||
<code class="literal">autoReconnectForPools</code> to
|
||
<code class="literal">true</code>. This allows the client to continue
|
||
using the same object instances after a failover event, without
|
||
taking any exceptional measures. This, however, may lead to
|
||
unexpected results: for example, if the driver is connected to
|
||
the primary host with read/write access mode and it fails-over
|
||
to a secondary host in real-only mode, further attempts to issue
|
||
data-changing queries will result in errors, and the client will
|
||
not be aware of that. This limitation is particularly relevant
|
||
when using data streaming: after the failover, the
|
||
<code class="literal">ResultSet</code> looks to be alright, but the
|
||
underlying connection may have changed already, and no backing
|
||
cursor is available anymore.
|
||
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections"></a>8.2 Configuring Load Balancing with Connector/J</h2></div></div></div><a class="indexterm" name="idm140266685695360"></a><a class="indexterm" name="idm140266685693968"></a><p>
|
||
Connector/J has long provided an effective means to distribute
|
||
read/write load across multiple MySQL server instances for
|
||
Cluster or master-master replication deployments. Starting with
|
||
Connector/J 5.1.3, you can now dynamically configure
|
||
load-balanced connections, with no service outage. In-process
|
||
transactions are not lost, and no application exceptions are
|
||
generated if any application is trying to use that particular
|
||
server instance.
|
||
</p><p>
|
||
The load balancing is configured at the initial setup stage of
|
||
the server connection by the following connection URL, which has
|
||
a similar format as
|
||
<a class="link" href="#connector-j-reference-url-format" title="JDBC URL Format">the general URL
|
||
for MySQL connection</a>, but a specialized scheme:
|
||
|
||
</p><pre class="programlisting">
|
||
jdbc:mysql:loadbalance://[<em class="replaceable"><code>host</code></em>1][:<em class="replaceable"><code>port</code></em>],[<em class="replaceable"><code>host</code></em>2][:<em class="replaceable"><code>port</code></em>][,[<em class="replaceable"><code>host</code></em>3][:<em class="replaceable"><code>port</code></em>]]...[/[<em class="replaceable"><code>database</code></em>]] »
|
||
[?<em class="replaceable"><code>propertyName1</code></em>=<em class="replaceable"><code>propertyValue1</code></em>[&<em class="replaceable"><code>propertyName2</code></em>=<em class="replaceable"><code>propertyValue2</code></em>]...]
|
||
</pre><p>
|
||
</p><p>
|
||
There are two configuration properties associated with this
|
||
functionality:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="literal">loadBalanceConnectionGroup</code> – This
|
||
provides the ability to group connections from different
|
||
sources. This allows you to manage these JDBC sources within
|
||
a single class loader in any combination you choose. If they
|
||
use the same configuration, and you want to manage them as a
|
||
logical single group, give them the same name. This is the
|
||
key property for management: if you do not define a name
|
||
(string) for <code class="literal">loadBalanceConnectionGroup</code>,
|
||
you cannot manage the connections. All load-balanced
|
||
connections sharing the same
|
||
<code class="literal">loadBalanceConnectionGroup</code> value,
|
||
regardless of how the application creates them, will be
|
||
managed together.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">loadBalanceEnableJMX</code> – The ability to
|
||
manage the connections is exposed when you define a
|
||
<code class="literal">loadBalanceConnectionGroup</code>; but if you
|
||
want to manage this externally, enable JMX by setting this
|
||
property to <code class="literal">true</code>. This enables a JMX
|
||
implementation, which exposes the management and monitoring
|
||
operations of a connection group. Further, start your
|
||
application with the
|
||
<code class="literal">-Dcom.sun.management.jmxremote</code> JVM flag.
|
||
You can then perform connect and perform operations using a
|
||
JMX client such as <code class="literal">jconsole</code>.
|
||
</p></li></ul></div><p>
|
||
Once a connection has been made using the correct connection
|
||
properties, a number of monitoring properties are available:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
Current active host count.
|
||
</p></li><li class="listitem"><p>
|
||
Current active physical connection count.
|
||
</p></li><li class="listitem"><p>
|
||
Current active logical connection count.
|
||
</p></li><li class="listitem"><p>
|
||
Total logical connections created.
|
||
</p></li><li class="listitem"><p>
|
||
Total transaction count.
|
||
</p></li></ul></div><p>
|
||
The following management operations can also be performed:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
Add host.
|
||
</p></li><li class="listitem"><p>
|
||
Remove host.
|
||
</p></li></ul></div><p>
|
||
The JMX interface,
|
||
<code class="literal">com.mysql.jdbc.jmx.LoadBalanceConnectionGroupManagerMBean</code>,
|
||
has the following methods:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="literal">int getActiveHostCount(String group);</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">int getTotalHostCount(String group);</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">long getTotalLogicalConnectionCount(String
|
||
group);</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">long getActiveLogicalConnectionCount(String
|
||
group);</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">long getActivePhysicalConnectionCount(String
|
||
group);</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">long getTotalPhysicalConnectionCount(String
|
||
group);</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">long getTotalTransactionCount(String
|
||
group);</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">void removeHost(String group, String host) throws
|
||
SQLException;</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">void stopNewConnectionsToHost(String group, String
|
||
host) throws SQLException;</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">void addHost(String group, String host, boolean
|
||
forExisting);</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">String getActiveHostsList(String group);</code>
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">String getRegisteredConnectionGroups();</code>
|
||
</p></li></ul></div><p>
|
||
The <code class="literal">getRegisteredConnectionGroups()</code> method
|
||
returns the names of all connection groups defined in that class
|
||
loader.
|
||
</p><p>
|
||
You can test this setup with the following code:
|
||
</p><pre class="programlisting">
|
||
|
||
public class Test {
|
||
|
||
private static String URL = "jdbc:mysql:loadbalance://" +
|
||
"localhost:3306,localhost:3310/test?" +
|
||
"loadBalanceConnectionGroup=first&loadBalanceEnableJMX=true";
|
||
|
||
public static void main(String[] args) throws Exception {
|
||
new Thread(new Repeater()).start();
|
||
new Thread(new Repeater()).start();
|
||
new Thread(new Repeater()).start();
|
||
}
|
||
|
||
static Connection getNewConnection() throws SQLException, ClassNotFoundException {
|
||
Class.forName("com.mysql.jdbc.Driver");
|
||
return DriverManager.getConnection(URL, "root", "");
|
||
}
|
||
|
||
static void executeSimpleTransaction(Connection c, int conn, int trans){
|
||
try {
|
||
c.setAutoCommit(false);
|
||
Statement s = c.createStatement();
|
||
s.executeQuery("SELECT SLEEP(1) /* Connection: " + conn + ", transaction: " + trans + " */");
|
||
c.commit();
|
||
} catch (SQLException e) {
|
||
e.printStackTrace();
|
||
}
|
||
}
|
||
|
||
public static class Repeater implements Runnable {
|
||
public void run() {
|
||
for(int i=0; i < 100; i++){
|
||
try {
|
||
Connection c = getNewConnection();
|
||
for(int j=0; j < 10; j++){
|
||
executeSimpleTransaction(c, i, j);
|
||
Thread.sleep(Math.round(100 * Math.random()));
|
||
}
|
||
c.close();
|
||
Thread.sleep(100);
|
||
} catch (Exception e) {
|
||
e.printStackTrace();
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
</pre><p>
|
||
After compiling, the application can be started with the
|
||
<code class="literal">-Dcom.sun.management.jmxremote</code> flag, to
|
||
enable remote management. <code class="literal">jconsole</code> can then
|
||
be started. The <code class="literal">Test</code> main class will be
|
||
listed by <code class="literal">jconsole</code>. Select this and click
|
||
<span class="guibutton">Connect</span>. You can then navigate to the
|
||
<code class="literal">com.mysql.jdbc.jmx.LoadBalanceConnectionGroupManager</code>
|
||
bean. At this point, you can click on various operations and
|
||
examine the returned result.
|
||
</p><p>
|
||
If you now had an additional instance of MySQL running on port
|
||
3309, you could ensure that Connector/J starts using it by using
|
||
the <code class="literal">addHost()</code>, which is exposed in
|
||
<code class="literal">jconsole</code>. Note that these operations can be
|
||
performed dynamically without having to stop the application
|
||
running.
|
||
</p><p>
|
||
For further information on the combination of load balancing and
|
||
failover, see
|
||
<a class="xref" href="#connector-j-usagenotes-j2ee-concepts-load-balancing-failover" title="8.4 Advanced Load-balancing and Failover Configuration">Section 8.4, “Advanced Load-balancing and Failover Configuration”</a>.
|
||
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-master-slave-replication-connection"></a>8.3 Configuring Master/Slave Replication with Connector/J</h2></div></div></div><a class="indexterm" name="idm140266685636832"></a><a class="indexterm" name="idm140266685635440"></a><p>
|
||
This section describe a number of features of Connector/J's
|
||
support for replication-aware deployments.
|
||
|
||
|
||
</p><p>
|
||
The replication is configured at the initial setup stage of the
|
||
server connection by the connection URL, which has a similar
|
||
format as <a class="link" href="#connector-j-reference-url-format" title="JDBC URL Format">the
|
||
general URL for MySQL connection</a>, but a specialized
|
||
scheme:
|
||
|
||
</p><pre class="programlisting">
|
||
jdbc:mysql:replication://[<em class="replaceable"><code>master host</code></em>][:<em class="replaceable"><code>port</code></em>],[<em class="replaceable"><code>slave host 1</code></em>][:<em class="replaceable"><code>port</code></em>][,[<em class="replaceable"><code>slave host 2</code></em>][:<em class="replaceable"><code>port</code></em>]]...[/[<em class="replaceable"><code>database</code></em>]] »
|
||
[?<em class="replaceable"><code>propertyName1</code></em>=<em class="replaceable"><code>propertyValue1</code></em>[&<em class="replaceable"><code>propertyName2</code></em>=<em class="replaceable"><code>propertyValue2</code></em>]...]
|
||
</pre><p>
|
||
</p><p>
|
||
Users may specify the property<code class="literal">
|
||
allowMasterDownConnections=true</code> to allow
|
||
<code class="literal">Connection</code> objects to be created even though
|
||
no master hosts are reachable. Such
|
||
<code class="literal">Connection</code> objects report they are read-only,
|
||
and <code class="literal">isMasterConnection()</code> returns false for
|
||
them. The <code class="literal">Connection</code> tests for available
|
||
master hosts when
|
||
<code class="literal">Connection.setReadOnly(false)</code> is called,
|
||
throwing an SQLException if it cannot establish a connection to
|
||
a master, or switching to a master connection if the host is
|
||
available.
|
||
</p><p>
|
||
For Connector/J 5.1.38 and later, users may specify the
|
||
property<code class="literal"> allowSlavesDownConnections=true</code> to
|
||
allow <code class="literal">Connection</code> objects to be created even
|
||
though no slave hosts are reachable. A
|
||
<code class="literal">Connection</code> then, at runtime, tests for
|
||
available slave hosts when
|
||
<code class="literal">Connection.setReadOnly(true)</code> is called (see
|
||
explanation for the method below), throwing an SQLException if
|
||
it cannot establish a connection to a slave, unless the property
|
||
<code class="literal">readFromMasterWhenNoSlaves</code> is set
|
||
to be <span class="quote">“<span class="quote">true</span>”</span> (see below for a description of the
|
||
property).
|
||
</p><h3><a name="idm140266685617984"></a>Scaling out Read Load by Distributing Read Traffic to Slaves</h3><p>
|
||
Connector/J 3.1.7 and higher includes a variant of the driver
|
||
that will automatically send queries to a read/write master, or
|
||
a failover or round-robin loadbalanced set of slaves based on
|
||
the state of <code class="literal">Connection.getReadOnly()</code>.
|
||
</p><p>
|
||
An application signals that it wants a transaction to be
|
||
read-only by calling
|
||
<code class="literal">Connection.setReadOnly(true)</code>. The
|
||
replication-aware connection will use one of the slave
|
||
connections, which are load-balanced per slave host using a
|
||
round-robin scheme. A given connection is sticky to a slave
|
||
until a transaction boundary command (a commit or rollback) is
|
||
issued, or until the slave is removed from service. For
|
||
Connector/J 5.1.38 and later, after calling
|
||
<code class="literal">Connection.setReadOnly(true)</code>, if you want to
|
||
allow connection to a master when no slaves are available, set
|
||
the property
|
||
<code class="literal">readFromMasterWhenNoSlaves</code> to
|
||
<span class="quote">“<span class="quote">true.</span>”</span> Notice that the master host will be used in
|
||
read-only state in those cases, as if it is a slave host. Also
|
||
notice that setting
|
||
<code class="literal">readFromMasterWhenNoSlaves=true</code>
|
||
might result in an extra load for the master host in a
|
||
transparent manner.
|
||
</p><p>
|
||
If you have a write transaction, or if you have a read that is
|
||
time-sensitive (remember, replication in MySQL is asynchronous),
|
||
set the connection to be not read-only, by calling
|
||
<code class="literal">Connection.setReadOnly(false)</code> and the driver
|
||
will ensure that further calls are sent to the master MySQL
|
||
server. The driver takes care of propagating the current state
|
||
of autocommit, isolation level, and catalog between all of the
|
||
connections that it uses to accomplish this load balancing
|
||
functionality.
|
||
</p><p>
|
||
To enable this functionality, use the
|
||
<code class="literal">com.mysql.jdbc.ReplicationDriver</code> class when
|
||
configuring your application server's connection pool or when
|
||
creating an instance of a JDBC driver for your standalone
|
||
application. Because it accepts the same URL format as the
|
||
standard MySQL JDBC driver, <code class="literal">ReplicationDriver</code>
|
||
does not currently work with
|
||
<code class="literal">java.sql.DriverManager</code>-based connection
|
||
creation unless it is the only MySQL JDBC driver registered with
|
||
the <code class="literal">DriverManager</code> .
|
||
</p><p>
|
||
Here is a short example of how
|
||
<code class="literal">ReplicationDriver</code> might be used in a
|
||
standalone application:
|
||
</p><a name="connector-j-using-replication-driver-example"></a><pre class="programlisting">
|
||
import java.sql.Connection;
|
||
import java.sql.ResultSet;
|
||
import java.util.Properties;
|
||
|
||
import com.mysql.jdbc.ReplicationDriver;
|
||
|
||
public class ReplicationDriverDemo {
|
||
|
||
public static void main(String[] args) throws Exception {
|
||
ReplicationDriver driver = new ReplicationDriver();
|
||
|
||
Properties props = new Properties();
|
||
|
||
// We want this for failover on the slaves
|
||
props.put("autoReconnect", "true");
|
||
|
||
// We want to load balance between the slaves
|
||
props.put("roundRobinLoadBalance", "true");
|
||
|
||
props.put("user", "foo");
|
||
props.put("password", "bar");
|
||
|
||
//
|
||
// Looks like a normal MySQL JDBC url, with a
|
||
// comma-separated list of hosts, the first
|
||
// being the 'master', the rest being any number
|
||
// of slaves that the driver will load balance against
|
||
//
|
||
|
||
Connection conn =
|
||
driver.connect("jdbc:mysql:replication://master,slave1,slave2,slave3/test",
|
||
props);
|
||
|
||
//
|
||
// Perform read/write work on the master
|
||
// by setting the read-only flag to "false"
|
||
//
|
||
|
||
conn.setReadOnly(false);
|
||
conn.setAutoCommit(false);
|
||
conn.createStatement().executeUpdate("UPDATE some_table ....");
|
||
conn.commit();
|
||
|
||
//
|
||
// Now, do a query from a slave, the driver automatically picks one
|
||
// from the list
|
||
//
|
||
|
||
conn.setReadOnly(true);
|
||
|
||
ResultSet rs =
|
||
conn.createStatement().executeQuery("SELECT a,b FROM alt_table");
|
||
|
||
.......
|
||
}
|
||
}
|
||
</pre><p>
|
||
Consider using the Load Balancing JDBC Pool
|
||
(<span class="command"><strong>lbpool</strong></span>) tool, which provides a wrapper
|
||
around the standard JDBC driver and enables you to use DB
|
||
connection pools that includes checks for system failures and
|
||
uneven load distribution. For more information, see
|
||
<a class="ulink" href="http://code.google.com/p/mysql-lbpool/" target="_top">Load
|
||
Balancing JDBC Driver for MySQL (mysql-lbpool)</a>.
|
||
</p><h3><a name="connector-j-multiple-master-replication"></a>Support for Multiple-Master Replication Topographies</h3><p>
|
||
Since Connector/J 5.1.27, multi-master replication topographies
|
||
are supported.
|
||
</p><p>
|
||
The connection URL for replication discussed earlier (i.e., in
|
||
the format of
|
||
<code class="literal">jdbc:mysql:replication://master,slave1,slave2,slave3/test</code>)
|
||
assumes that the first (and only the first) host is the master.
|
||
Supporting deployments with an arbitrary number of masters and
|
||
slaves requires a different URL syntax for specifying the hosts
|
||
and the properties for specific hosts, which is just an
|
||
expansion of the URL syntax discussed in
|
||
<a class="xref" href="#connector-j-reference-ipv6-url" title="IPv6 Connections">IPv6 Connections</a> with the
|
||
property <code class="literal">type=[master|slave]</code>; for example:
|
||
|
||
</p><pre class="programlisting">jdbc:mysql://address=(type=master)(host=master1host),address=(type=master)(host=master2host),address=(type=slave)(host=slave1host)/database</pre><p>
|
||
</p><p>
|
||
Connector/J uses a load-balanced connection internally for
|
||
management of the master connections, which means that
|
||
<code class="literal">ReplicationConnection</code>, when configured to use
|
||
multiple masters, exposes the same options to balance load
|
||
across master hosts as described in
|
||
<a class="xref" href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections" title="8.2 Configuring Load Balancing with Connector/J">Section 8.2, “Configuring Load Balancing with Connector/J”</a>.
|
||
</p><h3><a name="idm140266685594080"></a>Live Reconfiguration of Replication Topography</h3><p><a name="connector-j-live-reconfiguration-replication"></a>
|
||
Since Connector/J 5.1.28, live management of replication host
|
||
(single or multi-master) topographies is also supported. This
|
||
enables users to promote slaves for Java applications without
|
||
requiring an application restart.
|
||
</p><p>
|
||
The replication hosts are most effectively managed in the
|
||
context of a replication connection group. A
|
||
ReplicationConnectionGroup class represents a logical grouping
|
||
of connections which can be managed together. There may be one
|
||
or more such replication connection groups in a given Java class
|
||
loader (there can be an application with two different JDBC
|
||
resources needing to be managed independently). This key class
|
||
exposes host management methods for replication connections, and
|
||
<code class="literal">ReplicationConnection</code> objects register
|
||
themselves with the appropriate
|
||
<code class="literal">ReplicationConnectionGroup</code> if a value for the
|
||
new <code class="literal">replicationConnectionGroup</code> property is
|
||
specified. The <code class="literal">ReplicationConnectionGroup</code>
|
||
object tracks these connections until they are closed, and it is
|
||
used to manipulate the hosts associated with these connections.
|
||
</p><p>
|
||
Some important methods related to host management include:
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="literal">getMasterHosts()</code>: Returns a collection
|
||
of strings representing the hosts configured as masters
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">getSlaveHosts()</code>: Returns a collection
|
||
of strings representing the hosts configured as slaves
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">addSlaveHost(String host)</code>: Adds new
|
||
host to pool of possible slave hosts for selection at
|
||
start of new read-only workload
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">promoteSlaveToMaster(String host)</code>:
|
||
Removes the host from the pool of potential slaves for
|
||
future read-only processes (existing read-only process is
|
||
allowed to continue to completion) and adds the host to
|
||
the pool of potential master hosts
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">removeSlaveHost(String host, boolean
|
||
closeGently)</code>: Removes the host (host name match
|
||
must be exact) from the list of configured slaves; if
|
||
<code class="literal">closeGently</code> is false, existing
|
||
connections which have this host as currently active will
|
||
be closed hardly (application should expect exceptions)
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">removeMasterHost(String host, boolean
|
||
closeGently)</code>: Same as
|
||
<code class="literal">removeSlaveHost()</code>, but removes the host
|
||
from the list of configured masters
|
||
</p></li></ul></div><p>
|
||
</p><p>
|
||
Some useful management metrics include:
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="literal">getConnectionCountWithHostAsSlave(String
|
||
host)</code>: Returns the number of
|
||
ReplicationConnection objects that have the given host
|
||
configured as a possible slave
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal"> getConnectionCountWithHostAsMaster(String
|
||
host)</code>: Returns the number of
|
||
ReplicationConnection objects that have the given host
|
||
configured as a possible master
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">getNumberOfSlavesAdded()</code>: Returns the
|
||
number of times a slave host has been dynamically added to
|
||
the group pool
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">getNumberOfSlavesRemoved()</code>: Returns the
|
||
number of times a slave host has been dynamically removed
|
||
from the group pool
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">getNumberOfSlavePromotions()</code>: Returns
|
||
the number of times a slave host has been promoted to a
|
||
master
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">getTotalConnectionCount()</code>: Returns the
|
||
number of ReplicationConnection objects which have been
|
||
registered with this group
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">getActiveConnectionCount()</code>: Returns the
|
||
number of ReplicationConnection objects currently being
|
||
managed by this group
|
||
</p></li></ul></div><p>
|
||
</p><h3><a name="idm140266685565152"></a>ReplicationConnectionGroupManager</h3><p>
|
||
<code class="literal">com.mysql.jdbc.ReplicationConnectionGroupManager</code>
|
||
provides access to the replication connection groups, together
|
||
with some utility methods.
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="literal">getConnectionGroup(String groupName)</code>:
|
||
Returns the <code class="literal">ReplicationConnectionGroup</code>
|
||
object matching the groupName provided
|
||
</p></li></ul></div><p>
|
||
</p><p>
|
||
The other methods in
|
||
<code class="literal">ReplicationConnectionGroupManager</code> mirror
|
||
those of <code class="literal">ReplicationConnectionGroup</code>, except
|
||
that the first argument is a String group name. These methods
|
||
will operate on all matching ReplicationConnectionGroups, which
|
||
are helpful for removing a server from service and have it
|
||
decommissioned across all possible
|
||
<code class="literal">ReplicationConnectionGroups</code>.
|
||
</p><p>
|
||
These methods might be useful for in-JVM management of
|
||
replication hosts if an application triggers topography changes.
|
||
For managing host configurations from outside the JVM, JMX can
|
||
be used.
|
||
</p><h3><a name="idm140266685557744"></a>Using JMX for Managing Replication Hosts</h3><p>
|
||
When Connector/J is started with
|
||
<code class="literal">replicationEnableJMX=true</code> and a value set for
|
||
the property <code class="literal">replicationConnectionGroup</code>, a
|
||
JMX MBean will be registered, allowing manipulation of
|
||
replication hosts by a JMX client. The MBean interface is
|
||
defined in
|
||
<code class="literal">com.mysql.jdbc.jmx.ReplicationGroupManagerMBean</code>,
|
||
and leverages the
|
||
<code class="literal">ReplicationConnectionGroupManager</code> static
|
||
methods:
|
||
</p><pre class="programlisting">
|
||
public abstract void addSlaveHost(String groupFilter, String host) throws SQLException;
|
||
public abstract void removeSlaveHost(String groupFilter, String host) throws SQLException;
|
||
public abstract void promoteSlaveToMaster(String groupFilter, String host) throws SQLException;
|
||
public abstract void removeMasterHost(String groupFilter, String host) throws SQLException;
|
||
public abstract String getMasterHostsList(String group);
|
||
public abstract String getSlaveHostsList(String group);
|
||
public abstract String getRegisteredConnectionGroups();
|
||
public abstract int getActiveMasterHostCount(String group);
|
||
public abstract int getActiveSlaveHostCount(String group);
|
||
public abstract int getSlavePromotionCount(String group);
|
||
public abstract long getTotalLogicalConnectionCount(String group);
|
||
public abstract long getActiveLogicalConnectionCount(String group);
|
||
</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-j2ee-concepts-load-balancing-failover"></a>8.4 Advanced Load-balancing and Failover Configuration</h2></div></div></div><p>
|
||
Connector/J provides a useful load-balancing implementation for
|
||
MySQL Cluster or multi-master deployments, as explained in
|
||
<a class="xref" href="#connector-j-usagenotes-j2ee-concepts-managing-load-balanced-connections" title="8.2 Configuring Load Balancing with Connector/J">Section 8.2, “Configuring Load Balancing with Connector/J”</a>
|
||
and
|
||
<a class="xref" href="#connector-j-multiple-master-replication" title="Support for Multiple-Master Replication Topographies">Support for Multiple-Master Replication Topographies</a>.
|
||
As of Connector/J 5.1.12, this same implementation is used for
|
||
balancing load between read-only slaves with
|
||
<code class="literal">ReplicationDriver</code>.
|
||
</p><p>
|
||
When trying to balance workload between multiple servers, the
|
||
driver has to determine when it is safe to swap servers, doing
|
||
so in the middle of a transaction, for example, could cause
|
||
problems. It is important not to lose state information. For
|
||
this reason, Connector/J will only try to pick a new server when
|
||
one of the following happens:
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
At transaction boundaries (transactions are explicitly
|
||
committed or rolled back).
|
||
</p></li><li class="listitem"><p>
|
||
A communication exception (SQL State starting with "08") is
|
||
encountered.
|
||
</p></li><li class="listitem"><p>
|
||
When a <code class="literal">SQLException</code> matches conditions
|
||
defined by user, using the extension points defined by the
|
||
<code class="literal">loadBalanceSQLStateFailover</code>,
|
||
<code class="literal">loadBalanceSQLExceptionSubclassFailover</code>
|
||
or <code class="literal">loadBalanceExceptionChecker</code>
|
||
properties.
|
||
</p></li></ol></div><p>
|
||
The third condition revolves around three new properties
|
||
introduced with Connector/J 5.1.13. It allows you to control
|
||
which <code class="literal">SQLException</code>s trigger failover.
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="literal">loadBalanceExceptionChecker</code> - The
|
||
<code class="literal">loadBalanceExceptionChecker</code> property is
|
||
really the key. This takes a fully-qualified class name
|
||
which implements the new
|
||
<code class="literal">com.mysql.jdbc.LoadBalanceExceptionChecker</code>
|
||
interface. This interface is very simple, and you only need
|
||
to implement the following method:
|
||
</p><pre class="programlisting">
|
||
public boolean shouldExceptionTriggerFailover(SQLException ex)
|
||
</pre><p>
|
||
A <code class="literal">SQLException</code> is passed in, and a
|
||
boolean returned. A value of <code class="literal">true</code>
|
||
triggers a failover, <code class="literal">false</code> does not.
|
||
</p><p>
|
||
You can use this to implement your own custom logic. An
|
||
example where this might be useful is when dealing with
|
||
transient errors when using MySQL Cluster, where certain
|
||
buffers may become overloaded. The following code snippet
|
||
illustrates this:
|
||
</p><pre class="programlisting">
|
||
|
||
public class NdbLoadBalanceExceptionChecker
|
||
extends StandardLoadBalanceExceptionChecker {
|
||
|
||
public boolean shouldExceptionTriggerFailover(SQLException ex) {
|
||
return super.shouldExceptionTriggerFailover(ex)
|
||
|| checkNdbException(ex);
|
||
}
|
||
|
||
private boolean checkNdbException(SQLException ex){
|
||
// Have to parse the message since most NDB errors
|
||
// are mapped to the same DEMC.
|
||
return (ex.getMessage().startsWith("Lock wait timeout exceeded") ||
|
||
(ex.getMessage().startsWith("Got temporary error")
|
||
&& ex.getMessage().endsWith("from NDB")));
|
||
}
|
||
}
|
||
|
||
</pre><p>
|
||
The code above extends
|
||
<code class="literal">com.mysql.jdbc.StandardLoadBalanceExceptionChecker</code>,
|
||
which is the default implementation. There are a few
|
||
convenient shortcuts built into this, for those who want to
|
||
have some level of control using properties, without writing
|
||
Java code. This default implementation uses the two
|
||
remaining properties:
|
||
<code class="literal">loadBalanceSQLStateFailover</code> and
|
||
<code class="literal">loadBalanceSQLExceptionSubclassFailover</code>.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">loadBalanceSQLStateFailover</code> - allows you
|
||
to define a comma-delimited list of
|
||
<code class="literal">SQLState</code> code prefixes, against which a
|
||
<code class="literal">SQLException</code> is compared. If the prefix
|
||
matches, failover is triggered. So, for example, the
|
||
following would trigger a failover if a given
|
||
<code class="literal">SQLException</code> starts with "00", or is
|
||
"12345":
|
||
</p><pre class="programlisting">
|
||
loadBalanceSQLStateFailover=00,12345
|
||
</pre></li><li class="listitem"><p>
|
||
<code class="literal">loadBalanceSQLExceptionSubclassFailover</code> -
|
||
can be used in conjunction with
|
||
<code class="literal">loadBalanceSQLStateFailover</code> or on its
|
||
own. If you want certain subclasses of
|
||
<code class="literal">SQLException</code> to trigger failover, simply
|
||
provide a comma-delimited list of fully-qualified class or
|
||
interface names to check against. For example, if you want
|
||
all <code class="literal">SQLTransientConnectionExceptions</code> to
|
||
trigger failover, you would specify:
|
||
</p><pre class="programlisting">
|
||
loadBalanceSQLExceptionSubclassFailover=java.sql.SQLTransientConnectionException
|
||
</pre></li></ul></div><p>
|
||
While the three failover conditions enumerated earlier suit most
|
||
situations, if <code class="literal">autocommit</code> is enabled,
|
||
Connector/J never re-balances, and continues using the same
|
||
physical connection. This can be problematic, particularly when
|
||
load-balancing is being used to distribute read-only load across
|
||
multiple slaves. However, Connector/J can be configured to
|
||
re-balance after a certain number of statements are executed,
|
||
when <code class="literal">autocommit</code> is enabled. This
|
||
functionality is dependent upon the following properties:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="literal">loadBalanceAutoCommitStatementThreshold</code>
|
||
– defines the number of matching statements which will
|
||
trigger the driver to potentially swap physical server
|
||
connections. The default value, 0, retains the behavior that
|
||
connections with <code class="literal">autocommit</code> enabled are
|
||
never balanced.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">loadBalanceAutoCommitStatementRegex</code> –
|
||
the regular expression against which statements must match.
|
||
The default value, blank, matches all statements. So, for
|
||
example, using the following properties will cause
|
||
Connector/J to re-balance after every third statement that
|
||
contains the string <span class="quote">“<span class="quote">test</span>”</span>:
|
||
</p><pre class="programlisting">
|
||
loadBalanceAutoCommitStatementThreshold=3
|
||
loadBalanceAutoCommitStatementRegex=.*test.*
|
||
</pre><p>
|
||
<code class="literal">loadBalanceAutoCommitStatementRegex</code> can
|
||
prove useful in a number of situations. Your application may
|
||
use temporary tables, server-side session state variables,
|
||
or connection state, where letting the driver arbitrarily
|
||
swap physical connections before processing is complete
|
||
could cause data loss or other problems. This allows you to
|
||
identify a trigger statement that is only executed when it
|
||
is safe to swap physical connections.
|
||
</p></li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-interceptors"></a>Chapter 9 Using the Connector/J Interceptor Classes</h1></div></div></div><p>
|
||
An interceptor is a software design pattern that provides a
|
||
transparent way to extend or modify some aspect of a program,
|
||
similar to a user exit. No recompiling is required. With
|
||
Connector/J, the interceptors are enabled and disabled by updating
|
||
the connection string to refer to different sets of interceptor
|
||
classes that you instantiate.
|
||
</p><p>
|
||
The connection properties that control the interceptors are
|
||
explained in
|
||
<a class="xref" href="#connector-j-reference-configuration-properties" title="5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
|
||
for Connector/J”</a>:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="literal">connectionLifecycleInterceptors</code>, where you
|
||
specify the fully qualified names of classes that implement
|
||
the
|
||
<code class="literal">com.mysql.jdbc.ConnectionLifecycleInterceptor</code>
|
||
interface. In these kinds of interceptor classes, you might
|
||
log events such as rollbacks, measure the time between
|
||
transaction start and end, or count events such as calls to
|
||
<code class="literal">setAutoCommit()</code>.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">exceptionInterceptors</code>, where you specify
|
||
the fully qualified names of classes that implement the
|
||
<code class="literal">com.mysql.jdbc.ExceptionInterceptor</code>
|
||
interface. In these kinds of interceptor classes, you might
|
||
add extra diagnostic information to exceptions that can have
|
||
multiple causes or indicate a problem with server settings.
|
||
Because <code class="literal">exceptionInterceptors</code> classes are
|
||
only called when handling a <code class="literal">SQLException</code>
|
||
thrown from Connector/J code, they can be used even in
|
||
production deployments without substantial performance
|
||
overhead.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="literal">statementInterceptors</code>, where you specify
|
||
the fully qualified names of classes that implement the
|
||
<code class="literal">com.mysql.jdbc.StatementInterceptorV2</code>
|
||
interface. In these kinds of interceptor classes, you might
|
||
change or augment the processing done by certain kinds of
|
||
statements, such as automatically checking for queried data in
|
||
a <span class="command"><strong>memcached</strong></span> server, rewriting slow queries,
|
||
logging information about statement execution, or route
|
||
requests to remote servers.
|
||
</p></li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-tomcat"></a>Chapter 10 Using Connector/J with Tomcat</h1></div></div></div><a class="indexterm" name="idm140266685496208"></a><p>
|
||
The following instructions are based on the instructions for
|
||
Tomcat-5.x, available at
|
||
<a class="ulink" href="http://tomcat.apache.org/tomcat-5.5-doc/jndi-datasource-examples-howto.html" target="_top">http://tomcat.apache.org/tomcat-5.5-doc/jndi-datasource-examples-howto.html</a>
|
||
which is current at the time this document was written.
|
||
</p><p>
|
||
First, install the <code class="filename">.jar</code> file that comes with
|
||
Connector/J in <code class="filename">$CATALINA_HOME/common/lib</code> so
|
||
that it is available to all applications installed in the
|
||
container.
|
||
</p><p>
|
||
Next, configure the JNDI DataSource by adding a declaration
|
||
resource to <code class="filename">$CATALINA_HOME/conf/server.xml</code> in
|
||
the context that defines your web application:
|
||
</p><pre class="programlisting">
|
||
<Context ....>
|
||
|
||
...
|
||
|
||
<Resource name="jdbc/MySQLDB"
|
||
auth="Container"
|
||
type="javax.sql.DataSource"/>
|
||
|
||
<ResourceParams name="jdbc/MySQLDB">
|
||
<parameter>
|
||
<name>factory</name>
|
||
<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
|
||
</parameter>
|
||
|
||
<parameter>
|
||
<name>maxActive</name>
|
||
<value>10</value>
|
||
</parameter>
|
||
|
||
<parameter>
|
||
<name>maxIdle</name>
|
||
<value>5</value>
|
||
</parameter>
|
||
|
||
<parameter>
|
||
<name>validationQuery</name>
|
||
<value>SELECT 1</value>
|
||
</parameter>
|
||
|
||
<parameter>
|
||
<name>testOnBorrow</name>
|
||
<value>true</value>
|
||
</parameter>
|
||
|
||
<parameter>
|
||
<name>testWhileIdle</name>
|
||
<value>true</value>
|
||
</parameter>
|
||
|
||
<parameter>
|
||
<name>timeBetweenEvictionRunsMillis</name>
|
||
<value>10000</value>
|
||
</parameter>
|
||
|
||
<parameter>
|
||
<name>minEvictableIdleTimeMillis</name>
|
||
<value>60000</value>
|
||
</parameter>
|
||
|
||
<parameter>
|
||
<name>username</name>
|
||
<value>someuser</value>
|
||
</parameter>
|
||
|
||
<parameter>
|
||
<name>password</name>
|
||
<value>somepass</value>
|
||
</parameter>
|
||
|
||
<parameter>
|
||
<name>driverClassName</name>
|
||
<value>com.mysql.jdbc.Driver</value>
|
||
</parameter>
|
||
|
||
<parameter>
|
||
<name>url</name>
|
||
<value>jdbc:mysql://localhost:3306/test</value>
|
||
</parameter>
|
||
|
||
</ResourceParams>
|
||
</Context>
|
||
</pre><p>
|
||
Note that Connector/J 5.1.3 introduced a facility whereby, rather
|
||
than use a <code class="literal">validationQuery</code> value of
|
||
<code class="literal">SELECT 1</code>, it is possible to use
|
||
<code class="literal">validationQuery</code> with a value set to <code class="literal">/*
|
||
ping */</code>. This sends a ping to the server which then
|
||
returns a fake result set. This is a lighter weight solution. It
|
||
also has the advantage that if using
|
||
<code class="literal">ReplicationConnection</code> or
|
||
<code class="literal">LoadBalancedConnection</code> type connections, the
|
||
ping will be sent across all active connections. The following XML
|
||
snippet illustrates how to select this option:
|
||
</p><pre class="programlisting">
|
||
|
||
<parameter>
|
||
<name>validationQuery</name>
|
||
<value>/* ping */</value>
|
||
</parameter>
|
||
|
||
</pre><p>
|
||
Note that <code class="literal">/* ping */</code> has to be specified
|
||
exactly.
|
||
</p><p>
|
||
In general, follow the installation instructions that come with
|
||
your version of Tomcat, as the way you configure datasources in
|
||
Tomcat changes from time to time, and if you use the wrong syntax
|
||
in your XML file, you will most likely end up with an exception
|
||
similar to the following:
|
||
</p><pre class="programlisting">
|
||
Error: java.sql.SQLException: Cannot load JDBC driver class 'null ' SQL
|
||
state: null
|
||
</pre><p>
|
||
Note that the auto-loading of drivers having the
|
||
<code class="filename">META-INF/service/java.sql.Driver</code> class in
|
||
JDBC 4.0 and above causes an improper undeployment of the
|
||
Connector/J driver in Tomcat on Windows. Namely, the Connector/J
|
||
jar remains locked. This is an initialization problem that is not
|
||
related to the driver. The possible workarounds, if viable, are as
|
||
follows: use "<code class="literal">antiResourceLocking=true</code>" as a
|
||
Tomcat Context attribute, or remove the
|
||
<code class="filename">META-INF/</code> directory.
|
||
</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-jboss"></a>Chapter 11 Using Connector/J with JBoss</h1></div></div></div><a class="indexterm" name="idm140266685476416"></a><p>
|
||
These instructions cover JBoss-4.x. To make the JDBC driver
|
||
classes available to the application server, copy the
|
||
<code class="filename">.jar</code> file that comes with Connector/J to the
|
||
<code class="filename">lib</code> directory for your server configuration
|
||
(which is usually called <code class="filename">default</code>). Then, in
|
||
the same configuration directory, in the subdirectory named
|
||
deploy, create a datasource configuration file that ends with
|
||
<code class="literal">-ds.xml</code>, which tells JBoss to deploy this file
|
||
as a JDBC Datasource. The file should have the following contents:
|
||
</p><pre class="programlisting">
|
||
<datasources>
|
||
<local-tx-datasource>
|
||
|
||
<jndi-name>MySQLDB</jndi-name>
|
||
<connection-url>jdbc:mysql://localhost:3306/dbname</connection-url>
|
||
<driver-class>com.mysql.jdbc.Driver</driver-class>
|
||
<user-name>user</user-name>
|
||
<password>pass</password>
|
||
|
||
<min-pool-size>5</min-pool-size>
|
||
|
||
<max-pool-size>20</max-pool-size>
|
||
|
||
<idle-timeout-minutes>5</idle-timeout-minutes>
|
||
|
||
<exception-sorter-class-name>
|
||
com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter
|
||
</exception-sorter-class-name>
|
||
<valid-connection-checker-class-name>
|
||
com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker
|
||
</valid-connection-checker-class-name>
|
||
|
||
</local-tx-datasource>
|
||
</datasources>
|
||
</pre></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-spring-config"></a>Chapter 12 Using Connector/J with Spring</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-jdbctemplate">12.1 Using <code class="classname">JdbcTemplate</code></a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-transactional">12.2 Transactional JDBC Access</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-spring-config-connpooling">12.3 Connection Pooling with Spring</a></span></dt></dl></div><a class="indexterm" name="idm140266685469184"></a><p>
|
||
The Spring Framework is a Java-based application framework
|
||
designed for assisting in application design by providing a way to
|
||
configure components. The technique used by Spring is a well known
|
||
design pattern called Dependency Injection (see
|
||
<a class="ulink" href="http://www.martinfowler.com/articles/injection.html" target="_top">Inversion
|
||
of Control Containers and the Dependency Injection
|
||
pattern</a>). This article will focus on Java-oriented access
|
||
to MySQL databases with Spring 2.0. For those wondering, there is
|
||
a .NET port of Spring appropriately named Spring.NET.
|
||
</p><p>
|
||
Spring is not only a system for configuring components, but also
|
||
includes support for aspect oriented programming (AOP). This is
|
||
one of the main benefits and the foundation for Spring's resource
|
||
and transaction management. Spring also provides utilities for
|
||
integrating resource management with JDBC and Hibernate.
|
||
</p><p>
|
||
For the examples in this section the MySQL world sample database
|
||
will be used. The first task is to set up a MySQL data source
|
||
through Spring. Components within Spring use the
|
||
<span class="quote">“<span class="quote">bean</span>”</span> terminology. For example, to configure a
|
||
connection to a MySQL server supporting the world sample database,
|
||
you might use:
|
||
</p><pre class="programlisting">
|
||
|
||
<util:map id="dbProps">
|
||
<entry key="db.driver" value="com.mysql.jdbc.Driver"/>
|
||
<entry key="db.jdbcurl" value="jdbc:mysql://localhost/world"/>
|
||
<entry key="db.username" value="myuser"/>
|
||
<entry key="db.password" value="mypass"/>
|
||
</util:map>
|
||
|
||
</pre><p>
|
||
In the above example, we are assigning values to properties that
|
||
will be used in the configuration. For the datasource
|
||
configuration:
|
||
</p><pre class="programlisting">
|
||
|
||
<bean id="dataSource"
|
||
class="org.springframework.jdbc.datasource.DriverManagerDataSource">
|
||
<property name="driverClassName" value="${db.driver}"/>
|
||
<property name="url" value="${db.jdbcurl}"/>
|
||
<property name="username" value="${db.username}"/>
|
||
<property name="password" value="${db.password}"/>
|
||
</bean>
|
||
|
||
</pre><p>
|
||
The placeholders are used to provide values for properties of this
|
||
bean. This means that you can specify all the properties of the
|
||
configuration in one place instead of entering the values for each
|
||
property on each bean. We do, however, need one more bean to pull
|
||
this all together. The last bean is responsible for actually
|
||
replacing the placeholders with the property values.
|
||
</p><pre class="programlisting">
|
||
|
||
<bean
|
||
class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
|
||
<property name="properties" ref="dbProps"/>
|
||
</bean>
|
||
|
||
</pre><p>
|
||
Now that we have our MySQL data source configured and ready to go,
|
||
we write some Java code to access it. The example below will
|
||
retrieve three random cities and their corresponding country using
|
||
the data source we configured with Spring.
|
||
</p><pre class="programlisting">
|
||
// Create a new application context. this processes the Spring config
|
||
ApplicationContext ctx =
|
||
new ClassPathXmlApplicationContext("ex1appContext.xml");
|
||
// Retrieve the data source from the application context
|
||
DataSource ds = (DataSource) ctx.getBean("dataSource");
|
||
// Open a database connection using Spring's DataSourceUtils
|
||
Connection c = DataSourceUtils.getConnection(ds);
|
||
try {
|
||
// retrieve a list of three random cities
|
||
PreparedStatement ps = c.prepareStatement(
|
||
"select City.Name as 'City', Country.Name as 'Country' " +
|
||
"from City inner join Country on City.CountryCode = Country.Code " +
|
||
"order by rand() limit 3");
|
||
ResultSet rs = ps.executeQuery();
|
||
while(rs.next()) {
|
||
String city = rs.getString("City");
|
||
String country = rs.getString("Country");
|
||
System.out.printf("The city %s is in %s%n", city, country);
|
||
}
|
||
} catch (SQLException ex) {
|
||
// something has failed and we print a stack trace to analyse the error
|
||
ex.printStackTrace();
|
||
// ignore failure closing connection
|
||
try { c.close(); } catch (SQLException e) { }
|
||
} finally {
|
||
// properly release our connection
|
||
DataSourceUtils.releaseConnection(c, ds);
|
||
}
|
||
</pre><p>
|
||
This is very similar to normal JDBC access to MySQL with the main
|
||
difference being that we are using DataSourceUtils instead of the
|
||
DriverManager to create the connection.
|
||
</p><p>
|
||
While it may seem like a small difference, the implications are
|
||
somewhat far reaching. Spring manages this resource in a way
|
||
similar to a container managed data source in a J2EE application
|
||
server. When a connection is opened, it can be subsequently
|
||
accessed in other parts of the code if it is synchronized with a
|
||
transaction. This makes it possible to treat different parts of
|
||
your application as transactional instead of passing around a
|
||
database connection.
|
||
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-spring-config-jdbctemplate"></a>12.1 Using <code class="classname">JdbcTemplate</code></h2></div></div></div><p>
|
||
Spring makes extensive use of the Template method design pattern
|
||
(see
|
||
<a class="ulink" href="http://en.wikipedia.org/wiki/Template_method_pattern" target="_top">Template
|
||
Method Pattern</a>). Our immediate focus will be on the
|
||
<code class="literal">JdbcTemplate</code> and related classes,
|
||
specifically <code class="literal">NamedParameterJdbcTemplate</code>. The
|
||
template classes handle obtaining and releasing a connection for
|
||
data access when one is needed.
|
||
</p><p>
|
||
The next example shows how to use
|
||
<code class="literal">NamedParameterJdbcTemplate</code> inside of a DAO
|
||
(Data Access Object) class to retrieve a random city given a
|
||
country code.
|
||
</p><pre class="programlisting">
|
||
public class Ex2JdbcDao {
|
||
/**
|
||
* Data source reference which will be provided by Spring.
|
||
*/
|
||
private DataSource dataSource;
|
||
|
||
/**
|
||
* Our query to find a random city given a country code. Notice
|
||
* the ":country" parameter toward the end. This is called a
|
||
* named parameter.
|
||
*/
|
||
private String queryString = "select Name from City " +
|
||
"where CountryCode = :country order by rand() limit 1";
|
||
|
||
/**
|
||
* Retrieve a random city using Spring JDBC access classes.
|
||
*/
|
||
public String getRandomCityByCountryCode(String cntryCode) {
|
||
// A template that permits using queries with named parameters
|
||
NamedParameterJdbcTemplate template =
|
||
new NamedParameterJdbcTemplate(dataSource);
|
||
// A java.util.Map is used to provide values for the parameters
|
||
Map params = new HashMap();
|
||
params.put("country", cntryCode);
|
||
// We query for an Object and specify what class we are expecting
|
||
return (String)template.queryForObject(queryString, params, String.class);
|
||
}
|
||
|
||
/**
|
||
* A JavaBean setter-style method to allow Spring to inject the data source.
|
||
* @param dataSource
|
||
*/
|
||
public void setDataSource(DataSource dataSource) {
|
||
this.dataSource = dataSource;
|
||
}
|
||
}
|
||
</pre><p>
|
||
The focus in the above code is on the
|
||
<code class="function">getRandomCityByCountryCode()</code> method. We
|
||
pass a country code and use the
|
||
<code class="literal">NamedParameterJdbcTemplate</code> to query for a
|
||
city. The country code is placed in a Map with the key
|
||
"country", which is the parameter is named in the SQL query.
|
||
</p><p>
|
||
To access this code, you need to configure it with Spring by
|
||
providing a reference to the data source.
|
||
</p><pre class="programlisting">
|
||
|
||
<bean id="dao" class="code.Ex2JdbcDao">
|
||
<property name="dataSource" ref="dataSource"/>
|
||
</bean>
|
||
|
||
</pre><p>
|
||
At this point, we can just grab a reference to the DAO from
|
||
Spring and call
|
||
<code class="function">getRandomCityByCountryCode()</code>.
|
||
</p><pre class="programlisting">
|
||
// Create the application context
|
||
ApplicationContext ctx =
|
||
new ClassPathXmlApplicationContext("ex2appContext.xml");
|
||
// Obtain a reference to our DAO
|
||
Ex2JdbcDao dao = (Ex2JdbcDao) ctx.getBean("dao");
|
||
|
||
String countryCode = "USA";
|
||
|
||
// Find a few random cities in the US
|
||
for(int i = 0; i < 4; ++i)
|
||
System.out.printf("A random city in %s is %s%n", countryCode,
|
||
dao.getRandomCityByCountryCode(countryCode));
|
||
</pre><p>
|
||
This example shows how to use Spring's JDBC classes to
|
||
completely abstract away the use of traditional JDBC classes
|
||
including <code class="literal">Connection</code> and
|
||
<code class="literal">PreparedStatement</code>.
|
||
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-spring-config-transactional"></a>12.2 Transactional JDBC Access</h2></div></div></div><p>
|
||
You might be wondering how we can add transactions into our code
|
||
if we do not deal directly with the JDBC classes. Spring
|
||
provides a transaction management package that not only replaces
|
||
JDBC transaction management, but also enables declarative
|
||
transaction management (configuration instead of code).
|
||
</p><p>
|
||
To use transactional database access, we will need to change the
|
||
storage engine of the tables in the world database. The
|
||
downloaded script explicitly creates MyISAM tables which do not
|
||
support transactional semantics. The InnoDB storage engine does
|
||
support transactions and this is what we will be using. We can
|
||
change the storage engine with the following statements.
|
||
</p><pre class="programlisting">
|
||
ALTER TABLE City ENGINE=InnoDB;
|
||
ALTER TABLE Country ENGINE=InnoDB;
|
||
ALTER TABLE CountryLanguage ENGINE=InnoDB;
|
||
</pre><p>
|
||
A good programming practice emphasized by Spring is separating
|
||
interfaces and implementations. What this means is that we can
|
||
create a Java interface and only use the operations on this
|
||
interface without any internal knowledge of what the actual
|
||
implementation is. We will let Spring manage the implementation
|
||
and with this it will manage the transactions for our
|
||
implementation.
|
||
</p><p>
|
||
First you create a simple interface:
|
||
</p><pre class="programlisting">
|
||
public interface Ex3Dao {
|
||
Integer createCity(String name, String countryCode,
|
||
String district, Integer population);
|
||
}
|
||
</pre><p>
|
||
This interface contains one method that will create a new city
|
||
record in the database and return the id of the new record. Next
|
||
you need to create an implementation of this interface.
|
||
</p><pre class="programlisting">
|
||
public class Ex3DaoImpl implements Ex3Dao {
|
||
protected DataSource dataSource;
|
||
protected SqlUpdate updateQuery;
|
||
protected SqlFunction idQuery;
|
||
|
||
public Integer createCity(String name, String countryCode,
|
||
String district, Integer population) {
|
||
updateQuery.update(new Object[] { name, countryCode,
|
||
district, population });
|
||
return getLastId();
|
||
}
|
||
|
||
protected Integer getLastId() {
|
||
return idQuery.run();
|
||
}
|
||
}
|
||
</pre><p>
|
||
You can see that we only operate on abstract query objects here
|
||
and do not deal directly with the JDBC API. Also, this is the
|
||
complete implementation. All of our transaction management will
|
||
be dealt with in the configuration. To get the configuration
|
||
started, we need to create the DAO.
|
||
</p><pre class="programlisting">
|
||
|
||
<bean id="dao" class="code.Ex3DaoImpl">
|
||
<property name="dataSource" ref="dataSource"/>
|
||
<property name="updateQuery">...</property>
|
||
<property name="idQuery">...</property>
|
||
</bean>
|
||
|
||
</pre><p>
|
||
Now you need to set up the transaction configuration. The first
|
||
thing you must do is create transaction manager to manage the
|
||
data source and a specification of what transaction properties
|
||
are required for the <code class="literal">dao</code> methods.
|
||
</p><pre class="programlisting">
|
||
|
||
<bean id="transactionManager"
|
||
class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
|
||
<property name="dataSource" ref="dataSource"/>
|
||
</bean>
|
||
|
||
<tx:advice id="txAdvice" transaction-manager="transactionManager">
|
||
<tx:attributes>
|
||
<tx:method name="*"/>
|
||
</tx:attributes>
|
||
</tx:advice>
|
||
|
||
</pre><p>
|
||
The preceding code creates a transaction manager that handles
|
||
transactions for the data source provided to it. The
|
||
<code class="literal">txAdvice</code> uses this transaction manager and
|
||
the attributes specify to create a transaction for all methods.
|
||
Finally you need to apply this advice with an AOP pointcut.
|
||
</p><pre class="programlisting">
|
||
|
||
<aop:config>
|
||
<aop:pointcut id="daoMethods"
|
||
expression="execution(* code.Ex3Dao.*(..))"/>
|
||
<aop:advisor advice-ref="txAdvice" pointcut-ref="daoMethods"/>
|
||
</aop:config>
|
||
|
||
</pre><p>
|
||
This basically says that all methods called on the
|
||
<code class="literal">Ex3Dao</code> interface will be wrapped in a
|
||
transaction. To make use of this, you only have to retrieve the
|
||
<code class="literal">dao</code> from the application context and call a
|
||
method on the <code class="literal">dao</code> instance.
|
||
</p><pre class="programlisting">
|
||
Ex3Dao dao = (Ex3Dao) ctx.getBean("dao");
|
||
Integer id = dao.createCity(name, countryCode, district, pop);
|
||
</pre><p>
|
||
We can verify from this that there is no transaction management
|
||
happening in our Java code and it is all configured with Spring.
|
||
This is a very powerful notion and regarded as one of the most
|
||
beneficial features of Spring.
|
||
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-spring-config-connpooling"></a>12.3 Connection Pooling with Spring</h2></div></div></div><a class="indexterm" name="idm140266685420688"></a><p>
|
||
In many situations, such as web applications, there will be a
|
||
large number of small database transactions. When this is the
|
||
case, it usually makes sense to create a pool of database
|
||
connections available for web requests as needed. Although MySQL
|
||
does not spawn an extra process when a connection is made, there
|
||
is still a small amount of overhead to create and set up the
|
||
connection. Pooling of connections also alleviates problems such
|
||
as collecting large amounts of sockets in the
|
||
<code class="literal">TIME_WAIT</code> state.
|
||
</p><p>
|
||
Setting up pooling of MySQL connections with Spring is as simple
|
||
as changing the data source configuration in the application
|
||
context. There are a number of configurations that we can use.
|
||
The first example is based on the
|
||
<a class="ulink" href="http://jakarta.apache.org/commons/dbcp/" target="_top">Jakarta
|
||
Commons DBCP library</a>. The example below replaces the
|
||
source configuration that was based on
|
||
<code class="literal">DriverManagerDataSource</code> with DBCP's
|
||
BasicDataSource.
|
||
</p><pre class="programlisting">
|
||
|
||
<bean id="dataSource" destroy-method="close"
|
||
class="org.apache.commons.dbcp.BasicDataSource">
|
||
<property name="driverClassName" value="${db.driver}"/>
|
||
<property name="url" value="${db.jdbcurl}"/>
|
||
<property name="username" value="${db.username}"/>
|
||
<property name="password" value="${db.password}"/>
|
||
<property name="initialSize" value="3"/>
|
||
</bean>
|
||
|
||
</pre><p>
|
||
The configuration of the two solutions is very similar. The
|
||
difference is that DBCP will pool connections to the database
|
||
instead of creating a new connection every time one is
|
||
requested. We have also set a parameter here called
|
||
<code class="literal">initialSize</code>. This tells DBCP that we want
|
||
three connections in the pool when it is created.
|
||
</p><p>
|
||
Another way to configure connection pooling is to configure a
|
||
data source in our J2EE application server. Using JBoss as an
|
||
example, you can set up the MySQL connection pool by creating a
|
||
file called <code class="filename">mysql-local-ds.xml</code> and placing
|
||
it in the server/default/deploy directory in JBoss. Once we have
|
||
this setup, we can use JNDI to look it up. With Spring, this
|
||
lookup is very simple. The data source configuration looks like
|
||
this.
|
||
</p><pre class="programlisting">
|
||
|
||
<jee:jndi-lookup id="dataSource" jndi-name="java:MySQL_DS"/>
|
||
|
||
</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-glassfish-config"></a>Chapter 13 Using Connector/J with GlassFish</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-usagenotes-glassfish-config-jsp">13.1 A Simple JSP Application with GlassFish, Connector/J and MySQL</a></span></dt><dt><span class="section"><a href="#connector-j-usagenotes-glassfish-config-servlet">13.2 A Simple Servlet with GlassFish, Connector/J and MySQL</a></span></dt></dl></div><a class="indexterm" name="idm140266685409328"></a><a class="indexterm" name="idm140266685408240"></a><p>
|
||
This section explains how to use MySQL Connector/J with GlassFish ™
|
||
Server Open Source Edition 3.0.1. GlassFish can be downloaded from
|
||
the
|
||
<a class="ulink" href="https://glassfish.dev.java.net/public/downloadsindex.html#top" target="_top">GlassFish
|
||
website</a>.
|
||
</p><p>
|
||
Once GlassFish is installed, make sure it can access MySQL Connector/J. To do
|
||
this, copy the MySQL Connector/J <code class="filename">jar</code> file to the
|
||
<code class="filename"><em class="replaceable"><code>domain-dir</code></em>/lib</code>
|
||
directory. For example, copy
|
||
<code class="filename">mysql-connector-java-5.1.30-bin.jar</code> to
|
||
<code class="filename">C:\<em class="replaceable"><code>glassfish-install-path</code></em>\domains\<em class="replaceable"><code>domain-name</code></em>\lib</code>.
|
||
Restart the GlassFish Application Server. For more information,
|
||
see <span class="quote">“<span class="quote">Integrating the JDBC Driver</span>”</span> in
|
||
<em class="citetitle">GlassFish Server Open Source Edition Administration
|
||
Guide</em>, available at
|
||
<a class="ulink" href="https://glassfish.java.net/documentation.html" target="_top">GlassFish
|
||
Server Documentation</a>.
|
||
</p><p>
|
||
You are now ready to create JDBC Connection Pools and JDBC
|
||
Resources.
|
||
</p><p>
|
||
<span class="bold"><strong>Creating a Connection Pool</strong></span>
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
In the GlassFish Administration Console, using the navigation
|
||
tree navigate to <span class="guilabel">Resources</span>,
|
||
<span class="guilabel">JDBC</span>, <span class="guilabel">Connection
|
||
Pools</span>.
|
||
</p></li><li class="listitem"><p>
|
||
In the <span class="guilabel">JDBC Connection Pools</span> frame click
|
||
<span class="guibutton">New</span>. You will enter a two step wizard.
|
||
</p></li><li class="listitem"><p>
|
||
In the <span class="guilabel">Name</span> field under <span class="guilabel">General
|
||
Settings</span> enter the name for the connection pool,
|
||
for example enter <strong class="userinput"><code>MySQLConnPool</code></strong>.
|
||
</p></li><li class="listitem"><p>
|
||
In the <span class="guilabel">Resource Type</span> field, select
|
||
<code class="literal">javax.sql.DataSource</code> from the drop-down
|
||
listbox.
|
||
</p></li><li class="listitem"><p>
|
||
In the <span class="guilabel">Database Vendor</span> field, select
|
||
<code class="literal">MySQL</code> from the drop-down listbox. Click
|
||
<span class="guibutton">Next</span> to go to the next page of the
|
||
wizard.
|
||
</p></li><li class="listitem"><p>
|
||
You can accept the default settings for General Settings, Pool
|
||
Settings and Transactions for this example. Scroll down to
|
||
Additional Properties.
|
||
</p></li><li class="listitem"><p>
|
||
In Additional Properties you will need to ensure the following
|
||
properties are set:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<span class="bold"><strong>ServerName</strong></span> - The server
|
||
to connect to. For local testing this will be
|
||
<code class="literal">localhost</code>.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>User</strong></span> - The user name with
|
||
which to connect to MySQL.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>Password</strong></span> - The
|
||
corresponding password for the user.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>DatabaseName</strong></span> - The
|
||
database to connect to, for example the sample MySQL
|
||
database <code class="literal">World</code>.
|
||
</p></li></ul></div></li><li class="listitem"><p>
|
||
Click <span class="guibutton">Finish</span> to exit the wizard. You
|
||
will be taken to the <span class="guilabel">JDBC Connection
|
||
Pools</span> page where all current connection pools,
|
||
including the one you just created, will be displayed.
|
||
</p></li><li class="listitem"><p>
|
||
In the <span class="guilabel">JDBC Connection Pools</span> frame click
|
||
on the connection pool you just created. Here, you can review
|
||
and edit information about the connection pool. Because
|
||
Connector/J does not support optimized validation queries, go
|
||
to the <span class="guilabel">Advanced</span> tab, and under Connection
|
||
Validation, configure the following settings:
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<span class="bold"><strong>Connection Validation</strong></span> -
|
||
select <span class="guilabel">Required</span>.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>Validation Method</strong></span> -
|
||
select <span class="guilabel">table</span> from the drop-down
|
||
menu.
|
||
</p></li><li class="listitem"><p>
|
||
<span class="bold"><strong>Table Name</strong></span> - enter
|
||
<code class="literal">DUAL</code>.
|
||
</p></li></ul></div><p>
|
||
</p></li><li class="listitem"><p>
|
||
To test your connection pool click the
|
||
<span class="guibutton">Ping</span> button at the top of the frame. A
|
||
message will be displayed confirming correct operation or
|
||
otherwise. If an error message is received recheck the
|
||
previous steps, and ensure that MySQL Connector/J has been correctly copied
|
||
into the previously specified location.
|
||
</p></li></ol></div><p>
|
||
Now that you have created a connection pool you will also need to
|
||
create a JDBC Resource (data source) for use by your application.
|
||
</p><p>
|
||
<span class="bold"><strong>Creating a JDBC Resource</strong></span>
|
||
</p><p>
|
||
Your Java application will usually reference a data source object
|
||
to establish a connection with the database. This needs to be
|
||
created first using the following procedure.
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
Using the navigation tree in the GlassFish Administration
|
||
Console, navigate to <span class="guilabel">Resources</span>,
|
||
<span class="guilabel">JDBC</span>, <span class="guilabel">JDBC
|
||
Resources</span>. A list of resources will be displayed in
|
||
the <span class="guilabel">JDBC Resources</span> frame.
|
||
</p></li><li class="listitem"><p>
|
||
Click <span class="guibutton">New</span>. The <span class="guilabel">New JDBC
|
||
Resource</span> frame will be displayed.
|
||
</p></li><li class="listitem"><p>
|
||
In the <span class="guilabel">JNDI Name</span> field, enter the JNDI
|
||
name that will be used to access this resource, for example
|
||
enter <strong class="userinput"><code>jdbc/MySQLDataSource</code></strong>.
|
||
</p></li><li class="listitem"><p>
|
||
In the <span class="guilabel">Pool Name</span> field, select a
|
||
connection pool you want this resource to use from the
|
||
drop-down listbox.
|
||
</p></li><li class="listitem"><p>
|
||
Optionally, you can enter a description into the
|
||
<span class="guilabel">Description</span> field.
|
||
</p></li><li class="listitem"><p>
|
||
Additional properties can be added if required.
|
||
</p></li><li class="listitem"><p>
|
||
Click <span class="guibutton">OK</span> to create the new JDBC
|
||
resource. The <span class="guilabel">JDBC Resources</span> frame will
|
||
list all available JDBC Resources.
|
||
</p></li></ul></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-glassfish-config-jsp"></a>13.1 A Simple JSP Application with GlassFish, Connector/J and MySQL</h2></div></div></div><p>
|
||
This section shows how to deploy a simple JSP application on
|
||
GlassFish, that connects to a MySQL database.
|
||
</p><p>
|
||
This example assumes you have already set up a suitable
|
||
Connection Pool and JDBC Resource, as explained in the preceding
|
||
sections. It is also assumed you have a sample database
|
||
installed, such as <code class="literal">world</code>.
|
||
</p><p>
|
||
The main application code, <code class="filename">index.jsp</code> is
|
||
presented here:
|
||
</p><pre class="programlisting">
|
||
|
||
<%@ page import="java.sql.*, javax.sql.*, java.io.*, javax.naming.*" %>
|
||
<html>
|
||
<head><title>Hello world from JSP</title></head>
|
||
<body>
|
||
<%
|
||
InitialContext ctx;
|
||
DataSource ds;
|
||
Connection conn;
|
||
Statement stmt;
|
||
ResultSet rs;
|
||
|
||
try {
|
||
ctx = new InitialContext();
|
||
ds = (DataSource) ctx.lookup("java:comp/env/jdbc/MySQLDataSource");
|
||
//ds = (DataSource) ctx.lookup("jdbc/MySQLDataSource");
|
||
conn = ds.getConnection();
|
||
stmt = conn.createStatement();
|
||
rs = stmt.executeQuery("SELECT * FROM Country");
|
||
|
||
while(rs.next()) {
|
||
%>
|
||
<h3>Name: <%= rs.getString("Name") %></h3>
|
||
<h3>Population: <%= rs.getString("Population") %></h3>
|
||
<%
|
||
}
|
||
}
|
||
catch (SQLException se) {
|
||
%>
|
||
<%= se.getMessage() %>
|
||
<%
|
||
}
|
||
catch (NamingException ne) {
|
||
%>
|
||
<%= ne.getMessage() %>
|
||
<%
|
||
}
|
||
%>
|
||
</body>
|
||
</html>
|
||
|
||
</pre><p>
|
||
In addition two XML files are required:
|
||
<code class="filename">web.xml</code>, and
|
||
<code class="filename">sun-web.xml</code>. There may be other files
|
||
present, such as classes and images. These files are organized
|
||
into the directory structure as follows:
|
||
</p><pre class="programlisting">
|
||
index.jsp
|
||
WEB-INF
|
||
|
|
||
- web.xml
|
||
- sun-web.xml
|
||
</pre><p>
|
||
The code for <code class="filename">web.xml</code> is:
|
||
</p><pre class="programlisting">
|
||
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
|
||
<display-name>HelloWebApp</display-name>
|
||
<distributable/>
|
||
<resource-ref>
|
||
<res-ref-name>jdbc/MySQLDataSource</res-ref-name>
|
||
<res-type>javax.sql.DataSource</res-type>
|
||
<res-auth>Container</res-auth>
|
||
<res-sharing-scope>Shareable</res-sharing-scope>
|
||
</resource-ref>
|
||
</web-app>
|
||
|
||
</pre><p>
|
||
The code for <code class="filename">sun-web.xml</code> is:
|
||
</p><pre class="programlisting">
|
||
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 8.1 Servlet 2.4//EN" "http://www.sun.com/software/appserver/dtds/sun-web-app_2_4-1.dtd">
|
||
<sun-web-app>
|
||
<context-root>HelloWebApp</context-root>
|
||
<resource-ref>
|
||
<res-ref-name>jdbc/MySQLDataSource</res-ref-name>
|
||
<jndi-name>jdbc/MySQLDataSource</jndi-name>
|
||
</resource-ref>
|
||
</sun-web-app>
|
||
|
||
</pre><p>
|
||
These XML files illustrate a very important aspect of running
|
||
JDBC applications on GlassFish. On GlassFish it is important to
|
||
map the string specified for a JDBC resource to its JNDI name,
|
||
as set up in the GlassFish administration console. In this
|
||
example, the JNDI name for the JDBC resource, as specified in
|
||
the GlassFish Administration console when creating the JDBC
|
||
Resource, was <code class="literal">jdbc/MySQLDataSource</code>. This must
|
||
be mapped to the name given in the application. In this example
|
||
the name specified in the application,
|
||
<code class="literal">jdbc/MySQLDataSource</code>, and the JNDI name,
|
||
happen to be the same, but this does not necessarily have to be
|
||
the case. Note that the XML element <res-ref-name> is used
|
||
to specify the name as used in the application source code, and
|
||
this is mapped to the JNDI name specified using the
|
||
<jndi-name> element, in the file
|
||
<code class="filename">sun-web.xml</code>. The resource also has to be
|
||
created in the <code class="filename">web.xml</code> file, although the
|
||
mapping of the resource to a JNDI name takes place in the
|
||
<code class="filename">sun-web.xml</code> file.
|
||
</p><p>
|
||
If you do not have this mapping set up correctly in the XML
|
||
files you will not be able to lookup the data source using a
|
||
JNDI lookup string such as:
|
||
</p><pre class="programlisting">
|
||
ds = (DataSource) ctx.lookup("java:comp/env/jdbc/MySQLDataSource");
|
||
</pre><p>
|
||
You will still be able to access the data source directly using:
|
||
</p><pre class="programlisting">
|
||
ds = (DataSource) ctx.lookup("jdbc/MySQLDataSource");
|
||
</pre><p>
|
||
With the source files in place, in the correct directory
|
||
structure, you are ready to deploy the application:
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
In the navigation tree, navigate to
|
||
<span class="guilabel">Applications</span> - the
|
||
<span class="guilabel">Applications</span> frame will be displayed.
|
||
Click <span class="guibutton">Deploy</span>.
|
||
</p></li><li class="listitem"><p>
|
||
You can now deploy an application packaged into a single WAR
|
||
file from a remote client, or you can choose a packaged file
|
||
or directory that is locally accessible to the server. If
|
||
you are simply testing an application locally you can simply
|
||
point GlassFish at the directory that contains your
|
||
application, without needing to package the application into
|
||
a WAR file.
|
||
</p></li><li class="listitem"><p>
|
||
Now select the application type from the
|
||
<span class="guilabel">Type</span> drop-down listbox, which in this
|
||
example is <code class="literal">Web application</code>.
|
||
</p></li><li class="listitem"><p>
|
||
Click OK.
|
||
</p></li></ol></div><p>
|
||
Now, when you navigate to the <span class="guilabel">Applications</span>
|
||
frame, you will have the option to <span class="guilabel">Launch</span>,
|
||
<span class="guilabel">Redeploy</span>, or <span class="guilabel">Restart</span>
|
||
your application. You can test your application by clicking
|
||
<span class="guilabel">Launch</span>. The application will connection to
|
||
the MySQL database and display the Name and Population of
|
||
countries in the <code class="literal">Country</code> table.
|
||
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-usagenotes-glassfish-config-servlet"></a>13.2 A Simple Servlet with GlassFish, Connector/J and MySQL</h2></div></div></div><a class="indexterm" name="idm140266685303936"></a><p>
|
||
This section describes a simple servlet that can be used in the
|
||
GlassFish environment to access a MySQL database. As with the
|
||
previous section, this example assumes the sample database
|
||
<code class="literal">world</code> is installed.
|
||
</p><p>
|
||
The project is set up with the following directory structure:
|
||
</p><pre class="programlisting">
|
||
index.html
|
||
WEB-INF
|
||
|
|
||
- web.xml
|
||
- sun-web.xml
|
||
- classes
|
||
|
|
||
- HelloWebServlet.java
|
||
- HelloWebServlet.class
|
||
</pre><p>
|
||
The code for the servlet, located in
|
||
<code class="filename">HelloWebServlet.java</code>, is as follows:
|
||
</p><pre class="programlisting">
|
||
|
||
import javax.servlet.http.*;
|
||
import javax.servlet.*;
|
||
import java.io.*;
|
||
import java.sql.*;
|
||
import javax.sql.*;
|
||
import javax.naming.*;
|
||
|
||
public class HelloWebServlet extends HttpServlet {
|
||
|
||
InitialContext ctx = null;
|
||
DataSource ds = null;
|
||
Connection conn = null;
|
||
PreparedStatement ps = null;
|
||
ResultSet rs = null;
|
||
|
||
String sql = "SELECT Name, Population FROM Country WHERE Name=?";
|
||
|
||
public void init () throws ServletException {
|
||
try {
|
||
ctx = new InitialContext();
|
||
ds = (DataSource) ctx.lookup("java:comp/env/jdbc/MySQLDataSource");
|
||
conn = ds.getConnection();
|
||
ps = conn.prepareStatement(sql);
|
||
}
|
||
catch (SQLException se) {
|
||
System.out.println("SQLException: "+se.getMessage());
|
||
}
|
||
catch (NamingException ne) {
|
||
System.out.println("NamingException: "+ne.getMessage());
|
||
}
|
||
}
|
||
|
||
public void destroy () {
|
||
try {
|
||
if (rs != null)
|
||
rs.close();
|
||
if (ps != null)
|
||
ps.close();
|
||
if (conn != null)
|
||
conn.close();
|
||
if (ctx != null)
|
||
ctx.close();
|
||
}
|
||
catch (SQLException se) {
|
||
System.out.println("SQLException: "+se.getMessage());
|
||
}
|
||
catch (NamingException ne) {
|
||
System.out.println("NamingException: "+ne.getMessage());
|
||
}
|
||
}
|
||
|
||
public void doPost(HttpServletRequest req, HttpServletResponse resp){
|
||
try {
|
||
String country_name = req.getParameter("country_name");
|
||
resp.setContentType("text/html");
|
||
PrintWriter writer = resp.getWriter();
|
||
writer.println("<html><body>");
|
||
writer.println("<p>Country: "+country_name+"</p>");
|
||
ps.setString(1, country_name);
|
||
rs = ps.executeQuery();
|
||
if (!rs.next()){
|
||
writer.println("<p>Country does not exist!</p>");
|
||
}
|
||
else {
|
||
rs.beforeFirst();
|
||
while(rs.next()) {
|
||
writer.println("<p>Name: "+rs.getString("Name")+"</p>");
|
||
writer.println("<p>Population: "+rs.getString("Population")+"</p>");
|
||
}
|
||
}
|
||
writer.println("</body></html>");
|
||
writer.close();
|
||
}
|
||
catch (Exception e) {
|
||
e.printStackTrace();
|
||
}
|
||
}
|
||
|
||
public void doGet(HttpServletRequest req, HttpServletResponse resp){
|
||
try {
|
||
resp.setContentType("text/html");
|
||
PrintWriter writer = resp.getWriter();
|
||
writer.println("<html><body>");
|
||
writer.println("<p>Hello from servlet doGet()</p>");
|
||
writer.println("</body></html>");
|
||
writer.close();
|
||
}
|
||
catch (Exception e) {
|
||
e.printStackTrace();
|
||
}
|
||
}
|
||
}
|
||
|
||
</pre><p>
|
||
In the preceding code a basic <code class="literal">doGet()</code> method
|
||
is implemented, but is not used in the example. The code to
|
||
establish the connection with the database is as shown in the
|
||
previous example,
|
||
<a class="xref" href="#connector-j-usagenotes-glassfish-config-jsp" title="13.1 A Simple JSP Application with GlassFish, Connector/J and MySQL">Section 13.1, “A Simple JSP Application with GlassFish, Connector/J and MySQL”</a>,
|
||
and is most conveniently located in the servlet
|
||
<code class="literal">init()</code> method. The corresponding freeing of
|
||
resources is located in the destroy method. The main
|
||
functionality of the servlet is located in the
|
||
<code class="literal">doPost()</code> method. If the user enters into the
|
||
input form a country name that can be located in the database,
|
||
the population of the country is returned. The code is invoked
|
||
using a POST action associated with the input form. The form is
|
||
defined in the file <code class="filename">index.html</code>:
|
||
</p><pre class="programlisting">
|
||
|
||
<html>
|
||
<head><title>HelloWebServlet</title></head>
|
||
|
||
<body>
|
||
<h1>HelloWebServlet</h1>
|
||
|
||
<p>Please enter country name:</p>
|
||
|
||
<form action="HelloWebServlet" method="POST">
|
||
<input type="text" name="country_name" length="50" />
|
||
<input type="submit" value="Submit" />
|
||
</form>
|
||
|
||
</body>
|
||
</html>
|
||
|
||
</pre><p>
|
||
The XML files <code class="filename">web.xml</code> and
|
||
<code class="filename">sun-web.xml</code> are as for the example in the
|
||
preceding section,
|
||
<a class="xref" href="#connector-j-usagenotes-glassfish-config-jsp" title="13.1 A Simple JSP Application with GlassFish, Connector/J and MySQL">Section 13.1, “A Simple JSP Application with GlassFish, Connector/J and MySQL”</a>,
|
||
no additional changes are required.
|
||
</p><p>
|
||
When compiling the Java source code, you will need to specify
|
||
the path to the file <code class="filename">javaee.jar</code>. On
|
||
Windows, this can be done as follows:
|
||
</p><pre class="programlisting">
|
||
shell> javac -classpath c:\glassfishv3\glassfish\lib\javaee.jar HelloWebServlet.java
|
||
</pre><p>
|
||
Once the code is correctly located within its directory
|
||
structure, and compiled, the application can be deployed in
|
||
GlassFish. This is done in exactly the same way as described in
|
||
the preceding section,
|
||
<a class="xref" href="#connector-j-usagenotes-glassfish-config-jsp" title="13.1 A Simple JSP Application with GlassFish, Connector/J and MySQL">Section 13.1, “A Simple JSP Application with GlassFish, Connector/J and MySQL”</a>.
|
||
</p><p>
|
||
Once deployed the application can be launched from within the
|
||
GlassFish Administration Console. Enter a country name such as
|
||
<span class="quote">“<span class="quote">England</span>”</span>, and the application will return
|
||
<span class="quote">“<span class="quote">Country does not exist!</span>”</span>. Enter
|
||
<span class="quote">“<span class="quote">France</span>”</span>, and the application will return a
|
||
population of 59225700.
|
||
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-fabric"></a>Chapter 14 Using Connector/J with MySQL Fabric</h1></div></div></div><a class="indexterm" name="idm140266685279584"></a><p>
|
||
MySQL Fabric is a system for managing a farm of MySQL servers (and
|
||
other components). Fabric provides an extensible and easy to use
|
||
system for managing a MySQL deployment for sharding and
|
||
high-availability.
|
||
</p><p>
|
||
For more information on MySQL Fabric, see
|
||
<a class="ulink" href="http://dev.mysql.com/doc/mysql-utilities/1.5/en/fabric.html" target="_top">MySQL Fabric</a>. For instructions on how to use
|
||
Connector/J with MySQL Fabric, see
|
||
<a class="ulink" href="http://dev.mysql.com/doc/mysql-utilities/1.5/en/connector-j-fabric.html" target="_top">Using Connector/J with MySQL Fabric</a>.
|
||
</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-troubleshooting"></a>Chapter 15 Troubleshooting Connector/J Applications</h1></div></div></div><a class="indexterm" name="idm140266685274480"></a><a class="indexterm" name="idm140266685272992"></a><a class="indexterm" name="idm140266685271504"></a><p>
|
||
This section explains the symptoms and resolutions for the most
|
||
commonly encountered issues with applications using MySQL
|
||
Connector/J.
|
||
</p><p><span class="bold"><strong>Questions</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="link" href="#qandaitem-15-1-1">15.1: </a>
|
||
When I try to connect to the database with MySQL
|
||
Connector/J, I get the following exception:
|
||
</p><pre class="programlisting">
|
||
SQLException: Server configuration denies access to data source
|
||
SQLState: 08001
|
||
VendorError: 0
|
||
</pre><p>
|
||
What is going on? I can connect just fine with the MySQL
|
||
command-line client.
|
||
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-2">15.2: </a>
|
||
My application throws an SQLException 'No Suitable Driver'.
|
||
Why is this happening?
|
||
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-3">15.3: </a>
|
||
I'm trying to use MySQL Connector/J in an applet or
|
||
application and I get an exception similar to:
|
||
</p><pre class="programlisting">
|
||
SQLException: Cannot connect to MySQL server on host:3306.
|
||
Is there a MySQL server running on the machine/port you
|
||
are trying to connect to?
|
||
|
||
(java.security.AccessControlException)
|
||
SQLState: 08S01
|
||
VendorError: 0
|
||
</pre></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-4">15.4: </a>
|
||
I have a servlet/application that works fine for a day, and
|
||
then stops working overnight
|
||
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-5">15.5: </a>
|
||
I'm trying to use JDBC 2.0 updatable result sets, and I get
|
||
an exception saying my result set is not updatable.
|
||
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-6">15.6: </a>
|
||
I cannot connect to the MySQL server using Connector/J, and
|
||
I'm sure the connection parameters are correct.
|
||
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-7">15.7: </a>
|
||
I am trying to connect to my MySQL server within my
|
||
application, but I get the following error and stack trace:
|
||
</p><pre class="programlisting">
|
||
java.net.SocketException
|
||
MESSAGE: Software caused connection abort: recv failed
|
||
|
||
STACKTRACE:
|
||
|
||
java.net.SocketException: Software caused connection abort: recv failed
|
||
at java.net.SocketInputStream.socketRead0(Native Method)
|
||
at java.net.SocketInputStream.read(Unknown Source)
|
||
at com.mysql.jdbc.MysqlIO.readFully(MysqlIO.java:1392)
|
||
at com.mysql.jdbc.MysqlIO.readPacket(MysqlIO.java:1414)
|
||
at com.mysql.jdbc.MysqlIO.doHandshake(MysqlIO.java:625)
|
||
at com.mysql.jdbc.Connection.createNewIO(Connection.java:1926)
|
||
at com.mysql.jdbc.Connection.<init>(Connection.java:452)
|
||
at com.mysql.jdbc.NonRegisteringDriver.connect(NonRegisteringDriver.java:411)
|
||
</pre></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-8">15.8: </a>
|
||
My application is deployed through JBoss and I am using
|
||
transactions to handle the statements on the MySQL database.
|
||
Under heavy loads, I am getting an error and stack trace,
|
||
but these only occur after a fixed period of heavy activity.
|
||
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-9">15.9: </a>
|
||
When using <span class="command"><strong>gcj</strong></span>, a
|
||
<code class="literal">java.io.CharConversionException</code> exception
|
||
is raised when working with certain character sequences.
|
||
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-10">15.10: </a>
|
||
Updating a table that contains a
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/glossary.html#glos_primary_key" target="_top">primary key</a> that is
|
||
either <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a> or compound
|
||
primary key that uses <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a>
|
||
fails to update the table and raises an exception.
|
||
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-11">15.11: </a>
|
||
You get an
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/error-messages-server.html#error_er_net_packet_too_large" target="_top"><code class="literal">ER_NET_PACKET_TOO_LARGE</code></a>
|
||
exception, even though the binary blob size you want to
|
||
insert using JDBC is safely below the
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_max_allowed_packet" target="_top"><code class="literal">max_allowed_packet</code></a> size.
|
||
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-12">15.12: </a>
|
||
What should you do if you receive error messages similar to
|
||
the following: <span class="quote">“<span class="quote">Communications link failure – Last
|
||
packet sent to the server was X ms ago</span>”</span>?
|
||
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-13">15.13: </a>
|
||
Why does Connector/J not reconnect to MySQL and re-issue the
|
||
statement after a communication failure, instead of throwing
|
||
an Exception, even though I use the
|
||
<code class="literal">autoReconnect</code> connection string option?
|
||
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-14">15.14: </a>
|
||
How can I use 3-byte UTF8 with Connector/J?
|
||
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-15">15.15: </a>
|
||
How can I use 4-byte UTF8, <code class="literal">utf8mb4</code> with
|
||
Connector/J?
|
||
</p></li><li class="listitem"><p><a class="link" href="#qandaitem-15-1-16">15.16: </a>
|
||
Using <code class="literal">useServerPrepStmts=false</code> and
|
||
certain character encodings can lead to corruption when
|
||
inserting BLOBs. How can this be avoided?
|
||
</p></li></ul></div><p><span class="bold"><strong>Questions and Answers</strong></span></p><p><a name="qandaitem-15-1-1"></a><span class="bold"><strong>15.1: </strong></span><span class="bold"><strong>
|
||
When I try to connect to the database with MySQL
|
||
Connector/J, I get the following exception:
|
||
</strong></span></p><pre class="programlisting">
|
||
SQLException: Server configuration denies access to data source
|
||
SQLState: 08001
|
||
VendorError: 0
|
||
</pre><p><span class="bold"><strong>
|
||
What is going on? I can connect just fine with the MySQL
|
||
command-line client.
|
||
</strong></span></p><p>
|
||
MySQL Connector/J must use TCP/IP sockets to connect to
|
||
MySQL, as Java does not support Unix Domain Sockets.
|
||
Therefore, when MySQL Connector/J connects to MySQL, the
|
||
security manager in MySQL server will use its grant tables
|
||
to determine whether the connection is permitted.
|
||
</p><p>
|
||
You must add the necessary security credentials to the MySQL
|
||
server for this to happen, using the
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/grant.html" target="_top"><code class="literal">GRANT</code></a> statement to your MySQL
|
||
Server. See <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/grant.html" target="_top">GRANT Syntax</a>, for more information.
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
|
||
Testing your connectivity with the
|
||
<span class="command"><strong>mysql</strong></span> command-line client will not work
|
||
unless you add the "host" flag, and use something other
|
||
than <code class="literal">localhost</code> for the host. The
|
||
<span class="command"><strong>mysql</strong></span> command-line client will use Unix
|
||
domain sockets if you use the special host name
|
||
<code class="literal">localhost</code>. If you are testing
|
||
connectivity to <code class="literal">localhost</code>, use
|
||
<code class="literal">127.0.0.1</code> as the host name instead.
|
||
</p></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Warning</div><p>
|
||
Changing privileges and permissions improperly in MySQL
|
||
can potentially cause your server installation to not have
|
||
optimal security properties.
|
||
</p></div><p><a name="qandaitem-15-1-2"></a><span class="bold"><strong>15.2: </strong></span><span class="bold"><strong>
|
||
My application throws an SQLException 'No Suitable Driver'.
|
||
Why is this happening?
|
||
</strong></span></p><p>
|
||
There are three possible causes for this error:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
The Connector/J driver is not in your
|
||
<code class="literal">CLASSPATH</code>, see
|
||
<a class="xref" href="#connector-j-installing" title="Chapter 3 Connector/J Installation">Chapter 3, <i>Connector/J Installation</i></a>.
|
||
</p></li><li class="listitem"><p>
|
||
The format of your connection URL is incorrect, or you
|
||
are referencing the wrong JDBC driver.
|
||
</p></li><li class="listitem"><p>
|
||
When using DriverManager, the
|
||
<code class="literal">jdbc.drivers</code> system property has not
|
||
been populated with the location of the Connector/J
|
||
driver.
|
||
</p></li></ul></div><p><a name="qandaitem-15-1-3"></a><span class="bold"><strong>15.3: </strong></span><span class="bold"><strong>
|
||
I'm trying to use MySQL Connector/J in an applet or
|
||
application and I get an exception similar to:
|
||
</strong></span></p><pre class="programlisting">
|
||
SQLException: Cannot connect to MySQL server on host:3306.
|
||
Is there a MySQL server running on the machine/port you
|
||
are trying to connect to?
|
||
|
||
(java.security.AccessControlException)
|
||
SQLState: 08S01
|
||
VendorError: 0
|
||
</pre><p>
|
||
Either you're running an Applet, your MySQL server has been
|
||
installed with the "skip-networking" option set, or your
|
||
MySQL server has a firewall sitting in front of it.
|
||
</p><p>
|
||
Applets can only make network connections back to the
|
||
machine that runs the web server that served the .class
|
||
files for the applet. This means that MySQL must run on the
|
||
same machine (or you must have some sort of port
|
||
re-direction) for this to work. This also means that you
|
||
will not be able to test applets from your local file
|
||
system, you must always deploy them to a web server.
|
||
</p><p>
|
||
MySQL Connector/J can only communicate with MySQL using
|
||
TCP/IP, as Java does not support Unix domain sockets. TCP/IP
|
||
communication with MySQL might be affected if MySQL was
|
||
started with the "skip-networking" flag, or if it is
|
||
firewalled.
|
||
</p><p>
|
||
If MySQL has been started with the "skip-networking" option
|
||
set (the Debian Linux package of MySQL server does this for
|
||
example), you need to comment it out in the file
|
||
<code class="filename">/etc/mysql/my.cnf</code> or
|
||
<code class="filename">/etc/my.cnf</code>. Of course your
|
||
<code class="filename">my.cnf</code> file might also exist in the
|
||
<code class="filename">data</code> directory of your MySQL server, or
|
||
anywhere else (depending on how MySQL was compiled for your
|
||
system). Binaries created by us always look in
|
||
<code class="filename">/etc/my.cnf</code> and
|
||
<code class="filename"><em class="replaceable"><code>datadir</code></em>/my.cnf</code>.
|
||
If your MySQL server has been firewalled, you will need to
|
||
have the firewall configured to allow TCP/IP connections
|
||
from the host where your Java code is running to the MySQL
|
||
server on the port that MySQL is listening to (by default,
|
||
3306).
|
||
</p><p><a name="qandaitem-15-1-4"></a><span class="bold"><strong>15.4: </strong></span><span class="bold"><strong>
|
||
I have a servlet/application that works fine for a day, and
|
||
then stops working overnight
|
||
</strong></span></p><p>
|
||
MySQL closes connections after 8 hours of inactivity. You
|
||
either need to use a connection pool that handles stale
|
||
connections or use the <code class="option">autoReconnect</code>
|
||
parameter (see
|
||
<a class="xref" href="#connector-j-reference-configuration-properties" title="5.1 Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">Section 5.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties
|
||
for Connector/J”</a>).
|
||
</p><p>
|
||
Also, catch <code class="literal">SQLExceptions</code> in your
|
||
application and deal with them, rather than propagating them
|
||
all the way until your application exits. This is just good
|
||
programming practice. MySQL Connector/J will set the
|
||
<code class="literal">SQLState</code> (see
|
||
<code class="literal">java.sql.SQLException.getSQLState()</code> in
|
||
your API docs) to <code class="literal">08S01</code> when it
|
||
encounters network-connectivity issues during the processing
|
||
of a query. Attempt to reconnect to MySQL at this point.
|
||
</p><p>
|
||
The following (simplistic) example shows what code that can
|
||
handle these exceptions might look like:
|
||
</p><p>
|
||
</p><div class="example"><a name="connector-j-examples-transaction-retry"></a><p class="title"><b>Example 15.1 Connector/J: Example of transaction with retry logic</b></p><div class="example-contents"><pre class="programlisting">
|
||
public void doBusinessOp() throws SQLException {
|
||
Connection conn = null;
|
||
Statement stmt = null;
|
||
ResultSet rs = null;
|
||
|
||
//
|
||
// How many times do you want to retry the transaction
|
||
// (or at least _getting_ a connection)?
|
||
//
|
||
int retryCount = 5;
|
||
|
||
boolean transactionCompleted = false;
|
||
|
||
do {
|
||
try {
|
||
conn = getConnection(); // assume getting this from a
|
||
// javax.sql.DataSource, or the
|
||
// java.sql.DriverManager
|
||
|
||
conn.setAutoCommit(false);
|
||
|
||
//
|
||
// Okay, at this point, the 'retry-ability' of the
|
||
// transaction really depends on your application logic,
|
||
// whether or not you're using autocommit (in this case
|
||
// not), and whether you're using transactional storage
|
||
// engines
|
||
//
|
||
// For this example, we'll assume that it's _not_ safe
|
||
// to retry the entire transaction, so we set retry
|
||
// count to 0 at this point
|
||
//
|
||
// If you were using exclusively transaction-safe tables,
|
||
// or your application could recover from a connection going
|
||
// bad in the middle of an operation, then you would not
|
||
// touch 'retryCount' here, and just let the loop repeat
|
||
// until retryCount == 0.
|
||
//
|
||
retryCount = 0;
|
||
|
||
stmt = conn.createStatement();
|
||
|
||
String query = "SELECT foo FROM bar ORDER BY baz";
|
||
|
||
rs = stmt.executeQuery(query);
|
||
|
||
while (rs.next()) {
|
||
}
|
||
|
||
rs.close();
|
||
rs = null;
|
||
|
||
stmt.close();
|
||
stmt = null;
|
||
|
||
conn.commit();
|
||
conn.close();
|
||
conn = null;
|
||
|
||
transactionCompleted = true;
|
||
} catch (SQLException sqlEx) {
|
||
|
||
//
|
||
// The two SQL states that are 'retry-able' are 08S01
|
||
// for a communications error, and 40001 for deadlock.
|
||
//
|
||
// Only retry if the error was due to a stale connection,
|
||
// communications problem or deadlock
|
||
//
|
||
|
||
String sqlState = sqlEx.getSQLState();
|
||
|
||
if ("08S01".equals(sqlState) || "40001".equals(sqlState)) {
|
||
retryCount -= 1;
|
||
} else {
|
||
retryCount = 0;
|
||
}
|
||
} finally {
|
||
if (rs != null) {
|
||
try {
|
||
rs.close();
|
||
} catch (SQLException sqlEx) {
|
||
// You'd probably want to log this...
|
||
}
|
||
}
|
||
|
||
if (stmt != null) {
|
||
try {
|
||
stmt.close();
|
||
} catch (SQLException sqlEx) {
|
||
// You'd probably want to log this as well...
|
||
}
|
||
}
|
||
|
||
if (conn != null) {
|
||
try {
|
||
//
|
||
// If we got here, and conn is not null, the
|
||
// transaction should be rolled back, as not
|
||
// all work has been done
|
||
|
||
try {
|
||
conn.rollback();
|
||
} finally {
|
||
conn.close();
|
||
}
|
||
} catch (SQLException sqlEx) {
|
||
//
|
||
// If we got an exception here, something
|
||
// pretty serious is going on, so we better
|
||
// pass it up the stack, rather than just
|
||
// logging it...
|
||
|
||
throw sqlEx;
|
||
}
|
||
}
|
||
}
|
||
} while (!transactionCompleted && (retryCount > 0));
|
||
}
|
||
</pre></div></div><p><br class="example-break">
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
|
||
Use of the <code class="option">autoReconnect</code> option is not
|
||
recommended because there is no safe method of
|
||
reconnecting to the MySQL server without risking some
|
||
corruption of the connection state or database state
|
||
information. Instead, use a connection pool, which will
|
||
enable your application to connect to the MySQL server
|
||
using an available connection from the pool. The
|
||
<code class="option">autoReconnect</code> facility is deprecated, and
|
||
may be removed in a future release.
|
||
</p></div><p><a name="qandaitem-15-1-5"></a><span class="bold"><strong>15.5: </strong></span><span class="bold"><strong>
|
||
I'm trying to use JDBC 2.0 updatable result sets, and I get
|
||
an exception saying my result set is not updatable.
|
||
</strong></span></p><p>
|
||
Because MySQL does not have row identifiers, MySQL
|
||
Connector/J can only update result sets that have come from
|
||
queries on tables that have at least one
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/glossary.html#glos_primary_key" target="_top">primary key</a>, the
|
||
query must select every primary key column, and the query
|
||
can only span one table (that is, no joins). This is
|
||
outlined in the JDBC specification.
|
||
</p><p>
|
||
Note that this issue only occurs when using updatable result
|
||
sets, and is caused because Connector/J is unable to
|
||
guarantee that it can identify the correct rows within the
|
||
result set to be updated without having a unique reference
|
||
to each row. There is no requirement to have a unique field
|
||
on a table if you are using
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/update.html" target="_top"><code class="literal">UPDATE</code></a> or
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/delete.html" target="_top"><code class="literal">DELETE</code></a> statements on a table
|
||
where you can individually specify the criteria to be
|
||
matched using a <code class="literal">WHERE</code> clause.
|
||
</p><p><a name="qandaitem-15-1-6"></a><span class="bold"><strong>15.6: </strong></span><span class="bold"><strong>
|
||
I cannot connect to the MySQL server using Connector/J, and
|
||
I'm sure the connection parameters are correct.
|
||
</strong></span></p><p>
|
||
Make sure that the
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/server-options.html#option_mysqld_skip-networking" target="_top"><code class="option">skip-networking</code></a> option has
|
||
not been enabled on your server. Connector/J must be able to
|
||
communicate with your server over TCP/IP; named sockets are
|
||
not supported. Also ensure that you are not filtering
|
||
connections through a firewall or other network security
|
||
system. For more information, see
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/can-not-connect-to-server.html" target="_top">Can't connect to [local] MySQL server</a>.
|
||
</p><p><a name="qandaitem-15-1-7"></a><span class="bold"><strong>15.7: </strong></span><span class="bold"><strong>
|
||
I am trying to connect to my MySQL server within my
|
||
application, but I get the following error and stack trace:
|
||
</strong></span></p><pre class="programlisting">
|
||
java.net.SocketException
|
||
MESSAGE: Software caused connection abort: recv failed
|
||
|
||
STACKTRACE:
|
||
|
||
java.net.SocketException: Software caused connection abort: recv failed
|
||
at java.net.SocketInputStream.socketRead0(Native Method)
|
||
at java.net.SocketInputStream.read(Unknown Source)
|
||
at com.mysql.jdbc.MysqlIO.readFully(MysqlIO.java:1392)
|
||
at com.mysql.jdbc.MysqlIO.readPacket(MysqlIO.java:1414)
|
||
at com.mysql.jdbc.MysqlIO.doHandshake(MysqlIO.java:625)
|
||
at com.mysql.jdbc.Connection.createNewIO(Connection.java:1926)
|
||
at com.mysql.jdbc.Connection.<init>(Connection.java:452)
|
||
at com.mysql.jdbc.NonRegisteringDriver.connect(NonRegisteringDriver.java:411)
|
||
</pre><p>
|
||
The error probably indicates that you are using a older
|
||
version of the Connector/J JDBC driver (2.0.14 or 3.0.x) and
|
||
you are trying to connect to a MySQL server with version
|
||
4.1x or newer. The older drivers are not compatible with 4.1
|
||
or newer of MySQL as they do not support the newer
|
||
authentication mechanisms.
|
||
</p><p>
|
||
It is likely that the older version of the Connector/J
|
||
driver exists within your application directory or your
|
||
<code class="literal">CLASSPATH</code> includes the older Connector/J
|
||
package.
|
||
</p><p><a name="qandaitem-15-1-8"></a><span class="bold"><strong>15.8: </strong></span><span class="bold"><strong>
|
||
My application is deployed through JBoss and I am using
|
||
transactions to handle the statements on the MySQL database.
|
||
Under heavy loads, I am getting an error and stack trace,
|
||
but these only occur after a fixed period of heavy activity.
|
||
</strong></span></p><p>
|
||
This is a JBoss, not Connector/J, issue and is connected to
|
||
the use of transactions. Under heavy loads the time taken
|
||
for transactions to complete can increase, and the error is
|
||
caused because you have exceeded the predefined timeout.
|
||
</p><p>
|
||
You can increase the timeout value by setting the
|
||
<code class="literal">TransactionTimeout</code> attribute to the
|
||
<code class="literal">TransactionManagerService</code> within the
|
||
<code class="filename">/conf/jboss-service.xml</code> file
|
||
(pre-4.0.3) or <code class="filename">/deploy/jta-service.xml</code>
|
||
for JBoss 4.0.3 or later. See
|
||
<a class="ulink" href="http://wiki.jboss.org/wiki/Wiki.jsp?page=TransactionTimeout" target="_top">TransactionTimeout</a>
|
||
within the JBoss wiki for more information.
|
||
</p><p><a name="qandaitem-15-1-9"></a><span class="bold"><strong>15.9: </strong></span><span class="bold"><strong>
|
||
When using <span class="command"><strong>gcj</strong></span>, a
|
||
<code class="literal">java.io.CharConversionException</code> exception
|
||
is raised when working with certain character sequences.
|
||
</strong></span></p><p>
|
||
This is a known issue with <span class="command"><strong>gcj</strong></span> which
|
||
raises an exception when it reaches an unknown character or
|
||
one it cannot convert. Add
|
||
<code class="literal">useJvmCharsetConverters=true</code> to your
|
||
connection string to force character conversion outside of
|
||
the <span class="command"><strong>gcj</strong></span> libraries, or try a different
|
||
JDK.
|
||
</p><p><a name="qandaitem-15-1-10"></a><span class="bold"><strong>15.10: </strong></span><span class="bold"><strong>
|
||
Updating a table that contains a
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/glossary.html#glos_primary_key" target="_top">primary key</a> that is
|
||
either <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a> or compound
|
||
primary key that uses <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a>
|
||
fails to update the table and raises an exception.
|
||
</strong></span></p><p>
|
||
Connector/J adds conditions to the <code class="literal">WHERE</code>
|
||
clause during an <a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/update.html" target="_top"><code class="literal">UPDATE</code></a> to
|
||
check the old values of the primary key. If there is no
|
||
match, then Connector/J considers this a failure condition
|
||
and raises an exception.
|
||
</p><p>
|
||
The problem is that rounding differences between supplied
|
||
values and the values stored in the database may mean that
|
||
the values never match, and hence the update fails. The
|
||
issue will affect all queries, not just those from
|
||
Connector/J.
|
||
</p><p>
|
||
To prevent this issue, use a primary key that does not use
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a>. If you have to use a
|
||
floating point column in your primary key, use
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/floating-point-types.html" target="_top"><code class="literal">DOUBLE</code></a> or
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/fixed-point-types.html" target="_top"><code class="literal">DECIMAL</code></a> types in place of
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/floating-point-types.html" target="_top"><code class="literal">FLOAT</code></a>.
|
||
</p><p><a name="qandaitem-15-1-11"></a><span class="bold"><strong>15.11: </strong></span><span class="bold"><strong>
|
||
You get an
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/error-messages-server.html#error_er_net_packet_too_large" target="_top"><code class="literal">ER_NET_PACKET_TOO_LARGE</code></a>
|
||
exception, even though the binary blob size you want to
|
||
insert using JDBC is safely below the
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_max_allowed_packet" target="_top"><code class="literal">max_allowed_packet</code></a> size.
|
||
</strong></span></p><p>
|
||
This is because the <code class="literal">hexEscapeBlock()</code>
|
||
method in
|
||
<code class="literal">com.mysql.jdbc.PreparedStatement.streamToBytes()</code>
|
||
may almost double the size of your data.
|
||
</p><p><a name="qandaitem-15-1-12"></a><span class="bold"><strong>15.12: </strong></span><span class="bold"><strong>
|
||
What should you do if you receive error messages similar to
|
||
the following: <span class="quote">“<span class="quote">Communications link failure – Last
|
||
packet sent to the server was X ms ago</span>”</span>?
|
||
</strong></span></p><p>
|
||
Generally speaking, this error suggests that the network
|
||
connection has been closed. There can be several root
|
||
causes:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
Firewalls or routers may clamp down on idle connections
|
||
(the MySQL client/server protocol does not ping).
|
||
</p></li><li class="listitem"><p>
|
||
The MySQL Server may be closing idle connections that
|
||
exceed the <code class="literal">wait_timeout</code> or
|
||
<code class="literal">interactive_timeout</code> threshold.
|
||
</p></li></ul></div><p>
|
||
To help troubleshoot these issues, the following tips can be
|
||
used. If a recent (5.1.13+) version of Connector/J is used,
|
||
you will see an improved level of information compared to
|
||
earlier versions. Older versions simply display the last
|
||
time a packet was sent to the server, which is frequently 0
|
||
ms ago. This is of limited use, as it may be that a packet
|
||
was just sent, while a packet from the server has not been
|
||
received for several hours. Knowing the period of time since
|
||
Connector/J last received a packet from the server is useful
|
||
information, so if this is not displayed in your exception
|
||
message, it is recommended that you update Connector/J.
|
||
</p><p>
|
||
Further, if the time a packet was last sent/received exceeds
|
||
the <code class="literal">wait_timeout</code> or
|
||
<code class="literal">interactive_timeout</code> threshold, this is
|
||
noted in the exception message.
|
||
</p><p>
|
||
Although network connections can be volatile, the following
|
||
can be helpful in avoiding problems:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
Ensure connections are valid when used from the
|
||
connection pool. Use a query that starts with
|
||
<code class="literal">/* ping */</code> to execute a lightweight
|
||
ping instead of full query. Note, the syntax of the ping
|
||
needs to be exactly as specified here.
|
||
</p></li><li class="listitem"><p>
|
||
Minimize the duration a connection object is left idle
|
||
while other application logic is executed.
|
||
</p></li><li class="listitem"><p>
|
||
Explicitly validate the connection before using it if
|
||
the connection has been left idle for an extended period
|
||
of time.
|
||
</p></li><li class="listitem"><p>
|
||
Ensure that <code class="literal">wait_timeout</code> and
|
||
<code class="literal">interactive_timeout</code> are set
|
||
sufficiently high.
|
||
</p></li><li class="listitem"><p>
|
||
Ensure that <code class="literal">tcpKeepalive</code> is enabled.
|
||
</p></li><li class="listitem"><p>
|
||
Ensure that any configurable firewall or router timeout
|
||
settings allow for the maximum expected connection idle
|
||
time.
|
||
</p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p>
|
||
Do not expect to be able to reuse a connection without
|
||
problems, if it has being lying idle for a period. If a
|
||
connection is to be reused after being idle for any length
|
||
of time, ensure that you explicitly test it before reusing
|
||
it.
|
||
</p></div><p><a name="qandaitem-15-1-13"></a><span class="bold"><strong>15.13: </strong></span><span class="bold"><strong>
|
||
Why does Connector/J not reconnect to MySQL and re-issue the
|
||
statement after a communication failure, instead of throwing
|
||
an Exception, even though I use the
|
||
<code class="literal">autoReconnect</code> connection string option?
|
||
</strong></span></p><p>
|
||
There are several reasons for this. The first is
|
||
transactional integrity. The MySQL Reference Manual states
|
||
that <span class="quote">“<span class="quote">there is no safe method of reconnecting to the
|
||
MySQL server without risking some corruption of the
|
||
connection state or database state information</span>”</span>.
|
||
Consider the following series of statements for example:
|
||
</p><pre class="programlisting">
|
||
|
||
conn.createStatement().execute(
|
||
"UPDATE checking_account SET balance = balance - 1000.00 WHERE customer='Smith'");
|
||
conn.createStatement().execute(
|
||
"UPDATE savings_account SET balance = balance + 1000.00 WHERE customer='Smith'");
|
||
conn.commit();
|
||
|
||
</pre><p>
|
||
Consider the case where the connection to the server fails
|
||
after the <code class="literal">UPDATE</code> to
|
||
<code class="literal">checking_account</code>. If no exception is
|
||
thrown, and the application never learns about the problem,
|
||
it will continue executing. However, the server did not
|
||
commit the first transaction in this case, so that will get
|
||
rolled back. But execution continues with the next
|
||
transaction, and increases the
|
||
<code class="literal">savings_account</code> balance by 1000. The
|
||
application did not receive an exception, so it continued
|
||
regardless, eventually committing the second transaction, as
|
||
the commit only applies to the changes made in the new
|
||
connection. Rather than a transfer taking place, a deposit
|
||
was made in this example.
|
||
</p><p>
|
||
Note that running with <code class="literal">autocommit</code> enabled
|
||
does not solve this problem. When Connector/J encounters a
|
||
communication problem, there is no means to determine
|
||
whether the server processed the currently executing
|
||
statement or not. The following theoretical states are
|
||
equally possible:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
The server never received the statement, and therefore
|
||
no related processing occurred on the server.
|
||
</p></li><li class="listitem"><p>
|
||
The server received the statement, executed it in full,
|
||
but the response was not received by the client.
|
||
</p></li></ul></div><p>
|
||
If you are running with <code class="literal">autocommit</code>
|
||
enabled, it is not possible to guarantee the state of data
|
||
on the server when a communication exception is encountered.
|
||
The statement may have reached the server, or it may not.
|
||
All you know is that communication failed at some point,
|
||
before the client received confirmation (or data) from the
|
||
server. This does not only affect
|
||
<code class="literal">autocommit</code> statements though. If the
|
||
communication problem occurred during
|
||
<code class="literal">Connection.commit()</code>, the question arises
|
||
of whether the transaction was committed on the server
|
||
before the communication failed, or whether the server
|
||
received the commit request at all.
|
||
</p><p>
|
||
The second reason for the generation of exceptions is that
|
||
transaction-scoped contextual data may be vulnerable, for
|
||
example:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
Temporary tables.
|
||
</p></li><li class="listitem"><p>
|
||
User-defined variables.
|
||
</p></li><li class="listitem"><p>
|
||
Server-side prepared statements.
|
||
</p></li></ul></div><p>
|
||
These items are lost when a connection fails, and if the
|
||
connection silently reconnects without generating an
|
||
exception, this could be detrimental to the correct
|
||
execution of your application.
|
||
</p><p>
|
||
In summary, communication errors generate conditions that
|
||
may well be unsafe for Connector/J to simply ignore by
|
||
silently reconnecting. It is necessary for the application
|
||
to be notified. It is then for the application developer to
|
||
decide how to proceed in the event of connection errors and
|
||
failures.
|
||
</p><p><a name="qandaitem-15-1-14"></a><span class="bold"><strong>15.14: </strong></span><span class="bold"><strong>
|
||
How can I use 3-byte UTF8 with Connector/J?
|
||
</strong></span></p><p>
|
||
To use 3-byte UTF8 with Connector/J set
|
||
<code class="literal">characterEncoding=utf8</code> and set
|
||
<code class="literal">useUnicode=true</code> in the connection string.
|
||
</p><p><a name="qandaitem-15-1-15"></a><span class="bold"><strong>15.15: </strong></span><span class="bold"><strong>
|
||
How can I use 4-byte UTF8, <code class="literal">utf8mb4</code> with
|
||
Connector/J?
|
||
</strong></span></p><p>
|
||
To use 4-byte UTF8 with Connector/J configure the MySQL
|
||
server with <code class="literal">character_set_server=utf8mb4</code>.
|
||
Connector/J will then use that setting as long as
|
||
<code class="literal">characterEncoding</code> has not been set in the
|
||
connection string. This is equivalent to autodetection of
|
||
the character set.
|
||
</p><p><a name="qandaitem-15-1-16"></a><span class="bold"><strong>15.16: </strong></span><span class="bold"><strong>
|
||
Using <code class="literal">useServerPrepStmts=false</code> and
|
||
certain character encodings can lead to corruption when
|
||
inserting BLOBs. How can this be avoided?
|
||
</strong></span></p><p>
|
||
When using certain character encodings, such as SJIS, CP932,
|
||
and BIG5, it is possible that BLOB data contains characters
|
||
that can be interpreted as control characters, for example,
|
||
backslash, '\'. This can lead to corrupted data when
|
||
inserting BLOBs into the database. There are two things that
|
||
need to be done to avoid this:
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
Set the connection string option
|
||
<code class="literal">useServerPrepStmts</code> to
|
||
<code class="literal">true</code>.
|
||
</p></li><li class="listitem"><p>
|
||
Set <code class="literal">SQL_MODE</code> to
|
||
<code class="literal">NO_BACKSLASH_ESCAPES</code>.
|
||
</p></li></ol></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-usagenotes-known-issues-limitations"></a>Chapter 16 Known Issues and Limitations</h1></div></div></div><a class="indexterm" name="idm140266685073280"></a><a class="indexterm" name="idm140266685071792"></a><a class="indexterm" name="idm140266685070304"></a><a class="indexterm" name="idm140266685068816"></a><a class="indexterm" name="idm140266685067328"></a><p>
|
||
The following are some known issues and limitations for MySQL
|
||
Connector/J:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
When Connector/J retrieves timestamps for a daylight saving
|
||
time (DST) switch day using the
|
||
<code class="function">getTimeStamp()</code> method on the result set,
|
||
some of the returned values might be wrong. The errors can be
|
||
avoided by using the following connection options when
|
||
connecting to a database:
|
||
|
||
</p><pre class="programlisting">
|
||
useTimezone=true
|
||
useLegacyDatetimeCode=false
|
||
serverTimezone=UTC
|
||
</pre><p>
|
||
</p></li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-j-support"></a>Chapter 17 Connector/J Support</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#connector-j-support-community">17.1 Connector/J Community Support</a></span></dt><dt><span class="section"><a href="#connector-j-support-bug-report">17.2 How to Report Connector/J Bugs or Problems</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-support-community"></a>17.1 Connector/J Community Support</h2></div></div></div><p>
|
||
Oracle provides assistance to the user community by means of its
|
||
mailing lists. For Connector/J related issues, you can get help
|
||
from experienced users by using the MySQL and Java mailing list.
|
||
Archives and subscription information is available online at
|
||
<a class="ulink" href="http://lists.mysql.com/java" target="_top">http://lists.mysql.com/java</a>.
|
||
</p><p>
|
||
For information about subscribing to MySQL mailing lists or to
|
||
browse list archives, visit
|
||
<a class="ulink" href="http://lists.mysql.com/" target="_top">http://lists.mysql.com/</a>. See
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/mailing-lists.html" target="_top">MySQL Mailing Lists</a>.
|
||
</p><p>
|
||
Community support from experienced users is also available
|
||
through the <a class="ulink" href="http://forums.mysql.com/list.php?39" target="_top">JDBC
|
||
Forum</a>. You may also find help from other users in the
|
||
other MySQL Forums, located at
|
||
<a class="ulink" href="http://forums.mysql.com" target="_top">http://forums.mysql.com</a>. See
|
||
<a class="ulink" href="http://dev.mysql.com/doc/refman/5.7/en/forums.html" target="_top">MySQL Community Support at the MySQL Forums</a>.
|
||
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-j-support-bug-report"></a>17.2 How to Report Connector/J Bugs or Problems</h2></div></div></div><a class="indexterm" name="idm140266685052976"></a><p>
|
||
The normal place to report bugs is
|
||
<a class="ulink" href="http://bugs.mysql.com/" target="_top">http://bugs.mysql.com/</a>, which is the address for
|
||
our bugs database. This database is public, and can be browsed
|
||
and searched by anyone. If you log in to the system, you will
|
||
also be able to enter new reports.
|
||
</p><p>
|
||
If you find a sensitive security bug in MySQL Server, please let
|
||
us know immediately by sending an email message to
|
||
<code class="email"><<a class="email" href="mailto:secalert_us@oracle.com">secalert_us@oracle.com</a>></code>. Exception: Support
|
||
customers should report all problems, including security bugs,
|
||
to Oracle Support at <a class="ulink" href="http://support.oracle.com/" target="_top">http://support.oracle.com/</a>.
|
||
</p><p>
|
||
Writing a good bug report takes patience, but doing it right the
|
||
first time saves time both for us and for yourself. A good bug
|
||
report, containing a full test case for the bug, makes it very
|
||
likely that we will fix the bug in the next release.
|
||
</p><p>
|
||
This section will help you write your report correctly so that
|
||
you do not waste your time doing things that may not help us
|
||
much or at all.
|
||
</p><p>
|
||
If you have a repeatable bug report, please report it to the
|
||
bugs database at <a class="ulink" href="http://bugs.mysql.com/" target="_top">http://bugs.mysql.com/</a>. Any bug
|
||
that we are able to repeat has a high chance of being fixed in
|
||
the next MySQL release.
|
||
</p><p>
|
||
To report other problems, you can use one of the MySQL mailing
|
||
lists.
|
||
</p><p>
|
||
Remember that it is possible for us to respond to a message
|
||
containing too much information, but not to one containing too
|
||
little. People often omit facts because they think they know the
|
||
cause of a problem and assume that some details do not matter.
|
||
</p><p>
|
||
A good principle is this: If you are in doubt about stating
|
||
something, state it. It is faster and less troublesome to write
|
||
a couple more lines in your report than to wait longer for the
|
||
answer if we must ask you to provide information that was
|
||
missing from the initial report.
|
||
</p><p>
|
||
The most common errors made in bug reports are (a) not including
|
||
the version number of Connector/J or MySQL used, and (b) not
|
||
fully describing the platform on which Connector/J is installed
|
||
(including the JVM version, and the platform type and version
|
||
number that MySQL itself is installed on).
|
||
</p><p>
|
||
This is highly relevant information, and in 99 cases out of 100,
|
||
the bug report is useless without it. Very often we get
|
||
questions like, <span class="quote">“<span class="quote">Why doesn't this work for me?</span>”</span>
|
||
Then we find that the feature requested wasn't implemented in
|
||
that MySQL version, or that a bug described in a report has
|
||
already been fixed in newer MySQL versions.
|
||
</p><p>
|
||
Sometimes the error is platform-dependent; in such cases, it is
|
||
next to impossible for us to fix anything without knowing the
|
||
operating system and the version number of the platform.
|
||
</p><p>
|
||
If at all possible, create a repeatable, standalone testcase
|
||
that doesn't involve any third-party classes.
|
||
</p><p>
|
||
To streamline this process, we ship a base class for testcases
|
||
with Connector/J, named
|
||
'<code class="classname">com.mysql.jdbc.util.BaseBugReport</code>'. To
|
||
create a testcase for Connector/J using this class, create your
|
||
own class that inherits from
|
||
<code class="classname">com.mysql.jdbc.util.BaseBugReport</code> and
|
||
override the methods <code class="function">setUp()</code>,
|
||
<code class="function">tearDown()</code> and
|
||
<code class="function">runTest()</code>.
|
||
</p><p>
|
||
In the <code class="function">setUp()</code> method, create code that
|
||
creates your tables, and populates them with any data needed to
|
||
demonstrate the bug.
|
||
</p><p>
|
||
In the <code class="function">runTest()</code> method, create code that
|
||
demonstrates the bug using the tables and data you created in
|
||
the <code class="literal">setUp</code> method.
|
||
</p><p>
|
||
In the <code class="function">tearDown()</code> method, drop any tables
|
||
you created in the <code class="function">setUp()</code> method.
|
||
</p><p>
|
||
In any of the above three methods, use one of the variants of
|
||
the <code class="function">getConnection()</code> method to create a JDBC
|
||
connection to MySQL:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
<code class="function">getConnection()</code> - Provides a connection
|
||
to the JDBC URL specified in <code class="function">getUrl()</code>.
|
||
If a connection already exists, that connection is returned,
|
||
otherwise a new connection is created.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="function">getNewConnection()</code> - Use this if you
|
||
need to get a new connection for your bug report (that is,
|
||
there is more than one connection involved).
|
||
</p></li><li class="listitem"><p>
|
||
<code class="function">getConnection(String url)</code> - Returns a
|
||
connection using the given URL.
|
||
</p></li><li class="listitem"><p>
|
||
<code class="function">getConnection(String url, Properties
|
||
props)</code> - Returns a connection using the given URL
|
||
and properties.
|
||
</p></li></ul></div><p>
|
||
If you need to use a JDBC URL that is different from
|
||
'jdbc:mysql:///test', override the method
|
||
<code class="function">getUrl()</code> as well.
|
||
</p><p>
|
||
Use the <code class="function">assertTrue(boolean expression)</code> and
|
||
<code class="function">assertTrue(String failureMessage, boolean
|
||
expression)</code> methods to create conditions that must be
|
||
met in your testcase demonstrating the behavior you are
|
||
expecting (vs. the behavior you are observing, which is why you
|
||
are most likely filing a bug report).
|
||
</p><p>
|
||
Finally, create a <code class="function">main()</code> method that
|
||
creates a new instance of your testcase, and calls the
|
||
<code class="literal">run</code> method:
|
||
</p><pre class="programlisting">
|
||
public static void main(String[] args) throws Exception {
|
||
new MyBugReport().run();
|
||
}
|
||
</pre><p>
|
||
Once you have finished your testcase, and have verified that it
|
||
demonstrates the bug you are reporting, upload it with your bug
|
||
report to <a class="ulink" href="http://bugs.mysql.com/" target="_top">http://bugs.mysql.com/</a>.
|
||
</p></div></div></div><div class="copyright-footer"></div></body></html>
|