mysql-connector

MySQL Connector/J Copyright 1997-2008 MySQL AB This documentation is NOT distributed under a GPL license. Use of this documentation is subject to the following terms: You may create a printed copy of this documentation solely for your own personal use. Conversion to other formats is allowed as long as the actual content is not altered or edited in any way. You shall not publish or distribute this documentation in any form or on any media, except if you distribute the documentation in a manner similar to how MySQL disseminates it (that is, electronically for download on a Web site with the software) or on a CD-ROM or similar medium, provided however that the documentation is disseminated together with the software on the same medium. Any other use, such as any dissemination of printed copies or use of this documentation, in whole or in part, in another publication, requires the prior written consent from an authorized representative of MySQL AB. MySQL AB reserves any and all rights to this documentation not expressly granted above. For more information on the terms of this license, for details on how the MySQL documentation is built and produced, or if you are interested in doing a translation, please contact us at docs@mysql.com. If you want help with using MySQL, please visit either the MySQL Forums (http://forums.mysql.com) or MySQL Mailing Lists (http://lists.mysql.com) where you can discuss your issues with other MySQL users. For additional documentation on MySQL products, including translations of the documentation into other languages, and downloadable versions in variety of formats, including HTML, CHM and PDF formats, see MySQL Documentation Library (http://dev.mysql.com/doc). Abstract This manual describes MySQL Connector/J, the JDBC implementation for communicating with MySQL servers. Document generated on: 2008-03-01 (revision: 10086) _______________________________________________________ MySQL Connector/J MySQL provides connectivity for client applications developed in the Java programming language via a JDBC driver, which is called MySQL Connector/J. MySQL Connector/J is a JDBC Type 4 driver. Different versions are available that are compatible with the JDBC-3.0 and JDBC-4.0 specifications. The Type 4 designation means that the driver is pure-Java implementation of the MySQL protocol and does not rely on the MySQL client libraries. 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 naked JDBC for all but the most trivial problems and consider using one of the popular persistence frameworks such as Hibernate (http://www.hibernate.org/), Spring's JDBC templates (http://www.springframework.org/) or Ibatis SQL Maps (http://ibatis.apache.org/) to do the majority of repetitive work and heavier lifting that is sometimes required with JDBC. 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: * JDBC Basics (http://java.sun.com/docs/books/tutorial/jdbc/basics/index.htm l) --- A tutorial from Sun covering beginner topics in JDBC * JDBC Short Course (http://java.sun.com/developer/onlineTraining/Database/JDBCSho rtCourse/index.html) --- A more in-depth tutorial from Sun and JGuru Key topics: * For help with connection strings, connection options setting up your connection through JDBC, see Section 4.1, "Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J." * For tips on using Connector/J and JDBC with generic J2EE toolkits, see Section 5.2, "Using Connector/J with J2EE and Other Java Frameworks." * Developers using the Tomcat server platform, see Section 5.2.2, "Using Connector/J with Tomcat." * Developers using JBoss, see Section 5.2.3, "Using Connector/J with JBoss." * Developers using Spring, see Section 5.2.4, "Using Connector/J with Spring." MySQL Enterprise MySQL Enterprise subscribers will find more information about using JDBC with MySQL in the Knowledge Base articles about JDBC (https://kb.mysql.com/search.php?cat=search&category=10). Access to the MySQL Knowledge Base collection of articles is one of the advantages of subscribing to MySQL Enterprise. For more information see http://www.mysql.com/products/enterprise/advisors.html. Chapter 1. Connector/J Versions There are currently four versions of MySQL Connector/J available: * Connector/J 5.1 is the Type IV pure Java JDBC driver and provides compatibility with all the functionality of MySQL, including 4.1, 5.0, 5.1 and the 6.0 alpha release featuring the new Falcon storage engine. Connector/J 5.1 provides ease of development features, including auto-registration with the Driver Manager, standardized validity checks, categorized SQLExceptions, support for the JDBC-4.0 XML processing, per connection client information, NCHAR, NVARCHAR and NCLOB types. This release also includes all bug fixes up to and including Connector/J 5.0.6. * Connector/J 5.0 provides support for all the functionality offered by Connector/J 3.1 and includes distributed transaction (XA) support. * Connector/J 3.1 was designed for connectivity to MySQL 4.1 and MySQL 5.0 servers and provides support for all the functionality in MySQL 5.0 except distributed transaction (XA) support. * Connector/J 3.0 provides core functionality and was designed with connectivity to MySQL 3.x or MySQL 4.1 servers, although it will provide basic compatibility with later versions of MySQL. Connector/J 3.0 does not support server-side prepared statements, and does not support any of the features in versions of MySQL later than 4.1. The current recommended version for Connector/J is 5.1. This guide covers all three connector versions, with specific notes given where a setting applies to a specific option. 1.1. Java Versions Supported MySQL Connector/J supports Java-2 JVMs, including: * JDK 1.2.x (only for Connector/J 3.1.x or earlier) * JDK 1.3.x * JDK 1.4.x * JDK 1.5.x * JDK 1.6.x If you are building Connector/J from source using the source distribution (see Section 2.4, "Installing from the Development Source Tree") then you must use JDK 1.4.x or newer to compiler the Connector package. For Connector/J 5.1 you must use JDK-1.6.x. MySQL Connector/J does not support JDK-1.1.x or JDK-1.0.x. Because of the implementation of java.sql.Savepoint, Connector/J 3.1.0 and newer will not run on JDKs older than 1.4 unless the class verifier is turned off (by setting the -Xverify:none option to the Java runtime). This is because the class verifier will try to load the class definition for java.sql.Savepoint even though it is not accessed by the driver unless you actually use savepoint functionality. 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 java.util.LinkedHashMap which was first available in JDK-1.4.0. Chapter 2. Connector/J Installation You can install the Connector/J package using two methods, using either the binary or source distribution. The binary distribution provides the easiest methods for i