MySQL Connector/J 3.0.0 Beta (formerly MM.MySQL)
MySQL's JDBC Driver for MySQL
Copyright (c) 2002 MySQL-AB

CONTENTS

* License
* System Requirements
* Introduction
* Usage and Installation
* Troubleshooting
* Known Bugs
* Support

LICENSE

MySQL Connector/J is licensed under the GPL. Please see the COPYING
file for more information. If you need non-GPL licenses for
commercial distribution please contact me <mark@mysql.com> or
sales@mysql.com.


SYSTEM REQUIREMENTS
 
* Any Java virtual machine supporting JDBC-2.0 or newer (JDK-1.2 or newer)
* Any MySQL server supporting version 9 or 10 of the MySQL protocol

Because MySQL is not fully ANSI SQL-92 compliant, it is not possible to 
create a fully JDBC-compliant driver for MySQL.  However, this driver 
strives to implement as much of the JDBC API as is feasible.

INTRODUCTION

MySQL Connector/J is an implemntation of the JDBC API for the MySQL relational
database server. It strives to conform as much as possible to the API
as specified by JavaSoft. It is known to work with many third-party 
products, including Borland JBuilder, IBM Visual Age for Java, SQL/J,
JBoss, Weblogic, IBM WebSphere, Cocobase, ObjectRelationalBridge, etc.

USAGE AND INSTALLATION

MySQL Connector/J is distributed as a .zip or .tar.gz archive containing 
the sources and class files as well as a class-file only "binary" .jar 
archive named "mysql-connector-java-3.0.0-beta-bin.jar".

You will need to use the appropriate gui or command-line utility to un-archive 
the distribution (for example, WinZip for the .zip archive, and "tar" for 
the .tar.gz archive).

Once you have un-archived the distribution archive,
you can install the driver in one of two ways:

Either copy the "com" and "org" subdirectories and all of their contents
to anywhere you like, and put the directory holding the "com" and "org"
subdirectories in your classpath, or...

Put mysql-connector-java-3.0.0-beta-bin.jar in your classpath, either by adding the 
FULL path to it to your CLASSPATH enviornment variable, or putting it
in $JAVA_HOME/jre/lib/ext.

If you are using a servlet engine or application server, 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. If you are developing
servlets and/or JSPs, and your application server is J2EE-compliant, 
you should put the driver's .jar file in the WEB-INF/lib subdirectory
of your webapp, as this is the standard location for third party 
class libraries in J2EE web applications. You can also use the
MysqlDataSource, MysqlConnectionPoolDataSource or MysqlXADataSource 
classes in the com.mysql.jdbc.jdbc2.optional package, if your J2EE 
application server supports/requires them. MysqlDataSource supports the 
following parameters (through standard "set" mutators):

	user
	password
	serverName (see the next section about fail-over hosts)
	databaseName
	port

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.

You might use this name in a Class.forName() call to load the driver:

	Class.forName("com.mysql.jdbc.Driver").newInstance();

To connect to the database, you need to use a JDBC url with the following 
format ([xxx] denotes optional url components):

  jdbc:mysql://[hostname][,failoverhost...][:port]/[dbname][?param1=value1][&param2=value2].....

The driver now has fail-over support. This allows the driver to fail-over to any number
of "slave" hosts and still perform read-only queries.

The fail-over functionality has the following behavior:

If the URL parameter "autoReconnect" is false:
	
	Failover only happens at connection initialization, and failback occurs 
	when the driver determines that the first host has become available again
	
If the URL parameter "autoReconnect" is true:

	Failover happens when the driver determines that the connection has failed
	(before _every_ query), and falls back to the first host when it determines
	that the host has become available again.
	
In either case, whenever you are connected to a "failed-over" server, the connection
will be set to read-only status, so queries that would modify data will have exceptions
thrown (the query will _never_ be seen by the MySQL server).

URL Parameters (can be passed as properties in 
DriverManager.getConnection() as well):

==============================================================================
Name                | Use                                       | Default 
==============================================================================
user                | The user to connect as                    | none 
--------------------+-------------------------------------------+-------------
password            | The password to use when connecting       | none 
--------------------+-------------------------------------------+-------------
autoReconnect       | should the driver attempt to              | false
                    | re-connect if the connection dies?        |
                    | (true/false)                              | 		
--------------------+-------------------------------------------+-------------
maxReconnects       | if autoReconnect is enabled, how many     | 3
                    | times should the driver attemt to         |
                    | reconnect?                                |
--------------------+-------------------------------------------+-------------
initialTimeout      | if autoReconnect is enabled, the          | 2
                    | initial time to wait between              |
                    | re-connect attempts (seconds)             |
--------------------+-------------------------------------------+-------------
maxRows             | The maximum number of rows to return      | 0
                    | (0 means return all rows)                 |
--------------------+-------------------------------------------+-------------
useUnicode          | should the driver use Unicode character   | false 
                    | encodings when handling                   | 
                    | strings? If not used with                 |
                    | characterEncoding, the driver will        |
                    | attempt to determine the character set    |
                    | in use on the server, and adjust          |
                    | accordingly (true/false)                  | 	
--------------------+-------------------------------------------+-------------			
characterEncoding   | if useUnicode is true, what character     | none
                    | encoding should the driver use when       |
                    | dealing with strings?                     | 				
--------------------+-------------------------------------------+-------------
relaxAutoCommit	    | if the version of MySQL the driver        | false
                    | connects to does not support              |
                    | transactions, allow calls to commit,      |
                    | rollback and setAutoCommit? (true/false)	|
--------------------+-------------------------------------------+-------------
ultraDevHack	    | Create PreparedStatements for             | false
                    | prepareCall(), because UltraDev           |
                    | is broken? (true/false)                   |
--------------------+-------------------------------------------+-------------			
capitalizeTypeNames | Capitalize type names in                  | false
                    | DatabaseMetaData? (usually only           |
                    | usefull when using WebObjects)            |
--------------------+-------------------------------------------+-------------
profileSql          | Dump queries and execution/fetch times    | false
                    | to STDERR. Useful for optimizing queries  |
                    | that are auto-generated as in CMP EJBs    |   
                    | (true/false)                              |
------------------------------------------------------------------------------
			
A simple connection example looks like:

	Class.forName("com.mysql.jdbc.Driver").newInstance();
	
	java.sql.Connection conn;
	
	conn = DriverManager.getConnection(
		"jdbc:mysql://localhost/test?user=blah&password=blah");
	
If you need further JDBC tutorial information, please see
http://www.java.sun.com/products/jdbc/

The driver supports batch updates for Statements and PreparedStatements.
Batch updates will be processed in entirety, if any of the updates raise a
SQLException, a java.sql.BatchUpdateException will be thrown after all updates
have been processed, with update count values of '-3' for any statements that
were not completed (see section 6.1 in the JDBC-2.1 API spec for more details).

Various DataSource implementations exist, all under the 
com.mysql.jdbc.jdbc2.optional package. They are "MysqlDataSource",
"MysqlConnectionPoolDataSource" and "MysqlXaDataSource". Refer to your 
application server documentation for information on how to use these classes.
An example of using the standard DataSource ("MysqlDataSource") can be found
in the "testsuite" directory.

If you need to "stream" result sets, row-by-row, the driver
now supports this. What you need to do is create a statement in the
following manner:

  stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY, 
                            java.sql.ResultSet.CONCUR_READ_ONLY);
                            
  stmt.setFetchSize(Integer.MIN_VALUE);
  
This serves as a signal to the driver to "stream" result sets
row-by-row. After this any result sets created with the statement
will be retrieved row-by-row.

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.

This version of the driver also supports large packet sizes
(up to the limits of your server) when you're using MySQL-4.0
or newer. Your JVM will need to be able to allocate enough
memory to store the entire large packet, as well as an overhead
of 16 megabytes or so. Usually, you can control this by passing
the "-XmxNNNm" flag to your JVM, where NNN is the number of 
megabytes of memory that the JVM should be allowed to allocate.

TROUBLESHOOTING

There are a few issues that seem to be 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 below.

  Issue: 

  "When I try to connect to the database with MySQL Connector/J, I get the
  following exception:

  SQLException: Server configuration denies access to data source
  SQLState: 08001
  VendorError: 0

  What's going on? I can connect with the MySQL client."

  Resolution: 

  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 the
  HOSTS table to determine whether or not the connection should be allowed.

  You must add grants to allow this to happen. The following is an example
  of how to do this (but not the most secure).

  From the mysql command-line client, issue the following command

  "GRANT ALL PRIVILEGES ON [dbname].* to '[user]'@'[hostname]' identified by 
  '[password]'"

  replacing [dbname] with the name of your database, [user] with the username,
  [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.

  I suggest you read the permissions/security section of your MySQL server 
  manual for a much more detailed explanation of how this works.
  
  ----

  Issue: 

  "My application throws a SQLException 'No Suitable Driver'".

  Resolution: 

  One of two things are happening. Either the driver is not in
  your CLASSPATH (see the "USAGE AND INSTALLATION" section above), or your
  URL format is incoorect (once again see "USAGE AND INSTALLATION").

  ----

  Issue: 

  "I'm trying to use MySQL Connector/J in an applet and I get the following
  exception: 
  
  SQLException: Cannot connect to MySQL server on host:3306. Is there 
  a MySQL server running on the machine/port you are trying to connect to? 
  (java.security.AccessControlException) 
  SQLState:     08S01 
  VendorError:  0 
  
  What's wrong?"

  Resolution:
  
  Applets can only make network connections back to the machine that the
  webserver 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 filesystem, you must always deploy
  them to a webserver.

  ----

  Issue: 

  "I have a servlet/application that works fine for a day, and then stops 
  working overnight".

  Resolution: 

  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 "USAGE AND INSTALLATION"). 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 software development. 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.

  ----

  Issue:

  "I'm trying to use JDBC-2.0 updatable result sets, and I get an exception
  saying my result set is not updatable..."

  Resolution:

  Because MySQL does not have row identifiers, MySQL Connector/J can only update
  result sets that have come from queries that select the primary key(s) and
  only span one table (i.e. no joins). This is outlined in the JDBC specification.


KNOWN BUGS

There are some parts of the JDBC-3.0 spec that are not implemented (mostly 
because they can't be until MySQL supports the underlying features required
to implement them). 

The following methods are not implemented:

	Blob.setBinaryStream()
	Blob.setBytes()
	Blob.truncate()

	Connection.setSavePoint()
	Connection.setTypeMap(Map)
	Connection.getTypeMap()
	Connection.prepareCall(String)
	Connection.releaseSavepoint(Savepoint)
	Connection.rollback(Savepoint)

	PreparedStatement.setArray(int, Array)
	PreparedStatement.setBlob(int, Clob)
	PreparedStatement.getMetaData()
	PreparedStatement.setRef()
	PreparedStatement.getParameterMetaData()

	ResultSet.getArray(int)
	ResultSet.getArray(colName)
	ResultSet.getCharacterStream(int)
	ResultSet.getCharacterStream(String)
	ResultSet.getClob(int)
	ResultSet.getClob(String)
	ResultSet.getObject(int, Map)
	ResultSet.getObject(String, Map)
	ResultSet.getRef(int)
	ResultSet.getRef(String)
	ResultSet.rowDeleted()
	ResultSet.rowInserted()
	ResultSet.rowUpdated()
	ResultSet.updateArray(int, Array)
	ResultSet.updateArray(String, Array)
	ResultSet.updateBlob(int, Blob)
	ResultSet.updateBlob(String, Blob)
	ResultSet.updateClob(int, Clob)
	ResultSet.updateClob(String, Clob)
	ResultSet.updateRef(int, Ref)
	ResultSet.updateRef(String, Ref)

If you see something that is not implemented, and you have an idea on how to
do it, go ahead and let me know. I'm always looking for help and/or feedback
about the driver.


SUPPORT

Community-based support is available on the mysql-java mailing list 
available from http://www.mysql.com/documentation/lists.html 

MySQL-AB offers commercial support, and non-GPL commercial licenses for
this software. Contact me <mark@mysql.com> or <sales@mysql.com> for more 
information.

--
This software is OSI Certified Open Source Software.
OSI Certified is a certification mark of the Open Source Initiative.

--

