Author: mmatthews
Date: 2006-01-13 21:10:16 +0100 (Fri, 13 Jan 2006)
New Revision: 814
Log:
Added section for building from source repository.
Modified:
trunk/refman-5.0/connector-j.xml
Modified: trunk/refman-5.0/connector-j.xml
===================================================================
--- trunk/refman-5.0/connector-j.xml 2006-01-13 19:54:03 UTC (rev 813)
+++ trunk/refman-5.0/connector-j.xml 2006-01-13 20:10:16 UTC (rev 814)
@@ -1,116 +1,87 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
-[
- <!ENTITY % fixedchars.entities SYSTEM "../refman-common/fixedchars.ent">
- %fixedchars.entities;
- <!ENTITY % title.entities SYSTEM "../refman-common/titles.en.ent">
- %title.entities;
- <!ENTITY % versions.entities SYSTEM "versions.ent">
- %versions.entities;
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!ENTITY % fixedchars.entities SYSTEM "../refman-common/fixedchars.ent">
+%fixedchars.entities;
+<!ENTITY % title.entities SYSTEM "../refman-common/titles.en.ent">
+%title.entities;
+<!ENTITY % versions.entities SYSTEM "versions.ent">
+%versions.entities;
]>
<section id="java-connector">
+ <title>MySQL Connector/J</title>
- <title>&title-java-connector;</title>
+ <para>MySQL provides connectivity for client applications developed in the
+ Java programming language via a JDBC driver, which is called MySQL
+ Connector/J.</para>
- <para>
- MySQL provides connectivity for client applications developed in the
- Java programming language via a JDBC driver, which is called MySQL
- Connector/J.
- </para>
+ <para>MySQL Connector/J is a JDBC-3.0 <quote>Type 4</quote> driver, which
+ means that is pure Java, implements version 3.0 of the JDBC specification,
+ and communicates directly with the MySQL server using the MySQL
+ protocol.</para>
- <para>
- MySQL Connector/J is a JDBC-3.0 <quote>Type 4</quote> driver, which
- means that is pure Java, implements version 3.0 of the JDBC
- specification, and communicates directly with the MySQL server using
- the MySQL protocol.
- </para>
+ <para>This document is arranged for a beginning JDBC developer. If you are
+ already experienced with using JDBC, you might consider starting with the
+ section <xref linkend="cj-installing" />.</para>
- <para>
- This document is arranged for a beginning JDBC developer. If you are
- already experienced with using JDBC, you might consider starting
- with the section <xref linkend="cj-installing"/>.
- </para>
+ <para>Although JDBC is useful by itself, we would hope that if you are not
+ familiar with JDBC that after reading the first few sections of this manual,
+ that you would avoid using <quote>naked</quote> JDBC for all but the most
+ trivial problems and consider using one of the popular persistence
+ frameworks such as <ulink url="http://www.hibernate.org/">Hibernate</ulink>,
+ <ulink url="http://www.springframework.org/">Spring's JDBC templates</ulink>
+ or <ulink url="http://www.ibatis.com/common/sqlmaps.html">Ibatis SQL
+ Maps</ulink> to do the majority of repetitive work and heavier lifting that
+ is sometimes required with JDBC.</para>
- <para>
- Although JDBC is useful by itself, we would hope that if you are not
- familiar with JDBC that after reading the first few sections of this
- manual, that you would avoid using <quote>naked</quote> JDBC for all
- but the most trivial problems and consider using one of the popular
- persistence frameworks such as
- <ulink url="http://www.hibernate.org/">Hibernate</ulink>,
- <ulink url="http://www.springframework.org/">Spring's JDBC
- templates</ulink> or
- <ulink url="http://www.ibatis.com/common/sqlmaps.html">Ibatis SQL
- Maps</ulink> to do the majority of repetitive work and heavier
- lifting that is sometimes required with JDBC.
- </para>
+ <para>This section is not designed to be a complete JDBC tutorial. If you
+ need more information about using JDBC you might be interested in the
+ following online tutorials that are more in-depth than the information
+ presented here:</para>
- <para>
- This section is not designed to be a complete JDBC tutorial. If you
- need more information about using JDBC you might be interested in
- the following online tutorials that are more in-depth than the
- information presented here:
- </para>
-
<itemizedlist>
-
<listitem>
- <para>
- <ulink
+ <para><ulink
url="http://java.sun.com/docs/books/tutorial/jdbc/basics/index.html">JDBC
- Basics </ulink> — A tutorial from Sun covering beginner
- topics in JDBC
- </para>
+ Basics </ulink> — A tutorial from Sun covering beginner topics in
+ JDBC</para>
</listitem>
<listitem>
- <para>
- <ulink url="http://java.sun.com/developer/onlineTraining/Database/JDBCShortCourse/index.html">JDBC
- Short Course</ulink> — A more in-depth tutorial from Sun
- and JGuru
- </para>
+ <para><ulink
+ url="http://java.sun.com/developer/onlineTraining/Database/JDBCShortCourse/index.html">JDBC
+ Short Course</ulink> — A more in-depth tutorial from Sun and
+ JGuru</para>
</listitem>
-
</itemizedlist>
<section id="cj-basic-jdbc">
+ <title>Basic JDBC concepts</title>
- <title>&title-cj-basic-jdbc;</title>
+ <para>This section provides some general JDBC background.</para>
- <para>
- This section provides some general JDBC background.
- </para>
-
<section id="cj-connect-with-drivermanager">
+ <title>Connecting to MySQL using the <literal>DriverManager</literal>
+ Interface</title>
- <title>&title-cj-connect-with-drivermanager;</title>
+ <para>When you are using JDBC outside of an application server, the
+ <literal>DriverManager</literal> class manages the establishment of
+ Connections.</para>
- <para>
- When you are using JDBC outside of an application server, the
- <literal>DriverManager</literal> class manages the establishment
- of Connections.
- </para>
+ <para>The <literal>DriverManager</literal> needs to be told which JDBC
+ drivers it should try to make Connections with. The easiest way to do
+ this is to use <function>Class.forName()</function> on the class that
+ implements the <literal>java.sql.Driver</literal> interface. With MySQL
+ Connector/J, the name of this class is
+ <literal>com.mysql.jdbc.Driver</literal>. 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.</para>
- <para>
- The <literal>DriverManager</literal> needs to be told which JDBC
- drivers it should try to make Connections with. The easiest way
- to do this is to use <function>Class.forName()</function> on the
- class that implements the <literal>java.sql.Driver</literal>
- interface. With MySQL Connector/J, the name of this class is
- <literal>com.mysql.jdbc.Driver</literal>. 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.
- </para>
+ <para>The following section of Java code shows how you might register
+ MySQL Connector/J from the <function>main()</function> method of your
+ application:</para>
- <para>
- The following section of Java code shows how you might register
- MySQL Connector/J from the <function>main()</function> method of
- your application:
- </para>
-
-<programlisting>import java.sql.Connection;
+ <programlisting>import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
@@ -129,28 +100,24 @@
}
}</programlisting>
- <para>
- After the driver has been registered with the
- <literal>DriverManager</literal>, you can obtain a
- <literal>Connection</literal> instance that is connected to a
- particular database by calling
- <function>DriverManager.getConnection()</function>:
- </para>
+ <para>After the driver has been registered with the
+ <literal>DriverManager</literal>, you can obtain a
+ <literal>Connection</literal> instance that is connected to a particular
+ database by calling
+ <function>DriverManager.getConnection()</function>:</para>
<example>
+ <title>Obtaining a Connection From the
+ <literal>DriverManager</literal></title>
- <title>Obtaining a Connection From the <literal>DriverManager</literal></title>
+ <para>This example shows how you can obtain a
+ <literal>Connection</literal> instance from the
+ <literal>DriverManager</literal>. There are a few different signatures
+ for the <function>getConnection()</function> method. You should see
+ the API documentation that comes with your JDK for more specific
+ information on how to use them.</para>
- <para>
- This example shows how you can obtain a
- <literal>Connection</literal> instance from the
- <literal>DriverManager</literal>. There are a few different
- signatures for the <function>getConnection()</function>
- method. You should see the API documentation that comes with
- your JDK for more specific information on how to use them.
- </para>
-
-<programlisting>
+ <programlisting>
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
@@ -169,19 +136,15 @@
}
</programlisting>
- <para>
- Once a <classname>Connection</classname> is established, it
- can be used to create <classname>Statement</classname> and
- <classname>PreparedStatement</classname> objects, as well as
- retrieve metadata about the database. This is explained in the
- following sections.
- </para>
-
+ <para>Once a <classname>Connection</classname> is established, it can
+ be used to create <classname>Statement</classname> and
+ <classname>PreparedStatement</classname> objects, as well as retrieve
+ metadata about the database. This is explained in the following
+ sections.</para>
</example>
-
</section>
-<!--
+ <!--
<section id="cj-connect-with-datasource">
<title>&title-cj-connect-with-datasource;;</title>
@@ -189,7 +152,7 @@
</section>
-->
-<!--
+ <!--
<section id="cj-controlling-transactions">
<title>&title-cj-controlling-transactions;</title>
@@ -198,60 +161,46 @@
-->
<section id="cj-using-statements">
+ <title>Using Statements to Execute SQL</title>
- <title>&title-cj-using-statements;</title>
+ <para><classname>Statement</classname> objects allow you to execute
+ basic SQL queries and retrieve the results through the
+ <literal>ResultSet</literal> class which is described later.</para>
- <para>
- <classname>Statement</classname> objects allow you to execute
- basic SQL queries and retrieve the results through the
- <literal>ResultSet</literal> class which is described later.
- </para>
+ <para>To create a <classname>Statement</classname> instance, you call
+ the <function>createStatement()</function> method on the
+ <literal>Connection</literal> object you have retrieved via one of the
+ <function>DriverManager.getConnection()</function> or
+ <function>DataSource.getConnection()</function> methods described
+ earlier.</para>
- <para>
- To create a <classname>Statement</classname> instance, you call
- the <function>createStatement()</function> method on the
- <literal>Connection</literal> object you have retrieved via one
- of the <function>DriverManager.getConnection()</function> or
- <function>DataSource.getConnection()</function> methods
- described earlier.
- </para>
+ <para>Once you have a <classname>Statement</classname> instance, you can
+ execute a <literal>SELECT</literal> query by calling the
+ <literal>executeQuery(String)</literal> method with the SQL you want to
+ use.</para>
- <para>
- Once you have a <classname>Statement</classname> instance, you
- can execute a <literal>SELECT</literal> query by calling the
- <literal>executeQuery(String)</literal> method with the SQL you
- want to use.
- </para>
+ <para>To update data in the database, use the
+ <literal>executeUpdate(String SQL)</literal> method. This method returns
+ the number of rows affected by the update statement.</para>
- <para>
- To update data in the database, use the
- <literal>executeUpdate(String SQL)</literal> method. This method
- returns the number of rows affected by the update statement.
- </para>
+ <para>If you don't know ahead of time whether the SQL statement will be
+ a <literal>SELECT</literal> or an
+ <literal>UPDATE</literal>/<literal>INSERT</literal>, then you can use
+ the <literal>execute(String SQL)</literal> method. This method will
+ return true if the SQL query was a <literal>SELECT</literal>, or false
+ if it was an <literal>UPDATE</literal>, <literal>INSERT</literal>, or
+ <literal>DELETE</literal> statement. If the statement was a
+ <literal>SELECT</literal> query, you can retrieve the results by calling
+ the <function>getResultSet()</function> method. If the statement was an
+ <literal>UPDATE</literal>, <literal>INSERT</literal>, or
+ <literal>DELETE</literal> statement, you can retrieve the affected rows
+ count by calling <function>getUpdateCount()</function> on the
+ <classname>Statement</classname> instance.</para>
- <para>
- If you don't know ahead of time whether the SQL statement will
- be a <literal>SELECT</literal> or an
- <literal>UPDATE</literal>/<literal>INSERT</literal>, then you
- can use the <literal>execute(String SQL)</literal> method. This
- method will return true if the SQL query was a
- <literal>SELECT</literal>, or false if it was an
- <literal>UPDATE</literal>, <literal>INSERT</literal>, or
- <literal>DELETE</literal> statement. If the statement was a
- <literal>SELECT</literal> query, you can retrieve the results by
- calling the <function>getResultSet()</function> method. If the
- statement was an <literal>UPDATE</literal>,
- <literal>INSERT</literal>, or <literal>DELETE</literal>
- statement, you can retrieve the affected rows count by calling
- <function>getUpdateCount()</function> on the
- <classname>Statement</classname> instance.
- </para>
-
<example>
-
<title>Using java.sql.Statement to Execute a SELECT Query</title>
-<programlisting>// assume that conn is an already created JDBC connection
+ <programlisting>// assume that conn is an already created JDBC connection
Statement stmt = null;
ResultSet rs = null;
@@ -289,12 +238,10 @@
stmt = null;
}
}</programlisting>
-
</example>
-
</section>
-<!--
+ <!--
<section id="cj-using-prepared-statements">
<title>&title-cj-using-prepared-statements;</title>
@@ -303,40 +250,29 @@
-->
<section id="cj-using-callable-statements">
+ <title>Using <literal>CallableStatements</literal> to Execute Stored
+ Procedures</title>
- <title>&title-cj-using-callable-statements;</title>
+ <para>Starting with MySQL server version 5.0 when used with Connector/J
+ 3.1.1 or newer, the <classname>java.sql.CallableStatement</classname>
+ interface is fully implemented with the exception of the
+ <function>getParameterMetaData()</function> method.</para>
- <para>
- Starting with MySQL server version 5.0 when used with
- Connector/J 3.1.1 or newer, the
- <classname>java.sql.CallableStatement</classname> interface is
- fully implemented with the exception of the
- <function>getParameterMetaData()</function> method.
- </para>
+ <para>MySQL's stored procedure syntax is documented in the "<ulink
+ url="http://www.mysql.com/doc/en/stored-procedures.html">Stored
+ Procedures and Functions</ulink>" section of the MySQL Reference
+ Manual.</para>
- <para>
- MySQL's stored procedure syntax is documented in the
- "<ulink url="http://www.mysql.com/doc/en/stored-procedures.html">Stored
- Procedures and Functions</ulink>" section of the MySQL Reference
- Manual.
- </para>
+ <para>Connector/J exposes stored procedure functionality through JDBC's
+ <classname>CallableStatement</classname> interface.</para>
- <para>
- Connector/J exposes stored procedure functionality through
- JDBC's <classname>CallableStatement</classname> interface.
- </para>
-
- <para>
- The following example shows a stored procedure that returns the
- value of <varname>inOutParam</varname> incremented by 1, and the
- string passed in via <varname>inputParam</varname> as a
- <classname>ResultSet</classname>:
-
- <example>
-
+ <para>The following example shows a stored procedure that returns the
+ value of <varname>inOutParam</varname> incremented by 1, and the string
+ passed in via <varname>inputParam</varname> as a
+ <classname>ResultSet</classname>: <example>
<title>Stored Procedure Example</title>
-<programlisting>CREATE PROCEDURE demoSp(IN inputParam VARCHAR(255), INOUT inOutParam INT)
+ <programlisting>CREATE PROCEDURE demoSp(IN inputParam VARCHAR(255), INOUT inOutParam INT)
BEGIN
DECLARE z INT;
SET z = inOutParam + 1;
@@ -346,34 +282,24 @@
SELECT CONCAT('zyxw', inputParam);
END</programlisting>
+ </example></para>
- </example>
- </para>
+ <para>To use the <function>demoSp</function> procedure with Connector/J,
+ follow these steps:</para>
- <para>
- To use the <function>demoSp</function> procedure with
- Connector/J, follow these steps:
- </para>
-
<orderedlist>
-
<listitem>
- <para>
- Prepare the callable statement by using
- <function>Connection.prepareCall()</function> .
- </para>
+ <para>Prepare the callable statement by using
+ <function>Connection.prepareCall()</function> .</para>
- <para>
- Notice that you have to use JDBC escape syntax, and that the
- parentheses surrounding the parameter placeholders are not
- optional:
- </para>
+ <para>Notice that you have to use JDBC escape syntax, and that the
+ parentheses surrounding the parameter placeholders are not
+ optional:</para>
<example>
-
<title>Using <function>Connection.prepareCall()</function></title>
-<programlisting>import java.sql.CallableStatement;
+ <programlisting>import java.sql.CallableStatement;
...
@@ -389,44 +315,31 @@
cStmt.setString(1, "abcdefg");</programlisting>
-
</example>
<note>
-
- <para>
- <function>Connection.prepareCall()</function> is an
- expensive method, due to the metadata retrieval that the
- driver performs to support output parameters. For
- performance reasons, you should try to minimize
- unnecessary calls to
- <function>Connection.prepareCall()</function> by reusing
- <classname>CallableStatement</classname> instances in your
- code.
- </para>
-
+ <para><function>Connection.prepareCall()</function> is an
+ expensive method, due to the metadata retrieval that the driver
+ performs to support output parameters. For performance reasons,
+ you should try to minimize unnecessary calls to
+ <function>Connection.prepareCall()</function> by reusing
+ <classname>CallableStatement</classname> instances in your
+ code.</para>
</note>
</listitem>
<listitem>
- <para>
- Register the output parameters (if any exist)
- </para>
+ <para>Register the output parameters (if any exist)</para>
- <para>
- To retrieve the values of output parameters (parameters
- specified as <literal>OUT</literal> or
- <literal>INOUT</literal> when you created the stored
- procedure), JDBC requires that they be specified before
- statement execution using the various
- <function>registerOutputParameter()</function> methods in
- the <classname>CallableStatement</classname> interface:
-
- <example>
-
+ <para>To retrieve the values of output parameters (parameters
+ specified as <literal>OUT</literal> or <literal>INOUT</literal> when
+ you created the stored procedure), JDBC requires that they be
+ specified before statement execution using the various
+ <function>registerOutputParameter()</function> methods in the
+ <classname>CallableStatement</classname> interface: <example>
<title>Registering Output Parameters</title>
-<programlisting>
+ <programlisting>
import java.sql.Types;
...
//
@@ -460,28 +373,21 @@
cStmt.registerOutParameter("inOutParam", Types.INTEGER);
...
</programlisting>
-
- </example>
- </para>
+ </example></para>
</listitem>
<listitem>
- <para>
- Set the input parameters (if any exist)
- </para>
+ <para>Set the input parameters (if any exist)</para>
- <para>
- Input and in/out parameters are set as for
- <classname>PreparedStatement</classname> objects. However,
- <classname>CallableStatement</classname> also supports
- setting parameters by name:
+ <para>Input and in/out parameters are set as for
+ <classname>PreparedStatement</classname> objects. However,
+ <classname>CallableStatement</classname> also supports setting
+ parameters by name: <example>
+ <title>Setting <literal>CallableStatement</literal> Input
+ Parameters</title>
- <example>
+ <programlisting>...
- <title>Setting <literal>CallableStatement</literal> Input Parameters</title>
-
-<programlisting>...
-
//
// Set a parameter by index
//
@@ -509,32 +415,23 @@
cStmt.setInt("inOutParam", 1);
...</programlisting>
-
- </example>
- </para>
+ </example></para>
</listitem>
<listitem>
- <para>
- Execute the <classname>CallableStatement</classname>, and
- retrieve any result sets or output parameters.
- </para>
+ <para>Execute the <classname>CallableStatement</classname>, and
+ retrieve any result sets or output parameters.</para>
- <para>
- Although <classname>CallableStatement</classname> supports
- calling any of the <classname>Statement</classname> execute
- methods (<function>executeUpdate()</function>,
- <function>executeQuery()</function> or
- <function>execute()</function>), the most flexible method to
- call is <function>execute()</function>, as you do not need
- to know ahead of time if the stored procedure returns result
- sets:
-
- <example>
-
+ <para>Although <classname>CallableStatement</classname> supports
+ calling any of the <classname>Statement</classname> execute methods
+ (<function>executeUpdate()</function>,
+ <function>executeQuery()</function> or
+ <function>execute()</function>), the most flexible method to call is
+ <function>execute()</function>, as you do not need to know ahead of
+ time if the stored procedure returns result sets: <example>
<title>Retrieving Results and Output Parameter Values</title>
-<programlisting>...
+ <programlisting>...
boolean hadResults = cStmt.execute();
@@ -563,51 +460,40 @@
outputValue = cStmt.getInt("inOutParam"); // name-based
...</programlisting>
-
- </example>
- </para>
+ </example></para>
</listitem>
-
</orderedlist>
-
</section>
<section id="cj-retrieve-autoinc">
+ <title>Retrieving <literal>AUTO_INCREMENT</literal> Column
+ Values</title>
- <title>&title-cj-retrieve-autoinc;</title>
+ <para>Before version 3.0 of the JDBC API, there was no standard way of
+ retrieving key values from databases that supported <quote>auto
+ increment</quote> or identity columns. With older JDBC drivers for
+ MySQL, you could always use a MySQL-specific method on the
+ <classname>Statement</classname> interface, or issue the query
+ <literal>SELECT LAST_INSERT_ID()</literal> after issuing an
+ <literal>INSERT</literal> to a table that had an
+ <literal>AUTO_INCREMENT</literal> key. Using the MySQL-specific method
+ call isn't portable, and issuing a <literal>SELECT</literal> to get the
+ <literal>AUTO_INCREMENT</literal> 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
+ <literal>AUTO_INCREMENT</literal> values. First, we demonstrate the use
+ of the new JDBC-3.0 method <function>getGeneratedKeys()</function> which
+ is now the preferred method to use if you need to retrieve
+ <literal>AUTO_INCREMENT</literal> keys and have access to JDBC-3.0. The
+ second example shows how you can retrieve the same value using a
+ standard <literal>SELECT LAST_INSERT_ID()</literal> query. The final
+ example shows how updatable result sets can retrieve the
+ <literal>AUTO_INCREMENT</literal> value when using the
+ <function>insertRow()</function> method. <example>
+ <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values
+ using <function>Statement.getGeneratedKeys()</function></title>
- <para>
- Before version 3.0 of the JDBC API, there was no standard way of
- retrieving key values from databases that supported <quote>auto
- increment</quote> or identity columns. With older JDBC drivers
- for MySQL, you could always use a MySQL-specific method on the
- <classname>Statement</classname> interface, or issue the query
- <literal>SELECT LAST_INSERT_ID()</literal> after issuing an
- <literal>INSERT</literal> to a table that had an
- <literal>AUTO_INCREMENT</literal> key. Using the MySQL-specific
- method call isn't portable, and issuing a
- <literal>SELECT</literal> to get the
- <literal>AUTO_INCREMENT</literal> 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 <literal>AUTO_INCREMENT</literal>
- values. First, we demonstrate the use of the new JDBC-3.0 method
- <function>getGeneratedKeys()</function> which is now the
- preferred method to use if you need to retrieve
- <literal>AUTO_INCREMENT</literal> keys and have access to
- JDBC-3.0. The second example shows how you can retrieve the same
- value using a standard <literal>SELECT
- LAST_INSERT_ID()</literal> query. The final example shows how
- updatable result sets can retrieve the
- <literal>AUTO_INCREMENT</literal> value when using the
- <function>insertRow()</function> method.
-
- <example>
-
- <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values using
- <function>Statement.getGeneratedKeys()</function></title>
-
-<programlisting> Statement stmt = null;
+ <programlisting> Statement stmt = null;
ResultSet rs = null;
try {
@@ -683,15 +569,11 @@
}
}
</programlisting>
+ </example> <example>
+ <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values
+ using <function>SELECT LAST_INSERT_ID()</function></title>
- </example>
-
- <example>
-
- <title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values using
- <function>SELECT LAST_INSERT_ID()</function></title>
-
-<programlisting> Statement stmt = null;
+ <programlisting> Statement stmt = null;
ResultSet rs = null;
try {
@@ -759,15 +641,11 @@
}
}
</programlisting>
-
- </example>
-
- <example>
-
+ </example> <example>
<title>Retrieving <literal>AUTO_INCREMENT</literal> Column Values in
- <literal>Updatable ResultSets</literal></title>
+ <literal>Updatable ResultSets</literal></title>
-<programlisting> Statement stmt = null;
+ <programlisting> Statement stmt = null;
ResultSet rs = null;
try {
@@ -845,27 +723,21 @@
</programlisting>
-
- </example>
-
- When you run the preceding example code, you should get the
- following output: Key returned from
- <function>getGeneratedKeys()</function>: 1 Key returned from
- <literal>SELECT LAST_INSERT_ID()</literal>: 1 Key returned for
- inserted row: 2 You should be aware, that at times, it can be
- tricky to use the <literal>SELECT LAST_INSERT_ID()</literal>
- query, as that function's value is scoped to a connection. So,
- if some other query happens on the same connection, the value
- will be overwritten. On the other hand, the
- <function>getGeneratedKeys()</function> method is scoped by the
- <classname>Statement</classname> instance, so it can be used
- even if other queries happen on the same connection, but not on
- the same <classname>Statement</classname> instance.
- </para>
-
+ </example> When you run the preceding example code, you should get the
+ following output: Key returned from
+ <function>getGeneratedKeys()</function>: 1 Key returned from
+ <literal>SELECT LAST_INSERT_ID()</literal>: 1 Key returned for inserted
+ row: 2 You should be aware, that at times, it can be tricky to use the
+ <literal>SELECT LAST_INSERT_ID()</literal> query, as that function's
+ value is scoped to a connection. So, if some other query happens on the
+ same connection, the value will be overwritten. On the other hand, the
+ <function>getGeneratedKeys()</function> method is scoped by the
+ <classname>Statement</classname> instance, so it can be used even if
+ other queries happen on the same connection, but not on the same
+ <classname>Statement</classname> instance.</para>
</section>
-<!--
+ <!--
<section id="cj-retrieve-multiresults">
<title>&title-cj-retrieve-multiresults;</title>
@@ -873,7 +745,7 @@
</section>
-->
-<!--
+ <!--
<section id="cj-using-result-set-metadata">
<title>&title-cj-using-result-set-metadata;</title>
@@ -881,7 +753,7 @@
</section>
-->
-<!--
+ <!--
<section id="cj-using-database-metadata">
<title>&title-cj-using-database-metadata;</title>
@@ -889,2424 +761,2834 @@
</section>
-->
-<!--
+ <!--
<section id="cj-working-with-lobs">
<title>&title-cj-working-with-lobs;</title>
<para />
</section>
-->
-
</section>
<section id="cj-installing">
+ <title>Installing Connector/J</title>
- <title>&title-cj-installing;</title>
+ <para>Use the following instructions to install Connector/J</para>
- <para>
- Use the following instructions to install Connector/J
- </para>
-
<section id="cj-system-requirements">
+ <title>Required Software Versions</title>
- <title>&title-cj-system-requirements;</title>
-
<para></para>
<section id="cj-supported-java-versions">
+ <title>Java Versions Supported</title>
- <title>&title-cj-supported-java-versions;</title>
+ <para>MySQL Connector/J supports Java-2 JVMs, including JDK-1.2.x,
+ JDK-1.3.x, JDK-1.4.x and JDK-1.5.x, and requires JDK-1.4.x or newer to
+ compile (but not run). MySQL Connector/J does not support JDK-1.1.x or
+ JDK-1.0.x</para>
- <para>
- MySQL Connector/J supports Java-2 JVMs, including JDK-1.2.x,
- JDK-1.3.x, JDK-1.4.x and JDK-1.5.x, and requires JDK-1.4.x or
- newer to compile (but not run). MySQL Connector/J does not
- support JDK-1.1.x or JDK-1.0.x
- </para>
+ <para>Because of the implementation of
+ <classname>java.sql.Savepoint</classname>, Connector/J 3.1.0 and newer
+ will not run on JDKs older than 1.4 unless the class verifier is
+ turned off (<option>-Xverify:none</option>), as the class verifier
+ will try to load the class definition for
+ <classname>java.sql.Savepoint</classname> even though it is not
+ accessed by the driver unless you actually use savepoint
+ functionality.</para>
- <para>
- Because of the implementation of
- <classname>java.sql.Savepoint</classname>, Connector/J 3.1.0
- and newer will not run on JDKs older than 1.4 unless the class
- verifier is turned off (<option>-Xverify:none</option>), as
- the class verifier will try to load the class definition for
- <classname>java.sql.Savepoint</classname> even though it is
- not accessed by the driver unless you actually use savepoint
- functionality.
- </para>
+ <para>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
+ <classname>java.util.LinkedHashMap</classname> which was first
+ available in JDK-1.4.0.</para>
- <para>
- 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 <classname>java.util.LinkedHashMap</classname> which was
- first available in JDK-1.4.0.
- </para>
-
- <remark>
- MARKUP DONE TO HERE
- </remark>
-
+ <remark>MARKUP DONE TO HERE</remark>
</section>
<section id="cj-supported-mysql-versions">
+ <title>MySQL Server Version Guidelines</title>
- <title>&title-cj-supported-mysql-versions;</title>
+ <para>MySQL Connector/J supports all known MySQL server versions. Some
+ features (foreign keys, updatable result sets) require more recent
+ versions of MySQL to operate.</para>
- <para>
- MySQL Connector/J supports all known MySQL server versions.
- Some features (foreign keys, updatable result sets) require
- more recent versions of MySQL to operate.
- </para>
+ <para>When connecting to MySQL server version 4.1 or newer, it is best
+ to use MySQL Connector/J version 3.1, as it has full support for
+ features in the newer versions of the server, including Unicode
+ characters, views, stored procedures and server-side prepared
+ statements.</para>
- <para>
- When connecting to MySQL server version 4.1 or newer, it is
- best to use MySQL Connector/J version 3.1, as it has full
- support for features in the newer versions of the server,
- including Unicode characters, views, stored procedures and
- server-side prepared statements.
- </para>
-
- <para>
- Although Connector/J version 3.0 will connect to MySQL server,
- version 4.1 or newer, and implements Unicode characters and
- the new authorization mechanism, Connector/J 3.0 will not be
- updated to support new features in current and future server
- versions.
- </para>
-
+ <para>Although Connector/J version 3.0 will connect to MySQL server,
+ version 4.1 or newer, and implements Unicode characters and the new
+ authorization mechanism, Connector/J 3.0 will not be updated to
+ support new features in current and future server versions.</para>
</section>
<section id="cj-classpath">
+ <title id="c-j-installing-driver-classpath">Installing the Driver and
+ Configuring the <literal>CLASSPATH</literal></title>
- <title>&title-cj-classpath;</title>
+ <para>MySQL Connector/J is distributed as a .zip or .tar.gz archive
+ containing the sources, the class files a class-file only
+ <quote>binary</quote> .jar archive named
+ "<filename>mysql-connector-java-[version]-bin.jar</filename>", and
+ starting with Connector/J 3.1.8 a <quote>debug</quote> build of the
+ driver in a file named
+ "<filename>mysql-connector-java-[version]-bin-g.jar</filename>".</para>
- <para>
- MySQL Connector/J is distributed as a .zip or .tar.gz archive
- containing the sources, the class files a class-file only
- <quote>binary</quote> .jar archive named
- "<filename>mysql-connector-java-[version]-bin.jar</filename>",
- and starting with Connector/J 3.1.8 a <quote>debug</quote>
- build of the driver in a file named
- "<filename>mysql-connector-java-[version]-bin-g.jar</filename>".
- </para>
+ <para>Starting with Connector/J 3.1.9, we don't ship the .class files
+ <quote>unbundled,</quote> they are only available in the JAR archives
+ that ship with the driver.</para>
- <para>
- Starting with Connector/J 3.1.9, we don't ship the .class
- files <quote>unbundled,</quote> they are only available in the
- JAR archives that ship with the driver.
- </para>
+ <para>You should not use the <quote>debug</quote> build of the driver
+ unless instructed to do so when reporting a problem or bug to MySQL
+ AB, 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
+ <filename>src/lib/aspectjrt.jar</filename> file that comes with the
+ Connector/J distribution.</para>
- <para>
- You should not use the <quote>debug</quote> build of the
- driver unless instructed to do so when reporting a problem or
- bug to MySQL AB, 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
- <filename>src/lib/aspectjrt.jar</filename> file that comes
- with the Connector/J distribution.
- </para>
+ <para>You will need to use the appropriate graphical or command-line
+ utility to un-archive the distribution (for example, WinZip for the
+ .zip archive, and <command>tar</command> for the .tar.gz archive).
+ Because there are potentially long filenames in the distribution, we
+ use the GNU tar archive format. You will need to use GNU tar (or an
+ application that understands the GNU tar archive format) to unpack the
+ .tar.gz variant of the distribution.</para>
- <para>
- You will need to use the appropriate graphical or command-line
- utility to un-archive the distribution (for example, WinZip
- for the .zip archive, and <command>tar</command> for the
- .tar.gz archive). Because there are potentially long filenames
- in the distribution, we use the GNU tar archive format. You
- will need to use GNU tar (or an application that understands
- the GNU tar archive format) to unpack the .tar.gz variant of
- the distribution.
- </para>
+ <para>Once you have extracted the distribution archive, you can
+ install the driver by placing mysql-connector-java-[version]-bin.jar
+ in your classpath, either by adding the FULL path to it to your
+ CLASSPATH environment variable, or by directly specifying it with the
+ command line switch -cp when starting your JVM</para>
- <para>
- Once you have extracted the distribution archive, you can
- install the driver by placing
- mysql-connector-java-[version]-bin.jar in your classpath,
- either by adding the FULL path to it to your CLASSPATH
- environment variable, or by directly specifying it with the
- command line switch -cp when starting your JVM
- </para>
+ <para>If you are going to use the driver with the JDBC DriverManager,
+ you would use "com.mysql.jdbc.Driver" as the class that implements
+ java.sql.Driver.</para>
- <para>
- If you are going to use the driver with the JDBC
- DriverManager, you would use "com.mysql.jdbc.Driver" as the
- class that implements java.sql.Driver.
- </para>
-
<example>
-
<title>Setting the CLASSPATH Under UNIX</title>
- <para>
- The following command works for 'csh' under UNIX:
- </para>
+ <para>The following command works for 'csh' under UNIX:</para>
<screen>$ setenv CLASSPATH /path/to/mysql-connector-java-[version]-bin.jar:$CLASSPATH</screen>
-
</example>
- <para>
- The above command can be added to the appropriate startup file
- for the login shell to make MySQL Connector/J available to all
- Java applications.
- </para>
+ <para>The above command can be added to the appropriate startup file
+ for the login shell to make MySQL Connector/J available to all Java
+ applications.</para>
- <para>
- If you want to use MySQL Connector/J with an application
- server such as Tomcat or JBoss, you will have to read your
- vendor's documentation for more information on how to
- configure third-party class libraries, as most application
- servers ignore the CLASSPATH environment variable. This
- document does contain configuration examples for some J2EE
- application servers in the section named
- "<link
- linkend="cj-j2ee">Using Connector/J with J2EE
- and Other Java Frameworks</link>", however the authoritative
- source for JDBC connection pool configuration information for
- your particular application server is the documentation for
- that application server.
- </para>
+ <para>If you want to use MySQL Connector/J with an application server
+ such as Tomcat or JBoss, you will have to read your vendor's
+ documentation for more information on how to configure third-party
+ class libraries, as most application servers ignore the CLASSPATH
+ environment variable. This document does contain configuration
+ examples for some J2EE application servers in the section named "<link
+ linkend="cj-j2ee">Using Connector/J with J2EE and Other Java
+ Frameworks</link>", however the authoritative source for JDBC
+ connection pool configuration information for your particular
+ application server is the documentation for that application
+ server.</para>
- <para>
- If you are developing servlets or JSPs, and your application
- server is J2EE-compliant, you can put the driver's .jar file
- in the WEB-INF/lib subdirectory of your webapp, as this is a
- standard location for third party class libraries in J2EE web
- applications.
- </para>
+ <para>If you are developing servlets or JSPs, and your application
+ server is J2EE-compliant, you can put the driver's .jar file in the
+ WEB-INF/lib subdirectory of your webapp, as this is a standard
+ location for third party class libraries in J2EE web
+ applications.</para>
- <para>
- You can also use the MysqlDataSource or
- MysqlConnectionPoolDataSource classes in the
- com.mysql.jdbc.jdbc2.optional package, if your J2EE
- application server supports or requires them. Starting with
- Connector/J 5.0.0, the javax.sql.XADataSource interface is
- implemented via the
- com.mysql.jdbc.jdbc2.optional.MysqlXADataSource class, which
- supports XA distributed transactions when used in combination
- with MySQL server version 5.0.
- </para>
+ <para>You can also use the MysqlDataSource or
+ MysqlConnectionPoolDataSource classes in the
+ com.mysql.jdbc.jdbc2.optional package, if your J2EE application server
+ supports or requires them. Starting with Connector/J 5.0.0, the
+ javax.sql.XADataSource interface is implemented via the
+ com.mysql.jdbc.jdbc2.optional.MysqlXADataSource class, which supports
+ XA distributed transactions when used in combination with MySQL server
+ version 5.0.</para>
- <para>
- The various MysqlDataSource classes support the following
- parameters (through standard "set" mutators):
- </para>
+ <para>The various MysqlDataSource classes support the following
+ parameters (through standard "set" mutators):</para>
<itemizedlist>
-
<listitem>
- <para>
- user
- </para>
+ <para>user</para>
</listitem>
<listitem>
- <para>
- password
- </para>
+ <para>password</para>
</listitem>
<listitem>
- <para>
- serverName (see the previous section about fail-over
- hosts)
- </para>
+ <para>serverName (see the previous section about fail-over
+ hosts)</para>
</listitem>
<listitem>
- <para>
- databaseName
- </para>
+ <para>databaseName</para>
</listitem>
<listitem>
- <para>
- port
- </para>
+ <para>port</para>
</listitem>
-
</itemizedlist>
-
</section>
-
</section>
<section id="cj-upgrading">
+ <title>Upgrading from an Older Version</title>
- <title>&title-cj-upgrading;</title>
+ <para>MySQL AB tries to keep the upgrade process as easy as possible,
+ however as is the case with any software, sometimes changes need to be
+ made in new versions to support new features, improve existing
+ functionality, or comply with new standards.</para>
- <para>
- MySQL AB tries to keep the upgrade process as easy as possible,
- however as is the case with any software, sometimes changes need
- to be made in new versions to support new features, improve
- existing functionality, or comply with new standards.
- </para>
+ <para>This section has information about what users who are upgrading
+ from one version of Connector/J to another (or to a new version of the
+ MySQL server, with respect to JDBC functionality) should be aware
+ of.</para>
- <para>
- This section has information about what users who are upgrading
- from one version of Connector/J to another (or to a new version
- of the MySQL server, with respect to JDBC functionality) should
- be aware of.
- </para>
-
<section id="cj-upgrading-3-0-to-3-1">
+ <title>Upgrading from MySQL Connector/J 3.0 to 3.1</title>
- <title>&title-cj-upgrading-3-0-to-3-1;</title>
+ <para>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, SQLState codes
+ returned in error messages by the server and various performance
+ enhancements that can be enabled or disabled via configuration
+ properties.</para>
- <para>
- 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, SQLState codes returned in error messages by the
- server and various performance enhancements that can be
- enabled or disabled via configuration properties.
- </para>
-
<itemizedlist>
-
<listitem>
- <para>
- Unicode Character Sets - See the next section, as well as
- the "Character Sets" section in the server manual for
- information on this new feature of MySQL. If you have
- something misconfigured, it will usually show up as an
- error with a message similar to 'Illegal mix of
- collations'.
- </para>
+ <para>Unicode Character Sets - See the next section, as well as
+ the "Character Sets" section in the server manual for information
+ on this new feature of MySQL. If you have something misconfigured,
+ it will usually show up as an error with a message similar to
+ 'Illegal mix of collations'.</para>
</listitem>
<listitem>
- <para>
- <emphasis>Server-side Prepared Statements</emphasis> -
- 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).
- </para>
+ <para><emphasis>Server-side Prepared Statements</emphasis> -
+ 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).</para>
- <para>
- Starting with version 3.1.7, the driver scans SQL you are
- preparing via all variants of
- <methodname>Connection.prepareStatement()</methodname> 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
- <property>'emulateUnsupportedPstmts=false'</property> in
- your JDBC URL.
- </para>
+ <para>Starting with version 3.1.7, the driver scans SQL you are
+ preparing via all variants of
+ <methodname>Connection.prepareStatement()</methodname> 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
+ <property>'emulateUnsupportedPstmts=false'</property> in your JDBC
+ URL.</para>
- <para>
- 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:
- </para>
+ <para>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:</para>
- <para>
- <computeroutput>useServerPrepStmts=false</computeroutput>
- </para>
+ <para><computeroutput>useServerPrepStmts=false</computeroutput></para>
</listitem>
<listitem>
- <para>
- Datetimes with all-zero components ('0000-00-00 ...') -
- These values can not be represented reliably in Java.
- Connector/J 3.0.x always converted them to NULL when being
- read from a ResultSet.
- </para>
+ <para>Datetimes with all-zero components ('0000-00-00 ...') -
+ These values can not be represented reliably in Java. Connector/J
+ 3.0.x always converted them to NULL when being read from a
+ ResultSet.</para>
- <para>
- 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 '
- <property>zeroDateTimeBehavior</property> ' configuration
- property. The allowable values are: 'exception' (the
- default), which throws an SQLException with an SQLState of
- 'S1009', 'convertToNull', which returns NULL instead of
- the date, and 'round', which rounds the date to the
- nearest closest value which is '0001-01-01'.
- </para>
+ <para>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 ' <property>zeroDateTimeBehavior</property> '
+ configuration property. The allowable values are: 'exception' (the
+ default), which throws an SQLException with an SQLState of
+ 'S1009', 'convertToNull', which returns NULL instead of the date,
+ and 'round', which rounds the date to the nearest closest value
+ which is '0001-01-01'.</para>
- <para>
- Starting with Connector/J 3.1.7, ResultSet.getString() can
- be decoupled from this behavior via '
- <property>noDatetimeStringSync=true</property> ' (the
- default value is 'false') so that you can get retrieve the
- unaltered all-zero value as a String. It should be noted
- that this also precludes using any timezone conversions,
- therefore the driver will not allow you to enable
- <property>noDatetimeStringSync</property> and
- <property>useTimezone</property> at the same time.
- </para>
+ <para>Starting with Connector/J 3.1.7, ResultSet.getString() can
+ be decoupled from this behavior via '
+ <property>noDatetimeStringSync=true</property> ' (the default
+ value is 'false') so that you can get retrieve the unaltered
+ all-zero value as a String. It should be noted that this also
+ precludes using any timezone conversions, therefore the driver
+ will not allow you to enable
+ <property>noDatetimeStringSync</property> and
+ <property>useTimezone</property> at the same time.</para>
</listitem>
<listitem>
- <para>
- New SQLState Codes - Connector/J 3.1 uses SQL:1999
- SQLState codes returned by the MySQL server (if
- supported), which are different than the
- <quote>legacy</quote> 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
- following configuration property:
- </para>
+ <para>New SQLState Codes - Connector/J 3.1 uses SQL:1999 SQLState
+ codes returned by the MySQL server (if supported), which are
+ different than the <quote>legacy</quote> 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 following configuration
+ property:</para>
- <para>
- <computeroutput>useSqlStateCodes=false</computeroutput>
- </para>
+ <para><computeroutput>useSqlStateCodes=false</computeroutput></para>
</listitem>
<listitem>
- <para>
- Calling ResultSet.getString() on a BLOB column will now
- return the address of the byte[] array that represents it,
- instead of a String representation of the BLOB. BLOBs have
- no character set, so they can't be converted to
- java.lang.Strings without data loss or corruption.
- </para>
+ <para>Calling ResultSet.getString() on a BLOB column will now
+ return the address of the byte[] array that represents it, instead
+ of a String representation of the BLOB. BLOBs have no character
+ set, so they can't be converted to java.lang.Strings without data
+ loss or corruption.</para>
- <para>
- To store strings in MySQL with LOB behavior, use one of
- the TEXT types, which the driver will treat as a
- java.sql.Clob.
- </para>
+ <para>To store strings in MySQL with LOB behavior, use one of the
+ TEXT types, which the driver will treat as a java.sql.Clob.</para>
</listitem>
<listitem>
- <para>
- Starting with Connector/J 3.1.8 a <quote>debug</quote>
- build of the driver in a file named
- "<filename>mysql-connector-java-[version]-bin-g.jar</filename>"
- is shipped alongside the normal <quote>binary</quote> jar
- file that is named
- "<filename>mysql-connector-java-[version]-bin.jar</filename>".
- </para>
+ <para>Starting with Connector/J 3.1.8 a <quote>debug</quote> build
+ of the driver in a file named
+ "<filename>mysql-connector-java-[version]-bin-g.jar</filename>" is
+ shipped alongside the normal <quote>binary</quote> jar file that
+ is named
+ "<filename>mysql-connector-java-[version]-bin.jar</filename>".</para>
- <para>
- Starting with Connector/J 3.1.9, we don't ship the .class
- files <quote>unbundled,</quote> they are only available in
- the JAR archives that ship with the driver.
- </para>
+ <para>Starting with Connector/J 3.1.9, we don't ship the .class
+ files <quote>unbundled,</quote> they are only available in the JAR
+ archives that ship with the driver.</para>
- <para>
- You should not use the <quote>debug</quote> build of the
- driver unless instructed to do so when reporting a problem
- or bug to MySQL AB, 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
- <filename>src/lib/aspectjrt.jar</filename> file that comes
- with the Connector/J distribution.
- </para>
+ <para>You should not use the <quote>debug</quote> build of the
+ driver unless instructed to do so when reporting a problem or bug
+ to MySQL AB, 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 <filename>src/lib/aspectjrt.jar</filename>
+ file that comes with the Connector/J distribution.</para>
</listitem>
-
</itemizedlist>
-
</section>
<section id="cj-jdbc-upgrading-issues">
+ <title>JDBC-Specific Issues When Upgrading to MySQL Server 4.1 or
+ Newer</title>
- <title>&title-cj-jdbc-upgrading-issues;</title>
-
<itemizedlist>
-
<listitem>
- <para>
- <emphasis>Using the UTF-8 Character Encoding</emphasis> -
- 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 latin1 tables on the server.
- </para>
+ <para><emphasis>Using the UTF-8 Character Encoding</emphasis> -
+ 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 latin1 tables
+ on the server.</para>
- <para>
- 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,
- you should add the following property to your connection
- URL:
- </para>
+ <para>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, you should add the following
+ property to your connection URL:</para>
- <para>
- <computeroutput>useOldUTF8Behavior=true</computeroutput>
- </para>
+ <para><computeroutput>useOldUTF8Behavior=true</computeroutput></para>
</listitem>
<listitem>
- <para>
- <emphasis>Server-side Prepared Statements</emphasis> -
- 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:
- </para>
+ <para><emphasis>Server-side Prepared Statements</emphasis> -
+ 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:</para>
- <para>
- <computeroutput>useServerPrepStmts=false</computeroutput>
- </para>
+ <para><computeroutput>useServerPrepStmts=false</computeroutput></para>
</listitem>
-
</itemizedlist>
-
</section>
-
</section>
+ <section>
+ <title>Installing from the Development Source Tree</title>
+
+ <para><caution>
+ <para>You should read this section only if you are interested in
+ helping us test our new code. If you just want to get MySQL
+ Connector/J up and running on your system, you should use a standard
+ release distribution.</para>
+ </caution>To install MySQL Connector/J from the development source
+ tree, the following prerequesites are required:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Subversion available from <ulink
+ url="http://subversion.tigris.org/">http://subversion.tigris.org/</ulink>,
+ to checkout the sources from our repository</para>
+ </listitem>
+
+ <listitem>
+ <para>Apache Ant version 1.6 or newer, from <ulink
+ url="http://ant.apache.org/">http://ant.apache.org/</ulink> </para>
+ </listitem>
+
+ <listitem>
+ <para>JDK-1.4.2 or later. Although MySQL Connector/J can be
+ installed on older JDKs, it requires at least JDK-1.4.2 for
+ compilation.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The Subversion source code repository for MySQL Connector/J is
+ located at <ulink
+ url="http://svn.mysql.com/svnpublic/connector-j">http://svn.mysql.com/svnpublic/connector-j</ulink>.
+ In general, you should not checkout the entire repository as it contains
+ every branch and tag for MySQL Connector/J and is quite large.</para>
+
+ <para>To checkout and compile a specfic branch of MySQL Connector/J,
+ follow these steps:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Check out the latest code from a branch (replacing [major] and
+ [minor] with appropriate version numbers. At the time of this
+ writing there are three active branches of Connector/J. They are
+ "branch_3_0", "branch_3_1" and "branch_5_0":</para>
+
+ <programlisting>svn co http://svn.mysql.com/svnpublic/connector-j/branches/branch_[major]_[minor]/connector-j</programlisting>
+
+ <para>This will create a "connector-j" subdirectory in the current
+ directory that contains the latest sources for the requested
+ branch.</para>
+ </listitem>
+
+ <listitem>
+ <para>Change the working directory to this "connector-j"
+ directory:</para>
+
+ <programlisting>shell> cd connector-j</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Issue the following command to compile the driver and create a
+ .jar file suitable for installation:</para>
+
+ <programlisting>ant dist</programlisting>
+
+ <para>This will create a "build" directory in the current directory,
+ where all build output will go. A directory is created in the build
+ directory that includes the version number of the sources you are
+ building from. This directory contains the sources, compiled .class
+ files, and a .jar file suitable for deployment. For other possible
+ targets, including ones which will create a fully-packaged
+ distribution, issue the following command:<programlisting>ant --projecthelp</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>A newly-created .jar file containing the JDBC driver will be
+ placed in the directory build/mysql-connector-java-[version].</para>
+
+ <para>Install the newly-created JDBC driver as you would a binary
+ .jar file you download from MySQL by following the instructions in
+ the section "<link linkend="???">Installing the Driver and
+ Configuring the
+ <literal>CLASSPATH</literal></link><literal>".</literal></para>
+ </listitem>
+ </orderedlist>
+ </section>
</section>
<section id="cj-jdbc-reference">
+ <title>JDBC Reference</title>
- <title>&title-cj-jdbc-reference;</title>
-
<para></para>
<section id="cj-configuration-properties">
+ <title>Driver/Datasource Class Names, URL Syntax and Configuration
+ Properties for Connector/J</title>
- <title>&title-cj-configuration-properties;</title>
+ <para>The name of the class that implements java.sql.Driver in MySQL
+ Connector/J is 'com.mysql.jdbc.Driver'. The 'org.gjt.mm.mysql.Driver'
+ class name is also usable to remain backward-compatible with MM.MySQL.
+ You should use this class name when registering the driver, or when
+ otherwise configuring software to use MySQL Connector/J.</para>
- <para>
- The name of the class that implements java.sql.Driver in MySQL
- Connector/J is 'com.mysql.jdbc.Driver'. The
- 'org.gjt.mm.mysql.Driver' class name is also usable to remain
- backward-compatible with MM.MySQL. You should use this class
- name when registering the driver, or when otherwise configuring
- software to use MySQL Connector/J.
- </para>
+ <para>The JDBC URL format for MySQL Connector/J is as follows, with
+ items in square brackets ([, ]) being optional: <screen>jdbc:mysql://[host][,failoverhost...][:port]/[database][?propertyName1][=propertyValue1][&propertyName2][=propertyValue2]...</screen></para>
- <para>
- The JDBC URL format for MySQL Connector/J is as follows, with
- items in square brackets ([, ]) being optional:
+ <para>If the hostname is not specified, it defaults to '127.0.0.1'. If
+ the port is not specified, it defaults to '3306', the default port
+ number for MySQL servers.</para>
- <screen>jdbc:mysql://[host][,failoverhost...][:port]/[database][?propertyName1][=propertyValue1][&propertyName2][=propertyValue2]...</screen>
- </para>
-
- <para>
- If the hostname is not specified, it defaults to '127.0.0.1'. If
- the port is not specified, it defaults to '3306', the default
- port number for MySQL servers.
- </para>
-
<screen>jdbc:mysql://[host:port],[host:port].../[database][?propertyName1][=propertyValue1][&propertyName2][=propertyValue2]...</screen>
- <para>
- If the database is not specified, the connection will be made
- with no default database. In this case, you will need to either
- call the <function>setCatalog()</function> method on the
- Connection instance or fully-specify table names using the
- database name (i.e. 'SELECT dbname.tablename.colname FROM
- dbname.tablename...') in your SQL. Not specifying the database
- to use upon connection is generally only useful when building
- tools that work with multiple databases, such as GUI database
- managers.
- </para>
+ <para>If the database is not specified, the connection will be made with
+ no default database. In this case, you will need to either call the
+ <function>setCatalog()</function> method on the Connection instance or
+ fully-specify table names using the database name (i.e. 'SELECT
+ dbname.tablename.colname FROM dbname.tablename...') in your SQL. Not
+ specifying the database to use upon connection is generally only useful
+ when building tools that work with multiple databases, such as GUI
+ database managers.</para>
- <para>
- MySQL Connector/J has fail-over support. This allows the driver
- to fail-over to any number of <quote>slave</quote> hosts and
- still perform read-only queries. Fail-over only happens when the
- connection is in an autoCommit(true) state, because fail-over
- can not happen reliably when a transaction is in progress. Most
- application servers and connection pools set autoCommit to
- 'true' at the end of every transaction/connection use.
- </para>
+ <para>MySQL Connector/J has fail-over support. This allows the driver to
+ fail-over to any number of <quote>slave</quote> hosts and still perform
+ read-only queries. Fail-over only happens when the connection is in an
+ autoCommit(true) state, because fail-over can not happen reliably when a
+ transaction is in progress. Most application servers and connection
+ pools set autoCommit to 'true' at the end of every
+ transaction/connection use.</para>
- <para>
- The fail-over functionality has the following behavior:
- </para>
+ <para>The fail-over functionality has the following behavior:</para>
- <para>
- If the URL property "autoReconnect" is false: Failover only
- happens at connection initialization, and failback occurs when
- the driver determines that the first host has become available
- again.
- </para>
+ <para>If the URL property "autoReconnect" is false: Failover only
+ happens at connection initialization, and failback occurs when the
+ driver determines that the first host has become available again.</para>
- <para>
- If the URL property "autoReconnect" is true: Failover happens
- when the driver determines that the connection has failed
- (before <emphasis>every</emphasis> query), and falls back to the
- first host when it determines that the host has become available
- again (after queriesBeforeRetryMaster queries have been issued).
- </para>
+ <para>If the URL property "autoReconnect" is true: Failover happens when
+ the driver determines that the connection has failed (before
+ <emphasis>every</emphasis> query), and falls back to the first host when
+ it determines that the host has become available again (after
+ queriesBeforeRetryMaster queries have been issued).</para>
- <para>
- In either case, whenever you are connected to a "failed-over"
- server, the connection will be set to read-only state, so
- queries that would modify data will have exceptions thrown (the
- query will <emphasis>never</emphasis> be processed by the MySQL
- server).
- </para>
+ <para>In either case, whenever you are connected to a "failed-over"
+ server, the connection will be set to read-only state, so queries that
+ would modify data will have exceptions thrown (the query will
+ <emphasis>never</emphasis> be processed by the MySQL server).</para>
- <para>
- Configuration properties define how Connector/J will make a
- connection to a MySQL server. Unless otherwise noted, properties
- can be set for a DataSource object or for a Connection object.
- </para>
+ <para>Configuration properties define how Connector/J will make a
+ connection to a MySQL server. Unless otherwise noted, properties can be
+ set for a DataSource object or for a Connection object.</para>
- <para>
- Configuration Properties can be set in one of the following
- ways:
- </para>
+ <para>Configuration Properties can be set in one of the following
+ ways:</para>
<itemizedlist>
-
<listitem>
- <para>
- Using the set*() methods on MySQL implementations of
- java.sql.DataSource (which is the preferred method when
- using implementations of java.sql.DataSource):
- </para>
+ <para>Using the set*() methods on MySQL implementations of
+ java.sql.DataSource (which is the preferred method when using
+ implementations of java.sql.DataSource):</para>
<itemizedlist>
-
<listitem>
- <para>
- com.mysql.jdbc.jdbc2.optional.MysqlDataSource
- </para>
+ <para>com.mysql.jdbc.jdbc2.optional.MysqlDataSource</para>
</listitem>
<listitem>
- <para>
- com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource
- </para>
+ <para>com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource</para>
</listitem>
-
</itemizedlist>
</listitem>
<listitem>
- <para>
- As a key/value pair in the java.util.Properties instance
- passed to DriverManager.getConnection() or Driver.connect()
- </para>
+ <para>As a key/value pair in the java.util.Properties instance
+ passed to DriverManager.getConnection() or Driver.connect()</para>
</listitem>
<listitem>
- <para>
- As a JDBC URL parameter in the URL given to
- java.sql.DriverManager.getConnection(),
- java.sql.Driver.connect() or the MySQL implementations of
- javax.sql.DataSource's setURL() method.
-
- <note>
-
- <para>
- If the mechanism you use to configure a JDBC URL is
- XML-based, you will need to use the XML character
- literal &amp; to separate configuration parameters,
- as the ampersand is a reserved character for XML.
- </para>
-
- </note>
- </para>
+ <para>As a JDBC URL parameter in the URL given to
+ java.sql.DriverManager.getConnection(), java.sql.Driver.connect() or
+ the MySQL implementations of javax.sql.DataSource's setURL() method.
+ <note>
+ <para>If the mechanism you use to configure a JDBC URL is
+ XML-based, you will need to use the XML character literal
+ &amp; to separate configuration parameters, as the ampersand
+ is a reserved character for XML.</para>
+ </note></para>
</listitem>
-
</itemizedlist>
- <para>
- The properties are listed in the following table:
- </para>
+ <para>The properties are listed in the following table:</para>
-<!-- Generated by the genPropertiesTable target in the build script -->
+ <!-- Generated by the genPropertiesTable target in the build script -->
<table>
-
<title>Connection Properties</title>
<tgroup cols="5">
<colspec colname="cj_propstbl_prop_name" />
+
<colspec colname="cj_propstbl_prop_defn" />
+
<colspec colname="cj_propstbl_required" />
+
<colspec colname="cj_propstbl_required" />
+
<colspec colname="cj_propstbl_since_version" />
+
<spanspec nameend="cj_propstbl_since_version"
namest="cj_propstbl_prop_name"
spanname="cj_propstbl_span_all_cols" />
- <thead>
+ <thead>
<row>
<entry>Property Name</entry>
+
<entry>Definition</entry>
+
<entry>Required?</entry>
+
<entry>Default Value</entry>
+
<entry>Since Version</entry>
</row>
-
</thead>
+
<tbody>
<row>
<entry
spanname="cj_propstbl_span_all_cols"><emphasis>Connection/Authentication</emphasis></entry>
</row>
+
<row>
<entry>user</entry>
+
<entry>The user to connect as</entry>
+
<entry>No</entry>
+
<entry></entry>
+
<entry>all</entry>
</row>
+
<row>
<entry>password</entry>
+
<entry>The password to use when connecting</entry>
+
<entry>No</entry>
+
<entry></entry>
+
<entry>all</entry>
</row>
+
<row>
<entry>socketFactory</entry>
- <entry>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.</entry>
+
+ <entry>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.</entry>
+
<entry>No</entry>
+
<entry>com.mysql.jdbc.StandardSocketFactory</entry>
+
<entry>3.0.3</entry>
</row>
+
<row>
<entry>connectTimeout</entry>
- <entry>Timeout for socket connect (in milliseconds), with 0 being no timeout.
- Only works on JDK-1.4 or newer. Defaults to '0'.</entry>
+
+ <entry>Timeout for socket connect (in milliseconds), with 0
+ being no timeout. Only works on JDK-1.4 or newer. Defaults to
+ '0'.</entry>
+
<entry>No</entry>
+
<entry>0</entry>
+
<entry>3.0.1</entry>
</row>
+
<row>
<entry>socketTimeout</entry>
- <entry>Timeout on network socket operations (0, the default means no timeout).</entry>
+
+ <entry>Timeout on network socket operations (0, the default
+ means no timeout).</entry>
+
<entry>No</entry>
+
<entry>0</entry>
+
<entry>3.0.1</entry>
</row>
+
<row>
<entry>useConfigs</entry>
- <entry>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.</entry>
+
+ <entry>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.</entry>
+
<entry>No</entry>
+
<entry></entry>
+
<entry>3.1.5</entry>
</row>
+
<row>
<entry>interactiveClient</entry>
- <entry>Set the CLIENT_INTERACTIVE flag, which tells MySQL to timeout
- connections based on INTERACTIVE_TIMEOUT instead of
- WAIT_TIMEOUT</entry>
+
+ <entry>Set the CLIENT_INTERACTIVE flag, which tells MySQL to
+ timeout connections based on INTERACTIVE_TIMEOUT instead of
+ WAIT_TIMEOUT</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.0</entry>
</row>
+
<row>
<entry>propertiesTransform</entry>
- <entry>An implementation of com.mysql.jdbc.ConnectionPropertiesTransform that
- the driver will use to modify URL properties passed to
- the driver before attempting a connection</entry>
+
+ <entry>An implementation of
+ com.mysql.jdbc.ConnectionPropertiesTransform that the driver
+ will use to modify URL properties passed to the driver before
+ attempting a connection</entry>
+
<entry>No</entry>
+
<entry></entry>
+
<entry>3.1.4</entry>
</row>
+
<row>
<entry>useCompression</entry>
- <entry>Use zlib compression when communicating with the server (true/false)?
- Defaults to 'false'.</entry>
+
+ <entry>Use zlib compression when communicating with the server
+ (true/false)? Defaults to 'false'.</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.0.17</entry>
</row>
+
<row>
- <entry spanname="cj_propstbl_span_all_cols"><emphasis>High Availability and Clustering</emphasis></entry>
+ <entry spanname="cj_propstbl_span_all_cols"><emphasis>High
+ Availability and Clustering</emphasis></entry>
</row>
+
<row>
<entry>autoReconnect</entry>
- <entry>Should the driver try to re-establish stale 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'thandle
- SQLExceptions properly, and is only designed to be used
- when you are unable to configure your application to
- handle SQLExceptions resulting from dead andstale
- connections properly. Alternatively, investigate setting
- the MySQL server variable "wait_timeout"to some high
- value rather than the default of 8 hours.</entry>
+
+ <entry>Should the driver try to re-establish stale 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'thandle SQLExceptions properly, and is only
+ designed to be used when you are unable to configure your
+ application to handle SQLExceptions resulting from dead andstale
+ connections properly. Alternatively, investigate setting the
+ MySQL server variable "wait_timeout"to some high value rather
+ than the default of 8 hours.</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>1.1</entry>
</row>
+
<row>
<entry>autoReconnectForPools</entry>
- <entry>Use a reconnection strategy appropriate for connection pools (defaults
- to 'false')</entry>
+
+ <entry>Use a reconnection strategy appropriate for connection
+ pools (defaults to 'false')</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.3</entry>
</row>
+
<row>
<entry>failOverReadOnly</entry>
- <entry>When failing over in autoReconnect mode, should the connection be set to
- 'read-only'?</entry>
+
+ <entry>When failing over in autoReconnect mode, should the
+ connection be set to 'read-only'?</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.0.12</entry>
</row>
+
<row>
<entry>reconnectAtTxEnd</entry>
- <entry>If autoReconnect is set to true, should the driver attempt
- reconnectionsat the end of every transaction?</entry>
+
+ <entry>If autoReconnect is set to true, should the driver
+ attempt reconnectionsat the end of every transaction?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.0.10</entry>
</row>
+
<row>
<entry>roundRobinLoadBalance</entry>
- <entry>When autoReconnect is enabled, and failoverReadonly is false, should we
- pick hosts to connect to on a round-robin basis?</entry>
+
+ <entry>When autoReconnect is enabled, and failoverReadonly is
+ false, should we pick hosts to connect to on a round-robin
+ basis?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.2</entry>
</row>
+
<row>
<entry>queriesBeforeRetryMaster</entry>
- <entry>Number of queries to issue before falling back to master 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 master. Defaults to 50.</entry>
+
+ <entry>Number of queries to issue before falling back to master
+ 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 master. Defaults to 50.</entry>
+
<entry>No</entry>
+
<entry>50</entry>
+
<entry>3.0.2</entry>
</row>
+
<row>
<entry>secondsBeforeRetryMaster</entry>
- <entry>How long should the driver wait, when failed over, before attempting to
- reconnect to the master server? Whichever condition is
- met first, 'queriesBeforeRetryMaster' or
- 'secondsBeforeRetryMaster' will cause an attempt to be
- made to reconnect to the master. Time in seconds,
- defaults to 30</entry>
+
+ <entry>How long should the driver wait, when failed over, before
+ attempting to reconnect to the master server? Whichever
+ condition is met first, 'queriesBeforeRetryMaster' or
+ 'secondsBeforeRetryMaster' will cause an attempt to be made to
+ reconnect to the master. Time in seconds, defaults to 30</entry>
+
<entry>No</entry>
+
<entry>30</entry>
+
<entry>3.0.2</entry>
</row>
+
<row>
<entry>enableDeprecatedAutoreconnect</entry>
- <entry>Auto-reconnect functionality is deprecated starting with version 3.2,
- and will be removed in version 3.3. Set this property to
- 'true' to disable the check for the feature being
- configured.</entry>
+
+ <entry>Auto-reconnect functionality is deprecated starting with
+ version 3.2, and will be removed in version 3.3. Set this
+ property to 'true' to disable the check for the feature being
+ configured.</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.2.1</entry>
</row>
+
<row>
<entry
spanname="cj_propstbl_span_all_cols"><emphasis>Security</emphasis></entry>
</row>
+
<row>
<entry>allowMultiQueries</entry>
- <entry>Allow the use of ';' to delimit multiple queries during one statement
- (true/false, defaults to 'false'</entry>
+
+ <entry>Allow the use of ';' to delimit multiple queries during
+ one statement (true/false, defaults to 'false'</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.1</entry>
</row>
+
<row>
<entry>useSSL</entry>
- <entry>Use SSL when communicating with the server (true/false), defaults to
- 'false'</entry>
+
+ <entry>Use SSL when communicating with the server (true/false),
+ defaults to 'false'</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.0.2</entry>
</row>
+
<row>
<entry>requireSSL</entry>
- <entry>Require SSL connection if useSSL=true? (defaults to 'false').</entry>
+
+ <entry>Require SSL connection if useSSL=true? (defaults to
+ 'false').</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.0</entry>
</row>
+
<row>
<entry>allowUrlInLocalInfile</entry>
- <entry>Should the driver allow URLs in 'LOAD DATA LOCAL INFILE' statements?</entry>
+
+ <entry>Should the driver allow URLs in 'LOAD DATA LOCAL INFILE'
+ statements?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.4</entry>
</row>
+
<row>
<entry>paranoid</entry>
- <entry>Take measures to prevent exposure sensitive information in error
- messages and clear data structures holding sensitive
- data when possible? (defaults to 'false')</entry>
+
+ <entry>Take measures to prevent exposure sensitive information
+ in error messages and clear data structures holding sensitive
+ data when possible? (defaults to 'false')</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.0.1</entry>
</row>
+
<row>
<entry
- spanname="cj_propstbl_span_all_cols"><emphasis>Performance Extensions</emphasis></entry>
+ spanname="cj_propstbl_span_all_cols"><emphasis>Performance
+ Extensions</emphasis></entry>
</row>
+
<row>
<entry>metadataCacheSize</entry>
+
<entry>The number of queries to cacheResultSetMetadata for if
- cacheResultSetMetaData is set to 'true' (default 50)</entry>
+ cacheResultSetMetaData is set to 'true' (default 50)</entry>
+
<entry>No</entry>
+
<entry>50</entry>
+
<entry>3.1.1</entry>
</row>
+
<row>
<entry>prepStmtCacheSize</entry>
- <entry>If prepared statement caching is enabled, how many prepared statements
- should be cached?</entry>
+
+ <entry>If prepared statement caching is enabled, how many
+ prepared statements should be cached?</entry>
+
<entry>No</entry>
+
<entry>25</entry>
+
<entry>3.0.10</entry>
</row>
+
<row>
<entry>prepStmtCacheSqlLimit</entry>
- <entry>If prepared statement caching is enabled, what's the largest SQL the
- driver will cache the parsing for?</entry>
+
+ <entry>If prepared statement caching is enabled, what's the
+ largest SQL the driver will cache the parsing for?</entry>
+
<entry>No</entry>
+
<entry>256</entry>
+
<entry>3.0.10</entry>
</row>
+
<row>
<entry>useCursorFetch</entry>
- <entry>If connected to MySQL > 5.0.2, and setFetchSize() > 0 on a
- statement, should that statement use cursor-based
- fetching to retrieve rows?</entry>
+
+ <entry>If connected to MySQL > 5.0.2, and setFetchSize() >
+ 0 on a statement, should that statement use cursor-based
+ fetching to retrieve rows?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>5.0.0</entry>
</row>
+
<row>
<entry>blobSendChunkSize</entry>
- <entry>Chunk to use when sending BLOB/CLOBs via ServerPreparedStatements</entry>
+
+ <entry>Chunk to use when sending BLOB/CLOBs via
+ ServerPreparedStatements</entry>
+
<entry>No</entry>
+
<entry>1048576</entry>
+
<entry>3.1.9</entry>
</row>
+
<row>
<entry>cacheCallableStmts</entry>
- <entry>Should the driver cache the parsing stage of CallableStatements</entry>
+
+ <entry>Should the driver cache the parsing stage of
+ CallableStatements</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.2</entry>
</row>
+
<row>
<entry>cachePrepStmts</entry>
- <entry>Should the driver cache the parsing stage of PreparedStatements of
- client-side prepared statements, the
- <quote>check</quote> for suitability of server-side
- prepared and server-side prepared statements themselves?</entry>
+
+ <entry>Should the driver cache the parsing stage of
+ PreparedStatements of client-side prepared statements, the
+ <quote>check</quote> for suitability of server-side prepared and
+ server-side prepared statements themselves?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.0.10</entry>
</row>
+
<row>
<entry>cacheResultSetMetadata</entry>
- <entry>Should the driver cache ResultSetMetaData for Statements and
- PreparedStatements? (Req. JDK-1.4+, true/false, default
- 'false')</entry>
+
+ <entry>Should the driver cache ResultSetMetaData for Statements
+ and PreparedStatements? (Req. JDK-1.4+, true/false, default
+ 'false')</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.1</entry>
</row>
+
<row>
<entry>cacheServerConfiguration</entry>
- <entry>Should the driver cache the results of 'SHOW VARIABLES' and 'SHOW
- COLLATION' on a per-URL basis?</entry>
+
+ <entry>Should the driver cache the results of 'SHOW VARIABLES'
+ and 'SHOW COLLATION' on a per-URL basis?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.5</entry>
</row>
+
<row>
<entry>defaultFetchSize</entry>
- <entry>The driver will call setFetchSize(n) with this value on all
- newly-created Statements</entry>
+
+ <entry>The driver will call setFetchSize(n) with this value on
+ all newly-created Statements</entry>
+
<entry>No</entry>
+
<entry>0</entry>
+
<entry>3.1.9</entry>
</row>
+
<row>
<entry>dontTrackOpenResources</entry>
- <entry>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.</entry>
+
+ <entry>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.</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.7</entry>
</row>
+
<row>
<entry>dynamicCalendars</entry>
- <entry>Should the driver retrieve the default calendar when required, or cache
- it per connection/session?</entry>
+
+ <entry>Should the driver retrieve the default calendar when
+ required, or cache it per connection/session?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.5</entry>
</row>
+
<row>
<entry>elideSetAutoCommits</entry>
- <entry>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)?</entry>
+
+ <entry>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)?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.3</entry>
</row>
+
<row>
<entry>holdResultsOpenOverStatementClose</entry>
- <entry>Should the driver close result sets on Statement.close() as required by
- the JDBC specification?</entry>
+
+ <entry>Should the driver close result sets on Statement.close()
+ as required by the JDBC specification?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.7</entry>
</row>
+
<row>
<entry>locatorFetchBufferSize</entry>
- <entry>If 'emulateLocators' is configured to 'true', what size buffer should be
- used when fetching BLOB data for getBinaryInputStream?</entry>
+
+ <entry>If 'emulateLocators' is configured to 'true', what size
+ buffer should be used when fetching BLOB data for
+ getBinaryInputStream?</entry>
+
<entry>No</entry>
+
<entry>1048576</entry>
+
<entry>3.2.1</entry>
</row>
+
<row>
<entry>useFastIntParsing</entry>
- <entry>Use internal String->Integer conversion routines to avoid excessive
- object creation?</entry>
+
+ <entry>Use internal String->Integer conversion routines to
+ avoid excessive object creation?</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.1.4</entry>
</row>
+
<row>
<entry>useLocalSessionState</entry>
- <entry>Should the driver refer to the internal values of autocommit and
- transaction isolation that are set by
- Connection.setAutoCommit() and
- Connection.setTransactionIsolation(), rather than
- querying the database?</entry>
+
+ <entry>Should the driver refer to the internal values of
+ autocommit and transaction isolation that are set by
+ Connection.setAutoCommit() and
+ Connection.setTransactionIsolation(), rather than querying the
+ database?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.7</entry>
</row>
+
<row>
<entry>useReadAheadInput</entry>
- <entry>Use newer, optimized non-blocking, buffered input stream when reading
- from the server?</entry>
+
+ <entry>Use newer, optimized non-blocking, buffered input stream
+ when reading from the server?</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.1.5</entry>
</row>
+
<row>
<entry
spanname="cj_propstbl_span_all_cols"><emphasis>Debuging/Profiling</emphasis></entry>
</row>
+
<row>
<entry>logger</entry>
- <entry>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)</entry>
+
+ <entry>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)</entry>
+
<entry>No</entry>
+
<entry>com.mysql.jdbc.log.StandardLogger</entry>
+
<entry>3.1.1</entry>
</row>
+
<row>
<entry>profileSQL</entry>
- <entry>Trace queries and their execution/fetch times to the configured logger
- (true/false) defaults to 'false'</entry>
+
+ <entry>Trace queries and their execution/fetch times to the
+ configured logger (true/false) defaults to 'false'</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.0</entry>
</row>
+
<row>
<entry>reportMetricsIntervalMillis</entry>
- <entry>If 'gatherPerfMetrics' is enabled, how often should they be logged (in
- ms)?</entry>
+
+ <entry>If 'gatherPerfMetrics' is enabled, how often should they
+ be logged (in ms)?</entry>
+
<entry>No</entry>
+
<entry>30000</entry>
+
<entry>3.1.2</entry>
</row>
+
<row>
<entry>maxQuerySizeToLog</entry>
- <entry>Controls the maximum length/size of a query that will get logged when
- profiling or tracing</entry>
+
+ <entry>Controls the maximum length/size of a query that will get
+ logged when profiling or tracing</entry>
+
<entry>No</entry>
+
<entry>2048</entry>
+
<entry>3.1.3</entry>
</row>
+
<row>
<entry>packetDebugBufferSize</entry>
- <entry>The maximum number of packets to retain when 'enablePacketDebug' is true</entry>
+
+ <entry>The maximum number of packets to retain when
+ 'enablePacketDebug' is true</entry>
+
<entry>No</entry>
+
<entry>20</entry>
+
<entry>3.1.3</entry>
</row>
+
<row>
<entry>slowQueryThresholdMillis</entry>
- <entry>If 'logSlowQueries' is enabled, how long should a query (in ms) before
- it is logged as 'slow'?</entry>
+
+ <entry>If 'logSlowQueries' is enabled, how long should a query
+ (in ms) before it is logged as 'slow'?</entry>
+
<entry>No</entry>
+
<entry>2000</entry>
+
<entry>3.1.2</entry>
</row>
+
<row>
<entry>useUsageAdvisor</entry>
- <entry>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')?</entry>
+
+ <entry>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')?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.1</entry>
</row>
+
<row>
<entry>autoGenerateTestcaseScript</entry>
- <entry>Should the driver dump the SQL it is executing, including server-side
- prepared statements to STDERR?</entry>
+
+ <entry>Should the driver dump the SQL it is executing, including
+ server-side prepared statements to STDERR?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.9</entry>
</row>
+
<row>
<entry>dumpMetadataOnColumnNotFound</entry>
- <entry>Should the driver dump the field-level metadata of a result set into the
- exception message when ResultSet.findColumn() fails?</entry>
+
+ <entry>Should the driver dump the field-level metadata of a
+ result set into the exception message when
+ ResultSet.findColumn() fails?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.13</entry>
</row>
+
<row>
<entry>dumpQueriesOnException</entry>
- <entry>Should the driver dump the contents of the query sent to the server in
- the message for SQLExceptions?</entry>
+
+ <entry>Should the driver dump the contents of the query sent to
+ the server in the message for SQLExceptions?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.3</entry>
</row>
+
<row>
<entry>enablePacketDebug</entry>
- <entry>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</entry>
+
+ <entry>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</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.3</entry>
</row>
+
<row>
<entry>explainSlowQueries</entry>
- <entry>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?</entry>
+
+ <entry>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?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.2</entry>
</row>
+
<row>
<entry>logSlowQueries</entry>
- <entry>Should queries that take longer than 'slowQueryThresholdMillis' be
- logged?</entry>
+
+ <entry>Should queries that take longer than
+ 'slowQueryThresholdMillis' be logged?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.2</entry>
</row>
+
<row>
<entry>traceProtocol</entry>
+
<entry>Should trace-level network protocol be logged?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.2</entry>
</row>
+
<row>
<entry
spanname="cj_propstbl_span_all_cols"><emphasis>Miscellaneous</emphasis></entry>
</row>
+
<row>
<entry>useUnicode</entry>
- <entry>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'</entry>
+
+ <entry>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'</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>1.1g</entry>
</row>
+
<row>
<entry>characterEncoding</entry>
- <entry>If 'useUnicode' is set to true, what character encoding should the
- driver use when dealing with strings? (defaults is to
- 'autodetect')</entry>
+
+ <entry>If 'useUnicode' is set to true, what character encoding
+ should the driver use when dealing with strings? (defaults is to
+ 'autodetect')</entry>
+
<entry>No</entry>
+
<entry></entry>
+
<entry>1.1g</entry>
</row>
+
<row>
<entry>characterSetResults</entry>
- <entry>Character set to tell the server to return results as.</entry>
+
+ <entry>Character set to tell the server to return results
+ as.</entry>
+
<entry>No</entry>
+
<entry></entry>
+
<entry>3.0.13</entry>
</row>
+
<row>
<entry>connectionCollation</entry>
+
<entry>If set, tells the server to use this collation via 'set
- collation_connection'</entry>
+ collation_connection'</entry>
+
<entry>No</entry>
+
<entry></entry>
+
<entry>3.0.13</entry>
</row>
+
<row>
<entry>sessionVariables</entry>
- <entry>A comma-separated list of name/value pairs to be sent as SET SESSION ...
- to the server when the driver connects.</entry>
+
+ <entry>A comma-separated list of name/value pairs to be sent as
+ SET SESSION ... to the server when the driver connects.</entry>
+
<entry>No</entry>
+
<entry></entry>
+
<entry>3.1.8</entry>
</row>
+
<row>
<entry>allowNanAndInf</entry>
+
<entry>Should the driver allow NaN or +/- INF values in
- PreparedStatement.setDouble()?</entry>
+ PreparedStatement.setDouble()?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.5</entry>
</row>
+
<row>
<entry>autoClosePStmtStreams</entry>
- <entry>Should the driver automatically call .close() on streams/readers passed
- as arguments via set*() methods?</entry>
+
+ <entry>Should the driver automatically call .close() on
+ streams/readers passed as arguments via set*() methods?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.12</entry>
</row>
+
<row>
<entry>autoDeserialize</entry>
- <entry>Should the driver automatically detect and de-serialize objects stored
- in BLOB fields?</entry>
+
+ <entry>Should the driver automatically detect and de-serialize
+ objects stored in BLOB fields?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.5</entry>
</row>
+
<row>
<entry>capitalizeTypeNames</entry>
- <entry>Capitalize type names in DatabaseMetaData? (usually only useful when
- using WebObjects, true/false, defaults to 'false')</entry>
+
+ <entry>Capitalize type names in DatabaseMetaData? (usually only
+ useful when using WebObjects, true/false, defaults to
+ 'false')</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>2.0.7</entry>
</row>
+
<row>
<entry>clobCharacterEncoding</entry>
- <entry>The character encoding to use for sending and retrieving TEXT,
- MEDIUMTEXT and LONGTEXT values instead of the configured
- connection characterEncoding</entry>
+
+ <entry>The character encoding to use for sending and retrieving
+ TEXT, MEDIUMTEXT and LONGTEXT values instead of the configured
+ connection characterEncoding</entry>
+
<entry>No</entry>
+
<entry></entry>
+
<entry>5.0.0</entry>
</row>
+
<row>
<entry>clobberStreamingResults</entry>
- <entry>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.</entry>
+
+ <entry>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.</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.0.9</entry>
</row>
+
<row>
<entry>continueBatchOnError</entry>
- <entry>Should the driver continue processing batch commands if one statement
- fails. The JDBC spec allows either way (defaults to
- 'true').</entry>
+
+ <entry>Should the driver continue processing batch commands if
+ one statement fails. The JDBC spec allows either way (defaults
+ to 'true').</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.0.3</entry>
</row>
+
<row>
<entry>createDatabaseIfNotExist</entry>
- <entry>Creates the database given in the URL if it doesn't yet exist. Assumes
- the configured user has permissions to create databases.</entry>
+
+ <entry>Creates the database given in the URL if it doesn't yet
+ exist. Assumes the configured user has permissions to create
+ databases.</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.9</entry>
</row>
+
<row>
<entry>emptyStringsConvertToZero</entry>
- <entry>Should the driver allow conversions from empty string fields to numeric
- values of '0'?</entry>
+
+ <entry>Should the driver allow conversions from empty string
+ fields to numeric values of '0'?</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.1.8</entry>
</row>
+
<row>
<entry>emulateLocators</entry>
+
<entry>N/A</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.0</entry>
</row>
+
<row>
<entry>emulateUnsupportedPstmts</entry>
- <entry>Should the driver detect prepared statements that are not supported by
- the server, and replace them with client-side emulated
- versions?</entry>
+
+ <entry>Should the driver detect prepared statements that are not
+ supported by the server, and replace them with client-side
+ emulated versions?</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.1.7</entry>
</row>
+
<row>
<entry>ignoreNonTxTables</entry>
- <entry>Ignore non-transactional table warning for rollback? (defaults to
- 'false').</entry>
+
+ <entry>Ignore non-transactional table warning for rollback?
+ (defaults to 'false').</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.0.9</entry>
</row>
+
<row>
<entry>jdbcCompliantTruncation</entry>
- <entry>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)?</entry>
+
+ <entry>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)?</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.1.2</entry>
</row>
+
<row>
<entry>maxRows</entry>
- <entry>The maximum number of rows to return (0, the default means return all
- rows).</entry>
+
+ <entry>The maximum number of rows to return (0, the default
+ means return all rows).</entry>
+
<entry>No</entry>
+
<entry>-1</entry>
+
<entry>all versions</entry>
</row>
+
<row>
<entry>noDatetimeStringSync</entry>
+
<entry>Don't ensure that
- ResultSet.getDatetimeType().toString().equals(ResultSet.getString())</entry>
+ ResultSet.getDatetimeType().toString().equals(ResultSet.getString())</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.7</entry>
</row>
+
<row>
<entry>noTimezoneConversionForTimeType</entry>
+
<entry>Don't convert TIME values using the server timezone if
- 'useTimezone'='true'</entry>
+ 'useTimezone'='true'</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>5.0.0</entry>
</row>
+
<row>
<entry>nullCatalogMeansCurrent</entry>
- <entry>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)</entry>
+
+ <entry>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)</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.1.8</entry>
</row>
+
<row>
<entry>nullNamePatternMatchesAll</entry>
- <entry>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)</entry>
+
+ <entry>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)</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.1.8</entry>
</row>
+
<row>
<entry>overrideSupportsIntegrityEnhancementFacility</entry>
+
<entry>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)?</entry>
+ 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)?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.12</entry>
</row>
+
<row>
<entry>pedantic</entry>
+
<entry>Follow the JDBC spec to the letter.</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.0.0</entry>
</row>
+
<row>
<entry>processEscapeCodesForPrepStmts</entry>
- <entry>Should the driver process escape codes in queries that are prepared?</entry>
+
+ <entry>Should the driver process escape codes in queries that
+ are prepared?</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.1.12</entry>
</row>
+
<row>
<entry>relaxAutoCommit</entry>
- <entry>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')?</entry>
+
+ <entry>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')?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>2.0.13</entry>
</row>
+
<row>
<entry>retainStatementAfterResultSetClose</entry>
- <entry>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.</entry>
+
+ <entry>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.</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.11</entry>
</row>
+
<row>
<entry>rollbackOnPooledClose</entry>
- <entry>Should the driver issue a rollback() when the logical connection in a
- pool is closed?</entry>
+
+ <entry>Should the driver issue a rollback() when the logical
+ connection in a pool is closed?</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.0.15</entry>
</row>
+
<row>
<entry>runningCTS13</entry>
- <entry>Enables workarounds for bugs in Sun's JDBC compliance testsuite version
- 1.3</entry>
+
+ <entry>Enables workarounds for bugs in Sun's JDBC compliance
+ testsuite version 1.3</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.7</entry>
</row>
+
<row>
<entry>serverTimezone</entry>
- <entry>Override detection/mapping of timezone. Used when timezone from server
- doesn't map to Java timezone</entry>
+
+ <entry>Override detection/mapping of timezone. Used when
+ timezone from server doesn't map to Java timezone</entry>
+
<entry>No</entry>
+
<entry></entry>
+
<entry>3.0.2</entry>
</row>
+
<row>
<entry>strictFloatingPoint</entry>
+
<entry>Used only in older versions of compliance test</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.0.0</entry>
</row>
+
<row>
<entry>strictUpdates</entry>
- <entry>Should the driver do strict checking (all primary keys selected) of
- updatable result sets (true, false, defaults to 'true')?</entry>
+
+ <entry>Should the driver do strict checking (all primary keys
+ selected) of updatable result sets (true, false, defaults to
+ 'true')?</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.0.4</entry>
</row>
+
<row>
<entry>tinyInt1isBit</entry>
- <entry>Should the driver treat the datatype TINYINT(1) as the BIT type (because
- the server silently converts BIT -> TINYINT(1) when
- creating tables)?</entry>
+
+ <entry>Should the driver treat the datatype TINYINT(1) as the
+ BIT type (because the server silently converts BIT ->
+ TINYINT(1) when creating tables)?</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.0.16</entry>
</row>
+
<row>
<entry>transformedBitIsBoolean</entry>
- <entry>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?</entry>
+
+ <entry>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?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.9</entry>
</row>
+
<row>
<entry>ultraDevHack</entry>
- <entry>Create PreparedStatements for prepareCall() when required, because
- UltraDev is broken and issues a prepareCall() for _all_
- statements? (true/false, defaults to 'false')</entry>
+
+ <entry>Create PreparedStatements for prepareCall() when
+ required, because UltraDev is broken and issues a prepareCall()
+ for _all_ statements? (true/false, defaults to 'false')</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>2.0.3</entry>
</row>
+
<row>
<entry>useGmtMillisForDatetimes</entry>
- <entry>Convert between session timezone and GMT before creating Date and
- Timestamp instances (value of "false" is legacy
- behavior, "true" leads to more JDBC-compliant behavior.</entry>
+
+ <entry>Convert between session timezone and GMT before creating
+ Date and Timestamp instances (value of "false" is legacy
+ behavior, "true" leads to more JDBC-compliant behavior.</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.12</entry>
</row>
+
<row>
<entry>useHostsInPrivileges</entry>
- <entry>Add '@hostname' to users in DatabaseMetaData.getColumn/TablePrivileges()
- (true/false), defaults to 'true'.</entry>
+
+ <entry>Add '@hostname' to users in
+ DatabaseMetaData.getColumn/TablePrivileges() (true/false),
+ defaults to 'true'.</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.0.2</entry>
</row>
+
<row>
<entry>useInformationSchema</entry>
- <entry>When connected to MySQL-5.0.7 or newer, should the driver use the
- INFORMATION_SCHEMA to derive information used by
- DatabaseMetaData?</entry>
+
+ <entry>When connected to MySQL-5.0.7 or newer, should the driver
+ use the INFORMATION_SCHEMA to derive information used by
+ DatabaseMetaData?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>5.0.0</entry>
</row>
+
<row>
<entry>useJDBCCompliantTimezoneShift</entry>
- <entry>Should the driver use JDBC-compliant rules when converting
- TIME/TIMESTAMP/DATETIME values' timezone information for
- those JDBC arguments which take a java.util.Calendar
- argument? (Notice that this option is exclusive of the
- "useTimezone=true" configuration option.)</entry>
+
+ <entry>Should the driver use JDBC-compliant rules when
+ converting TIME/TIMESTAMP/DATETIME values' timezone information
+ for those JDBC arguments which take a java.util.Calendar
+ argument? (Notice that this option is exclusive of the
+ "useTimezone=true" configuration option.)</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>5.0.0</entry>
</row>
+
<row>
<entry>useOldUTF8Behavior</entry>
- <entry>Use the UTF-8 behavior the driver did when communicating with 4.0 and
- older servers</entry>
+
+ <entry>Use the UTF-8 behavior the driver did when communicating
+ with 4.0 and older servers</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.1.6</entry>
</row>
+
<row>
<entry>useOnlyServerErrorMessages</entry>
- <entry>Don't prepend 'standard' SQLState error messages to error messages
- returned by the server.</entry>
+
+ <entry>Don't prepend 'standard' SQLState error messages to error
+ messages returned by the server.</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.0.15</entry>
</row>
+
<row>
<entry>useServerPrepStmts</entry>
- <entry>Use server-side prepared statements if the server supports them?
- (defaults to 'true').</entry>
+
+ <entry>Use server-side prepared statements if the server
+ supports them? (defaults to 'true').</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.1.0</entry>
</row>
+
<row>
<entry>useSqlStateCodes</entry>
- <entry>Use SQL Standard state codes instead of 'legacy' X/Open/SQL state codes
- (true/false), default is 'true'</entry>
+
+ <entry>Use SQL Standard state codes instead of 'legacy'
+ X/Open/SQL state codes (true/false), default is 'true'</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.1.3</entry>
</row>
+
<row>
<entry>useStreamLengthsInPrepStmts</entry>
+
<entry>Honor stream length parameter in
- PreparedStatement/ResultSet.setXXXStream() method calls
- (true/false, defaults to 'true')?</entry>
+ PreparedStatement/ResultSet.setXXXStream() method calls
+ (true/false, defaults to 'true')?</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.0.2</entry>
</row>
+
<row>
<entry>useTimezone</entry>
- <entry>Convert time/date types between client and server timezones (true/false,
- defaults to 'false')?</entry>
+
+ <entry>Convert time/date types between client and server
+ timezones (true/false, defaults to 'false')?</entry>
+
<entry>No</entry>
+
<entry>false</entry>
+
<entry>3.0.2</entry>
</row>
+
<row>
<entry>useUnbufferedInput</entry>
- <entry>Don't use BufferedInputStream for reading data from the server</entry>
+
+ <entry>Don't use BufferedInputStream for reading data from the
+ server</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.0.11</entry>
</row>
+
<row>
<entry>yearIsDateType</entry>
- <entry>Should the JDBC driver treat the MySQL type "YEAR" as a java.sql.Date,
- or as a SHORT?</entry>
+
+ <entry>Should the JDBC driver treat the MySQL type "YEAR" as a
+ java.sql.Date, or as a SHORT?</entry>
+
<entry>No</entry>
+
<entry>true</entry>
+
<entry>3.1.9</entry>
</row>
+
<row>
<entry>zeroDateTimeBehavior</entry>
- <entry>What should happen when the driver encounters DATETIME values that are
- composed entirely of zeroes (used by MySQL to represent
- invalid dates)? Valid values are 'exception', 'round'
- and 'convertToNull'.</entry>
+
+ <entry>What should happen when the driver encounters DATETIME
+ values that are composed entirely of zeroes (used by MySQL to
+ represent invalid dates)? Valid values are 'exception', 'round'
+ and 'convertToNull'.</entry>
+
<entry>No</entry>
+
<entry>exception</entry>
+
<entry>3.1.4</entry>
</row>
</tbody>
</tgroup>
-
</table>
- <para>
- Connector/J also supports access to MySQL via named pipes on
- Windows NT/2000/XP using the 'NamedPipeSocketFactory' as a
- plugin-socket factory via the 'socketFactory' property. If you
- don't use a 'namedPipePath' property, the default of
- '\\.\pipe\MySQL' will be used. If you use the
- NamedPipeSocketFactory, the hostname and port number values in
- the JDBC url will be ignored.
- </para>
+ <para>Connector/J also supports access to MySQL via named pipes on
+ Windows NT/2000/XP using the 'NamedPipeSocketFactory' as a plugin-socket
+ factory via the 'socketFactory' property. If you don't use a
+ 'namedPipePath' property, the default of '\\.\pipe\MySQL' will be used.
+ If you use the NamedPipeSocketFactory, the hostname and port number
+ values in the JDBC url will be ignored.</para>
- <para>
- Adding the following property to your URL will enable the
- NamedPipeSocketFactory:
- </para>
+ <para>Adding the following property to your URL will enable the
+ NamedPipeSocketFactory:</para>
- <para>
- socketFactory=com.mysql.jdbc.NamedPipeSocketFactory
- </para>
+ <para>socketFactory=com.mysql.jdbc.NamedPipeSocketFactory</para>
- <para>
- Named pipes only work when connecting to a MySQL server on the
- same physical machine as the one the JDBC driver is being used
- on. In simple performance tests, it appears that named pipe
- access is between 30%-50% faster than the standard TCP/IP
- access.
- </para>
+ <para>Named pipes only work when connecting to a MySQL server on the
+ same physical machine as the one the JDBC driver is being used on. In
+ simple performance tests, it appears that named pipe access is between
+ 30%-50% faster than the standard TCP/IP access.</para>
- <para>
- You can create your own socket factories by following the
- example code in
- <classname>com.mysql.jdbc.NamedPipeSocketFactory</classname>, or
- <classname>com.mysql.jdbc.StandardSocketFactory</classname>.
- </para>
-
+ <para>You can create your own socket factories by following the example
+ code in <classname>com.mysql.jdbc.NamedPipeSocketFactory</classname>, or
+ <classname>com.mysql.jdbc.StandardSocketFactory</classname>.</para>
</section>
<section id="cj-implementation-notes">
+ <title>JDBC API Implementation Notes</title>
- <title>&title-cj-implementation-notes;</title>
+ <para>MySQL Connector/J passes all of the tests in the
+ publicly-available version of Sun's JDBC compliance test suite. However,
+ in many places the JDBC specification is vague about how certain
+ functionality should be implemented, or the specification allows leeway
+ in implementation.</para>
- <para>
- MySQL Connector/J passes all of the tests in the
- publicly-available version of Sun's JDBC compliance test suite.
- However, in many places the JDBC specification is vague about
- how certain functionality should be implemented, or the
- specification allows leeway in implementation.
- </para>
+ <para>This section gives details on a interface-by-interface level about
+ how certain implementation decisions may affect how you use MySQL
+ Connector/J.</para>
- <para>
- This section gives details on a interface-by-interface level
- about how certain implementation decisions may affect how you
- use MySQL Connector/J.
- </para>
-
<itemizedlist>
-
<listitem>
- <para>
- Blob
- </para>
+ <para>Blob</para>
- <para>
- The Blob implementation does not allow in-place modification
- (they are 'copies', as reported by the
- DatabaseMetaData.locatorsUpdateCopies() method). Because of
- this, you should use the corresponding
- PreparedStatement.setBlob() or ResultSet.updateBlob() (in
- the case of updatable result sets) methods to save changes
- back to the database.
- </para>
+ <para>The Blob implementation does not allow in-place modification
+ (they are 'copies', as reported by the
+ DatabaseMetaData.locatorsUpdateCopies() method). Because of this,
+ you should use the corresponding PreparedStatement.setBlob() or
+ ResultSet.updateBlob() (in the case of updatable result sets)
+ methods to save changes back to the database.</para>
- <para>
- Starting with Connector/J version 3.1.0, you can emulate
- Blobs with locators by adding the property
- 'emulateLocators=true' to your JDBC URL. You must then use a
- column alias with the value of the column set to the actual
- name of the Blob column in the SELECT that you write to
- retrieve the Blob. The SELECT must also reference only one
- table, the table must have a primary key, and the SELECT
- must cover all columns that make up the primary key. The
- driver will then delay loading the actual Blob data until
- you retrieve the Blob and call retrieval methods
- (getInputStream(), getBytes(), and so forth) on it.
- </para>
+ <para>Starting with Connector/J version 3.1.0, you can emulate Blobs
+ with locators by adding the property 'emulateLocators=true' to your
+ JDBC URL. You must then use a column alias with the value of the
+ column set to the actual name of the Blob column in the SELECT that
+ you write to retrieve the Blob. The SELECT must also reference only
+ one table, the table must have a primary key, and the SELECT must
+ cover all columns that make up the primary key. The driver will then
+ delay loading the actual Blob data until you retrieve the Blob and
+ call retrieval methods (getInputStream(), getBytes(), and so forth)
+ on it.</para>
</listitem>
<listitem>
- <para>
- CallableStatement
- </para>
+ <para>CallableStatement</para>
- <para>
- Starting with Connector/J 3.1.1, stored procedures are
- supported when connecting to MySQL version 5.0 or newer via
- the <classname>CallableStatement</classname> interface.
- Currently, the <function>getParameterMetaData()</function>
- method of <classname>CallableStatement</classname> is not
- supported.
- </para>
+ <para>Starting with Connector/J 3.1.1, stored procedures are
+ supported when connecting to MySQL version 5.0 or newer via the
+ <classname>CallableStatement</classname> interface. Currently, the
+ <function>getParameterMetaData()</function> method of
+ <classname>CallableStatement</classname> is not supported.</para>
</listitem>
<listitem>
- <para>
- Clob
- </para>
+ <para>Clob</para>
- <para>
- The Clob implementation does not allow in-place modification
- (they are 'copies', as reported by the
- DatabaseMetaData.locatorsUpdateCopies() method). Because of
- this, you should use the PreparedStatement.setClob() method
- to save changes back to the database. The JDBC API does not
- have a ResultSet.updateClob() method.
- </para>
+ <para>The Clob implementation does not allow in-place modification
+ (they are 'copies', as reported by the
+ DatabaseMetaData.locatorsUpdateCopies() method). Because of this,
+ you should use the PreparedStatement.setClob() method to save
+ changes back to the database. The JDBC API does not have a
+ ResultSet.updateClob() method.</para>
</listitem>
<listitem>
- <para>
- Connection
- </para>
+ <para>Connection</para>
- <para>
- Unlike older versions of MM.MySQL the
- <function>isClosed()</function> method does not
- <quote>ping</quote> the server to determine if it is alive.
- In accordance with the JDBC specification, it only returns
- true if 'closed()' has been called on the connection. If you
- need to determine if the connection is still valid, you
- should issue a simple query, such as "SELECT 1". The driver
- will throw an exception if the connection is no longer
- valid.
- </para>
+ <para>Unlike older versions of MM.MySQL the
+ <function>isClosed()</function> method does not <quote>ping</quote>
+ the server to determine if it is alive. In accordance with the JDBC
+ specification, it only returns true if 'closed()' has been called on
+ the connection. If you need to determine if the connection is still
+ valid, you should issue a simple query, such as "SELECT 1". The
+ driver will throw an exception if the connection is no longer
+ valid.</para>
</listitem>
<listitem>
- <para>
- DatabaseMetaData
- </para>
+ <para>DatabaseMetaData</para>
- <para>
- Foreign Key information (getImported/ExportedKeys() and
- getCrossReference()) is only available from 'InnoDB'-type
- tables. However, the driver uses 'SHOW CREATE TABLE' to
- retrieve this information, so when other storage engines
- support foreign keys, the driver will transparently support
- them as well.
- </para>
+ <para>Foreign Key information (getImported/ExportedKeys() and
+ getCrossReference()) is only available from 'InnoDB'-type tables.
+ However, the driver uses 'SHOW CREATE TABLE' to retrieve this
+ information, so when other storage engines support foreign keys, the
+ driver will transparently support them as well.</para>
</listitem>
<listitem>
- <para>
- Driver
- </para>
+ <para>Driver</para>
</listitem>
<listitem>
- <para>
- PreparedStatement
- </para>
+ <para>PreparedStatement</para>
- <para>
- PreparedStatements are implemented by the driver, as MySQL
- does not have a prepared statement feature. Because of this,
- the driver does not implement getParameterMetaData() or
- getMetaData() as it would require the driver to have a
- complete SQL parser in the client.
- </para>
+ <para>PreparedStatements are implemented by the driver, as MySQL
+ does not have a prepared statement feature. Because of this, the
+ driver does not implement getParameterMetaData() or getMetaData() as
+ it would require the driver to have a complete SQL parser in the
+ client.</para>
- <para>
- 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.
- </para>
+ <para>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.</para>
- <para>
- Take care when using a server-side prepared statement with
- <quote>large</quote> parameters that are set via
- setBinaryStream(), setAsciiStream(), setUnicodeStream(),
- setBlob(), or setClob(). If you want to re-execute the
- statement with any <quote>large</quote> parameter changed to
- a non-<quote>large</quote> parameter, it is necessary to
- call clearParameters() and set all parameters again. The
- reason for this is as follows:
- </para>
+ <para>Take care when using a server-side prepared statement with
+ <quote>large</quote> parameters that are set via setBinaryStream(),
+ setAsciiStream(), setUnicodeStream(), setBlob(), or setClob(). If
+ you want to re-execute the statement with any <quote>large</quote>
+ parameter changed to a non-<quote>large</quote> parameter, it is
+ necessary to call clearParameters() and set all parameters again.
+ The reason for this is as follows:</para>
<itemizedlist>
-
<listitem>
- <para>
- The driver streams the 'large' data 'out-of-band' to the
- prepared statement on the server side when the parameter
- is set (before execution of the prepared statement).
- </para>
+ <para>The driver streams the 'large' data 'out-of-band' to the
+ prepared statement on the server side when the parameter is set
+ (before execution of the prepared statement).</para>
</listitem>
-
</itemizedlist>
<itemizedlist>
-
<listitem>
- <para>
- Once that has been done, the stream used to read the
- data on the client side is closed (as per the JDBC
- spec), and can't be read from again.
- </para>
+ <para>Once that has been done, the stream used to read the data
+ on the client side is closed (as per the JDBC spec), and can't
+ be read from again.</para>
</listitem>
-
</itemizedlist>
<itemizedlist>
-
<listitem>
- <para>
- If a parameter changes from <quote>large</quote> to
- non-<quote>large,</quote> 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 <quote>large</quote> value. This removes all of
- the 'large' data that has already been sent to the
- server, thus requiring the data to be re-sent, via the
- setBinaryStream(), setAsciiStream(), setUnicodeStream(),
- setBlob() or setClob() methods.
- </para>
+ <para>If a parameter changes from <quote>large</quote> to
+ non-<quote>large,</quote> 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
+ <quote>large</quote> value. This removes all of the 'large' data
+ that has already been sent to the server, thus requiring the
+ data to be re-sent, via the setBinaryStream(), setAsciiStream(),
+ setUnicodeStream(), setBlob() or setClob() methods.</para>
</listitem>
-
</itemizedlist>
- <para>
- Consequently, if you want to change the <quote>type</quote>
- of a parameter to a non-<quote>large</quote> one, you must
- call clearParameters() and set all parameters of the
- prepared statement again before it can be re-executed.
- </para>
+ <para>Consequently, if you want to change the <quote>type</quote> of
+ a parameter to a non-<quote>large</quote> one, you must call
+ clearParameters() and set all parameters of the prepared statement
+ again before it can be re-executed.</para>
</listitem>
<listitem>
- <para>
- ResultSet
- </para>
+ <para>ResultSet</para>
- <para>
- 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 can
- not 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.
- </para>
+ <para>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 can not 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.</para>
- <para>
- To enable this functionality, you need to create a Statement
- instance in the following manner:
- </para>
+ <para>To enable this functionality, you need to create a Statement
+ instance in the following manner:</para>
-<programlisting>
+ <programlisting>
stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
java.sql.ResultSet.CONCUR_READ_ONLY);
stmt.setFetchSize(Integer.MIN_VALUE);</programlisting>
- <para>
- The combination of a forward-only, read-only result set,
- with a fetch size of Integer.MIN_VALUE serves as a signal to
- the driver to <quote>stream</quote> result sets row-by-row.
- After this any result sets created with the statement will
- be retrieved row-by-row.
- </para>
+ <para>The combination of a forward-only, read-only result set, with
+ a fetch size of Integer.MIN_VALUE serves as a signal to the driver
+ to <quote>stream</quote> result sets row-by-row. After this any
+ result sets created with the statement will be retrieved
+ row-by-row.</para>
- <para>
- There are some caveats with this approach. You will have to
- 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.
- </para>
+ <para>There are some caveats with this approach. You will have to
+ 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.</para>
- <para>
- The earliest the locks these statements hold can be released
- (whether they be <literal>MyISAM</literal> table-level locks
- or row-level locks in some other storage engine such as
- <literal>InnoDB</literal>) is when the statement completes.
- </para>
+ <para>The earliest the locks these statements hold can be released
+ (whether they be <literal>MyISAM</literal> table-level locks or
+ row-level locks in some other storage engine such as
+ <literal>InnoDB</literal>) is when the statement completes.</para>
- <para>
- 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.
- </para>
+ <para>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.</para>
- <para>
- Therefore, if using <quote>streaming</quote> results, you
- should process them as quickly as possible if you want to
- maintain concurrent access to the tables referenced by the
- statement producing the result set.
- </para>
+ <para>Therefore, if using <quote>streaming</quote> results, you
+ should process them as quickly as possible if you want to maintain
+ concurrent access to the tables referenced by the statement
+ producing the result set.</para>
</listitem>
<listitem>
- <para>
- ResultSetMetaData
- </para>
+ <para>ResultSetMetaData</para>
- <para>
- The "isAutoIncrement()" method only works when using MySQL
- servers 4.0 and newer.
- </para>
+ <para>The "isAutoIncrement()" method only works when using MySQL
+ servers 4.0 and newer.</para>
</listitem>
<listitem>
- <para>
- Statement
- </para>
+ <para>Statement</para>
- <para>
- When using versions of the JDBC driver earlier than 3.2.1,
- and connected to server versions earlier than 5.0.3, the
- "setFetchSize()" method has no effect, other than to toggle
- result set streaming as described above.
- </para>
+ <para>When using versions of the JDBC driver earlier than 3.2.1, and
+ connected to server versions earlier than 5.0.3, the
+ "setFetchSize()" method has no effect, other than to toggle result
+ set streaming as described above.</para>
- <para>
- MySQL does not support SQL cursors, and the JDBC driver
- doesn't emulate them, so "setCursorName()" has no effect.
- </para>
+ <para>MySQL does not support SQL cursors, and the JDBC driver
+ doesn't emulate them, so "setCursorName()" has no effect.</para>
</listitem>
-
</itemizedlist>
-
</section>
<section id="cj-type-conversions">
+ <title>Java, JDBC and MySQL Types</title>
- <title>&title-cj-type-conversions;</title>
+ <para>MySQL Connector/J is flexible in the way it handles conversions
+ between MySQL data types and Java data types.</para>
- <para>
- MySQL Connector/J is flexible in the way it handles conversions
- between MySQL data types and Java data types.
- </para>
+ <para>In general, any MySQL data type can be converted to a
+ java.lang.String, and any numerical type can be converted to any of the
+ Java numerical types, although round-off, overflow, or loss of precision
+ may occur.</para>
- <para>
- In general, any MySQL data type can be converted to a
- java.lang.String, and any numerical type can be converted to any
- of the Java numerical types, although round-off, overflow, or
- loss of precision may occur.
- </para>
+ <para>Starting with Connector/J 3.1.0, the JDBC driver will issue
+ warnings or throw DataTruncation exceptions as is required by the JDBC
+ specification unless the connection was configured not to do so by using
+ the property "jdbcCompliantTruncation" and setting it to "false".</para>
- <para>
- Starting with Connector/J 3.1.0, the JDBC driver will issue
- warnings or throw DataTruncation exceptions as is required by
- the JDBC specification unless the connection was configured not
- to do so by using the property "jdbcCompliantTruncation" and
- setting it to "false".
- </para>
+ <para>The conversions that are always guaranteed to work are listed in
+ the following table:</para>
- <para>
- The conversions that are always guaranteed to work are listed in
- the following table:
- </para>
-
<table>
-
<title>Conversion Table</title>
<tgroup cols="2">
<thead>
-
<row>
<entry>These MySQL Data Types</entry>
+
<entry>Can always be converted to these Java types</entry>
</row>
-
</thead>
+
<tbody>
<row>
- <entry><type>CHAR, VARCHAR, BLOB, TEXT, ENUM, and SET</type></entry>
- <entry><classname>java.lang.String, java.io.InputStream, java.io.Reader,
- java.sql.Blob, java.sql.Clob</classname></entry>
+ <entry><type>CHAR, VARCHAR, BLOB, TEXT, ENUM, and
+ SET</type></entry>
+
+ <entry><classname>java.lang.String, java.io.InputStream,
+ java.io.Reader, java.sql.Blob, java.sql.Clob</classname></entry>
</row>
+
<row>
- <entry><type>FLOAT, REAL, DOUBLE PRECISION, NUMERIC, DECIMAL, TINYINT,
- SMALLINT, MEDIUMINT, INTEGER, BIGINT</type></entry>
- <entry><classname>java.lang.String, java.lang.Short, java.lang.Integer,
- java.lang.Long, java.lang.Double,
- java.math.BigDecimal</classname>
+ <entry><type>FLOAT, REAL, DOUBLE PRECISION, NUMERIC, DECIMAL,
+ TINYINT, SMALLINT, MEDIUMINT, INTEGER, BIGINT</type></entry>
- <note>
-
- <para>
- 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.
- </para>
-
+ <entry><classname>java.lang.String, java.lang.Short,
+ java.lang.Integer, java.lang.Long, java.lang.Double,
+ java.math.BigDecimal</classname> <note>
+ <para>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.</para>
</note></entry>
</row>
+
<row>
<entry><type>DATE, TIME, DATETIME, TIMESTAMP</type></entry>
+
<entry><classname>java.lang.String, java.sql.Date,
- java.sql.Timestamp</classname></entry>
+ java.sql.Timestamp</classname></entry>
</row>
</tbody>
</tgroup>
-
</table>
- <para>
- The <classname>ResultSet.getObject()</classname> method uses the
- following type conversions between MySQL and Java types,
- following the JDBC specification where appropriate:
- </para>
+ <para>The <classname>ResultSet.getObject()</classname> method uses the
+ following type conversions between MySQL and Java types, following the
+ JDBC specification where appropriate:</para>
- <para>
- <table>
-
+ <para><table>
<title>MySQL Types to Java Types for ResultSet.getObject()</title>
<tgroup cols="2">
<thead>
-
<row>
<entry>MySQL Type Name</entry>
+
<entry>Returned as Java Class</entry>
</row>
-
</thead>
+
<tbody>
<row>
<entry><type>BIT(1)</type> (new in MySQL-5.0)</entry>
+
<entry><classname>java.lang.Boolean</classname></entry>
</row>
+
<row>
<entry><type>BIT( > 1)</type> (new in MySQL-5.0)</entry>
+
<entry><classname>byte[]</classname></entry>
</row>
+
<row>
<entry><type>TINYINT</type></entry>
- <entry><classname>java.lang.Boolean</classname> if the configuration property
- "tinyInt1isBit" is set to "true" (the default) and the
- storage size is "1", or
- <classname>java.lang.Integer</classname> if not.</entry>
+
+ <entry><classname>java.lang.Boolean</classname> if the
+ configuration property "tinyInt1isBit" is set to "true" (the
+ default) and the storage size is "1", or
+ <classname>java.lang.Integer</classname> if not.</entry>
</row>
+
<row>
<entry><type>BOOL , BOOLEAN</type></entry>
- <entry>See <type>TINYINT</type>, above as these are aliases for
- <type>TINYINT(1)</type>, currently.</entry>
+
+ <entry>See <type>TINYINT</type>, above as these are aliases
+ for <type>TINYINT(1)</type>, currently.</entry>
</row>
+
<row>
<entry><type>SMALLINT[(M)] [UNSIGNED]</type></entry>
- <entry><classname>java.lang.Integer</classname> (regardless if UNSIGNED or not)</entry>
+
+ <entry><classname>java.lang.Integer</classname> (regardless if
+ UNSIGNED or not)</entry>
</row>
+
<row>
<entry><type>MEDIUMINT[(M)] [UNSIGNED]</type></entry>
+
<entry><classname>java.lang.Integer,</classname> if UNSIGNED
- <classname>java.lang.Long</classname></entry>
+ <classname>java.lang.Long</classname></entry>
</row>
+
<row>
<entry><type>INT,INTEGER[(M)] [UNSIGNED]</type></entry>
+
<entry><classname>java.lang.Integer</classname>, if UNSIGNED
- <classname>java.lang.Long</classname></entry>
+ <classname>java.lang.Long</classname></entry>
</row>
+
<row>
<entry><type>BIGINT[(M)] [UNSIGNED]</type></entry>
+
<entry><classname>java.lang.Long</classname>, if UNSIGNED
- <classname>java.math.BigInteger</classname></entry>
+ <classname>java.math.BigInteger</classname></entry>
</row>
+
<row>
<entry><type>FLOAT[(M,D)]</type></entry>
+
<entry><classname>java.lang.Float</classname></entry>
</row>
+
<row>
<entry><type>DOUBLE[(M,B)]</type></entry>
+
<entry><classname>java.lang.Double</classname></entry>
</row>
+
<row>
<entry><type>DECIMAL[(M[,D])]</type></entry>
+
<entry><classname>java.math.BigDecimal</classname></entry>
</row>
+
<row>
<entry><type>DATE</type></entry>
+
<entry><classname>java.sql.Date</classname></entry>
</row>
+
<row>
<entry><type>DATETIME</type></entry>
+
<entry><classname>java.sql.Timestamp</classname></entry>
</row>
+
<row>
<entry><type>TIMESTAMP[(M)]</type></entry>
+
<entry><classname>java.sql.Timestamp</classname></entry>
</row>
+
<row>
<entry><type>TIME</type></entry>
+
<entry><classname>java.sql.Time</classname></entry>
</row>
+
<row>
<entry><type>YEAR[(2|4)]</type></entry>
- <entry><classname>java.sql.Date</classname> (with the date set two January 1st,
- at midnight)</entry>
+
+ <entry><classname>java.sql.Date</classname> (with the date set
+ two January 1st, at midnight)</entry>
</row>
+
<row>
<entry><type>CHAR(M)</type></entry>
- <entry><classname>java.lang.String</classname> (unless the character set for
- the column is <type>BINARY</type>, then
- <classname>byte[]</classname> is returned.</entry>
+
+ <entry><classname>java.lang.String</classname> (unless the
+ character set for the column is <type>BINARY</type>, then
+ <classname>byte[]</classname> is returned.</entry>
</row>
+
<row>
<entry><type>VARCHAR(M) [BINARY]</type></entry>
- <entry><classname>java.lang.String</classname> (unless the character set for
- the column is <type>BINARY</type>, then
- <classname>byte[]</classname> is returned.</entry>
+
+ <entry><classname>java.lang.String</classname> (unless the
+ character set for the column is <type>BINARY</type>, then
+ <classname>byte[]</classname> is returned.</entry>
</row>
+
<row>
<entry><type>BINARY(M)</type></entry>
+
<entry><classname>byte[]</classname></entry>
</row>
+
<row>
<entry><type>VARBINARY(M)</type></entry>
+
<entry><classname>byte[]</classname></entry>
</row>
+
<row>
<entry><type>TINYBLOB</type></entry>
+
<entry><classname>byte[]</classname></entry>
</row>
+
<row>
<entry><type>TINYTEXT</type></entry>
+
<entry><classname>java.lang.String</classname></entry>
</row>
+
<row>
<entry><type>BLOB</type></entry>
+
<entry><classname>byte[]</classname></entry>
</row>
+
<row>
<entry><type>TEXT</type></entry>
+
<entry><classname>java.lang.String</classname></entry>
</row>
+
<row>
<entry><type>MEDIUMBLOB</type></entry>
+
<entry><classname>byte[]</classname></entry>
</row>
+
<row>
<entry><type>MEDIUMTEXT</type></entry>
+
<entry><classname>java.lang.String</classname></entry>
</row>
+
<row>
<entry><type>LONGBLOB</type></entry>
+
<entry><classname>byte[]</classname></entry>
</row>
+
<row>
<entry><type>LONGTEXT</type></entry>
+
<entry><classname>java.lang.String</classname></entry>
</row>
+
<row>
<entry><type>ENUM('value1','value2',...)</type></entry>
+
<entry><classname>java.lang.String</classname></entry>
</row>
+
<row>
<entry><type>SET('value1','value2',...)</type></entry>
+
<entry><classname>java.lang.String</classname></entry>
</row>
</tbody>
</tgroup>
-
- </table>
- </para>
-
+ </table></para>
</section>
<section id="cj-character-sets">
+ <title>Using Character Sets and Unicode</title>
- <title>&title-cj-character-sets;</title>
+ <para>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 via
+ <methodname>Statement.execute()</methodname>,
+ <methodname>Statement.executeUpdate()</methodname>,
+ <methodname>Statement.executeQuery()</methodname> as well as all
+ <interfacename>PreparedStatement</interfacename> and
+ <interfacename>CallableStatement</interfacename> parameters with the
+ exclusion of parameters set using <methodname>setBytes()</methodname>,
+ <methodname>setBinaryStream()</methodname>,
+ <methodname>setAsciiStream()</methodname>,
+ <methodname>setUnicodeStream()</methodname> and
+ <methodname>setBlob()</methodname> .</para>
- <para>
- 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 via
- <methodname>Statement.execute()</methodname>,
- <methodname>Statement.executeUpdate()</methodname>,
- <methodname>Statement.executeQuery()</methodname> as well as all
+ <para>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 <parameter>"useUnicode"</parameter> and "
+ <parameter>characterEncoding</parameter> " properties.</para>
- <interfacename>PreparedStatement</interfacename>
+ <para>Starting with MySQL Server 4.1, 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
+ <classname>ResultSets</classname>.</para>
- and
+ <para>The character encoding between client and server is automatically
+ detected upon connection. The encoding used by the driver is specified
+ on the server via the configuration variable '
+ <parameter>character_set</parameter> ' for server versions older than
+ 4.1.0 and ' <parameter>character_set_server</parameter> ' for server
+ versions 4.1.0 and newer. See the "<ulink
+ url="http://www.mysql.com/doc/en/Charset-server.html">Server Character
+ Set and Collation</ulink>" section in the MySQL server manual for more
+ information.</para>
- <interfacename>CallableStatement</interfacename>
+ <para>To override the automatically-detected encoding on the client
+ side, use the <parameter>characterEncoding</parameter> property in the
+ URL used to connect to the server.</para>
- parameters with the exclusion of parameters set using
- <methodname>setBytes()</methodname>,
- <methodname>setBinaryStream()</methodname>,
- <methodname>setAsciiStream()</methodname>,
- <methodname>setUnicodeStream()</methodname> and
- <methodname>setBlob()</methodname> .
- </para>
-
- <para>
- 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
-
- <parameter>"useUnicode"</parameter>
-
- and "
-
- <parameter>characterEncoding</parameter>
-
- " properties.
- </para>
-
- <para>
- Starting with MySQL Server 4.1, 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 <classname>ResultSets</classname>.
- </para>
-
- <para>
- The character encoding between client and server is
- automatically detected upon connection. The encoding used by the
- driver is specified on the server via the configuration variable
- '
-
- <parameter>character_set</parameter>
-
- ' for server versions older than 4.1.0 and '
-
- <parameter>character_set_server</parameter>
-
- ' for server versions 4.1.0 and newer. See the
- "<ulink
- url="http://www.mysql.com/doc/en/Charset-server.html">Server
- Character Set and Collation</ulink>" section in the MySQL server
- manual for more information.
- </para>
-
- <para>
- To override the automatically-detected encoding on the client
- side, use the
-
- <parameter>characterEncoding</parameter>
-
- property in the URL used to connect to the server.
- </para>
-
- <para>
- When specifying character encodings on the client side,
- Java-style names should be used. The following table lists
- Java-style names for MySQL character sets:
-
- <table>
-
+ <para>When specifying character encodings on the client side, Java-style
+ names should be used. The following table lists Java-style names for
+ MySQL character sets: <table>
<title>MySQL to Java Encoding Name Translations</title>
<tgroup cols="2">
<thead>
-
<row>
<entry>MySQL Character Set Name</entry>
+
<entry>Java-Style Character Encoding Name</entry>
</row>
-
</thead>
+
<tbody>
<row>
<entry>usa7</entry>
+
<entry>US-ASCII</entry>
</row>
+
<row>
<entry>big5</entry>
+
<entry>Big5</entry>
</row>
+
<row>
<entry>gbk</entry>
+
<entry>GBK</entry>
</row>
+
<row>
<entry>sjis</entry>
- <entry>SJIS (or Cp932 or MS932 for MySQL Server < 4.1.11)</entry>
+
+ <entry>SJIS (or Cp932 or MS932 for MySQL Server <
+ 4.1.11)</entry>
</row>
+
<row>
<entry>cp932</entry>
+
<entry>Cp932 or MS932 (MySQL Server > 4.1.11)</entry>
</row>
+
<row>
<entry>gb2312</entry>
+
<entry>EUC_CN</entry>
</row>
+
<row>
<entry>ujis</entry>
+
<entry>EUC_JP</entry>
</row>
+
<row>
<entry>euc_kr</entry>
+
<entry>EUC_KR</entry>
</row>
+
<row>
<entry>latin1</entry>
+
<entry>ISO8859_1</entry>
</row>
+
<row>
<entry>latin1_de</entry>
+
<entry>ISO8859_1</entry>
</row>
+
<row>
<entry>german1</entry>
+
<entry>ISO8859_1</entry>
</row>
+
<row>
<entry>danish</entry>
+
<entry>ISO8859_1</entry>
</row>
+
<row>
<entry>latin2</entry>
+
<entry>ISO8859_2</entry>
</row>
+
<row>
<entry>czech</entry>
+
<entry>ISO8859_2</entry>
</row>
+
<row>
<entry>hungarian</entry>
+
<entry>ISO8859_2</entry>
</row>
+
<row>
<entry>croat</entry>
+
<entry>ISO8859_2</entry>
</row>
+
<row>
<entry>greek</entry>
+
<entry>ISO8859_7</entry>
</row>
+
<row>
<entry>hebrew</entry>
+
<entry>ISO8859_8</entry>
</row>
+
<row>
<entry>latin5</entry>
+
<entry>ISO8859_9</entry>
</row>
+
<row>
<entry>latvian</entry>
+
<entry>ISO8859_13</entry>
</row>
+
<row>
<entry>latvian1</entry>
+
<entry>ISO8859_13</entry>
</row>
+
<row>
<entry>estonia</entry>
+
<entry>ISO8859_13</entry>
</row>
+
<row>
<entry>dos</entry>
+
<entry>Cp437</entry>
</row>
+
<row>
<entry>pclatin2</entry>
+
<entry>Cp852</entry>
</row>
+
<row>
<entry>cp866</entry>
+
<entry>Cp866</entry>
</row>
+
<row>
<entry>koi8_ru</entry>
+
<entry>KOI8_R</entry>
</row>
+
<row>
<entry>tis620</entry>
+
<entry>TIS620</entry>
</row>
+
<row>
<entry>win1250</entry>
+
<entry>Cp1250</entry>
</row>
+
<row>
<entry>win1250ch</entry>
+
<entry>Cp1250</entry>
</row>
+
<row>
<entry>win1251</entry>
+
<entry>Cp1251</entry>
</row>
+
<row>
<entry>cp1251</entry>
+
<entry>Cp1251</entry>
</row>
+
<row>
<entry>win1251ukr</entry>
+
<entry>Cp1251</entry>
</row>
+
<row>
<entry>cp1257</entry>
+
<entry>Cp1257</entry>
</row>
+
<row>
<entry>macroman</entry>
+
<entry>MacRoman</entry>
</row>
+
<row>
<entry>macce</entry>
+
<entry>MacCentralEurope</entry>
</row>
+
<row>
<entry>utf8</entry>
+
<entry>UTF-8</entry>
</row>
+
<row>
<entry>ucs2</entry>
+
<entry>UnicodeBig</entry>
</row>
</tbody>
</tgroup>
+ </table></para>
- </table>
- </para>
-
<warning>
-
- <para>
- Do not issue the query 'set names' 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.
- </para>
-
+ <para>Do not issue the query 'set names' 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.</para>
</warning>
- <para>
- To allow multiple character sets to be sent from the client, the
- "UTF-8" encoding should be used, either by configuring "utf8" as
- the default server character set, or by configuring the JDBC
- driver to use "UTF-8" through the
-
- <parameter>characterEncoding</parameter>
-
- property.
- </para>
-
+ <para>To allow multiple character sets to be sent from the client, the
+ "UTF-8" encoding should be used, either by configuring "utf8" as the
+ default server character set, or by configuring the JDBC driver to use
+ "UTF-8" through the <parameter>characterEncoding</parameter>
+ property.</para>
</section>
-<!--
+ <!--
<section id="cj-usage-advisor">
<title>&title-cj-usage-advisor;</title>
@@ -3315,75 +3597,53 @@
-->
<section id="cj-using-ssl">
+ <title>Connecting Securely Using SSL</title>
- <title>&title-cj-using-ssl;</title>
+ <para>SSL in MySQL Connector/J encrypts all data (other than the initial
+ handshake) between the JDBC driver and the server. The performance
+ penalty for enabling SSL is an increase in query processing time between
+ 35% and 50%, depending on the size of the query, and the amount of data
+ it returns.</para>
- <para>
- SSL in MySQL Connector/J encrypts all data (other than the
- initial handshake) between the JDBC driver and the server. The
- performance penalty for enabling SSL is an increase in query
- processing time between 35% and 50%, depending on the size of
- the query, and the amount of data it returns.
- </para>
+ <para>For SSL Support to work, you must have the following:</para>
- <para>
- For SSL Support to work, you must have the following:
- </para>
-
<itemizedlist>
-
<listitem>
- <para>
- 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:
- <ulink
- url="http://developer.java.sun.com/developer/bugParade/bugs/4273544.html">http://developer.java.sun.com/developer/bugParade/bugs/4273544.html</ulink>
- </para>
+ <para>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: <ulink
+ url="http://developer.java.sun.com/developer/bugParade/bugs/4273544.html">http://developer.java.sun.com/developer/bugParade/bugs/4273544.html</ulink></para>
</listitem>
<listitem>
- <para>
- A MySQL server that supports SSL and has been compiled and
- configured to do so, which is MySQL-4.0.4 or later, see:
- <ulink
- url="http://www.mysql.com/doc/en/Secure_connections.html">http://www.mysql.com/doc/en/Secure_connections.html</ulink>
- </para>
+ <para>A MySQL server that supports SSL and has been compiled and
+ configured to do so, which is MySQL-4.0.4 or later, see: <ulink
+ url="http://www.mysql.com/doc/en/Secure_connections.html">http://www.mysql.com/doc/en/Secure_connections.html</ulink></para>
</listitem>
<listitem>
- <para>
- A client certificate (covered later in this section)
- </para>
+ <para>A client certificate (covered later in this section)</para>
</listitem>
-
</itemizedlist>
- <para>
- 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 'SSL' subdirectory of the MySQL source
- distribution. This is what SSL will use to determine if you are
- communicating with a secure MySQL server.
- </para>
+ <para>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 'SSL' subdirectory of the MySQL source distribution. This is what
+ SSL will use to determine if you are communicating with a secure MySQL
+ server.</para>
- <para>
- To use Java's 'keytool' to create a truststore in the current
- directory , and import the server's CA certificate
- ('cacert.pem'), you can do the following (assuming that'keytool'
- is in your path. It's located in the 'bin' subdirectory of your
- JDK or JRE):
- </para>
+ <para>To use Java's 'keytool' to create a truststore in the current
+ directory , and import the server's CA certificate ('cacert.pem'), you
+ can do the following (assuming that'keytool' is in your path. It's
+ located in the 'bin' subdirectory of your JDK or JRE):</para>
-<programlisting>shell> keytool -import -alias mysqlServerCACert -file cacert.pem -keystore truststore
+ <programlisting>shell> keytool -import -alias mysqlServerCACert -file cacert.pem -keystore truststore
</programlisting>
- <para>
- Keytool will respond with the following information:
- </para>
+ <para>Keytool will respond with the following information:</para>
-<programlisting>Enter keystore password: *********
+ <programlisting>Enter keystore password: *********
Owner: EMAILADDRESS=walrus@stripped, CN=Walrus, O=MySQL AB, L=Orenburg, ST=Some
-State, C=RU
Issuer: EMAILADDRESS=walrus@stripped, CN=Walrus, O=MySQL AB, L=Orenburg, ST=Som
@@ -3396,24 +3656,18 @@
Trust this certificate? [no]: yes
Certificate was added to keystore</programlisting>
- <para>
- You will then need to generate a client certificate, so that the
- MySQL server knows that it is talking to a secure client:
- </para>
+ <para>You will then need to generate a client certificate, so that the
+ MySQL server knows that it is talking to a secure client:</para>
-<programlisting> shell> keytool -genkey -keyalg rsa -alias mysqlClientCertificate -keystore keystore </programlisting>
+ <programlisting> shell> keytool -genkey -keyalg rsa -alias mysqlClientCertificate -keystore keystore </programlisting>
- <para>
- Keytool will prompt you for the following information, and
- create a keystore named 'keystore' in the current directory.
- </para>
+ <para>Keytool will prompt you for the following information, and create
+ a keystore named 'keystore' in the current directory.</para>
- <para>
- You should respond with information that is appropriate for your
- situation:
- </para>
+ <para>You should respond with information that is appropriate for your
+ situation:</para>
-<programlisting>Enter keystore password: *********
+ <programlisting>Enter keystore password: *********
What is your first and last name?
[Unknown]: Matthews
What is the name of your organizational unit?
@@ -3433,35 +3687,28 @@
Enter key password for <mysqlClientCertificate>
(RETURN if same as keystore password):</programlisting>
- <para>
- 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 'path_to_keystore_file' with
- the full path to the keystore file you created,
- 'path_to_truststore_file' with the path to the truststore file
- you created, and using the appropriate password values for each
- property.
- </para>
+ <para>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 'path_to_keystore_file' with the full path to
+ the keystore file you created, 'path_to_truststore_file' with the path
+ to the truststore file you created, and using the appropriate password
+ values for each property.</para>
-<programlisting>-Djavax.net.ssl.keyStore=path_to_keystore_file
+ <programlisting>-Djavax.net.ssl.keyStore=path_to_keystore_file
-Djavax.net.ssl.keyStorePassword=*********
-Djavax.net.ssl.trustStore=path_to_truststore_file
-Djavax.net.ssl.trustStorePassword=********* </programlisting>
- <para>
- You will also need to set 'useSSL' to 'true' in your connection
- parameters for MySQL Connector/J, either by adding 'useSSL=true'
- to your URL, or by setting the property 'useSSL' to 'true' in
- the java.util.Properties instance you pass to
- DriverManager.getConnection().
- </para>
+ <para>You will also need to set 'useSSL' to 'true' in your connection
+ parameters for MySQL Connector/J, either by adding 'useSSL=true' to your
+ URL, or by setting the property 'useSSL' to 'true' in the
+ java.util.Properties instance you pass to
+ DriverManager.getConnection().</para>
- <para>
- You can test that SSL is working by turning on JSSE debugging
- (as detailed below), and look for the following key events:
- </para>
+ <para>You can test that SSL is working by turning on JSSE debugging (as
+ detailed below), and look for the following key events:</para>
-<programlisting>...
+ <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: {}
@@ -3492,67 +3739,50 @@
main, READ: SSL v3.1 Handshake, length = 1712
...</programlisting>
- <para>
- JSSE provides debugging (to STDOUT) when you set the following
- system property: -Djavax.net.debug=all 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.
- </para>
-
+ <para>JSSE provides debugging (to STDOUT) when you set the following
+ system property: -Djavax.net.debug=all 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.</para>
</section>
<section id="cj-replication-connection">
+ <title>Using Master/Slave Replication with ReplicationConnection</title>
- <title>&title-cj-replication-connection;</title>
+ <para>Starting with Connector/J 3.1.7, we've made available 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 <function>Connection.getReadOnly()</function> .</para>
- <para>
- Starting with Connector/J 3.1.7, we've made available 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
- <function>Connection.getReadOnly()</function> .
- </para>
+ <para>An application signals that it wants a transaction to be read-only
+ by calling <function>Connection.setReadOnly(true)</function>, this
+ "replication-aware" connection will use one of the slave connections,
+ which are load-balanced per-vm using a round-robin scheme (a given
+ connection is <quote>sticky</quote> to a slave unless that slave is
+ removed from service). 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
+ <function>Connection.setReadOnly(false)</function> and the driver will
+ ensure that further calls are sent to the <quote>master</quote> 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.</para>
- <para>
- An application signals that it wants a transaction to be
- read-only by calling
- <function>Connection.setReadOnly(true)</function>, this
- "replication-aware" connection will use one of the slave
- connections, which are load-balanced per-vm using a round-robin
- scheme (a given connection is <quote>sticky</quote> to a slave
- unless that slave is removed from service). 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
- <function>Connection.setReadOnly(false)</function> and the
- driver will ensure that further calls are sent to the
- <quote>master</quote> 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.
- </para>
+ <para>To enable this functionality, use the "
+ <function>com.mysql.jdbc.ReplicationDriver</function> " 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,
+ <function>ReplicationDriver</function> does not currently work with
+ <function>java.sql.DriverManager</function> -based connection creation
+ unless it is the only MySQL JDBC driver registered with the
+ <function>DriverManager</function> .</para>
- <para>
- To enable this functionality, use the "
- <function>com.mysql.jdbc.ReplicationDriver</function> " 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,
- <function>ReplicationDriver</function> does not currently work
- with <function>java.sql.DriverManager</function> -based
- connection creation unless it is the only MySQL JDBC driver
- registered with the <function>DriverManager</function> .
- </para>
+ <para>Here is a short, simple example of how ReplicationDriver might be
+ used in a standalone application.</para>
- <para>
- Here is a short, simple example of how ReplicationDriver might
- be used in a standalone application.
- </para>
-
-<programlisting id="cj-using-replication-driver-example">import java.sql.Connection;
+ <programlisting id="cj-using-replication-driver-example">import java.sql.Connection;
import java.sql.ResultSet;
import java.util.Properties;
@@ -3607,150 +3837,107 @@
}
}
</programlisting>
-
</section>
-
</section>
<section id="cj-j2ee">
+ <title>Using Connector/J with J2EE and Other Java Frameworks</title>
- <title>&title-cj-j2ee;</title>
+ <para>This section describes how to use Connector/J in several
+ contexts.</para>
- <para>
- This section describes how to use Connector/J in several contexts.
- </para>
-
<section id="cj-general-j2ee-concepts">
+ <title>General J2EE Concepts</title>
- <title>&title-cj-general-j2ee-concepts;</title>
+ <para>This section provides general background on J2EE concepts that
+ pertain to use of Connector/J.</para>
- <para>
- This section provides general background on J2EE concepts that
- pertain to use of Connector/J.
- </para>
-
<section id="cj-connection-pooling">
+ <title>Understanding Connection Pooling</title>
- <title>&title-cj-connection-pooling;</title>
+ <para>Connection pooling is a technique of creating and managing a
+ pool of connections that are ready for use by any thread that needs
+ them.</para>
- <para>
- Connection pooling is a technique of creating and managing a
- pool of connections that are ready for use by any thread that
- needs them.
- </para>
+ <para>This technique of <quote>pooling</quote> connections is based on
+ the fact that most applications only need a thread to have access to a
+ JDBC connection when they are actively processing a transaction, which
+ usually take only milliseconds to complete. When not processing a
+ transaction, the connection would otherwise sit idle. Instead,
+ connection pooling allows the idle connection to be used by some other
+ thread to do useful work.</para>
- <para>
- This technique of <quote>pooling</quote> connections is based
- on the fact that most applications only need a thread to have
- access to a JDBC connection when they are actively processing
- a transaction, which usually take only milliseconds to
- complete. When not processing a transaction, the connection
- would otherwise sit idle. Instead, connection pooling allows
- the idle connection to be used by some other thread to do
- useful work.
- </para>
+ <para>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 may be used by any other threads that want to use
+ it.</para>
- <para>
- 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 may be used by any other
- threads that want to use it.
- </para>
+ <para>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
+ DriverManager.getConnection() every time it needed a JDBC connection,
+ however with connection pooling, your thread may end up using either a
+ new, or already-existing connection.</para>
- <para>
- 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 DriverManager.getConnection() every time it needed a
- JDBC connection, however with connection pooling, your thread
- may end up using either a new, or already-existing connection.
- </para>
+ <para>Connection pooling can greatly increase the performance of your
+ Java application, while reducing overall resource usage. The main
+ benefits to connection pooling are:</para>
- <para>
- Connection pooling can greatly increase the performance of
- your Java application, while reducing overall resource usage.
- The main benefits to connection pooling are:
- </para>
-
<itemizedlist>
-
<listitem>
- <para>
- Reduced connection creation time
- </para>
+ <para>Reduced connection creation time</para>
- <para>
- 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."
- </para>
+ <para>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."</para>
</listitem>
<listitem>
- <para>
- Simplified programming model
- </para>
+ <para>Simplified programming model</para>
- <para>
- When using connection pooling, each individual thread can
- act as though it has created its own JDBC connection,
- allowing you to use straight-forward JDBC programming
- techniques.
- </para>
+ <para>When using connection pooling, each individual thread can
+ act as though it has created its own JDBC connection, allowing you
+ to use straight-forward JDBC programming techniques.</para>
</listitem>
<listitem>
- <para>
- Controlled resource usage
- </para>
+ <para>Controlled resource usage</para>
- <para>
- If you don't use connection pooling, and instead create a
- new connection every time a thread needs one, your
- application's resource usage can be quite wasteful and
- lead to unpredictable behavior under load.
- </para>
+ <para>If you don't use connection pooling, and instead create a
+ new connection every time a thread needs one, your application's
+ resource usage can be quite wasteful and lead to unpredictable
+ behavior under load.</para>
</listitem>
-
</itemizedlist>
- <para>
- Remember that 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!
- </para>
+ <para>Remember that 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!</para>
- <para>
- 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.
- </para>
+ <para>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.</para>
- <para>
- Luckily, Sun has standardized the concept of connection
- pooling in JDBC through the JDBC-2.0 "Optional" interfaces,
- and all major application servers have implementations of
- these APIs that work fine with MySQL Connector/J.
- </para>
+ <para>Luckily, Sun has standardized the concept of connection pooling
+ in JDBC through the JDBC-2.0 "Optional" interfaces, and all major
+ application servers have implementations of these APIs that work fine
+ with MySQL Connector/J.</para>
- <para>
- Generally, you configure a connection pool in your application
- server configuration files, and access it via 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:
+ <para>Generally, you configure a connection pool in your application
+ server configuration files, and access it via 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: <example>
+ <title>Using a Connection Pool with a J2EE Application
+ Server</title>
- <example>
-
- <title>Using a Connection Pool with a J2EE Application Server</title>
-
-<programlisting>import java.sql.Connection;
+ <programlisting>import java.sql.Connection;
import java.sql.SQLException;
import java.sql.Statement;
@@ -3844,95 +4031,69 @@
}
}
}</programlisting>
+ </example> As shown in the example above, after obtaining the JNDI
+ InitialContext, and looking up the DataSource, the rest of the code
+ should look familiar to anyone who has done JDBC programming in the
+ past.</para>
- </example>
+ <para>The most important thing to remember when using connection
+ pooling is to make sure that no matter what happens in your code
+ (exceptions, flow-of-control, and so forth), connections, and anything
+ created by them (such as statements or result sets) are closed, so
+ that they may be re-used, otherwise they will be "stranded," which in
+ the best case means that the MySQL server resources they represent
+ (such as buffers, locks, or sockets) may be tied up for some time, or
+ worst case, may be tied up forever.</para>
- As shown in the example above, after obtaining the JNDI
- InitialContext, and looking up the DataSource, the rest of the
- code should look familiar to anyone who has done JDBC
- programming in the past.
- </para>
+ <para>What's the Best Size for my Connection Pool?</para>
- <para>
- The most important thing to remember when using connection
- pooling is to make sure that no matter what happens in your
- code (exceptions, flow-of-control, and so forth), connections,
- and anything created by them (such as statements or result
- sets) are closed, so that they may be re-used, otherwise they
- will be "stranded," which in the best case means that the
- MySQL server resources they represent (such as buffers, locks,
- or sockets) may be tied up for some time, or worst case, may
- be tied up forever.
- </para>
+ <para>As with all other configuration rules-of-thumb, the answer is
+ "It depends." Although the optimal size depends on anticipated load
+ and average database transaction time, the optimum connection pool
+ size is smaller than you might expect. If you take Sun'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 response times that are
+ acceptable.</para>
- <para>
- What's the Best Size for my Connection Pool?
- </para>
+ <para>To correctly size a connection pool for your application, you
+ should create load test scripts with tools such as Apache JMeter or
+ The Grinder, and load test your application.</para>
- <para>
- As with all other configuration rules-of-thumb, the answer is
- "It depends." Although the optimal size depends on anticipated
- load and average database transaction time, the optimum
- connection pool size is smaller than you might expect. If you
- take Sun'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 response times that are acceptable.
- </para>
-
- <para>
- To correctly size a connection pool for your application, you
- should create load test scripts with tools such as Apache
- JMeter or The Grinder, and load test your application.
- </para>
-
- <para>
- 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.
- </para>
-
+ <para>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.</para>
</section>
-<!--
+ <!--
<section id="cj-understanding-transactions">
<title>&title-cj-understanding-transactions;</title>
<para />
</section>
-->
-
</section>
<section id="cj-tomcat-config">
+ <title>Using Connector/J with Tomcat</title>
- <title>&title-cj-tomcat-config;</title>
-
- <para>
- The following instructions are based on the instructions for
- Tomcat-5.x, available at
- <ulink
+ <para>The following instructions are based on the instructions for
+ Tomcat-5.x, available at <ulink
url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/jndi-datasource-examples-howto.html">http://jakarta.apache.org/tomcat/tomcat-5.0-doc/jndi-datasource-examples-howto.html</ulink>
- which is current at the time this document was written.
- </para>
+ which is current at the time this document was written.</para>
- <para>
- First, install the .jar file that comes with Connector/J in
- <filename>$CATALINA_HOME/common/lib</filename> so that it is
- available to all applications installed in the container.
- </para>
+ <para>First, install the .jar file that comes with Connector/J in
+ <filename>$CATALINA_HOME/common/lib</filename> so that it is available
+ to all applications installed in the container.</para>
- <para>
- Next, Configure the JNDI DataSource by adding a declaration
- resource to <filename>$CATALINA_HOME/conf/server.xml</filename>
- in the context that defines your web application:
- </para>
+ <para>Next, Configure the JNDI DataSource by adding a declaration
+ resource to <filename>$CATALINA_HOME/conf/server.xml</filename> in the
+ context that defines your web application:</para>
-<programlisting><Context ....>
+ <programlisting><Context ....>
...
@@ -4058,37 +4219,30 @@
</ResourceParams>
</Context></programlisting>
- <para>
- In general, you should 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
- unfortunately if you use the wrong syntax in your XML file, you
- will most likely end up with an exception similar to the
- following:
- </para>
+ <para>In general, you should 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 unfortunately if you use the
+ wrong syntax in your XML file, you will most likely end up with an
+ exception similar to the following:</para>
-<programlisting>Error: java.sql.SQLException: Cannot load JDBC driver class 'null ' SQL
+ <programlisting>Error: java.sql.SQLException: Cannot load JDBC driver class 'null ' SQL
state: null </programlisting>
-
</section>
<section id="cj-jboss-config">
+ <title>Using Connector/J with JBoss</title>
- <title>&title-cj-jboss-config;</title>
+ <para>These instructions cover JBoss-4.x. To make the JDBC driver
+ classes available to the application server, copy the .jar file that
+ comes with Connector/J to the <filename>lib</filename> directory for
+ your server configuration (which is usually called
+ "<filename>default</filename>"). Then, in the same configuration
+ directory, in the subdirectory named <quote>deploy,</quote> create a
+ datasource configuration file that ends with "-ds.xml", which tells
+ JBoss to deploy this file as a JDBC Datasource. The file should have the
+ following contents:</para>
- <para>
- These instructions cover JBoss-4.x. To make the JDBC driver
- classes available to the application server, copy the .jar file
- that comes with Connector/J to the <filename>lib</filename>
- directory for your server configuration (which is usually called
- "<filename>default</filename>"). Then, in the same configuration
- directory, in the subdirectory named <quote>deploy,</quote>
- create a datasource configuration file that ends with "-ds.xml",
- which tells JBoss to deploy this file as a JDBC Datasource. The
- file should have the following contents:
- </para>
-
-<programlisting><datasources>
+ <programlisting><datasources>
<local-tx-datasource>
<!-- This connection pool will be bound into JNDI with the name
"java:/MySQLDB" -->
@@ -4124,10 +4278,9 @@
</local-tx-datasource>
</datasources> </programlisting>
-
</section>
-<!--
+ <!--
<section id="cj-hibernate-config">
<title>&title-cj-hibernate-config;</title>
@@ -4135,7 +4288,7 @@
</section>
-->
-<!--
+ <!--
<section id="cj-spring-config">
<title>&title-cj-spring-config;</title>
@@ -4143,7 +4296,7 @@
</section>
-->
-<!--
+ <!--
<section id="cj-struts-config">
<title>&title-cj-struts-config;</title>
@@ -4152,7 +4305,7 @@
-->
-<!--
+ <!--
<section id="cj-weblogic-config">
<title>&title-cj-weblogic-config;</title>
@@ -4160,7 +4313,7 @@
</section>
-->
-<!--
+ <!--
<section id="cj-websphere-config">
<title>&title-cj-websphere-config;</title>
@@ -4168,169 +4321,115 @@
</section>
-->
-<!--
+ <!--
<section id="cj-ias-config">
<title>&title-cj-ias-config;</title>
<para />
</section>
-->
-
</section>
<section id="cj-troubleshooting">
+ <title>Diagnosing Connector/J Problems</title>
- <title>&title-cj-troubleshooting;</title>
+ <para>This section describes how to solve problems that you may encounter
+ when using Connector/J.</para>
- <para>
- This section describes how to solve problems that you may
- encounter when using Connector/J.
- </para>
-
<section id="cj-faq">
+ <title>Common Problems and Solutions</title>
- <title>&title-cj-faq;</title>
+ <para>There are a few issues that seem to be commonly encountered often
+ by users of MySQL Connector/J. This section deals with their symptoms,
+ and their resolutions. If you have further issues, see the "SUPPORT"
+ section.</para>
- <para>
- There are a few issues that seem to be commonly encountered
- often by users of MySQL Connector/J. This section deals with
- their symptoms, and their resolutions. If you have further
- issues, see the "SUPPORT" section.
- </para>
-
<qandaset>
-
<qandaentry>
-
<question>
+ <para>When I try to connect to the database with MySQL
+ Connector/J, I get the following exception:</para>
- <para>
- When I try to connect to the database with MySQL
- Connector/J, I get the following exception:
- </para>
-
<screen>SQLException: Server configuration denies access to data source
SQLState: 08001
VendorError: 0</screen>
- <para>
- What's going on? I can connect just fine with the MySQL
- command-line client.
- </para>
-
+ <para>What's going on? I can connect just fine with the MySQL
+ command-line client.</para>
</question>
<answer>
+ <para>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 or not
+ the connection should be allowed.</para>
- <para>
- 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 or not the connection should be
- allowed.
- </para>
+ <para>You must add grants to allow this to happen. The following
+ is an example of how to do this (but not the most secure).</para>
- <para>
- You must add grants to allow this to happen. The following
- is an example of how to do this (but not the most secure).
- </para>
+ <para>From the mysql command-line client, logged in as a user that
+ can grant privileges, issue the following command:</para>
- <para>
- From the mysql command-line client, logged in as a user
- that can grant privileges, issue the following command:
- </para>
-
<screen>GRANT ALL PRIVILEGES ON [dbname].* to
'[user]'@'[hostname]' identified by
'[password]'</screen>
- <para>
- replacing [dbname] with the name of your database, [user]
- with the user name, [hostname] with the host that MySQL
- Connector/J will be connecting from, and [password] with
- the password you want to use. Be aware that RedHat Linux
- is broken with respect to the hostname portion for the
- case when you are connecting from localhost. You need to
- use "localhost.localdomain" for the [hostname] value in
- this case. Follow this by issuing the "FLUSH PRIVILEGES"
- command.
- </para>
+ <para>replacing [dbname] with the name of your database, [user]
+ with the user name, [hostname] with the host that MySQL
+ Connector/J will be connecting from, and [password] with the
+ password you want to use. Be aware that RedHat Linux is broken
+ with respect to the hostname portion for the case when you are
+ connecting from localhost. You need to use "localhost.localdomain"
+ for the [hostname] value in this case. Follow this by issuing the
+ "FLUSH PRIVILEGES" command.</para>
<note>
-
- <para>
- Testing your connectivity with the
- <command>mysql</command> command-line client will not
- work unless you add the <option>--host</option> flag,
- and use something other than
- <literal>localhost</literal> for the host. The
- <command>mysql</command> command-line client will use
- Unix domain sockets if you use the special hostname
- <literal>localhost</literal>. If you are testing
- connectivity to <literal>localhost</literal>, use
- <literal>127.0.0.1</literal> as the hostname instead.
- </para>
-
+ <para>Testing your connectivity with the
+ <command>mysql</command> command-line client will not work
+ unless you add the <option>--host</option> flag, and use
+ something other than <literal>localhost</literal> for the host.
+ The <command>mysql</command> command-line client will use Unix
+ domain sockets if you use the special hostname
+ <literal>localhost</literal>. If you are testing connectivity to
+ <literal>localhost</literal>, use <literal>127.0.0.1</literal>
+ as the hostname instead.</para>
</note>
<warning>
-
- <para>
- If you don't understand what the 'GRANT' command does,
- or how it works, you should read and understand the
- <ulink
+ <para>If you don't understand what the 'GRANT' command does, or
+ how it works, you should read and understand the <ulink
url="http://www.mysql.com/doc/en/Privilege_system.html">'General
- Security Issues and the MySQL Access Privilege
- System'</ulink> section of the MySQL manual before
- attempting to change privileges.
- </para>
+ Security Issues and the MySQL Access Privilege System'</ulink>
+ section of the MySQL manual before attempting to change
+ privileges.</para>
- <para>
- Changing privileges and permissions improperly in MySQL
- can potentially cause your server installation to not
- have optimal security properties.
- </para>
-
+ <para>Changing privileges and permissions improperly in MySQL
+ can potentially cause your server installation to not have
+ optimal security properties.</para>
</warning>
-
</answer>
-
</qandaentry>
<qandaentry>
-
<question>
-
- <para>
- My application throws an SQLException 'No Suitable
- Driver'. Why is this happening?
- </para>
-
+ <para>My application throws an SQLException 'No Suitable Driver'.
+ Why is this happening?</para>
</question>
<answer>
-
- <para>
- One of two things are happening. Either the driver is not
- in your CLASSPATH (see the "INSTALLATION" section above),
- or your URL format is incorrect (see "Developing
- Applications with MySQL Connector/J").
- </para>
-
+ <para>One of two things are happening. Either the driver is not in
+ your CLASSPATH (see the "INSTALLATION" section above), or your URL
+ format is incorrect (see "Developing Applications with MySQL
+ Connector/J").</para>
</answer>
-
</qandaentry>
<qandaentry>
-
<question>
+ <para>I'm trying to use MySQL Connector/J in an applet or
+ application and I get an exception similar to:</para>
- <para>
- I'm trying to use MySQL Connector/J in an applet or
- application and I get an exception similar to:
- </para>
-
<screen>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?
@@ -4338,98 +4437,70 @@
(java.security.AccessControlException)
SQLState: 08S01
VendorError: 0 </screen>
-
</question>
<answer>
+ <para>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.</para>
- <para>
- 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.
- </para>
+ <para>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.</para>
- <para>
- 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.
- </para>
+ <para>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.</para>
- <para>
- 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.
- </para>
-
- <para>
- 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
- /etc/mysql/my.cnf or /etc/my.cnf. Of course your my.cnf
- file might also exist in the <filename>data</filename>
- directory of your MySQL server, or anywhere else
- (depending on how MySQL was compiled for your system).
- Binaries created by MySQL AB always look in /etc/my.cnf
- and [datadir]/my.cnf. 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).
- </para>
-
+ <para>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 /etc/mysql/my.cnf
+ or /etc/my.cnf. Of course your my.cnf file might also exist in the
+ <filename>data</filename> directory of your MySQL server, or
+ anywhere else (depending on how MySQL was compiled for your
+ system). Binaries created by MySQL AB always look in /etc/my.cnf
+ and [datadir]/my.cnf. 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).</para>
</answer>
-
</qandaentry>
<qandaentry>
-
<question>
-
- <para id="connector_j_wait_timeout_q_and_a">
- I have a servlet/application that works fine for a day,
- and then stops working overnight
- </para>
-
+ <para id="connector_j_wait_timeout_q_and_a">I have a
+ servlet/application that works fine for a day, and then stops
+ working overnight</para>
</question>
<answer>
+ <para>MySQL closes connections after 8 hours of inactivity. You
+ either need to use a connection pool that handles stale
+ connections or use the "autoReconnect" parameter (see "Developing
+ Applications with MySQL Connector/J").</para>
- <para>
- MySQL closes connections after 8 hours of inactivity. You
- either need to use a connection pool that handles stale
- connections or use the "autoReconnect" parameter (see
- "Developing Applications with MySQL Connector/J").
- </para>
+ <para>Also, you should be catching SQLExceptions in your
+ application and dealing 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 SQLState (see
+ java.sql.SQLException.getSQLState() in your APIDOCS) to "08S01"
+ when it encounters network-connectivity issues during the
+ processing of a query. Your application code should then attempt
+ to re-connect to MySQL at this point.</para>
- <para>
- Also, you should be catching SQLExceptions in your
- application and dealing 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 SQLState (see java.sql.SQLException.getSQLState() in
- your APIDOCS) to "08S01" when it encounters
- network-connectivity issues during the processing of a
- query. Your application code should then attempt to
- re-connect to MySQL at this point.
- </para>
+ <para>The following (simplistic) example shows what code that can
+ handle these exceptions might look like:</para>
- <para>
- The following (simplistic) example shows what code that
- can handle these exceptions might look like:
- </para>
-
- <para>
- <example>
-
+ <para><example>
<title>Example of transaction with retry logic</title>
-<programlisting>public void doBusinessOp() throws SQLException {
+ <programlisting>public void doBusinessOp() throws SQLException {
Connection conn = null;
Statement stmt = null;
ResultSet rs = null;
@@ -4548,45 +4619,29 @@
}
} while (!transactionCompleted && (retryCount > 0));
}</programlisting>
-
- </example>
- </para>
-
+ </example></para>
</answer>
-
</qandaentry>
<qandaentry>
-
<question>
-
- <para>
- I'm trying to use JDBC-2.0 updatable result sets, and I
- get an exception saying my result set is not updatable.
- </para>
-
+ <para>I'm trying to use JDBC-2.0 updatable result sets, and I get
+ an exception saying my result set is not updatable.</para>
</question>
<answer>
-
- <para>
- 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 primary key,
- the query must select every primary key and the query can
- only span one table (that is, no joins). This is outlined
- in the JDBC specification.
- </para>
-
+ <para>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 primary key, the query
+ must select every primary key and the query can only span one
+ table (that is, no joins). This is outlined in the JDBC
+ specification.</para>
</answer>
-
</qandaentry>
-
</qandaset>
-
</section>
-<!--
+ <!--
<section id="cj-tracing">
<title>&title-cj-tracing;</title>
@@ -4595,206 +4650,142 @@
-->
<section id="cj-reporting-bugs">
+ <title>How to Report Connector/J Bugs or Problems</title>
- <title>&title-cj-reporting-bugs;</title>
+ <para>The normal place to report bugs is <ulink
+ url="http://bugs.mysql.com/">http://bugs.mysql.com/</ulink>, 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.</para>
- <para>
- The normal place to report bugs is
- <ulink
- url="http://bugs.mysql.com/">http://bugs.mysql.com/</ulink>,
- 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.
- </para>
+ <para>If you have found a sensitive security bug in MySQL, you can send
+ email to <ulink
+ url="mailto:security@stripped">security@stripped</ulink>.</para>
- <para>
- If you have found a sensitive security bug in MySQL, you can
- send email to
- <ulink
- url="mailto:security@stripped">security@stripped</ulink>.
- </para>
+ <para>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.</para>
- <para>
- 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.
- </para>
+ <para>This section will help you write your report correctly so that you
+ don't waste your time doing things that may not help us much or at
+ all.</para>
- <para>
- This section will help you write your report correctly so that
- you don't waste your time doing things that may not help us much
- or at all.
- </para>
+ <para>If you have a repeatable bug report, please report it to the bugs
+ database at <ulink url="???">http://bugs.mysql.com/</ulink>.</para>
- <para>
- If you have a repeatable bug report, please report it to the
- bugs database at
- <ulink url="???">http://bugs.mysql.com/</ulink>.
- </para>
+ <para>Any bug that we are able to repeat has a high chance of being
+ fixed in the next MySQL release.</para>
- <para>
- Any bug that we are able to repeat has a high chance of being
- fixed in the next MySQL release.
- </para>
+ <para>To report other problems, you can use one of the MySQL mailing
+ lists.</para>
- <para>
- To report other problems, you can use one of the MySQL mailing
- lists.
- </para>
+ <para>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 don't matter.</para>
- <para>
- 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 don't matter.
- </para>
+ <para>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.</para>
- <para>
- 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.
- </para>
+ <para>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).</para>
- <para>
- 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).
- </para>
+ <para>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,
+ ``Why doesn't this work for me?'' 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.</para>
- <para>
- 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, ``Why doesn't this work for me?'' 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.
- </para>
+ <para>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.</para>
- <para>
- 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.
- </para>
+ <para>If at all possible, you should create a repeatable, stanalone
+ testcase that doesn't involve any third-party classes.</para>
- <para>
- If at all possible, you should create a repeatable, stanalone
- testcase that doesn't involve any third-party classes.
- </para>
+ <para>To streamline this process, we ship a base class for testcases
+ with Connector/J, named
+ '<classname>com.mysql.jdbc.util.BaseBugReport</classname>'. To create a
+ testcase for Connector/J using this class, create your own class that
+ inherits from <classname>com.mysql.jdbc.util.BaseBugReport</classname>
+ and override the methods <methodname>setUp()</methodname>,
+ <methodname>tearDown()</methodname> and <methodname>runTest</methodname>
+ ().</para>
- <para>
- To streamline this process, we ship a base class for testcases
- with Connector/J, named
- '<classname>com.mysql.jdbc.util.BaseBugReport</classname>'. To
- create a testcase for Connector/J using this class, create your
- own class that inherits from
- <classname>com.mysql.jdbc.util.BaseBugReport</classname> and
- override the methods <methodname>setUp()</methodname>,
- <methodname>tearDown()</methodname> and
- <methodname>runTest</methodname> ().
- </para>
+ <para>In the <methodname>setUp()</methodname> method, create code that
+ creates your tables, and populates them with any data needed to
+ demonstrate the bug.</para>
- <para>
- In the <methodname>setUp()</methodname> method, create code that
- creates your tables, and populates them with any data needed to
- demonstrate the bug.
- </para>
+ <para>In the <methodname>runTest</methodname> () method, create code
+ that demonstrates the bug using the tables and data you created in the
+ <function>setUp</function> method.</para>
- <para>
- In the <methodname>runTest</methodname> () method, create code
- that demonstrates the bug using the tables and data you created
- in the <function>setUp</function> method.
- </para>
+ <para>In the <methodname>tearDown()</methodname> method, drop any tables
+ you created in the <methodname>setUp()</methodname> method.</para>
- <para>
- In the <methodname>tearDown()</methodname> method, drop any
- tables you created in the <methodname>setUp()</methodname>
- method.
- </para>
+ <para>In any of the above three methods, you should use one of the
+ variants of the <methodname>getConnection</methodname> () method to
+ create a JDBC connection to MySQL:</para>
- <para>
- In any of the above three methods, you should use one of the
- variants of the <methodname>getConnection</methodname> () method
- to create a JDBC connection to MySQL:
- </para>
-
<itemizedlist>
-
<listitem>
- <para>
- getConnection() - Provides a connection to the JDBC URL
- specified in getUrl(). If a connection already exists, that
- connection is returned, otherwise a new connection is
- created.
- </para>
+ <para>getConnection() - Provides a connection to the JDBC URL
+ specified in getUrl(). If a connection already exists, that
+ connection is returned, otherwise a new connection is
+ created.</para>
</listitem>
<listitem>
- <para>
- getNewConnection() - Use this if you need to get a new
- connection for your bug report (i.e. there's more than one
- connection involved).
- </para>
+ <para>getNewConnection() - Use this if you need to get a new
+ connection for your bug report (i.e. there's more than one
+ connection involved).</para>
</listitem>
<listitem>
- <para>
- getConnection(String url) - Returns a connection using the
- given URL.
- </para>
+ <para>getConnection(String url) - Returns a connection using the
+ given URL.</para>
</listitem>
<listitem>
- <para>
- getConnection(String url, Properties props) - Returns a
- connection using the given URL and properties.
- </para>
+ <para>getConnection(String url, Properties props) - Returns a
+ connection using the given URL and properties.</para>
</listitem>
-
</itemizedlist>
- <para>
- If you need to use a JDBC URL that is different than
- 'jdbc:mysql:///test', then override the method
- <methodname>getUrl()</methodname> as well.
- </para>
+ <para>If you need to use a JDBC URL that is different than
+ 'jdbc:mysql:///test', then override the method
+ <methodname>getUrl()</methodname> as well.</para>
- <para>
- Use the <methodname>assertTrue(boolean expression)</methodname>
- and <methodname>assertTrue(String failureMessage, boolean
- expression)</methodname> 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).
- </para>
+ <para>Use the <methodname>assertTrue(boolean expression)</methodname>
+ and <methodname>assertTrue(String failureMessage, boolean
+ expression)</methodname> 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).</para>
- <para>
- Finally, create a <methodname>main</methodname> () method that
- creates a new instance of your testcase, and calls the
- <methodname>run</methodname> method:
- </para>
+ <para>Finally, create a <methodname>main</methodname> () method that
+ creates a new instance of your testcase, and calls the
+ <methodname>run</methodname> method:</para>
-<programlisting>public static void main(String[] args) throws Exception {
+ <programlisting>public static void main(String[] args) throws Exception {
new MyBugReport().run();
}</programlisting>
- <para>
- Once you have finished your testcase, and have verified that it
- demonstrates the bug you are reporting, upload it with your bug
- report to
- <ulink
- url="http://bugs.mysql.com/">http://bugs.mysql.com/</ulink>.
- </para>
-
+ <para>Once you have finished your testcase, and have verified that it
+ demonstrates the bug you are reporting, upload it with your bug report
+ to <ulink
+ url="http://bugs.mysql.com/">http://bugs.mysql.com/</ulink>.</para>
</section>
-
</section>
<xi:include href="../refman-common/news-connector-j.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
-
-</section>
+</section>
\ No newline at end of file
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r814 - trunk/refman-5.0 | mmatthews | 13 Jan |
