MySQL Connector/J 3.0.9-stable (formerly MM.MySQL)
MySQL AB's JDBC Driver for MySQL
Copyright (c) 2002/2003 MySQL AB

CONTENTS

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

LICENSE

MySQL Connector/J is licensed under the GPL or a commercial license
from MySQL AB. 

If you have licensed this product under the GPL, please see the COPYING
file for more information. 

If you have licensed this product under a commercial license from
MySQL AB, please see the file "MySQLEULA.txt" that comes with this 
distribution for the terms of the license.

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 that also includes a class-file only "binary" .jar 
archive named "mysql-connector-java-3.0.9-stable-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.9-stable-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. Fail-over only happens when the
connection is in a autoCommit(true) state, because fail-over can not happen reliably
when a transaction is in progress. Most good application servers and connection pools
set autoCommit to 'true' at the end of every transaction/connection use.

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 (after queriesBeforeRetryMaster 
	queries have been issued).
	
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).

Connector/J 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.

Adding the following parameter to your URL will enable the NamedPipeSocketFactory:

socketFactory=com.mysql.jdbc.NamedPipeSocketFactory

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.

You can create your own socket factories by following the example code in 
NamedPipeSocketFactory, or StandardSocketFactory.

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 attempt to        |
                    | reconnect?                                |
--------------------+-------------------------------------------+-------------
initialTimeout      | if autoReconnect is enabled, the          | 2
                    | initial time to wait between              |
                    | re-connect attempts (seconds)             |
--------------------+-------------------------------------------+-------------
queriesBeforeRetry  | Specifies how many queries to issue when  | 50
Master              | failed over before attempting to          |
                    | reconnect to the master                   |
--------------------+-------------------------------------------+-------------
maxRows             | The maximum number of rows to return      | 0
                    | (0 means return all rows)                 |
--------------------+-------------------------------------------+-------------
useUnicode          | should the driver use Unicode character   | true 
                    | 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)                  |
                    |                                           |
                    | See the CHARACTER SETS section for more   |
                    | information.                              | 	
--------------------+-------------------------------------------+-------------			
characterEncoding   | if useUnicode is true, what character     | none
                    | encoding should the driver use when       |
                    | dealing with strings?                     | 
                    |                                           |
                    | See the CHARACTER SETS section for more   |
                    | information.                              | 				
--------------------+-------------------------------------------+-------------
relaxAutoCommit	    | if the version of MySQL the driver        | false
                    | connects to does not support              |
                    | transactions, allow calls to commit,      |
                    | rollback and setAutoCommit? (true/false)	|
--------------------+-------------------------------------------+-------------
ignoreNonTxTables   | Should the driver not throw an exception  | false
                    | when calling rollback() on non-tx-tables? |
                    | Use this when mixing non-tx and tx-tables |
                    | and you are sure you want the behavior.   | 
                    | (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)                              |
--------------------+-------------------------------------------+-------------
connectTimeout      | Timeout for socket connect (in            | 0
                    | milliseconds), with 0 being no timeout.   |
                    | Only works on JDK-1.4 or newer. Defaults  |
                    | to '0'.                                   |
--------------------+-------------------------------------------+-------------
socketTimeout       | When set to something other than '0', the | 0
                    | driver will throw a SQLException when     |   
                    | this timeout (in ms) has expired, and     |
                    | invalidate (close) the connection.        |
                    | The SQLState when this happens will be    |
                    | "08S01", just as when communication fails |
                    | for other reasons.                        |
                    |                                           |
                    | Your application should have code to      |
                    | recover from this event (by creating a    |
                    | new connection, for example)              |
--------------------+-------------------------------------------+-------------
paranoid            | Don't show "sensitive" information in     | false
                    | exceptions and error messages, and clear  |
                    | "sensitive" information from internal     |   
                    | data structures when possible             | 
                    | (true/false)                              |
--------------------+-------------------------------------------+-------------
useHostsInPrivileges| Add '@hostname' to users in               | true 
                    | DatabaseMetaData.getColumn/               |
                    | TablePrivileges()                         |
--------------------+-------------------------------------------+-------------
useTimezone         | Convert time/date values between server   | false 
                    | and client timezones?                     |
--------------------+-------------------------------------------+-------------
serverTimezone      | Use when there is no mapping between your | null 
                    | server timezone and Java timezone. Must   |
                    | use timezone ID supported by your JVM.    |
--------------------+-------------------------------------------+-------------
useSSL              | Should Connector/J use SSL when           | false 
                    | communicating with the server, if the     |
                    | server supports it? (see the SSL SUPPORT  |
                    | section of this document for important    |
                    | information for making this work.         |
--------------------+-------------------------------------------+-------------
useStreamLengthsIn\ | Should Connector/J honor stream lengths   | true
PrepStmts           | when calling PreparedStatement            |
                    | setBinary/AsciiStream() and ResultSet     |
                    | updateBinary/AsciiStream() ?   (note: the |
                    | parameter name is one word with no '\')   |
--------------------+-------------------------------------------+-------------
continueBatchOnError| Should Connector/J continue processing    | true
                    | batch commands if one statement fails?    |
                    |                                           |
                    | The JDBC spec allows either way.          |
--------------------+-------------------------------------------+-------------
allowLoadLocalInfile| Should Connector/J allow/support 'LOAD    | true
                    | DATA LOCAL INFILE' queries (your server   |
                    | must also allow these types of queries)   |
--------------------+-------------------------------------------+-------------
socketFactory       | The name of the class that the driver     | com.mysql.\
                    | should use for creating socket            | jdbc.\
                    | connections to the server. This class     | Standard\
                    | must implement the interface              | Socket\
                    | 'com.mysql.jdbc.SocketFactory' and have   | Factory
                    | a public no-args constructor.             |
--------------------+-------------------------------------------+-------------
strictUpdates       | Should the driver ensure that all primary | true
                    | keys of a given table are selected before |
                    | allowing the result set to be made        |
                    | updatable? (required by JDBC spec,        |
                    | defaults to 'true').                      |
--------------------+-------------------------------------------+-------------
clobberStreamingResults | This will cause a 'streaming'         | false
                    | ResultSet to be automatically closed, and |
                    | any oustanding data still streaming from  |
                    | the server to be discarded if another     |
                    | query is executed before all the data has |
                    | been read from the server.                |
------------------------------------------------------------------------------
  				
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",
and "MysqlConnectionPoolDataSource". 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. Some of the positioning methods
will not work as well, especially ones that require 'knowledge'
of the entire result set, like isBeforeFirst(), isAfterLast()
(when the result set is empty), absolute(), relative(), isLast()
(call .next() and check for a 'false' return value instead). This
is because the driver does not know how many rows are going to be
returned.

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.

CHARACTER SETS

MySQL Connector/J now handles character sets in a more transparent way
than MM.MySQL did. The driver attempts to determine the character
set of the MySQL server you are connecting to, and map it to the
Java character set that is appropriate. This mapping is kept up to
date with new server releases. In almost all cases you will not
need to set the "useUnicode" or "characterEncoding" parameters,
as the driver will do this for you. Because of this the "useUnicode"
parameter has the default value of "true". If you need to force
the old behavior of the driver, you need to add "useUnicode=false"
to your URL.

For single-byte character sets, the driver uses an optimized 
character translation scheme that yields performance that is as
good or better than MM.MySQL or the first 3.0 version of 
MySQL Connector/J. Multi-byte character sets use your JVM's built
in character translation support, and on average this is 5-10%
slower than single-byte character support.

If you have a character set that was not created by MySQL AB, a
driver version older than the version of MySQL server you are using,
or for some reason can not get the mapping to work, you can force
the character set using the "useUnicode=true" and 
"characterEncoding=some_charset" parameters in your URL to tell
the driver which character set to use, where "some_charset" is
a character set that your JVM supports.

You can also store UTF-8 encoded data in MySQL server versions 
prior to 4.1 by using 'useUnicode=true&characterEncoding=UTF8' 
as parameters in your JDBC URL. You might encounter wierd collation
results (sorting/comparing) because UTF-8 encompasses all Unicode
character sets, so this is best used when you sort/search on
keys in a normal (latin1) character set.

SSL SUPPORT

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.

For SSL Support to work, you must have the following:

 * A JDK that includes JSSE (Java Secure Sockets Extension), 
   like JDK-1.4.1 or newer. Due to a bug with the JSSE, you 
   can not use Connector/J and SSL on JVMs prior to JDK-1.4.
   
 * A MySQL server that supports SSL and has been compiled 
   and configured to do so, which is MySQL-4.0.4 or later,
   see:
   
   http://www.mysql.com/doc/en/Secure_connections.html
   
 * A client certificate (covered later in this section)
 
 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.
 
 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):
 
shell> keytool -import -alias mysqlServerCACert -file cacert.pem \
        -keystore truststore
        
Keytool will respond with the following information:

------------------------------------------------------
Enter keystore password:  *********
Owner: EMAILADDRESS=walrus@mysql.com, CN=Walrus, O=MySQL AB, L=Orenburg, ST=Some
-State, C=RU
Issuer: EMAILADDRESS=walrus@mysql.com, CN=Walrus, O=MySQL AB, L=Orenburg, ST=Som
e-State, C=RU
Serial number: 0
Valid from: Fri Aug 02 16:55:53 CDT 2002 until: Sat Aug 02 16:55:53 CDT 2003
Certificate fingerprints:
         MD5:  61:91:A0:F2:03:07:61:7A:81:38:66:DA:19:C4:8D:AB
         SHA1: 25:77:41:05:D5:AD:99:8C:14:8C:CA:68:9C:2F:B8:89:C3:34:4D:6C
Trust this certificate? [no]:  yes
Certificate was added to keystore
------------------------------------------------------
        
You will then need to generate a client certificate, so that the MySQL 
server knows that it is talking to a secure client:

shell> keytool -genkey -keyalg rsa -alias mysqlClientCertificate \
      -keystore keystore

Keytool will prompt you for the following information, and create a keystore
named 'keystore' in the current directory. You should respond with 
information that is appropriate for your situation:

------------------------------------------------------
Enter keystore password:  *********
What is your first and last name?
  [Unknown]:  Matthews
What is the name of your organizational unit?
  [Unknown]:  Software Development
What is the name of your organization?
  [Unknown]:  MySQL AB
What is the name of your City or Locality?
  [Unknown]:  Flossmoor
What is the name of your State or Province?
  [Unknown]:  IL
What is the two-letter country code for this unit?
  [Unknown]:  US
Is <CN=Matthews, OU=Software Development, O=MySQL AB,
 L=Flossmoor, ST=IL, C=US> correct?
  [no]:  y

Enter key password for <mysqlClientCertificate>
        (RETURN if same as keystore password):
------------------------------------------------------

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.

 -Djavax.net.ssl.keyStore=path_to_keystore_file
 -Djavax.net.ssl.keyStorePassword=********* 
 -Djavax.net.ssl.trustStore=path_to_truststore_file 
 -Djavax.net.ssl.trustStorePassword=********* 
 
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().
 
Testing the SSL Layer:

You can test that SSL is working by turning on JSSE debugging 
(as detailed below), and look for the following key events:

------------------------------------------------------
 ...
 *** ClientHello, v3.1
 RandomCookie:  GMT: 1018531834 bytes = { 199, 148, 180, 215, 74, 12, 54, 244, 0, 168, 55, 103, 215, 64, 16, 138, 225, 190, 132, 153, 2, 217, 219, 239, 202, 19, 121, 78 }
 Session ID:  {}
 Cipher Suites:  { 0, 5, 0, 4, 0, 9, 0, 10, 0, 18, 0, 19, 0, 3, 0, 17 }
 Compression Methods:  { 0 }
 ***
 [write] MD5 and SHA1 hashes:  len = 59
 0000: 01 00 00 37 03 01 3D B6   90 FA C7 94 B4 D7 4A 0C  ...7..=.......J.
 0010: 36 F4 00 A8 37 67 D7 40   10 8A E1 BE 84 99 02 D9  6...7g.@........
 0020: DB EF CA 13 79 4E 00 00   10 00 05 00 04 00 09 00  ....yN..........
 0030: 0A 00 12 00 13 00 03 00   11 01 00                 ...........
 main, WRITE:  SSL v3.1 Handshake, length = 59
 main, READ:  SSL v3.1 Handshake, length = 74
 *** ServerHello, v3.1
 RandomCookie:  GMT: 1018577560 bytes = { 116, 50, 4, 103, 25, 100, 58, 202, 79, 185, 178, 100, 215, 66, 254, 21, 83, 187, 190, 42, 170, 3, 132, 110, 82, 148, 160, 92 }
 Session ID:  {163, 227, 84, 53, 81, 127, 252, 254, 178, 179, 68, 63, 182, 158, 30, 11, 150, 79, 170, 76, 255, 92, 15, 226, 24, 17, 177, 219, 158, 177, 187, 143}
 Cipher Suite:  { 0, 5 }
 Compression Method: 0
 ***
 %% Created:  [Session-1, SSL_RSA_WITH_RC4_128_SHA]
 ** SSL_RSA_WITH_RC4_128_SHA
 [read] MD5 and SHA1 hashes:  len = 74
 0000: 02 00 00 46 03 01 3D B6   43 98 74 32 04 67 19 64  ...F..=.C.t2.g.d
 0010: 3A CA 4F B9 B2 64 D7 42   FE 15 53 BB BE 2A AA 03  :.O..d.B..S..*..
 0020: 84 6E 52 94 A0 5C 20 A3   E3 54 35 51 7F FC FE B2  .nR..\ ..T5Q....
 0030: B3 44 3F B6 9E 1E 0B 96   4F AA 4C FF 5C 0F E2 18  .D?.....O.L.\...
 0040: 11 B1 DB 9E B1 BB 8F 00   05 00                    ..........
 main, READ:  SSL v3.1 Handshake, length = 1712
 ...
------------------------------------------------------

Debugging the SSL Layer:
 
 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.
 


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.
  
  NOTE:
  
  Testing your connectivity with the "mysql" command-line client will not
  work unless you add the "--host" flag, and use something other than 
  "localhost" for the host. The "mysql" command-line client will use Unix
  domain sockets if you use the special hostname "localhost". If you are
  testing connectivity to "localhost", use "127.0.0.1" as the hostname
  instead.

  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 or application and I 
  get an exception similar to: 
  
  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:
  
  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.
  
  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.
  
  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.
  
  If MySQL has been started with the "--skip-networking" option set 
  (The Debian Linux install 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 "data" 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 (by default, 3306).
  

  ----

  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.truncate()

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

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

	ResultSet.getArray(int)
	ResultSet.getArray(colName)
	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.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.

--

