Chapter 23.  Connectors

Table of Contents

23.1. MySQL Connector/ODBC
23.1.1. Introduction to MyODBC
23.1.2. General Information About ODBC and MyODBC
23.1.3. How to Install MyODBC
23.1.4. Installing MyODBC from a Binary Distribution on Windows
23.1.5. Installing MyODBC from a Binary Distribution on Unix
23.1.6. Installing MyODBC from a Source Distribution on Windows
23.1.7. Installing MyODBC from a Source Distribution on Unix
23.1.8. Installing MyODBC from the BitKeeper Development Source Tree
23.1.9. MyODBC Configuration
23.1.10. MyODBC Connection-Related Issues
23.1.11. MyODBC and Microsoft Access
23.1.12. MyODBC and Microsoft VBA and ASP
23.1.13. MyODBC and Third-Party ODBC Tools
23.1.14. MyODBC General Functionality
23.1.15. Basic MyODBC Application Steps
23.1.16. MyODBC API Reference
23.1.17. MyODBC Data Types
23.1.18. MyODBC Error Codes
23.1.19. MyODBC With VB: ADO, DAO and RDO
23.1.20. MyODBC with Microsoft .NET
23.1.21. Credits
23.2. MySQL Connector/NET
23.2.1. Introduction
23.2.2. Downloading and Installing MySQL Connector/NET
23.2.3. Connector/NET Architecture
23.2.4. Using MySQL Connector/NET
23.2.5. MySQL Connector/NET Change History
23.3. MySQL Connector/J
23.3.1. Basic JDBC concepts
23.3.2. Installing Connector/J
23.3.3. JDBC Reference
23.3.4. Using Connector/J with J2EE and Other Java Frameworks
23.3.5. Diagnosing Connector/J Problems
23.3.6. Changelog
23.4. MySQL Connector/MXJ
23.4.1. Introduction
23.4.2. Support Platforms:
23.4.3. JUnit Test Requirements
23.4.4. Running the JUnit Tests
23.4.5. Running as part of the JDBC Driver
23.4.6. Running within a Java Object
23.4.7. The MysqldResource API
23.4.8. Running within a JMX Agent (custom)
23.4.9. Deployment in a standard JMX Agent environment (JBoss)
23.4.10. Installation

This chapter describes MySQL Connectors, drivers that provide connectivity to the MySQL server for client programs.

23.1. MySQL Connector/ODBC

MySQL provides support for ODBC by means of MySQL Connector/ODBC, the family of MyODBC drivers. This is the reference for the Connector/ODBC product family of MyODBC drivers that provide ODBC 3.5x compliant access to the MySQL Database System. It teaches you how to install MyODBC and how to use it. There is also information about common programs that are known to work with MyODBC and answers to some of the most frequently asked questions about MyODBC.

This reference applies to MyODBC 3.51. You can find a manual for an older version of MyODBC in the binary or source distribution for that version.

This is a reference to the MySQL ODBC drivers, not a general ODBC reference. For more information about ODBC, refer to http://www.microsoft.com/data/.

The application development part of this reference assumes a good working knowledge of C, general DBMS knowledge, and finally, but not least, familiarity with MySQL. For more information about MySQL functionality and its syntax, refer to http://dev.mysql.com/doc/.

If you have questions that are not answered in this document, please send a mail message to .

23.1.1. Introduction to MyODBC

23.1.1.1. What is ODBC?

ODBC (Open Database Connectivity) provides a way for client programs to access a wide range of databases or data sources. ODBC is a standardized API that allows connections to SQL database servers. It was developed according to the specifications of the SQL Access Group and defines a set of function calls, error codes, and data types that can be used to develop database-independent applications. ODBC usually is used when database independence or simultaneous access to different data sources is required.

For more information about ODBC, refer to http://www.microsoft.com/data/.

23.1.1.2. What is Connector/ODBC?

Connector/ODBC is the term designating the MySQL AB product family of MySQL ODBC drivers. These are known as the MyODBC drivers.

23.1.1.3. What is MyODBC 2.50?

MyODBC 2.50 is a 32-bit ODBC driver from MySQL AB that is based on ODBC 2.50 specification level 0 (with level 1 and 2 features). This is one of the most popular ODBC drivers in the Open Source market, used by many users to access the MySQL functionality.

23.1.1.4. What is MyODBC 3.51?

MyODBC 3.51 is a 32-bit ODBC driver, also known as the MySQL ODBC 3.51 driver. This version is enhanced compared to the existing MyODBC 2.50 driver. It has support for ODBC 3.5x specification level 1 (complete core API + level 2 features) in order to continue to provide all functionality of ODBC for accessing MySQL.

23.1.1.5. Where to Get MyODBC

MySQL AB distributes all its products under the General Public License (GPL). You can get a copy of the latest version of MyODBC binaries and sources from the MySQL AB Web site http://dev.mysql.com/downloads/.

For more information about MyODBC, visit http://www.mysql.com/products/myodbc/.

For more information about licensing, visit http://www.mysql.com/company/legal/licensing/.

23.1.1.6. Supported Platforms

MyODBC can be used on all major platforms supported by MySQL, such as:

  • Windows 95, 98, Me, NT, 2000, XP, and 2003

  • All Unix Operating Systems

    • AIX

    • Amiga

    • BSDI

    • DEC

    • FreeBSD

    • HP-UX 10, 11

    • Linux

    • Mac OS X Server

    • Mac OS X

    • NetBSD

    • OpenBSD

    • OS/2

    • SGI Irix

    • Solaris

    • SunOS

    • SCO OpenServer

    • SCO UnixWare

    • Tru64 Unix

If a binary distribution is not available for downloading for a particular platform, you can build the driver yourself by downloading the driver sources. You can contribute the binaries to MySQL by sending a mail message to , so that it becomes available for other users.

23.1.1.7. MyODBC Mailing List

MySQL AB provides assistance to the user community by means of its mailing lists. For MyODBC-related issues, you can get help from experienced users by using the mailing list.

For information about subscribing to MySQL mailing lists or to browse list archives, visit http://lists.mysql.com/.

Of particular interest is the ODBC forum in the MySQL Connectors section of the forums.

23.1.1.8. MyODBC Forum

Community support from experienced users is available through the MySQL Forums, located at http://forums.mysql.com.

23.1.1.9. How to Report MyODBC Problems or Bugs

If you encounter difficulties or problems with MyODBC, you should start by making a log file from the ODBC Manager (the log you get when requesting logs from ODBC ADMIN) and MyODBC. The procedure for doing this is described in Section 23.1.9.7, “Getting an ODBC Trace File”.

Check the MyODBC trace file to find out what could be wrong. You should be able to determine what statements were issued by searching for the string >mysql_real_query in the myodbc.log file.

You should also try issuing the statements from the mysql client program or from admndemo. This helps you determine whether the error is in MyODBC or MySQL.

If you find out something is wrong, please only send the relevant rows (maximum 40 rows) to the myodbc mailing list. See Section 1.7.1.1, “The MySQL Mailing Lists”. Please never send the whole MyODBC or ODBC log file!

If you are unable to find out what's wrong, the last option is to create an archive in tar or Zip format that contains a MyODBC trace file, the ODBC log file, and a README file that explains the problem. You can send this to ftp://ftp.mysql.com/pub/mysql/upload/. Only we at MySQL AB has access to the files you upload, and we are very discreet with the data.

If you can create a program that also demonstrates the problem, please include it in the archive as well.

If the program works with some other SQL server, you should include an ODBC log file where you do exactly the same thing in the other SQL server.

Remember that the more information you can supply to us, the more likely it is that we can fix the problem.

23.1.1.10. How to Submit a MyODBC Patch

You can send a patch or suggest a better solution for any existing code or problems by sending a mail message to .

23.1.2. General Information About ODBC and MyODBC

23.1.2.1. Introduction to ODBC

Open Database Connectivity (ODBC) is a widely accepted application-programming interface (API) for database access. It is based on the Call-Level Interface (CLI) specifications from X/Open and ISO/IEC for database APIs and uses Structured Query Language (SQL) as its database access language.

A survey of ODBC functions supported by MyODBC is given at Section 23.1.16, “MyODBC API Reference”. For general information about ODBC, see http://www.microsoft.com/data/.

23.1.2.2. MyODBC Architecture

The MyODBC architecture is based on five components, as shown in the following diagram:

MyODBC Architecture
  • Application:

    An application is a program that calls the ODBC API to access the data from the MySQL server. The Application communicates with the Driver Manager using the standard ODBC calls. The Application does not care where the data is stored, how it is stored, or even how the system is configured to access the data. It needs to know only the Data Source Name (DSN).

    A number of tasks are common to all applications, no matter how they use ODBC. These tasks are:

    • Selecting the MySQL server and connecting to it

    • Submitting SQL statements for execution

    • Retrieving results (if any)

    • Processing errors

    • Committing or rolling back the transaction enclosing the SQL statement

    • Disconnecting from the MySQL server

    Because most data access work is done with SQL, the primary tasks for applications that use ODBC are submitting SQL statements and retrieving any results generated by those statements.

  • Driver manager:

    The Driver Manager is a library that manages communication between application and driver or drivers. It performs the following tasks:

    • Resolves Data Source Names (DSN)

    • Driver loading and unloading

    • Processes ODBC function calls or passes them to the driver

  • MyODBC Driver:

    The MyODBC driver is a library that implements the functions in the ODBC API. It processes ODBC function calls, submits SQL requests to MySQL server, and returns results back to the application. If necessary, the driver modifies an application's request so that the request conforms to syntax supported by the MySQL.

  • ODBC.INI:

    ODBC.INI is the ODBC configuration file that stores the driver and database information required to connect to the server. It is used by the Driver Manager to determine which driver to be loaded using the Data Source Name. The driver uses this to read connection parameters based on the DSN specified. For more information, Section 23.1.9, “MyODBC Configuration”.

  • MySQL Server:

    The MySQL server is the source of data. MySQL is:

    • A database management system (DBMS)

    • A relational database management system (RDBMS)

    • Open Source Software

23.1.2.3. ODBC Driver Managers

An ODBC Driver Manager is a library that manages communication between the ODBC aware application and driver(s). Its main functionality includes:

  • Resolving Data Source Names (DSN)

  • Driver loading and unloading

  • Processing ODBC function calls or passing them to the driver

The following driver managers are commonly used:

MyODBC 3.51 also is shipped with UnixODBC beginning with version 2.1.2.

23.1.2.4. Types of MySQL ODBC Drivers

MySQL AB supports two Open Source ODBC drivers for accessing MySQL functionality through the ODBC API: MyODBC (MyODBC 2.50) and MySQL ODBC 3.51 Driver (MyODBC 3.51).

Note: From this section onward, we refer both the drivers generically as MyODBC. Whenever there is a difference, we use the original names.

23.1.3. How to Install MyODBC

MyODBC works on Windows 9x, Me, NT, 2000, XP, and 2003, and on most Unix platforms.

MyODBC is Open Source. You can find the newest version at http://dev.mysql.com/downloads/connector/odbc/. Please note that the 2.50.x versions are LGPL licensed, whereas the 3.51.x versions are GPL licensed.

If you have problem with MyODBC and your program also works with OLEDB, you should try the OLEDB driver.

Normally you need to install MyODBC only on Windows machines. You need MyODBC for Unix only if you have a program like ColdFusion that is running on a Unix machine and uses ODBC to connect for database access.

If you want to install MyODBC on a Unix box, you also need an ODBC manager. MyODBC is known to work with most Unix ODBC managers.

  • To make a connection to a Unix box from a Windows box with an ODBC application (one that doesn't support MySQL natively), you must first install MyODBC on the Windows machine.

  • The user and Windows machine must have access privileges for the MySQL server on the Unix machine. This is set up with the GRANT command. See Section 13.5.1.3, “GRANT and REVOKE Syntax”.

  • You must create an ODBC DSN entry as follows:

    1. Open the Control Panel on the Windows machine.

    2. Double-click the ODBC Data Sources 32-bit icon.

    3. Click the tab User DSN.

    4. Click the Add button.

    5. Select MySQL in the screen Create New Data Source and click the Finish button.

    6. The MySQL Driver default configuration screen is shown. See Section 23.1.9.2, “Configuring a MyODBC DSN on Windows”.

  • Start your application and select the ODBC driver with the DSN that you specified in the ODBC administrator.

Notice that other configuration options are shown on the MySQL screen that you can try if you run into problems (options such as trace, don't prompt on connect, and so forth).

23.1.4. Installing MyODBC from a Binary Distribution on Windows

To install MyODBC on Windows, you should download the appropriate distribution file from http://dev.mysql.com/downloads/connector/odbc/, unpack it, and execute the MyODBC-VERSION.exe file.

On Windows, you may get the following error when trying to install the older MyODBC 2.50 driver:

An error occurred while copying C:\WINDOWS\SYSTEM\MFC30.DLL. Restart
Windows and try installing again (before running any applications
which use ODBC)

The problem is that some other program is using ODBC. Because of how Windows is designed, you may not be able in this case to install new ODBC drivers with Microsoft's ODBC setup program. In most cases, you can continue by pressing Ignore to copy the rest of the MyODBC files and the final installation should still work. If it doesn't, the solution is to re-boot your computer in “safe mode.” Choose safe mode by pressing F8 just before your machine starts Windows during re-booting, install MyODBC, and re-boot to normal mode.

23.1.5. Installing MyODBC from a Binary Distribution on Unix

23.1.5.1. Installing MyODBC from an RPM Distribution

To install or upgrade MyODBC from an RPM distribution on Linux, simply download the RPM distribution of the latest version of MyODBC and follow the instructions below. Use su root to become root, then install the RPM file.

If you are installing for the first time:

shell> su root
shell> rpm -ivh MyODBC-3.51.01.i386-1.rpm

If the driver exists, upgrade it like this:

shell> su root
shell> rpm -Uvh MyODBC-3.51.01.i386-1.rpm

If there is any dependency error for MySQL client library, libmysqlclient, simply ignore it by supplying the --nodeps option, and then make sure the MySQL client shared library is in the path or set through LD_LIBRARY_PATH.

This installs the driver libraries and related documents to /usr/local/lib and /usr/share/doc/MyODBC respectively. Proceed onto Section 23.1.9.3, “Configuring a MyODBC DSN on Unix”.

To uninstall the driver, become root and execute an rpm command:

shell> su root
shell> rpm -e MyODBC

23.1.5.2. Installing MyODBC from a Binary Tarball Distribution

To install the driver from a tarball distribution (.tar.gz file), download the latest version of the driver for your operating system and follow these steps:

shell> su root
shell> gunzip MyODBC-3.51.01-i686-pc-linux.tar.gz
shell> tar xvf MyODBC-3.51.01-i686-pc-linux.tar
shell> cd MyODBC-3.51.01-i686-pc-linux

Read the installation instructions in the INSTALL-BINARY file and execute these commands.

shell> cp libmyodbc* /usr/local/lib
shell> cp odbc.ini /usr/local/etc
shell> export ODBCINI=/usr/local/etc/odbc.ini

Then proceed on to Section 23.1.9.3, “Configuring a MyODBC DSN on Unix” to configure the DSN for MyODBC. For more information, refer to the INSTALL-BINARY file that comes with your distribution.

23.1.6. Installing MyODBC from a Source Distribution on Windows

23.1.6.1. Requirements

  • MDAC, Microsoft Data Access SDK from http://www.microsoft.com/data/.

  • MySQL client libraries and include files from MySQL 4.0.0 or higher. (Preferably MySQL 4.0.16 or higher). This is required because MyODBC uses new calls and structures that exist only starting from this version of the library. To get the client libraries and include files, visit http://dev.mysql.com/downloads/.

23.1.6.2. Building MyODBC 3.51

MyODBC 3.51 source distributions include Makefiles that uses nmake. In the distribution, you can find Makefile for building the release version and Makefile_debug for building debugging versions of the driver libraries and DLLs.

To build the driver, use this procedure:

  1. Download and extract the sources to a folder, then change location into that folder. The following command assumes the folder is named myodbc3-src:

    C:\> cd myodbc3-src
    
  2. Edit Makefile to specify the correct path for the MySQL client libraries and header files. Then use the following commands to build and install the release version:

    C:\> nmake -f Makefile
    C:\> nmake -f Makefile install
    

    nmake -f Makefile builds the release version of the driver and places the binaries in subdirectory called Release.

    nmake -f Makefile install installs (copies) the driver DLLs and libraries(myodbc3.dll, myodbc3.lib) to your system directory.

  3. To build the debug version, use Makefile_Debug rather than Makefile, as shown below:

    C:\> nmake -f Makefile_debug
    C:\> nmake -f Makefile_debug install
    
  4. You can clean and rebuild the driver by using:

    C:\> nmake -f Makefile clean
    C:\> nmake -f Makefile install
    

Note:

  • Make sure to specify the correct MySQL client libraries and header files path in the Makefiles (set the MYSQL_LIB_PATH and MYSQL_INCLUDE_PATH variables). The default header file path is assumed to be C:\mysql\include. The default library path is assumed to be C:\mysql\lib\opt for release DLLs and C:\mysql\lib\debug for debug versions.

  • For the complete usage of nmake, visit http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dv_vcce4/html/evgrfRunningNMAKE.asp.

  • If you are using the BitKeeper tree for compiling, All Windows-specific Makefiles are named as Win_Makefile*.

23.1.6.3. Testing

After the driver libraries are copied/installed to the system directory, you can test whether the libraries are properly built by using the samples provided in the samples subdirectory:

C:\> cd samples
C:\> nmake -f Makefile all

23.1.6.4. Building MyODBC 2.50

The MyODBC 2.50 source distribution includes VC workspace files. You can build the driver using these files (.dsp and .dsw) directly by loading them from Microsoft Visual Studio 6.0 or higher.

23.1.7. Installing MyODBC from a Source Distribution on Unix

23.1.7.1. Requirements

  • MySQL client libraries and include files from MySQL 4.0.0 or higher. (Preferably MySQL 4.0.16 or higher). This is required because MyODBC uses new calls and structures that exist only starting from this version of the library. To get the client libraries and include files, visit http://dev.mysql.com/downloads/.

  • The MySQL library must be configured with the --enable-thread-safe-client option. libmysqlclient installed as a shared library.

  • One of the following Unix ODBC driver managers must be installed:

  • If using a character set that isn't compiled into the MySQL client library (the defaults are: latin1 big5 czech euc_kr gb2312 gbk sjis tis620 ujis) then you need to install the mysql character definitions from the charsets directory into SHAREDIR (by default, /usr/local/mysql/share/mysql/charsets). These should be in place if you have installed the MySQL server on the same machine.

Once you have all the required files, unpack the source files to a separate directory and follow the instructions as given below:

23.1.7.2. Typical configure Options

The configure script gives you a great deal of control over how you configure your MyODBC build. Typically you do this using options on the configure command line. You can also affect configure using certain environment variables. For a list of options and environment variables supported by configure, run this command:

shell> ./configure --help

Some of the more commonly used configure options are described here:

  1. To compile MyODBC, you need to supply the MySQL client include and library files path using the --with-mysql-path=DIR option, where DIR is the directory where the MySQL is installed.

    MySQL compile options can be determined by running DIR/bin/mysql_config.

  2. Supply the standard header and library files path for your ODBC Driver Manager(iodbc or unixobc).

    • If you are using iodbc and iodbc is not installed in its default location (/usr/local), you might have to use the --with-iodbc=DIR option, where DIR is the directory where iodbc is installed.

      If the iodbc headers do not reside in DIR/include, you can use the --with-iodbc-includes=INCDIR option to specify their location.

      The applies to libraries. If they are not in DIR/lib, you can use the --with-iodbc-libs=LIBDIR option.

    • If you are using unixODBC, use the --with-unixODBC=DIR option (case sensitive) to make configure look for unixODBC instead of iodbc by default, DIR is the directory where unixODBC is installed.

      If the unixODBC headers and libraries aren't located in DIR/include and DIR/lib, use the --with-unixODBC-includes=INCDIR and --with-unixODBC-libs=LIBDIR options.

  3. You might want to specify an installation prefix other than /usr/local. For example, to install the MyODBC drivers in /usr/local/odbc/lib, use the --prefix=/usr/local/odbc option.

The final configuration command looks something like this:

shell> ./configure --prefix=/usr/local \
         --with-iodbc=/usr/local \
         --with-mysql-path=/usr/local/mysql

23.1.7.3. Thread-Safe Client

In order to link the driver with MySQL thread safe client libraries libmysqlclient_r.so or libmysqlclient_r.a, you must specify the following configure option:

--enable-thread-safe

and can be disabled(default) using

--disable-thread-safe

This option enables the building of driver thread-safe library libmyodbc3_r.so from by linking with mysql thread-safe client library libmysqlclient_r.so (The extensions are OS dependent).

In case while configuring with thread-safe option, and gotten into a configure error; then look at the config.log and see if it is due to the lack of thread-libraries in the system; and supply one with LIBS options i.e.

LIBS="-lpthread" ./configure ..

23.1.7.4. Shared or Static Options

You can enable or disable the shared and static versions using these options:

--enable-shared[=yes/no]
--disable-shared
--enable-static[=yes/no]
--disable-static

23.1.7.5. Enabling Debugging Information

By default, all the binary distributions are built as non-debugging versions (configured with --without-debug).

To enable debugging information, build the driver from source distribution and use the --with-debug) when you run configure.

23.1.7.6. Enabling the Documentation

This option is available only for BK clone trees; not for normal source distributions.

By default, the driver is built with (--without-docs); And in case if you want the documentation to be taken care in the normal build, then configure with:

--with-docs

23.1.7.7. Building and Compilation

To build the driver libraries, you have to just execute make, which takes care of everything.

shell> make

If any errors occur, correct them and continue the build process. If you aren't able to build, then send a detailed email to for further assistance.

23.1.7.8. Building Shared Libraries

On most platforms, MySQL doesn't build or support .so (shared) client libraries by default, because building with shared libraries has caused us problems in the past.

In cases like this, you have to download the MySQL distribution and configure it with these options:

--without-server --enable-shared

To build shared driver libraries, you must specify the --enable-shared option for configure. By default, configure does not enable this option.

If you have configured with the --disable-shared option, you can build the .so file from the static libraries using the following commands:

shell> cd MyODBC-3.51.01
shell> make
shell> cd driver
shell> CC=/usr/bin/gcc \
     $CC -bundle -flat_namespace -undefined error \
         -o .libs/libmyodbc3-3.51.01.so \
         catalog.o connect.o cursor.o dll.o error.o execute.o \
         handle.o info.o misc.o myodbc3.o options.o prepare.o \
         results.o transact.o utility.o \
         -L/usr/local/mysql/lib/mysql/ \
         -L/usr/local/iodbc/lib/ \
         -lz -lc -lmysqlclient -liodbcinst

Make sure to change -liodbcinst to -lodbcinst if you are using unixODBC instead of iODBC, and configure the library paths accordingly.

This builds and places the libmyodbc3-3.51.01.so file in the .libs directory. Copy this file to MyODBC library directory (/usr/local/lib (or the lib directory under the installation directory that you supplied with the --prefix).

shell> cd .libs
shell> cp libmyodbc3-3.51.01.so /usr/local/lib
shell> cd /usr/local/lib
shell> ln -s libmyodbc3-3.51.01.so libmyodbc3.so

To build the thread-safe driver library:

shell> CC=/usr/bin/gcc \
     $CC -bundle -flat_namespace -undefined error
      -o .libs/libmyodbc3_r-3.51.01.so
      catalog.o connect.o cursor.o dll.o error.o execute.o
      handle.o info.o misc.o myodbc3.o options.o prepare.o
      results.o transact.o utility.o
      -L/usr/local/mysql/lib/mysql/
      -L/usr/local/iodbc/lib/
      -lz -lc -lmysqlclient_r -liodbcinst

23.1.7.9. Installing Driver Libraries

To install the driver libraries, execute the following command:

shell> make install

That command installs one of the following sets of libraries:

For MyODBC 3.51:

  • libmyodbc3.so

  • libmyodbc3-3.51.01.so, where 3.51.01 is the version of the driver

  • libmyodbc3.a

For thread-safe MyODBC 3.51:

  • libmyodbc3_r.so

  • libmyodbc3-3_r.51.01.so

  • libmyodbc3_r.a

For MyODBC 2.5.0:

  • libmyodbc.so

  • libmyodbc-2.50.39.so, where 2.50.39 is the version of the driver

  • libmyodbc.a

For more information on build process, refer to the INSTALL file that comes with the source distribution. Note that if you are trying to use the make from Sun, you may end up with errors. On the other hand, GNU gmake should work fine on all platforms.

23.1.7.10. Testing MyODBC on Unix

To run the basic samples provided in the distribution with the libraries that you built, just execute:

shell> make test

Make sure the DSN 'myodbc3' is configured first in odbc.ini and environment variable ODBCINI is pointing to the right odbc.ini file; and MySQL server is running. You can find a sample odbc.ini with the driver distribution.

You can even modify the samples/run-samples script to pass the desired DSN, UID, and PASSWORD values as the command line arguments to each sample.

23.1.7.11. Mac OS X Notes

To build the driver on Mac OS X (Darwin), make use of the following configure example:

shell> ./configure --prefix=/usr/local
           --with-unixODBC=/usr/local
           --with-mysql-path=/usr/local/mysql
           --disable-shared
           --enable-gui=no
           --host=powerpc-apple

The command assumes that the unixODBC and MySQL are installed in the default locations. If not, configure accordingly.

On Mac OS X, --enable-shared builds .dylib files by default. You can build .so files like this:

shell> make
shell> cd driver
shell> CC=/usr/bin/gcc \
     $CC -bundle -flat_namespace -undefined error
         -o .libs/libmyodbc3-3.51.01.so *.o
         -L/usr/local/mysql/lib/
         -L/usr/local/iodbc/lib
         -liodbcinst -lmysqlclient -lz -lc

To build the thread-safe driver library:

shell> CC=/usr/bin/gcc \
     $CC -bundle -flat_namespace -undefined error
     -o .libs/libmyodbc3-3.51.01.so *.o
     -L/usr/local/mysql/lib/
     -L/usr/local/iodbc/lib
     -liodbcinst -lmysqlclienti_r -lz -lc -lpthread

Make sure to change the -liodbcinst to -lodbcinst in case of using unixODBC instead of iODBC and configure the libraries path accordingly.

In Apple's version of GCC, both cc and gcc are actually symbolic links to gcc3.

Copy this library to the $prefix/lib directory and symlink to libmyodbc3.so.

You can cross-check the output shared-library properties using this command:

shell> otool -LD .libs/libmyodbc3-3.51.01.so

23.1.7.12. HP-UX Notes

To build the driver on HP-UX 10.x or 11.x, make use of the following configure example:

If using cc:

shell> CC="cc" \
     CFLAGS="+z" \
     LDFLAGS="-Wl,+b:-Wl,+s" \
     ./configure --prefix=/usr/local
           --with-unixodbc=/usr/local
           --with-mysql-path=/usr/local/mysql/lib/mysql
           --enable-shared
           --enable-thread-safe

If using gcc:

shell> CC="gcc" \
     LDFLAGS="-Wl,+b:-Wl,+s" \
     ./configure --prefix=/usr/local
           --with-unixodbc=/usr/local
           --with-mysql-path=/usr/local/mysql
           --enable-shared
           --enable-thread-safe

Once the driver is built, cross-check its attributes using chatr .libs/libmyodbc3.sl to see whether or not you need to have the MySQL client libraries path using the SHLIB_PATH environment variable. For static versions, ignore all shared-library options and run configure with the --disable-shared option.

23.1.7.13. AIX Notes:

To build the driver on AIX, make use of the following configure example:

shell> ./configure --prefix=/usr/local
           --with-unixodbc=/usr/local
           --with-mysql-path=/usr/local/mysql
           --disable-shared
           --enable-thread-safe

NOTE: For more information about how to build and set up the static and shared libraries across the different platforms refer to ' Using static and shared libraries across platforms'.

23.1.8. Installing MyODBC from the BitKeeper Development Source Tree

Note: You should read this section only if you are interested in helping us test our new code.

To obtain our most recent development source tree, use these instructions:

  1. See Section 2.8.3, “Installing from the Development Source Tree” for instructions on how to download and install BitKeeper.

  2. After BitKeeper is installed, first go to the directory you want to work from, and then use this command if you want to clone the MyODBC 3.51 branch:

    shell> bk clone bk://mysql.bkbits.net/myodbc3 myodbc-3.51
    

    In the preceding example, the source tree is set up in the myodbc-3.51/ or by default myodbc3/ subdirectory of your current directory. If you are behind the firewall and can only initiate HTTP connections, you can also use BitKeeper via HTTP. If you are required to use a proxy server, simply set the environment variable http_proxy to point to your proxy:

    shell> export http_proxy="http://your.proxy.server:8080/"
    

    Replace the bk:// with http:// when doing a clone. Example:

    shell> bk clone http://mysql.bkbits.net/myodbc3 myodbc-3.51
    

    The initial download of the source tree may take a while, depending on the speed of your connection; be patient.

  3. You need GNU autoconf 2.52 (or newer), automake 1.4, libtool 1.4, and m4 to run the next set of commands.

    shell> cd myodbc-3.51
    shell> bk -r edit
    shell> aclocal; autoheader; autoconf;  automake;
    shell> ./configure  # Add your favorite options here
    shell> make
    

    For more information on how to build, refer to INSTALL file located in the same directory. On Windows, make use of Windows Makefiles WIN-Makefile and WIN-Makefile_debug in building the driver, for more information, see Section 23.1.6, “Installing MyODBC from a Source Distribution on Windows”.

  4. When the build is done, run make install to install the MyODBC 3.51 driver on your system.

  5. If you have gotten to the make stage and the distribution does not compile, please report it to .

  6. After the initial bk clone operation to get the source tree, you should run bk pull periodically to get the updates.

  7. You can examine the change history for the tree with all the diffs by using bk sccstool. If you see some funny diffs or code that you have a question about, do not hesitate to send e-mail to .

    Also, if you think you have a better idea on how to do something, send an e-mail to the same address with a patch. bk diffs produces a patch for you after you have made changes to the source. If you do not have the time to code your idea, just send a description.

  8. BitKeeper has a help utility that you can access via bk helptool.

You can also browse changesets, comments and source code online by browsing to http://mysql.bkbits.net:8080/myodbc3.

23.1.9. MyODBC Configuration

This section describes how to configure MyODBC, including DSN creation and the different arguments that the driver takes as an input arguments in the connection string. It also describes how to create an ODBC trace file.

23.1.9.1. What is a Data Source Name?

A "data source" is a place where data comes from. The data source must have a persistent identifier, the Data Source Name. Using the Data Source Name, MySQL can access initialization information. With the initialization information, MySQL knows where to access the database and what settings to use when the access starts.

In effect, the data source is the path to the data. In different contexts this might mean different things, but typically it identifies a running MySQL server (for example via a network address or service name), plus the default database for that server at connection time, plus necessary connection information such as the port. The MySQL drivers (and, on Windows systems, the ODBC Driver Manager) use the data source for connecting. An administrative utility called the Microsoft ODBC Data Source Administrator may be useful for this purpose.

There are two places where the initialization information might be: in the Windows registry (on a Windows system), or in a DSN file (on any system).

If the information is in the Windows registry, it is called a "Machine data source". It might be a "User data source", in which case only one user can see it. Or it might be a "System data source" in which case it is accessible to all users on the computer, or indeed to all users connected to the computer, if the users are connected by Microsoft Windows NT services. When you run the ODBC Data Administration program, you have a choice whether to use "User" or "System" -- there are separate tabs.

If the information is in a DSN file, it is called a "File data source". This is a text file. Its advantages are: (a) it is an option for any kind of computer, not just a computer with a Windows operating system; (b) its contents can be transmitted or copied relatively easily.

23.1.9.2. Configuring a MyODBC DSN on Windows

To add and configure a new MyODBC data source on Windows, use the ODBC Data Source Administrator. The ODBC Administrator updates your data source connection information. As you add data sources, the ODBC Administrator updates the registry information for you.

To open the ODBC Administrator from the Control Panel:

  1. Click Start, point to Settings, and then click Control Panel.

  2. On computers running Microsoft Windows 2000 or newer, double-click Administrative Tools, and then double-click Data Sources (ODBC). On computers running older versions of Windows, double-click 32-bit ODBC or ODBC.

    ODBC Data Sources
              Icon

    The ODBC Data Source Administrator dialog box appears, as shown here:

    ODBC Data Source
              Administrator Dialog

    Click Help for detailed information about each tab of the ODBC Data Source Administrator dialog box.

To add a data source on Windows:

  1. Open the ODBC Data Source Administrator.

  2. In the ODBC Data Source Administrator dialog box, click Add. The Create New Data Source dialog box appears.

  3. Select MySQL ODBC 3.51 Driver, and then click Finish. The MySQL ODBC 3.51 Driver - DSN Configuration dialog box appears, as shown here:

    MySQL ODBC DSN
              Configuration Dialog
  4. In the Data Source Name box, enter the name of the data source you want to access. It can be any valid name that you choose.

  5. In the Description box, enter the description needed for the DSN.

  6. For Host or Server Name (or IP) box, enter the name of the MySQL server host that you want to access. By default, it is localhost.

  7. In the Database Name box, enter the name of the MySQL database that you want to use as the default database.

  8. In the User box, enter your MySQL username (your database user ID).

  9. In the Password box, enter your password.

  10. In the Port box, enter the port number if it is not the default (3306).

  11. In the SQL Command box, you can enter an optional SQL statement that you want to issue automatically after the connection has been established.

    The final dialog looks like this:

    Filled-In MySQL ODBC DSN
              Configuration Dialog

    Click OK to add this data source.

Note: Upon clicking OK, the Data Sources dialog box appears, and the ODBC Administrator updates the registry information. The username and connect string that you entered become the default connection values for this data source when you connect to it.

You can also test whether your settings are suitable for connecting to the server using the button Test Data Source. This feature is available only for the MyODBC 3.51 driver. A successful test results in the following window:

MyODBC Successful Connection
          Message

A failed test results in an error:

MyODBC Failed Connection Message

The DSN configuration dialog also has an Options button. If you select it, the following options dialog appears displaying that control driver behavior. Refer to Section 23.1.9.4, “Connection Parameters” for information about the meaning of these options.

MyODBC Options Dialog

Note: The options listed under Driver Trace Options are disabled (grayed out) unless you are using the debugging version of the driver DLL.

To modify a data source on Windows:

  1. Open the ODBC Data Source Administrator. Click the appropriate DSN tab.

  2. Select the MySQL data source that you want to modify and then click Configure. The MySQL ODBC 3.51 Driver - DSN Configuration dialog box appears.

  3. Modify the applicable data source fields, and then click OK.

When you have finished modifying the information in this dialog box, the ODBC Administrator updates the registry information.

23.1.9.3. Configuring a MyODBC DSN on Unix

On Unix, you configure DSN entries directly in the odbc.ini file. Here is a typical odbc.ini file that configures myodbc and myodbc3 as the DSN names for MyODBC 2.50 and MyODBC 3.51, respectively:

;
;  odbc.ini configuration for MyODBC and MyODBC 3.51 drivers
;

[ODBC Data Sources]
myodbc      = MyODBC 2.50 Driver DSN
myodbc3     = MyODBC 3.51 Driver DSN

[myodbc]
Driver       = /usr/local/lib/libmyodbc.so
Description  = MyODBC 2.50 Driver DSN
SERVER       = localhost
PORT         =
USER         = root
Password     =
Database     = test
OPTION       = 3
SOCKET       =

[myodbc3]
Driver       = /usr/local/lib/libmyodbc3.so
Description  = MyODBC 3.51 Driver DSN
SERVER       = localhost
PORT         =
USER         = root
Password     =
Database     = test
OPTION       = 3
SOCKET       =

[Default]
Driver       = /usr/local/lib/libmyodbc3.so
Description  = MyODBC 3.51 Driver DSN
SERVER       = localhost
PORT         =
USER         = root
Password     =
Database     = test
OPTION       = 3
SOCKET       =

Refer to the Section 23.1.9.4, “Connection Parameters”, for the list of connection parameters that can be supplied.

Note: If you are using unixODBC, you can use the following tools in order to set up the DSN:

In some cases when using unixODBC, you might get this error:

Data source name not found and no default driver specified

If this happens, make sure the ODBCINI and ODBCSYSINI environment variables are pointing to the right odbc.ini file. For example, if your odbc.ini file is located in /usr/local/etc, set the environment variables like this:

export ODBCINI=/usr/local/etc/odbc.ini
export ODBCSYSINI=/usr/local/etc

23.1.9.4. Connection Parameters

You can specify the following parameters for MyODBC in the [Data Source Name] section of an ODBC.INI file or through the InConnectionString argument in the SQLDriverConnect() call.

ParameterDefault ValueComment
userODBC (on Windows)The username used to connect to MySQL.
serverlocalhostThe hostname of the MySQL server.
database The default database.
option0Options that specify how MyODBC should work. See below.
port3306The TCP/IP port to use if server is not localhost.
stmt A statement to execute when connecting to MySQL.
password The password for the user account on server.
socket The Unix socket file or Windows named pipe to connect to if server is localhost.

The option argument is used to tell MyODBC that the client isn't 100% ODBC compliant. On Windows, you normally select options by toggling the checkboxes in the connection screen, but you can also select them in the option argument. The following options are listed in the order in which they appear in the MyODBC connect screen:

ValueDescription
1The client can't handle that MyODBC returns the real width of a column.
2The client can't handle that MySQL returns the true value of affected rows. If this flag is set, MySQL returns “found rows” instead. You must have MySQL 3.21.14 or newer to get this to work.
4Make a debug log in c:\myodbc.log. This is the same as putting MYSQL_DEBUG=d:t:O,c::\myodbc.log in AUTOEXEC.BAT. (On Unix, the file is /tmp/myodbc.log.)
8Don't set any packet limit for results and parameters.
16Don't prompt for questions even if driver would like to prompt.
32Enable or disable the dynamic cursor support. (Not allowed in MyODBC 2.50.)
64Ignore use of database name in db_name.tbl_name.col_name.
128Force use of ODBC manager cursors (experimental).
256Disable the use of extended fetch (experimental).
512Pad CHAR columns to full column length.
1024SQLDescribeCol() returns fully qualified column names.
2048Use the compressed client/server protocol.
4096Tell server to ignore space after function name and before ‘(’ (needed by PowerBuilder). This makes all function names keywords.
8192Connect with named pipes to a mysqld server running on NT.
16384Change LONGLONG columns to INT columns (some applications can't handle LONGLONG).
32768Return 'user' as Table_qualifier and Table_owner from SQLTables (experimental).
65536Read parameters from the [client] and [odbc] groups from my.cnf.
131072Add some extra safety checks (should not be needed but...).
262144Disable transactions.
524288Enable query logging to c:\myodbc.sql(/tmp/myodbc.sql) file. (Enabled only in debug mode.)
1048576Do not cache the results locally in the driver, instead read from server (mysql_use_result()). This works only for forward-only cursors. This option is very important in dealing with large tables when you don't want the driver to cache the entire result set.
2097152Force the use of Forward-only cursor type. In case of applications setting the default static/dynamic cursor type, and one wants the driver to use non-cache result sets, then this option ensures the forward-only cursor behavior.

To select multiple options, add together their values. For example, setting option to 12 (4+8) gives you debugging without packet limits.

The default myodbc3.dll is compiled for optimal performance. If you want to debug MyODBC 3.51 (for example, to enable tracing), you should instead use myodbc3d.dll. To install this file, copy myodbc3d.dll over the installed myodbc3.dll file. Make sure to revert back to the release version of the driver DLL once you are done with the debugging because the debug version may cause performance issues. Note that the myodbc3d.dll isn't included in MyODBC 3.51.07 through 3.51.11. If you are using one of these versions, you should copy that DLL from a previous version (for example, 3.51.06).

For MyODBC 2.50, myodbc.dll and myodbcd.dll are used instead.

The following table shows some recommended option values for various configurations:

ConfigurationOption Value
Microsoft Access3
Microsoft Visual Basic3
Large tables with too many rows2049
Driver trace generation (Debug mode)4
Query log generation (Debug mode)524288
Generate driver trace as well as query log (Debug mode)524292
Large tables with no-cache results3145731

23.1.9.5. Connecting Without a Predefined DSN

Yes. You can connect to the MySQL server using SQLDriverConnect, by specifying the DRIVER name field. Here are the connection strings for MyODBC using DSN-Less connection:

For MyODBC 2.50:

ConnectionString = "DRIVER={MySQL};\
                  SERVER=localhost;\
                  DATABASE=test;\
                  USER=venu;\
                  PASSWORD=venu;\
                  OPTION=3;"

For MyODBC 3.51:

ConnectionString = "DRIVER={MySQL ODBC 3.51 Driver};\
                  SERVER=localhost;\
                  DATABASE=test;\
                  USER=venu;\
                  PASSWORD=venu;\
                  OPTION=3;"

If your programming language converts backslash followed by whitespace to a space, it is preferable to specify the connection string as a single long string, or to use a concatenation of multiple strings that does not add spaces in between. For example:

ConnectionString = "DRIVER={MySQL ODBC 3.51 Driver};"
                  "SERVER=localhost;"
                  "DATABASE=test;"
                  "USER=venu;"
                  "PASSWORD=venu;"
                  "OPTION=3;"

Refer to the Section 23.1.9.4, “Connection Parameters”, for the list of connection parameters that can be supplied.

23.1.9.6. Establishing a Remote Connection to System A from System B

If you want to connect to system A from system B with a username and password of myuser and mypassword, here is a simple procedure.

On system A, follow these steps:

  1. Start the MySQL server.

  2. Use GRANT to set up an account with a username of myuser that can connect from system B using a password of myuser:

    GRANT ALL ON *.* to 'myuser'@'B' IDENTIFIED BY 'mypassword';
    
  3. The GRANT statement grants all privileges to user myuser for connecting from system B using the password mypassword. To execute this statement, you should be either root on system A (or another user who has appropriate privileges). For more information about MySQL privileges, refer to Section 5.8, “MySQL User Account Management”.

On system B, follow these steps:

  1. Configure a MyODBC DSN using the following connection parameters:

    DSN            = remote_test
    SERVER or HOST = A (or IP address of system A)
    DATABASE       = test (The default database or an appropriate one)
    USER           = myuser
    PASSWORD       = mypassword
    

    To set up a DSN-less connection, refer to Section 23.1.9.5, “Connecting Without a Predefined DSN”.

  2. Check whether you are able to access system A from system B by using ping or other means. If you are not able to reach system A, check your network or Internet connections or contact your system administrator.

  3. Try to connect using DSN=remote_test. If it fails, trace the MyODBC log, and take the further steps based on the error message from the log. If you need further assistance, send a detailed mail message to .

You can also find a simple HOWTO at http://www.phphelp.com/tutorial/using-myodbc-to-connect-to-a-remote-database.html.

23.1.9.7. Getting an ODBC Trace File

If you encounter difficulties or problems with MyODBC, you should start by making a log file from the ODBC Manager (the log you get when requesting logs from ODBC ADMIN) and MyODBC.

To get an ODBC trace through Driver Manager, do the following:

  • Open ODBC Data source administrator:

    1. Click Start, point to Settings, and then click Control Panel.

    2. On computers running Microsoft Windows 2000, XP, or 2003, double-click Administrative Tools, and then double-click Data Sources (ODBC), as shown below.

      ODBC Data Sources
                  Icon

      On computers running an earlier version of Microsoft Windows, double-click 32-bit ODBC or ODBC in the Control Panel.

    3. The ODBC Data Source Administrator dialog box appears, as shown below:

      ODBC Data Source
                  Administrator Dialog
    4. Click Help for detailed information about each tab of the ODBC Data Source Administrator dialog box.

  • Enable the trace option. The procedure for this differs for Windows and Unix.

    To enable the trace option on Windows:

    1. The Tracing tab of the ODBC Data Source Administrator dialog box enables you to configure the way ODBC function calls are traced.

    2. When you activate tracing from the Tracing tab, the Driver Manager logs all ODBC function calls for all subsequently run applications.

    3. ODBC function calls from applications running before tracing is activated are not logged. ODBC function calls are recorded in a log file you specify.

    4. Tracing ceases only after you click Stop Tracing Now. Remember that while tracing is on, the log file continues to increase in size and that tracing affects the performance of all your ODBC applications.

      ODBC Tracing
                  Tab

    To enable the trace option on Unix:

    1. On Unix, you need to explicitly set the Trace option in the ODBC.INI file.

      Set the tracing ON or OFF by using TraceFile and Trace parameters in odbc.ini as shown below:

      TraceFile  = /tmp/odbc.trace
      Trace      = 1
      

      TraceFile specifies the name and full path of the trace file and Trace is set to ON or OFF. You can also use 1 or YES for ON and 0 or NO for OFF. If you are using ODBCConfig from unixODBC, then follow the instructions for tracing unixODBC calls at HOWTO-ODBCConfig.

    To generate a MyODBC log, do the following:

    1. Ensure that you are using the driver debug DLL (that is, myodbc3d.dll and not myodbc3.dll for MyODBC 3.51, and myodbcd.dll for MyODBC 2.50).

      The easiest way to do this is to get myodbc3d.dll (or myodbcd.dll) from the MyODBC 3.51 distribution and copy it over the myodbc3.dll (or myodbc.dll), which is probably in your C:\windows\system32 or C:\winnt\system32 directory. Note that you probably want to restore the old myodbc.dll file when you have finished testing, as this is a lot faster than myodbc3d.dll (or myodbcd.dll), so do keep a backup copy of original DLLs.

    2. Enable the Trace MyODBC option flag in the MyODBC connect/configure screen. The log is written to file C:\myodbc.log. If the trace option is not remembered when you are going back to the above screen, it means that you are not using the myodbcd.dll driver (see above). On Linux or if you are using DSN-Less connection, then you need to supply OPTION=4 in the connection string.

    3. Start your application and try to get it to fail. Then check the MyODBC trace file to find out what could be wrong.

      If you find out something is wrong, please send a mail message to (or to if you have a support contract from MySQL AB) with a brief description of the problem, with the following additional information:

      • MyODBC version

      • ODBC Driver Manager type and version

      • MySQL server version

      • ODBC trace from Driver Manager

      • MyODBC log file from MyODBC driver

      • Simple reproducible sample

    Remember that the more information you can supply to us, the more likely it is that we can fix the problem!

    Also, before posting the bug, check the MyODBC mailing list archive at http://lists.mysql.com/.

23.1.9.8. Applications Tested with MyODBC

MyODBC has been tested with the following applications:

If you know of any other applications that work with MyODBC, please send mail to about them.

23.1.9.9. Programs Known to Work With MyODBC

Most programs should work with MyODBC, but for each of those listed here, we have tested it ourselves or received confirmation from some user that it works. Many of the descriptions provide workarounds for problems that you might encounter.

  • Program

    Comment

  • Access

    To make Access work:

    • If you are using Access 2000, you should get and install the newest (version 2.6 or higher) Microsoft MDAC (Microsoft Data Access Components) from http://www.microsoft.com/data/. This fixes a bug in Access that when you export data to MySQL, the table and column names aren't specified. Another way to work around this bug is to upgrade to MyODBC 2.50.33 and MySQL 3.23.x, which together provide a workaround for the problem.

      You should also get and apply the Microsoft Jet 4.0 Service Pack 5 (SP5) which can be found at http://support.microsoft.com/default.aspx?scid=kb;EN-US;q239114. This fixes some cases where columns are marked as #DELETED# in Access.

      Note: If you are using MySQL 3.22, you must to apply the MDAC patch and use MyODBC 2.50.32 or 2.50.34 and up to work around this problem.

    • For all versions of Access, you should enable the MyODBC Return matching rows option. For Access 2.0, you should additionally enable the Simulate ODBC 1.0 option.

    • You should have a timestamp in all tables that you want to be able to update. For maximum portability, don't use a length specification in the column declaration. That is, use TIMESTAMP, not TIMESTAMP(n), n < 14.

    • You should have a primary key in the table. If not, new or updated rows may show up as #DELETED#.

    • Use only DOUBLE float fields. Access fails when comparing with single floats. The symptom usually is that new or updated rows may show up as #DELETED# or that you can't find or update rows.

    • If you are using MyODBC to link to a table that has a BIGINT column, the results are displayed as #DELETED. The work around solution is:

      • Have one more dummy column with TIMESTAMP as the data type.

      • Select the Change BIGINT columns to INT option in the connection dialog in ODBC DSN Administrator.

      • Delete the table link from Access and re-create it.

      Old records still display as #DELETED#, but newly added/updated records are displayed properly.

    • If you still get the error Another user has changed your data after adding a TIMESTAMP column, the following trick may help you:

      Don't use a table data sheet view. Instead, create a form with the fields you want, and use that form data sheet view. You should set the DefaultValue property for the TIMESTAMP column to NOW(). It may be a good idea to hide the TIMESTAMP column from view so your users are not confused.

    • In some cases, Access may generate illegal SQL statements that MySQL can't understand. You can fix this by selecting "Query|SQLSpecific|Pass-Through" from the Access menu.

    • On NT, Access reports BLOB columns as OLE OBJECTS. If you want to have MEMO columns instead, you should change BLOB columns to TEXT with ALTER TABLE.

    • Access can't always handle DATE columns properly. If you have a problem with these, change the columns to DATETIME.

    • If you have in Access a column defined as BYTE, Access tries to export this as TINYINT instead of TINYINT UNSIGNED. This gives you problems if you have values larger than 127 in the column.

  • ADO

    When you are coding with the ADO API and MyODBC, you need to pay attention to some default properties that aren't supported by the MySQL server. For example, using the CursorLocation Property as adUseServer returns a result of -1 for the RecordCount Property. To have the right value, you need to set this property to adUseClient, as shown in the VB code here:

    Dim myconn As New ADODB.Connection
    Dim myrs As New Recordset
    Dim mySQL As String
    Dim myrows As Long
    
    myconn.Open "DSN=MyODBCsample"
    mySQL = "SELECT * from user"
    myrs.Source = mySQL
    Set myrs.ActiveConnection = myconn
    myrs.CursorLocation = adUseClient
    myrs.Open
    myrows = myrs.RecordCount
    
    myrs.Close
    myconn.Close
    

    Another workaround is to use a SELECT COUNT(*) statement for a similar query to get the correct row count.

  • Active server pages (ASP)

    You should select the Return matching rows option.

  • BDE applications

    To get these to work, you should select the Don't optimize column widths and Return matching rows options.

  • Borland Builder 4

    When you start a query, you can use the Active property or the Open method. Note that Active starts by automatically issuing a SELECT * FROM ... query. That may not be a good thing if your tables are large.

  • ColdFusion (On Unix)

    The following information is taken from the ColdFusion documentation:

    Use the following information to configure ColdFusion Server for Linux to use the unixODBC driver with MyODBC for MySQL data sources. Allaire has verified that MyODBC 2.50.26 works with MySQL 3.22.27 and ColdFusion for Linux. (Any newer version should also work.) You can download MyODBC at http://dev.mysql.com/downloads/connector/odbc/.

    ColdFusion Version 4.5.1 allows you to us the ColdFusion Administrator to add the MySQL data source. However, the driver is not included with ColdFusion Version 4.5.1. Before the MySQL driver appears in the ODBC datasources drop-down list, you must build and copy the MyODBC driver to /opt/coldfusion/lib/libmyodbc.so.

    The Contrib directory contains the program mydsn-xxx.zip which allows you to build and remove the DSN registry file for the MyODBC driver on Coldfusion applications.

  • DataJunction

    You have to change it to output VARCHAR rather than ENUM, as it exports the latter in a manner that causes MySQL problems.

  • Excel

    Works. A few tips:

    • If you have problems with dates, try to select them as strings using the CONCAT() function. For example:

      SELECT CONCAT(rise_time), CONCAT(set_time)
        FROM sunrise_sunset;
      

      Values retrieved as strings this way should be correctly recognized as time values by Excel97.

      The purpose of CONCAT() in this example is to fool ODBC into thinking the column is of “string type.” Without the CONCAT(), ODBC knows the column is of time type, and Excel does not understand that.

      Note that this is a bug in Excel, because it automatically converts a string to a time. This would be great if the source was a text file, but is unfortunate when the source is an ODBC connection that reports exact types for each column.

  • Word

    To retrieve data from MySQL to Word/Excel documents, you need to use the MyODBC driver and the Add-in Microsoft Query help.

    For example, create a database with a table containing two columns of text:

    • Insert rows using the mysql client command-line tool.

    • Create a DSN file using the ODBC manager, for example, my for the database that was just created.

    • Open the Word application.

    • Create a blank new document.

    • In the Database tool bar, press the Insert Database button.

    • Press the Get Data button.

    • At the right hand of the Get Data screen, press the Ms Query button.

    • In Ms Query, create a new data source using the my DSN file.

    • Select the new query.

    • Select the columns that you want.

    • Make a filter if you want.

    • Make a Sort if you want.

    • Select Return Data to Microsoft Word.

    • Click Finish.

    • Click Insert Data and select the records.

    • Click OK and you see the rows in your Word document.

  • odbcadmin

    Test program for ODBC.

  • Delphi

    You must use BDE Version 3.2 or newer. Select the Don't optimize column width option when connecting to MySQL.

    Also, here is some potentially useful Delphi code that sets up both an ODBC entry and a BDE entry for MyODBC. The BDE entry requires a BDE Alias Editor that is free at a Delphi Super Page near you. (Thanks to Bryan Brunton for this):

    fReg:= TRegistry.Create;
    fReg.OpenKey('\Software\ODBC\ODBC.INI\DocumentsFab', True);
    fReg.WriteString('Database', 'Documents');
    fReg.WriteString('Description', ' ');
    fReg.WriteString('Driver', 'C:\WINNT\System32\myodbc.dll');
    fReg.WriteString('Flag', '1');
    fReg.WriteString('Password', '');
    fReg.WriteString('Port', ' ');
    fReg.WriteString('Server', 'xmark');
    fReg.WriteString('User', 'winuser');
    fReg.OpenKey('\Software\ODBC\ODBC.INI\ODBC Data Sources', True);
    fReg.WriteString('DocumentsFab', 'MySQL');
    fReg.CloseKey;
    fReg.Free;
    
    Memo1.Lines.Add('DATABASE NAME=');
    Memo1.Lines.Add('USER NAME=');
    Memo1.Lines.Add('ODBC DSN=DocumentsFab');
    Memo1.Lines.Add('OPEN MODE=READ/WRITE');
    Memo1.Lines.Add('BATCH COUNT=200');
    Memo1.Lines.Add('LANGDRIVER=');
    Memo1.Lines.Add('MAX ROWS=-1');
    Memo1.Lines.Add('SCHEMA CACHE DIR=');
    Memo1.Lines.Add('SCHEMA CACHE SIZE=8');
    Memo1.Lines.Add('SCHEMA CACHE TIME=-1');
    Memo1.Lines.Add('SQLPASSTHRU MODE=SHARED AUTOCOMMIT');
    Memo1.Lines.Add('SQLQRYMODE=');
    Memo1.Lines.Add('ENABLE SCHEMA CACHE=FALSE');
    Memo1.Lines.Add('ENABLE BCD=FALSE');
    Memo1.Lines.Add('ROWSET SIZE=20');
    Memo1.Lines.Add('BLOBS TO CACHE=64');
    Memo1.Lines.Add('BLOB SIZE=32');
    
    AliasEditor.Add('DocumentsFab','MySQL',Memo1.Lines);
    
  • C++ Builder

    Tested with BDE Version 3.0. The only known problem is that when the table schema changes, query fields are not updated. BDE, however, does not seem to recognize primary keys, only the index named PRIMARY, though this has not been a problem.

  • Vision

    You should select the Return matching rows option.

  • Visual Basic

    To be able to update a table, you must define a primary key for the table.

    Visual Basic with ADO can't handle big integers. This means that some queries like SHOW PROCESSLIST do not work properly. The fix is to use OPTION=16384 in the ODBC connect string or to select the Change BIGINT columns to INT option in the MyODBC connect screen. You may also want to select the Return matching rows option.

  • VisualInterDev

    If you have a BIGINT in your result, you may get the error [Microsoft][ODBC Driver Manager] Driver does not support this parameter Try selecting the Change BIGINT columns to INT option in the MyODBC connect screen.

  • Visual Objects

    You should select the Don't optimize column widths option.

  • MS Visio Enterprise 2000

    We made database model diagram by connecting from MS Vision Enterprise 2000 to MySQL via MyODBC (2.50.37 or greater) and using Visio's reverse engineer function to retrieve information about the DB (Visio shows all the column definitions, primary keys, Indexes and so on). Also we tested by designing new tables in Visio and exported them to MySQL via MyODBC.

23.1.10. MyODBC Connection-Related Issues

This section answers MyODBC connection-related questions.

23.1.10.1. While Configuring a MyODBC DSN, a Could Not Load Translator or Setup Library Error Occurs

For more information, refer to MS KnowledgeBase Article(Q260558). Also, make sure you have the latest valid ctl3d32.dll in your system directory.

23.1.10.2. While Connecting, an Access denied Error Occurs

Refer to Section 5.7.8, “Causes of Access denied Errors”.

23.1.10.3. INFO: About ODBC Connection Pooling

Refer to this document about connection pooling: http://support.microsoft.com/default.aspx?scid=kb;EN-US;q169470.

23.1.11. MyODBC and Microsoft Access

This section of the document answers questions related to MyODBC with Microsoft Access.

23.1.11.1. How to Set Up Microsoft Access to Work with MySQL using MyODBC?

The following must be done on your client PC in order to make Microsoft Access work with MyODBC.

  1. If you are using Access 2000, you should get and install the newest (version 2.6 or higher) Microsoft MDAC (Microsoft Data Access Components) from http://www.microsoft.com/data/. This fixes a bug in Access that when you export data to MySQL, the table and column names aren't specified. Another way to work around this bug is to upgrade to MyODBC 2.50.33 and MySQL 3.23.x, which together provide a workaround for the problem.

    You should also get and apply the Microsoft Jet 4.0 Service Pack 5 (SP5) which can be found at http://support.microsoft.com/default.aspx?scid=kb;EN-US;q239114. This fixes some cases where columns are marked as #DELETED# in Access.

    Note: If you are using MySQL 3.22, you must to apply the MDAC patch and use MyODBC 2.50.32 or 2.50.34 and up to work around this problem.

  2. Install the latest version of MySQL from http://dev.mysql.com/downloads/.

  3. Install the latest version of MyODBC 3.51 or 2.50 from http://dev.mysql.com/downloads/connector/odbc/.

  4. For all Access versions, you should enable the Return matching rows option.

  5. Start working with Access as the front-end for MySQL Server through MyODBC.

23.1.11.2. How to Export a Table or Query from Access to MySQL?

You cannot export a table or query to MySQL unless you have installed MyODBC.

To export a table from Access to MySQL, follow these instructions:

  1. When you open an Access database or an Access project, a Database window appears. It displays shortcuts for creating new database objects and opening existing objects.

    Access Database
  2. Click the name of the table or query you want to export, and then in the File menu, select Export.

  3. In the Export Object Type Object name To dialog box, in the Save As Type box, select ODBC Databases () as shown here:

    Selecting an ODBC Database
  4. In the Export dialog box, enter a name for the file (or use the suggested name), and then select OK.

  5. The Select Data Source dialog box is displayed; it lists the defined data sources for any ODBC drivers installed on your computer. Click either the File Data Source or Machine Data Source tab, and then double-click the MyODBC or MyODBC 3.51 data source that you want to export to. To define a new data source for MyODBC, please Section 23.1.9.2, “Configuring a MyODBC DSN on Windows”.

Microsoft Access connects to the MySQL Server through this data source and exports new tables and or data.

23.1.11.3. How to Import or Link MySQL Database Tables to Access?

You cannot export a table or query to MySQL database unless you have installed the MyODBC.

To import or link a table(s) from MySQL to Access, follow the instructions:

  1. Open a database, or switch to the Database window for the open database.

  2. To import tables, on the File menu, point to Get External Data, and then click Import. To link tables, on the File menu, point to Get External Data, and then click Link Tables.

  3. In the Import (or Link) dialog box, in the Files Of Type box, select ODBC Databases (). The Select Data Source dialog box lists the defined data sources The Select Data Source dialog box is displayed; it lists the defined data sources for any ODBC drivers installed on your computer. Click either the File Data Source or Machine Data Source tab, and then double-click the MyODBC or MyODBC 3.51 data source that you want to export to. To define a new data source for the MyODBC or MyODBC 3.51 driver, please Section 23.1.9.2, “Configuring a MyODBC DSN on Windows”.

  4. If the ODBC data source that you selected requires you to log on, enter your login ID and password (additional information might also be required), and then click OK.

  5. Microsoft Access connects to the MySQL server through ODBC data source and displays the list of tables that you can import or link.

  6. Click each table that you want to import or link, and then click OK. If you're linking a table and it doesn't have an index that uniquely identifies each record, then Microsoft Access displays a list of the fields in the linked table. Click a field or a combination of fields that uniquely identifies each record, and then click OK.

23.1.11.4. The Structure or Location of a Linked Table has been Changed. Can I See Those Changes Locally in Linked Tables?

Yes. Use the following procedure to view or to refresh links when the structure or location of a linked table has changed. The Linked Table Manager lists the paths to all currently linked tables.

To view or refresh links:

  1. Open the database that contains links to tables.

  2. On the Tools menu, point to Add-ins (Database Utilities in Access 2000 or newer), and then click Linked Table Manager.

  3. Select the check box for the tables whose links you want to refresh.

  4. Click OK to refresh the links.

Microsoft Access confirms a successful refresh or, if the table wasn't found, displays the Select New Location of <table name> dialog box in which you can specify its the table's new location.If several selected tables have moved to the new location that you specify, the Linked Table Manager searches that location for all selected tables, and updates all links in one step.

To change the path for a set of linked tables:

  1. Open the database that contains links to tables.

  2. On the Tools menu, point to Add-ins (Database Utilities in Access 2000 or newer), and then click Linked Table Manager.

  3. Select the Always Prompt For A New Location check box.

  4. Select the check box for the tables whose links you want to change, and then click OK.

  5. In the Select New Location of <table name> dialog box, specify the new location, click Open, and then click OK.

23.1.11.5. When I Insert or Update a Record in Linked Tables, I Get #DELETED#

If the inserted or updated records are shown as #DELETED# in the access, then:

  • If you are using Access 2000, you should get and install the newest (version 2.6 or higher) Microsoft MDAC (Microsoft Data Access Components) from http://www.microsoft.com/data/. This fixes a bug in Access that when you export data to MySQL, the table and column names aren't specified. Another way to work around this bug is to upgrade to MyODBC 2.50.33 and MySQL 3.23.x, which together provide a workaround for the problem.

    You should also get and apply the Microsoft Jet 4.0 Service Pack 5 (SP5) which can be found at http://support.microsoft.com/default.aspx?scid=kb;EN-US;q239114. This fixes some cases where columns are marked as #DELETED# in Access.

    Note: If you are using MySQL 3.22, you must to apply the MDAC patch and use MyODBC 2.50.32 or 2.50.34 and up to work around this problem.

  • For all versions of Access, you should enable the MyODBC Return matching rows option. For Access 2.0, you should additionally enable the Simulate ODBC 1.0 option.

  • You should have a timestamp in all tables that you want to be able to update. For maximum portability, don't use a length specification in the column declaration. That is, use TIMESTAMP, not TIMESTAMP(n), n < 14.

  • You should have a primary key in the table. If not, new or updated rows may show up as #DELETED#.

  • Use only DOUBLE float fields. Access fails when comparing with single floats. The symptom usually is that new or updated rows may show up as #DELETED# or that you can't find or update rows.

  • If you are using MyODBC to link to a table that has a BIGINT column, the results are displayed as #DELETED. The work around solution is:

    • Have one more dummy column with TIMESTAMP as the data type.

    • Select the Change BIGINT columns to INT option in the connection dialog in ODBC DSN Administrator.

    • Delete the table link from Access and re-create it.

    Old records still display as #DELETED#, but newly added/updated records are displayed properly.

23.1.11.6. How Do I Handle Write Conflicts or Row Location Errors?

If you see the following errors, select the Return Matching Rows option in the DSN configuration dialog, or specify OPTION=2, as the connection parameter:

Write Conflict. Another user has changed your data.

Row cannot be located for updating. Some values may have been changed
since it was last read.

23.1.11.7. Whenever I Export a Table from Access 97, a Strange Syntax Error Occurs

This is a strange issue from Access 97, and doesn't appear with Access 2000 or 2002. You can overcome this by upgrading the MyODBC driver to at least MyODBC 3.51.02.

23.1.11.8. Access Returns Another user has modified the record that you have modified While Editing Records

With some programs, this error may occur: Another user has modified the record that you have modified. In most cases, this can be solved by doing one of the following things:

  • Add a primary key for the table if one doesn't exist.

  • Add a timestamp column if one doesn't exist.

  • Only use double float fields. Some programs may fail when they compare single floats.

If these strategies don't help, you should start by making a log file from the ODBC manager (the log you get when requesting logs from ODBCADMIN) and a MyODBC log to help you figure out why things go wrong. For instructions, see Section 23.1.9.7, “Getting an ODBC Trace File”.

23.1.11.9. How to Trap ODBC Login Error Messages in Access?

Read “How to Trap ODBC Login Error Messages in Access” at http://support.microsoft.com/support/kb/articles/Q124/9/01.asp?LN=EN-US&SD=gn&FR=0%3CP%3E.

23.1.11.11. I Have Very Long Tables. What is the Best Configuration for MyODBC to Access These Tables?

If you have very large (long) tables in Access, it might take a very long time to open them. Or you might run low on virtual memory and eventually get an ODBC Query Failed error and the table cannot open. To deal with this, select the following options:

  • Return Matching Rows (2)

  • Allow BIG Results (8).

These add up to a value of 10 (OPTION=10).

23.1.11.12. How to Set the QueryTimeout Value for ODBC Connections?

Read “Set the QueryTimeout Value for ODBC Connections” at http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B153756.

23.1.11.13. INFO: Tools to Export/Import from/to Access to/from MySQL

Refer to converters section for list of available tools.

23.1.12. MyODBC and Microsoft VBA and ASP

This section answers questions related to using MyODBC with Microsoft Visual Basic(ADO, DAO & RDO) and ASP.

23.1.12.1. Why Does SELECT COUNT(*) FROM tbl_name Return an Error?

It's because the COUNT(*) expression is returning a BIGINT, and ADO can't make sense of a number this big. Select the Change BIGINT columns to INT option (option value 16384).

23.1.12.2. Whenever I Use the AppendChunk() or GetChunk() ADO Methods, I Get an Error Multiple-step operation generated errors. Check each status value.

The GetChunk() and AppendChunk() methods from ADO doesn't work as expected when the cursor location is specified as adUseServer. On the other hand, you can overcome this error by using adUseClient.

A simple example can be found from, http://www.dwam.net/iishelp/ado/docs/adomth02_4.htm

23.1.12.3. How to Find the Total Number of Rows Affected by a Particular SQL Statement in ADO?

You can make use of RecordsAffected property in the ADO execute method. For more information on the usage of execute method, refer to http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ado270/htm/mdmthcnnexecute.asp.

23.1.12.4. How Do I Handle Blob Data in Visual Basic?

Here is an excellent article from Mike Hillyer (); explaining how to insert and/or fetch data from blob columns through MyODBC from ADO: MySQL BLOB columns and Visual Basic 6.

23.1.12.5. How Do I Map Visual Basic Data Types to MySQL Types?

Here is yet another good article from Mike Hillyer (): How to map Visual basic data type to MySQL types.

23.1.12.6. SAMPLES: VB with ADO, DAO and RDO

A simple examples for the usage of ADO, DAO and RDO with VB can be found her:

If you find any other good example or HOW-TO on ADO/DAO/RDO, then please send the details to

23.1.12.7. ASP and MySQL with MyODBC

For more information about how to access MySQL via ASP using MyODBC, refer to the following articles:

A Frequently Asked Questions list for ASP can be found at http://support.microsoft.com/default.aspx?scid=/Support/ActiveServer/faq/data/adofaq.asp.

23.1.12.8. INFO: Frequently Asked Questions on ActiveX Data Objects (ADO)

For information, see ActiveX Data Objects(ADO) Frequently Asked Questions.

23.1.13. MyODBC and Third-Party ODBC Tools

This section answers questions related to MyODBC with various ODBC-related tools; such as Microsoft Word, Excel and ColdFusion.

23.1.13.1. How to Retrieve Data from MySQL into MS-Word/Excel Documents?

To retrieve data from MySQL to Word/Excel documents, you need to use the MyODBC driver and the Add-in Microsoft Query help.

For example, create a database with a table containing two columns of text:

  • Insert rows using the mysql client command-line tool.

  • Create a DSN file using the ODBC manager, for example, my for the database that was just created.

  • Open the Word application.

  • Create a blank new document.

  • In the Database tool bar, press the Insert Database button.

  • Press the Get Data button.

  • At the right hand of the Get Data screen, press the Ms Query button.

  • In Ms Query, create a new data source using the my DSN file.

  • Select the new query.

  • Select the columns that you want.

  • Make a filter if you want.

  • Make a Sort if you want.

  • Select Return Data to Microsoft Word.

  • Click Finish.

  • Click Insert Data and select the records.

  • Click OK and you see the rows in your Word document.

23.1.13.2. Exporting Tables from MS DTS to MySQL Using MyODBC Results in a Syntax Error

This is an issue similar to that of Access 97 when your table consists of TEXT or VARCHAR data types. You can fix this error by upgrading your MyODBC driver to version 3.51.02 or higher.

23.1.13.3. HOWTO: Configure MySQL+MyODBC+unixODBC+ColdFusion on Solaris

Refer to MySQL ColdFusion unixODBC MyODBC and Solaris - how to succeed

23.1.14. MyODBC General Functionality

This section of the document answers questions related to MyODBC general functionality.

23.1.14.1. How to Get the Value of an AUTO_INCREMENT Column in ODBC

A common problem is how to get the value of an automatically generated ID from an INSERT statement. With ODBC, you can do something like this (assuming that auto is an AUTO_INCREMENT field):

INSERT INTO tbl (auto,text) VALUES(NULL,'text');
SELECT LAST_INSERT_ID();

Or, if you are just going to insert the ID into another table, you can do this:

INSERT INTO tbl (auto,text) VALUES(NULL,'text');
INSERT INTO tbl2 (id,text) VALUES(LAST_INSERT_ID(),'text');

See Section 22.2.13.3, “How to Get the Unique ID for the Last Inserted Row”.

For the benefit of some ODBC applications (at least Delphi and Access), the following query can be used to find a newly inserted row:

SELECT * FROM tbl WHERE auto IS NULL;

23.1.14.2. Does MyODBC Support Dynamic Cursor Type?

Yes. MyODBC 3.51 supports Dynamic cursor type along with Forward-only and static.

Due to the performance issues, the driver does not support this feature by default. You can enable this by specifying the connection option flag as OPTION=32 or by checking the Enable Dynamic Cursor option from the DSN configuration.

23.1.14.3. What Causes Transactions are not enabled Errors?

The driver returns this error when an application issues any transactional call but the underlying MySQL server either does not support transactions or they are not enabled.

To avoid this problem, you must use a server that has either or both of the InnoDB or BDB storage engines enabled, and use tables of those types. MySQL servers from version 4.0 and up support InnoDB by default. MySQL-Max servers also support BDB on platforms where BDB is available.

Also, if your server supports transactional table types (InnoDB and BDB) make sure the disable transactions option is not set from the DSN configuration.

23.1.14.4. What Causes Cursor not found Errors?

This is because the application is using old MyODBC 2.50 version, and it did not set the cursor name explicitly through SQLSetCursorName. The fix is to upgrade to MyODBC 3.51 version.

23.1.14.5. Can I Use MyODBC 2.50 Applications with MyODBC 3.51?

Yes. If you find something is not working with MyODBC 3.51 that works with MyODBC 2.50, then send a mail message to

23.1.14.6. Can I Access MySQL from .NET Environment Using MyODBC?

Yes. You can make use of odbc.net to connect to MySQL through MyODBC. Here are the few basic samples to connect to MySQL from VC.NET and VB.NET.

Here is yet another excellent article "Exploring MySQL on .NET environment" by Venu (MyODBC developer) that covers about all MySQL .NET interfaces along with some useful examples.

Caution: Using ODBC.NET with MyODBC, while fetching empty string (0 length), it starts giving the SQL_NO_DATA exception. You can get the patch for this from http://support.microsoft.com/default.aspx?scid=kb;EN-US;q319243.

23.1.14.7. Why Does MyODBC Perform Poorly, and Also Make a Lot of Disk Activity for Relatively Small Queries?

MyODBC is a lot faster than any other ODBC driver. Slowness might be due to not using the following options.

  • The ODBC Tracing option is turned on. You can cross-check whether this option is not turned on by following the instructions from here.

    ODBC Tracing
              Tab

    As shown in the above image, the 'When to trace' option from the ODBC Data Source Administrator 'Tracing' tab should always point to 'Start Tracing Now', instead of 'Stop Tracing Now'.

  • The Debug version of the driver is used. If you are using the debug version of the driver DLL, it can also relatively slow down the query processing time. You can cross-check whether you are using the debug or release version of the DLL from the 'Comments' section of the driver DLL properties (from the system directory, right click on the driver DLL and click on properties) as shown below:

    DLL Properties Dialog
  • The Driver trace and query logs are enabled. Even if you intent to use the debug version of the driver (you should always use the release version in the production environment), make sure the driver trace and query log options(OPTION=4,524288 respectively) are not enabled as shown below:

    MyODBC Options Dialog

23.1.15. Basic MyODBC Application Steps

Interacting with a MySQL server from MyODBC applications involves the following operations:

  • Configure the MyODBC DSN

  • Connect to MySQL server

  • Initialization operations

  • Execute SQL statements

  • Retrieve results

  • Perform Transactions

  • Disconnect from the server

Most applications use some variation of these steps. The basic application steps are shown in the following diagram:

MyODBC Programming Flowchart

23.1.16. MyODBC API Reference

This section summarizes ODBC routines, categorized by functionality.

For the complete ODBC API reference, please refer to the ODBC Programer's Reference at http://msdn.microsoft.com/library/en-us/odbc/htm/odbcabout_this_manual.asp.

An application can call SQLGetInfo function to obtain conformance information about MyODBC. To obtain information about support for a specific function in the driver, an application can call SQLGetFunctions.

Note: For backward compatibility, the MyODBC 3.51 driver supports all deprecated functions.

The following tables list MyODBC API calls grouped by task:

Connecting to a data source:

Function nameMyODBCMyODBCConformancePurpose
 2.503.51  
SQLAllocHandleNoYesISO 92Obtains an environment, connection, statement, or descriptor handle.
SQLConnectYesYesISO 92Connects to a specific driver by data source name, user ID, and password.
SQLDriverConnectYesYesODBCConnects to a specific driver by connection string or requests that the Driver Manager and driver display connection dialog boxes for the user.
SQLAllocEnvYesYesDeprecatedObtains an environment handle allocated from driver.
SQLAllocConnectYesYesDeprecatedObtains a connection handle

Obtaining information about a driver and data source:

Function nameMyODBCMyODBCConformancePurpose
 2.503.51  
SQLDataSourcesNoNoISO 92Returns the list of available data sources, handled by the Driver Manager
SQLDriversNoNoODBCReturns the list of installed drivers and their attributes, handles by Driver Manager
SQLGetInfoYesYesISO 92Returns information about a specific driver and data source.
SQLGetFunctionsYesYesISO 92Returns supported driver functions.
SQLGetTypeInfoYesYesISO 92Returns information about supported data types.

Setting and retrieving driver attributes:

Function nameMyODBCMyODBCConformancePurpose
 2.503.51  
SQLSetConnectAttrNoYesISO 92Sets a connection attribute.
SQLGetConnectAttrNoYesISO 92Returns the value of a connection attribute.
SQLSetConnectOptionYesYesDeprecatedSets a connection option
SQLGetConnectOptionYesYesDeprecatedReturns the value of a connection option
SQLSetEnvAttrNoYesISO 92Sets an environment attribute.
SQLGetEnvAttrNoYesISO 92Returns the value of an environment attribute.
SQLSetStmtAttrNoYesISO 92Sets a statement attribute.
SQLGetStmtAttrNoYesISO 92Returns the value of a statement attribute.
SQLSetStmtOptionYesYesDeprecatedSets a statement option
SQLGetStmtOptionYesYesDeprecatedReturns the value of a statement option

Preparing SQL requests:

Function nameMyODBCMyODBCConformancePurpose
 2.503.51  
SQLAllocStmtYesYesDeprecatedAllocates a statement handle
SQLPrepareYesYesISO 92Prepares an SQL statement for later execution.
SQLBindParameterYesYesODBCAssigns storage for a parameter in an SQL statement.
SQLGetCursorNameYesYesISO 92Returns the cursor name associated with a statement handle.
SQLSetCursorNameYesYesISO 92Specifies a cursor name.
SQLSetScrollOptionsYesYesODBCSets options that control cursor behavior.

Submitting requests:

Function nameMyODBCMyODBCConformancePurpose
 2.503.51  
SQLExecuteYesYesISO 92Executes a prepared statement.
SQLExecDirectYesYesISO 92Executes a statement
SQLNativeSqlYesYesODBCReturns the text of an SQL statement as translated by the driver.
SQLDescribeParamYesYesODBCReturns the description for a specific parameter in a statement.
SQLNumParamsYesYesISO 92Returns the number of parameters in a statement.
SQLParamDataYesYesISO 92Used in conjunction with SQLPutData to supply parameter data at execution time. (Useful for long data values.)
SQLPutDataYesYesISO 92Sends part or all of a data value for a parameter. (Useful for long data values.)

Retrieving results and information about results:

Function nameMyODBCMyODBCConformancePurpose
 2.503.51  
SQLRowCountYesYesISO 92Returns the number of rows affected by an insert, update, or delete request.
SQLNumResultColsYesYesISO 92Returns the number of columns in the result set.
SQLDescribeColYesYesISO 92Describes a column in the result set.
SQLColAttributeNoYesISO 92Describes attributes of a column in the result set.
SQLColAttributesYesYesDeprecatedDescribes attributes of a column in the result set.
SQLFetchYesYesISO 92Returns multiple result rows.
SQLFetchScrollNoYesISO 92Returns scrollable result rows.
SQLExtendedFetchYesYesDeprecatedReturns scrollable result rows.
SQLSetPosYesYesODBCPositions a cursor within a fetched block of data and allows an application to refresh data in the rowset or to update or delete data in the result set.
SQLBulkOperationsNoYesODBCPerforms bulk insertions and bulk bookmark operations, including update, delete, and fetch by bookmark.

Retrieving error or diagnostic information:

Function nameMyODBCMyODBCConformancePurpose
 2.503.51  
SQLErrorYesYesDeprecatedReturns additional error or status information
SQLGetDiagFieldYesYesISO 92Returns additional diagnostic information (a single field of the diagnostic data structure).
SQLGetDiagRecYesYesISO 92Returns additional diagnostic information (multiple fields of the diagnostic data structure).

Obtaining information about the data source's system tables (catalog functions) item:

Function nameMyODBCMyODBCConformancePurpose
 2.503.51  
SQLColumnPrivilegesYesYesODBCReturns a list of columns and associated privileges for one or more tables.
SQLColumnsYesYesX/OpenReturns the list of column names in specified tables.
SQLForeignKeysYesYesODBCReturns a list of column names that make up foreign keys, if they exist for a specified table.
SQLPrimaryKeysYesYesODBCReturns the list of column names that make up the primary key for a table.
SQLSpecialColumnsYesYesX/OpenReturns information about the optimal set of columns that uniquely identifies a row in a specified table, or the columns that are automatically updated when any value in the row is updated by a transaction.
SQLStatisticsYesYesISO 92Returns statistics about a single table and the list of indexes associated with the table.
SQLTablePrivilegesYesYesODBCReturns a list of tables and the privileges associated with each table.
SQLTablesYesYesX/OpenReturns the list of table names stored in a specific data source.

Performing transactions:

Function nameMyODBCMyODBCConformancePurpose
 2.503.51  
SQLTransactYesYesDeprecatedCommits or rolls back a transaction
SQLEndTranNoYesISO 92Commits or rolls back a transaction.

Terminating a statement:

Function nameMyODBCMyODBCConformancePurpose
 2.503.51  
SQLFreeStmtYesYesISO 92Ends statement processing, discards pending results, and, optionally, frees all resources associated with the statement handle.
SQLCloseCursorYesYesISO 92Closes a cursor that has been opened on a statement handle.
SQLCancelYesYesISO 92Cancels an SQL statement.

Terminating a connection:

Function nameMyODBCMyODBCConformancePurpose
 2.503.51  
SQLDisconnectYesYesISO 92Closes the connection.
SQLFreeHandleNoYesISO 92Releases an environment, connection, statement, or descriptor handle.
SQLFreeConnectYesYesDeprecatedReleases connection handle
SQLFreeEnvYesYesDeprecatedReleases an environment handle

23.1.17. MyODBC Data Types

The following table illustrates how driver maps the server data types to default SQL and C data types:

Native ValueSQL TypeC Type
bitSQL_BITSQL_C_BIT
tinyintSQL_TINYINTSQL_C_STINYINT
tinyint unsignedSQL_TINYINTSQL_C_UTINYINT
bigintSQL_BIGINTSQL_C_SBIGINT
bigint unsignedSQL_BIGINTSQL_C_UBIGINT
long varbinarySQL_LONGVARBINARYSQL_C_BINARY
blobSQL_LONGVARBINARYSQL_C_BINARY
longblobSQL_LONGVARBINARYSQL_C_BINARY
tinyblobSQL_LONGVARBINARYSQL_C_BINARY
mediumblobSQL_LONGVARBINARYSQL_C_BINARY
long varcharSQL_LONGVARCHARSQL_C_CHAR
textSQL_LONGVARCHARSQL_C_CHAR
mediumtextSQL_LONGVARCHARSQL_C_CHAR
charSQL_CHARSQL_C_CHAR
numericSQL_NUMERICSQL_C_CHAR
decimalSQL_DECIMALSQL_C_CHAR
integerSQL_INTEGERSQL_C_SLONG
integer unsignedSQL_INTEGERSQL_C_ULONG
intSQL_INTEGERSQL_C_SLONG
int unsignedSQL_INTEGERSQL_C_ULONG
mediumintSQL_INTEGERSQL_C_SLONG
mediumint unsignedSQL_INTEGERSQL_C_ULONG
smallintSQL_SMALLINTSQL_C_SSHORT
smallint unsignedSQL_SMALLINTSQL_C_USHORT
realSQL_FLOATSQL_C_DOUBLE
doubleSQL_FLOATSQL_C_DOUBLE
floatSQL_REALSQL_C_FLOAT
double precisionSQL_DOUBLESQL_C_DOUBLE
dateSQL_DATESQL_C_DATE
timeSQL_TIMESQL_C_TIME
yearSQL_SMALLINTSQL_C_SHORT
datetimeSQL_TIMESTAMPSQL_C_TIMESTAMP
timestampSQL_TIMESTAMPSQL_C_TIMESTAMP
textSQL_VARCHARSQL_C_CHAR
varcharSQL_VARCHARSQL_C_CHAR
enumSQL_VARCHARSQL_C_CHAR
setSQL_VARCHARSQL_C_CHAR
bitSQL_CHARSQL_C_CHAR
boolSQL_CHARSQL_C_CHAR

23.1.18. MyODBC Error Codes

The following tables lists the error codes returned by the driver apart from the server errors.

Native CodeSQLSTATE 2SQLSTATE 3Error Message
5000100001000General warning
5010100401004String data, right truncated
50201S0201S02Option value changed
50301S0301S03No rows updated/deleted
50401S0401S04More than one row updated/deleted
50501S0601S06Attempt to fetch before the result set returned the first row set
5060700107002SQLBindParameter not used for all parameters
5070700507005Prepared statement not a cursor-specification
5080700907009Invalid descriptor index
5090800208002Connection name in use
5100800308003Connection does not exist
5112400024000Invalid cursor state
5122500025000Invalid transaction state
51325S0125S01Transaction state unknown
5143400034000Invalid cursor name
515S1000HY000General driver defined error
516S1001HY001Memory allocation error
517S1002HY002Invalid column number
518S1003HY003Invalid application buffer type
519S1004HY004Invalid SQL data type
520S1009HY009Invalid use of null pointer
521S1010HY010Function sequence error
522S1011HY011Attribute can not be set now
523S1012HY012Invalid transaction operation code
524S1013HY013Memory management error
525S1015HY015No cursor name available
526S1024HY024Invalid attribute value
527S1090HY090Invalid string or buffer length
528S1091HY091Invalid descriptor field identifier
529S1092HY092Invalid attribute/option identifier
530S1093HY093Invalid parameter number
531S1095HY095Function type out of range
532S1106HY106Fetch type out of range
533S1117HY117Row value out of range
534S1109HY109Invalid cursor position
535S1C00HYC00Optional feature not implemented
021S0121S01Column count does not match value count
02300023000Integrity constraint violation
04200042000Syntax error or access violation
042S0242S02Base table or view not found
042S1242S12Index not found
042S2142S21Column already exists
042S2242S22Column not found
008S0108S01Communication link failure

23.1.19. MyODBC With VB: ADO, DAO and RDO

This section contains simple examples of the use of MySQL ODBC 3.51 Driver with ADO, DAO and RDO.

23.1.19.1. ADO: rs.addNew, rs.delete, and rs.update

The following ADO (ActiveX Data Objects) example creates a table my_ado and demonstrates the use of rs.addNew, rs.delete, and rs.update.

Private Sub myodbc_ado_Click()

Dim conn As ADODB.Connection
Dim rs As ADODB.Recordset
Dim fld As ADODB.Field
Dim sql As String

'connect to MySQL server using MySQL ODBC 3.51 Driver
Set conn = New ADODB.Connection
conn.ConnectionString = "DRIVER={MySQL ODBC 3.51 Driver};"_
                      & "SERVER=localhost;"_
                      & " DATABASE=test;"_
                      & "UID=venu;PWD=venu; OPTION=3"

conn.Open

'create table
conn.Execute "DROP TABLE IF EXISTS my_ado"
conn.Execute "CREATE TABLE my_ado(id int not null primary key, name varchar(20)," _
                               & "txt text, dt date, tm time, ts timestamp)"

'direct insert
conn.Execute "INSERT INTO my_ado(id,name,txt) values(1,100,'venu')"
conn.Execute "INSERT INTO my_ado(id,name,txt) values(2,200,'MySQL')"
conn.Execute "INSERT INTO my_ado(id,name,txt) values(3,300,'Delete')"

Set rs = New ADODB.Recordset
rs.CursorLocation = adUseServer

'fetch the initial table ..
rs.Open "SELECT * FROM my_ado", conn
  Debug.Print rs.RecordCount
  rs.MoveFirst
  Debug.Print String(50, "-") & "Initial my_ado Result Set " & String(50, "-")
  For Each fld In rs.Fields
    Debug.Print fld.Name,
    Next
    Debug.Print

    Do Until rs.EOF
    For Each fld In rs.Fields
    Debug.Print fld.Value,
    Next
    rs.MoveNext
    Debug.Print
  Loop
rs.Close

'rs insert
rs.Open "select * from my_ado", conn, adOpenDynamic, adLockOptimistic
rs.AddNew
rs!Name = "Monty"
rs!txt = "Insert row"
rs.Update
rs.Close

'rs update
rs.Open "SELECT * FROM my_ado"
rs!Name = "update"
rs!txt = "updated-row"
rs.Update
rs.Close

'rs update second time..
rs.Open "SELECT * FROM my_ado"
rs!Name = "update"
rs!txt = "updated-second-time"
rs.Update
rs.Close

'rs delete
rs.Open "SELECT * FROM my_ado"
rs.MoveNext
rs.MoveNext
rs.Delete
rs.Close

'fetch the updated table ..
rs.Open "SELECT * FROM my_ado", conn
  Debug.Print rs.RecordCount
  rs.MoveFirst
  Debug.Print String(50, "-") & "Updated my_ado Result Set " & String(50, "-")
  For Each fld In rs.Fields
    Debug.Print fld.Name,
    Next
    Debug.Print

    Do Until rs.EOF
    For Each fld In rs.Fields
    Debug.Print fld.Value,
    Next
    rs.MoveNext
    Debug.Print
  Loop
rs.Close
conn.Close
End Sub

23.1.19.2. DAO: rs.addNew, rs.update, and Scrolling

The following DAO (Data Access Objects) example creates a table my_dao and demonstrates the use of rs.addNew, rs.update, and result set scrolling.

Private Sub myodbc_dao_Click()

Dim ws As Workspace
Dim conn As Connection
Dim queryDef As queryDef
Dim str As String

'connect to MySQL using MySQL ODBC 3.51 Driver
Set ws = DBEngine.CreateWorkspace("", "venu", "venu", dbUseODBC)
str = "odbc;DRIVER={MySQL ODBC 3.51 Driver};"_
                      & "SERVER=localhost;"_
                      & " DATABASE=test;"_
                      & "UID=venu;PWD=venu; OPTION=3"
Set conn = ws.OpenConnection("test", dbDriverNoPrompt, False, str)

'Create table my_dao
Set queryDef = conn.CreateQueryDef("", "drop table if exists my_dao")
queryDef.Execute

Set queryDef = conn.CreateQueryDef("", "create table my_dao(Id INT AUTO_INCREMENT PRIMARY KEY, " _
                                                         & "Ts TIMESTAMP(14) NOT NULL, Name varchar(20), Id2 INT)")
queryDef.Execute

'Insert new records using rs.addNew
Set rs = conn.OpenRecordset("my_dao")
Dim i As Integer

  For i = 10 To 15
  rs.AddNew
  rs!Name = "insert record" & i
  rs!Id2 = i
  rs.Update
  Next i
           rs.Close

'rs update..
Set rs = conn.OpenRecordset("my_dao")
rs.Edit
rs!Name = "updated-string"
rs.Update
rs.Close

'fetch the table back...
Set rs = conn.OpenRecordset("my_dao", dbOpenDynamic)
str = "Results:"
rs.MoveFirst
While Not rs.EOF
str = " " & rs!Id & " , " & rs!Name & ", " & rs!Ts & ", " & rs!Id2
Debug.Print "DATA:" & str
rs.MoveNext
Wend

'rs Scrolling
rs.MoveFirst
str = " FIRST ROW: " & rs!Id & " , " & rs!Name & ", " & rs!Ts & ", " & rs!Id2
Debug.Print str

rs.MoveLast
str = " LAST ROW: " & rs!Id & " , " & rs!Name & ", " & rs!Ts & ", " & rs!Id2
Debug.Print str

rs.MovePrevious
str = " LAST-1 ROW: " & rs!Id & " , " & rs!Name & ", " & rs!Ts & ", " & rs!Id2
Debug.Print str

'free all resources
rs.Close
queryDef.Close
conn.Close
ws.Close

End Sub

23.1.19.3. RDO: rs.addNew and rs.update

The following RDO (Remote Data Objects) example creates a table my_rdo and demonstrates the use of rs.addNew and rs.update.

Dim rs As rdoResultset
  Dim cn As New rdoConnection
  Dim cl As rdoColumn
  Dim SQL As String

  'cn.Connect = "DSN=test;"
  cn.Connect = "DRIVER={MySQL ODBC 3.51 Driver};"_
                      & "SERVER=localhost;"_
                      & " DATABASE=test;"_
                      & "UID=venu;PWD=venu; OPTION=3"

  cn.CursorDriver = rdUseOdbc
  cn.EstablishConnection rdDriverPrompt


  'drop table my_rdo
  SQL = "drop table if exists my_rdo"
  cn.Execute SQL, rdExecDirect

  'create table my_rdo
  SQL = "create table my_rdo(id int, name varchar(20))"
  cn.Execute SQL, rdExecDirect

  'insert - direct
  SQL = "insert into my_rdo values (100,'venu')"
  cn.Execute SQL, rdExecDirect

  SQL = "insert into my_rdo values (200,'MySQL')"
  cn.Execute SQL, rdExecDirect

  'rs insert
  SQL = "select * from my_rdo"
  Set rs = cn.OpenResultset(SQL, rdOpenStatic, rdConcurRowVer, rdExecDirect)
  rs.AddNew
  rs!id = 300
  rs!Name = "Insert1"
  rs.Update
  rs.Close

  'rs insert
  SQL = "select * from my_rdo"
  Set rs = cn.OpenResultset(SQL, rdOpenStatic, rdConcurRowVer, rdExecDirect)
  rs.AddNew
  rs!id = 400
  rs!Name = "Insert 2"
  rs.Update
  rs.Close

  'rs update
  SQL = "select * from my_rdo"
  Set rs = cn.OpenResultset(SQL, rdOpenStatic, rdConcurRowVer, rdExecDirect)
  rs.Edit
  rs!id = 999
  rs!Name = "updated"
  rs.Update
  rs.Close

  'fetch back...
  SQL = "select * from my_rdo"
  Set rs = cn.OpenResultset(SQL, rdOpenStatic, rdConcurRowVer, rdExecDirect)
  Do Until rs.EOF
  For Each cl In rs.rdoColumns
              Debug.Print cl.Value,
    Next
    rs.MoveNext
    Debug.Print
             Loop
  Debug.Print "Row count="; rs.RowCount

  'close
  rs.Close
  cn.Close

End Sub

23.1.20. MyODBC with Microsoft .NET

This section contains simple examples that demonstrate the use of MyODBC drivers with ODBC.NET.

23.1.20.1. ODBC.NET: CSHARP(C#)

The following sample creates a table my_odbc_net and demonstrates the use in C#.

/**
* @sample    : mycon.cs
* @purpose   : Demo sample for ODBC.NET using MyODBC
* @author    : Venu, 
*
* (C) Copyright MySQL AB, 1995-2004
*
**/

/* build command
*
*  csc /t:exe
*      /out:mycon.exe mycon.cs
*      /r:Microsoft.Data.Odbc.dll
*/

using Console = System.Console;
using Microsoft.Data.Odbc;

namespace myodbc3
{
class mycon
{
  static void Main(string[] args)
  {
    try
    {
      //Connection string for MyODBC 2.50
      /*string MyConString = "DRIVER={MySQL};" +
                           "SERVER=localhost;" +
                           "DATABASE=test;" +
                           "UID=venu;" +
                           "PASSWORD=venu;" +
                           "OPTION=3";
      */
      //Connection string for MyODBC 3.51
      string MyConString = "DRIVER={MySQL ODBC 3.51 Driver};" +
                           "SERVER=localhost;" +
                           "DATABASE=test;" +
                           "UID=venu;" +
                           "PASSWORD=venu;" +
                           "OPTION=3";

      //Connect to MySQL using MyODBC
      OdbcConnection MyConnection = new OdbcConnection(MyConString);
      MyConnection.Open();

      Console.WriteLine("\n !!! success, connected successfully !!!\n");

      //Display connection information
      Console.WriteLine("Connection Information:");
      Console.WriteLine("\tConnection String:" + MyConnection.ConnectionString);
      Console.WriteLine("\tConnection Timeout:" + MyConnection.ConnectionTimeout);
      Console.WriteLine("\tDatabase:" + MyConnection.Database);
      Console.WriteLine("\tDataSource:" + MyConnection.DataSource);
      Console.WriteLine("\tDriver:" + MyConnection.Driver);
      Console.WriteLine("\tServerVersion:" + MyConnection.ServerVersion);

      //Create a sample table
      OdbcCommand MyCommand = new OdbcCommand("DROP TABLE IF EXISTS my_odbc_net",MyConnection);
      MyCommand.ExecuteNonQuery();
      MyCommand.CommandText = "CREATE TABLE my_odbc_net(id int, name varchar(20), idb bigint)";
      MyCommand.ExecuteNonQuery();

      //Insert
      MyCommand.CommandText = "INSERT INTO my_odbc_net VALUES(10,'venu', 300)";
      Console.WriteLine("INSERT, Total rows affected:" + MyCommand.ExecuteNonQuery());;

      //Insert
      MyCommand.CommandText = "INSERT INTO my_odbc_net VALUES(20,'mysql',400)";
      Console.WriteLine("INSERT, Total rows affected:" + MyCommand.ExecuteNonQuery());

      //Insert
      MyCommand.CommandText = "INSERT INTO my_odbc_net VALUES(20,'mysql',500)";
      Console.WriteLine("INSERT, Total rows affected:" + MyCommand.ExecuteNonQuery());

      //Update
      MyCommand.CommandText = "UPDATE my_odbc_net SET id=999 WHERE id=20";
      Console.WriteLine("Update, Total rows affected:" + MyCommand.ExecuteNonQuery());

      //COUNT(*)
      MyCommand.CommandText = "SELECT COUNT(*) as TRows FROM my_odbc_net";
      Console.WriteLine("Total Rows:" + MyCommand.ExecuteScalar());

      //Fetch
      MyCommand.CommandText = "SELECT * FROM my_odbc_net";
      OdbcDataReader MyDataReader;
      MyDataReader =  MyCommand.ExecuteReader();
      while (MyDataReader.Read())
      {
       if(string.Compare(MyConnection.Driver,"myodbc3.dll") == 0) {
         Console.WriteLine("Data:" + MyDataReader.GetInt32(0) + " " +
                                     MyDataReader.GetString(1) + " " +
                                     MyDataReader.GetInt64(2)); //Supported only by MyODBC 3.51
       }
       else {
         Console.WriteLine("Data:" + MyDataReader.GetInt32(0) + " " +
                                     MyDataReader.GetString(1) + " " +
                                     MyDataReader.GetInt32(2)); //BIGINTs not supported by MyODBC
       }
      }

      //Close all resources
      MyDataReader.Close();
      MyConnection.Close();
    }
    catch (OdbcException MyOdbcException)//Catch any ODBC exception ..
    {
      for (int i=0; i < MyOdbcException.Errors.Count; i++)
      {
        Console.Write("ERROR #" + i + "\n" +
          "Message: " + MyOdbcException.Errors[i].Message + "\n" +
          "Native: " + MyOdbcException.Errors[i].NativeError.ToString() + "\n" +
          "Source: " + MyOdbcException.Errors[i].Source + "\n" +
          "SQL: " + MyOdbcException.Errors[i].SQLState + "\n");
      }
    }
  }
}
}

23.1.20.2. ODBC.NET: VB

The following sample creates a table my_vb_net and demonstrates the use in VB.

' @sample    : myvb.vb
' @purpose   : Demo sample for ODBC.NET using MyODBC
' @author    : Venu, 
'
' (C) Copyright MySQL AB, 1995-2004
'
'

'
' build command
'
' vbc /target:exe
'     /out:myvb.exe
'     /r:Microsoft.Data.Odbc.dll
'     /r:System.dll
'     /r:System.Data.dll
'

Imports Microsoft.Data.Odbc
Imports System

Module myvb
  Sub Main()
      Try

          'MyODBC 3.51 connection string
          Dim MyConString As String = "DRIVER={MySQL ODBC 3.51 Driver};" & _
                         "SERVER=localhost;" & _
                         "DATABASE=test;" & _
                         "UID=venu;" & _
                         "PASSWORD=venu;" & _
                         "OPTION=3;"

          'Connection
          Dim MyConnection As New OdbcConnection(MyConString)
          MyConnection.Open()

          Console.WriteLine ("Connection State::" & MyConnection.State.ToString)

          'Drop
          Console.WriteLine ("Dropping table")
          Dim MyCommand As New OdbcCommand()
          MyCommand.Connection = MyConnection
          MyCommand.CommandText = "DROP TABLE IF EXISTS my_vb_net"
          MyCommand.ExecuteNonQuery()

          'Create
          Console.WriteLine ("Creating....")
          MyCommand.CommandText = "CREATE TABLE my_vb_net(id int, name varchar(30))"
          MyCommand.ExecuteNonQuery()

          'Insert
          MyCommand.CommandText = "INSERT INTO my_vb_net VALUES(10,'venu')"
          Console.WriteLine("INSERT, Total rows affected:" & MyCommand.ExecuteNonQuery())

          'Insert
          MyCommand.CommandText = "INSERT INTO my_vb_net VALUES(20,'mysql')"
          Console.WriteLine("INSERT, Total rows affected:" & MyCommand.ExecuteNonQuery())

          'Insert
          MyCommand.CommandText = "INSERT INTO my_vb_net VALUES(20,'mysql')"
          Console.WriteLine("INSERT, Total rows affected:" & MyCommand.ExecuteNonQuery())

          'Insert
          MyCommand.CommandText = "INSERT INTO my_vb_net(id) VALUES(30)"
          Console.WriteLine("INSERT, Total rows affected:" & MyCommand.ExecuteNonQuery())

          'Update
          MyCommand.CommandText = "UPDATE my_vb_net SET id=999 WHERE id=20"
          Console.WriteLine("Update, Total rows affected:" & MyCommand.ExecuteNonQuery())

          'COUNT(*)
          MyCommand.CommandText = "SELECT COUNT(*) as TRows FROM my_vb_net"
          Console.WriteLine("Total Rows:" & MyCommand.ExecuteScalar())

          'Select
          Console.WriteLine ("Select * FROM my_vb_net")
          MyCommand.CommandText = "SELECT * FROM my_vb_net"
          Dim MyDataReader As OdbcDataReader
          MyDataReader = MyCommand.ExecuteReader
          While MyDataReader.Read
              If MyDataReader("name") Is DBNull.Value Then
                  Console.WriteLine ("id = " & CStr(MyDataReader("id")) & "  name = " & _
                    "NULL")
              Else
                  Console.WriteLine ("id = " & CStr(MyDataReader("id")) & "  name = " & _
                                        CStr(MyDataReader("name")))
              End If
          End While

      'Catch ODBC Exception
      Catch MyOdbcException As OdbcException
          Dim i As Integer
          Console.WriteLine (MyOdbcException.ToString)

      'Catch program exception
      Catch MyException As Exception
          Console.WriteLine (MyException.ToString)
  End Try
  End Sub
End Module

23.1.21. Credits

These are the developers that have worked on the MyODBC and MyODBC 3.51 Drivers from MySQL AB.

  • Micheal (Monty) Widenius

  • Venu Anuganti

  • Peter Harvey

23.2. MySQL Connector/NET

23.2.1. Introduction

MySQL Connector/NET enables developers to easily create .NET applications that require secure, high-performance data connectivity with MySQL. It implements the required ADO.NET interfaces and integrates into ADO.NET aware tools. Developers can build applications using their choice of .NET languages. MySQL Connector/NET is a fully managed ADO.NET driver written in 100% pure C#.

MySQL Connector/NET includes full support for:

  • MySQL 5.0 features (stored procedures, etc.)

  • MySQL 4.1 features (server-side prepared statements, Unicode, and shared memory access, etc.)

  • Large-packet support for sending and receiving rows and BLOBs up to 2 gigabytes in size.

  • Protocol compression which allows for compressing the data stream between the client and server.

  • Support for connecting using TCP/IP sockets, named pipes, or shared memory on Windows.

  • Support for connecting using TCP/IP sockets or Unix sockets on Unix.

  • Support for the open source Mono framework developed by Novell.

  • Fully managed, does not utilize the MySQL client library.

The developers of MySQL Connector/NET greatly value the input of our users in the software development process. If you find MySQL Connector/NET lacking some feature important to you, or if you discover a bug, please use our MySQL Bug System to request features or report problems.

Additional resources

This document is intended as a user's guide to MySQL Connector/NET and not as a syntax reference. If you need detailed syntax information you should read the Documentation.chm file included with the MySQL Connector/NET distribution.

23.2.2. Downloading and Installing MySQL Connector/NET

MySQL Connector/NET runs on any platform that supports the .NET framework. The .NET framework is primarily supported on recent versions of Microsoft Windows, and is supported on Linux through the open source Mono framework developed by Novell (see http://www.mono-project.com).

MySQL Connector/NET is installed through the use of a Windows Installer (.msi) installation package, which can be used to install MySQL Connector/NET on all Windows operating systems. The MSI package in contained within a ZIP archive named mysql-connector-net-version.zip, where version indicates the MySQL Connector/NET version.

MySQL Connector/NET is available for download from http://dev.mysql.com/downloads/connector/net/1.0.html.

The Windows Installer engine was updated with the release of Windows XP; those using an older version can reference this Microsoft Knowledge Base article for information on upgrading to the latest version.

To install MySQL Connector/NET, right-click on the MSI file and select Install. The installation will begin automatically after the installer prompts you for your installation preferences. The Typical installation is recommended for most users.

If you are having problems running the installer, you can download a ZIP file without an installer as an alternative. That file is called mysql-connector-net-version-noinstall.zip. Using a ZIP program, unpack it to a directory of your choice.

Unless you choose otherwise, MySQL Connector/NET is installed in C:\Program Files\MySQL\MySQL Connector Net X.X.X, where X.X.X is replaced with the version of MySQL Connector/NET you are installing. New installations do not overwrite existing versions of MySQL Connector/NET.

23.2.3. Connector/NET Architecture

MySQL Connector/NET comprises several classes that are used to connect to the database, execute queries and statements, and manage query results.

The following are the major classes of MySQL Connector/NET:

  • MySqlCommand: Represents a SQL statement to execute against a MySQL database.

  • MySqlCommandBuilder: Automatically generates single-table commands used to reconcile changes made to a DataSet with the associated MySQL database.

  • MySqlConnection: Represents an open connection to a MySQL Server database.

  • MySqlDataAdapter: Represents a set of data commands and a database connection that are used to fill a dataset and update a MySQL database.

  • MySqlDataReader: Provides a means of reading a forward-only stream of rows from a MySQL database.

  • MySqlException: The exception that is thrown when MySQL returns an error.

  • MySqlHelper: Helper class that makes it easier to work with the provider.

  • MySqlTransaction: Represents a SQL transaction to be made in a MySQL database.

Each of these objects will be described in the upcoming sections. These sections are intended to be an overview of the major classes of MySQL Connector/NET, and not a syntax reference. If you need more detailed information you should read the Documentation.chm file included with the MySQL Connector/NET distribution.

23.2.3.1. The MySqlCommand Class

The MySqlCommand class represents a SQL statement to execute against a MySQL database.

Note: Prior versions of the provider used the '@' symbol to mark parameters in SQL. This is incompatible with MySQL user variables, so the provider now uses the '?' symbol to locate parameters in SQL. To support older code, you can set 'old syntax=yes' in your connection string. If you do this, please be aware that an exception will not be thrown if you fail to define a parameter that you intended to use in your SQL.

23.2.3.1.1. Properties

The following properties are available:

  • CommandText: Gets or sets the SQL statement to execute at the data source.

  • CommandTimeout: Gets or sets the wait time before terminating the attempt to execute a command and generating an error.

  • CommandType: Gets or sets a value indicating how the CommandText property is to be interpreted. Possible types are StoredProcedure, TableDirect, and Text.

  • Connection: Gets or sets the MySqlConnection used by this instance of the MySqlCommand.

  • IsPrepared: Is true if this command has been prepared, false otherwise.

  • Parameters: Gets the MySqlParameterCollection.

  • Transaction: Gets or sets the MySqlTransaction within which the MySqlCommand executes.

  • UpdatedRowSource: Gets or sets how command results are applied to the DataRow when used by the Update method of the DbDataAdapter.

23.2.3.1.2. Methods

The following methods are available:

  • Cancel: Attempts to cancel the execution of a MySqlCommand. This operation is not supported.

  • Clone: Creates a clone of this MySqlCommand object. CommandText, Connection, and Transaction properties are included as well as the entire parameter list.

  • CreateParameter: Creates a new instance of a MySqlParameter object.

  • Dispose: Disposes of this instance of MySqlCommand.

  • ExecuteNonQuery: Executes a SQL statement against the connection and returns the number of rows affected.

  • ExecuteReader: Sends the CommandText to the Connection and builds a MySqlDataReader.

  • ExecuteScalar: Executes the query, and returns the first column of the first row in the result set returned by the query. Extra columns or rows are ignored.

  • Prepare: Creates a prepared version of the command on an instance of MySQL Server.

23.2.3.1.3. Usage

The following example creates a MySqlCommand and a MySqlConnection. The MySqlConnection is opened and set as the Connection for the MySqlCommand. The example then calls ExecuteNonQuery, and closes the connection. To accomplish this, the ExecuteNonQuery is passed a connection string and a query string that is a SQL INSERT statement.

23.2.3.1.3.1. VB.NET

The following example show how to use the MySqlCommand class with VB.NET:

Public Sub InsertRow(myConnectionString As String)
    ' If the connection string is null, use a default.
    If myConnectionString = "" Then
        myConnectionString = "Database=Test;Data Source=localhost;User Id=username;Password=pass"
    End If
    Dim myConnection As New MySqlConnection(myConnectionString)
    Dim myInsertQuery As String = "INSERT INTO Orders (id, customerId, amount) Values(1001, 23, 30.66)"
    Dim myCommand As New MySqlCommand(myInsertQuery)
    myCommand.Connection = myConnection
    myConnection.Open()
    myCommand.ExecuteNonQuery()
    myCommand.Connection.Close()
End Sub
23.2.3.1.3.2. C#

The following example show how to use the MySqlCommand class with C#:

public void InsertRow(string myConnectionString) 
{
    // If the connection string is null, use a default.
    if(myConnectionString == "") 
    {
        myConnectionString = "Database=Test;Data Source=localhost;User Id=username;Password=pass";
    }
    MySqlConnection myConnection = new MySqlConnection(myConnectionString);
    string myInsertQuery = "INSERT INTO Orders (id, customerId, amount) Values(1001, 23, 30.66)";
    MySqlCommand myCommand = new MySqlCommand(myInsertQuery);
    myCommand.Connection = myConnection;
    myConnection.Open();
    myCommand.ExecuteNonQuery();
    myCommand.Connection.Close();
}

23.2.3.2. The MySqlCommandBuilder Class

The MySqlDataAdapter does not automatically generate the SQL statements required to reconcile changes made to a DataSet with the associated instance of MySQL. However, you can create a MySqlCommandBuilder object to automatically generate SQL statements for single-table updates if you set the SelectCommand property of the MySqlDataAdapter. Then, any additional SQL statements that you do not set are generated by the MySqlCommandBuilder.

The MySqlCommandBuilder registers itself as a listener for OnRowUpdating events whenever you set the DataAdapter property. You can only associate one MySqlDataAdapter or MySqlCommandBuilder object with each other at one time.

To generate INSERT, UPDATE, or DELETE statements, the MySqlCommandBuilder uses the SelectCommand property to retrieve a required set of metadata automatically. If you change the SelectCommand after the metadata has is retrieved (for example, after the first update), you should call the RefreshSchema method to update the metadata.

The SelectCommand must also return at least one primary key or unique column. If none are present, an InvalidOperation exception is generated, and the commands are not generated.

The MySqlCommandBuilder also uses the Connection, CommandTimeout, and Transaction properties referenced by the SelectCommand. The user should call RefreshSchema if any of these properties are modified, or if the SelectCommand itself is replaced. Otherwise the InsertCommand, UpdateCommand, and DeleteCommand properties retain their previous values.

If you call Dispose, the MySqlCommandBuilder is disassociated from the MySqlDataAdapter, and the generated commands are no longer used.

23.2.3.2.1. Properties

The following properties are available:

  • DataAdapter: The MySqlCommandBuilder registers itself as a listener for RowUpdating events that are generated by the MySqlDataAdapter specified in this property. When you create a new instance MySqlCommandBuilder, any existing MySqlCommandBuilder associated with this MySqlDataAdapter is released.

  • QuotePrefix, QuoteSuffix: Database objects in MySQL can contain special characters such as spaces that would make normal SQL strings impossible to correctly parse. Use of the QuotePrefix and the QuoteSuffix properties allows the MySqlCommandBuilder to build SQL commands that handle this situation.

23.2.3.2.2. Methods

The following methods are available:

  • DeriveParameters: Retrieves parameter information from the stored procedure specified in the MySqlCommand and populates the Parameters collection of the specified MySqlCommand object. This method is not currently supported since stored procedures are not available in MySql.

  • GetDeleteCommand: Gets the automatically generated MySqlCommand object required to perform deletions on the database.

  • GetInsertCommand: Gets the automatically generated MySqlCommand object required to perform insertions on the database.

  • GetUpdateCommand: Gets the automatically generated MySqlCommand object required to perform updates on the database.

  • RefreshSchema: Refreshes the database schema information used to generate INSERT, UPDATE, or DELETE statements.

23.2.3.2.3. Usage

The following example uses the MySqlCommand, along MySqlDataAdapter and MySqlConnection, to select rows from a data source. The example is passed an initialized DataSet, a connection string, a query string that is a SQL SELECT statement, and a string that is the name of the database table. The example then creates a MySqlCommandBuilder.

23.2.3.2.3.1. VB.NET

The following example shows how to use the MySqlCommandBuilder class with VB.NET:

  Public Shared Function SelectRows(myConnection As String, mySelectQuery As String, myTableName As String) As DataSet
        Dim myConn As New MySqlConnection(myConnection)
        Dim myDataAdapter As New MySqlDataAdapter()
        myDataAdapter.SelectCommand = New MySqlCommand(mySelectQuery, myConn)
        Dim cb As SqlCommandBuilder = New MySqlCommandBuilder(myDataAdapter)

        myConn.Open()

        Dim ds As DataSet = New DataSet
        myDataAdapter.Fill(ds, myTableName)

        ' Code to modify data in DataSet here 

        ' Without the MySqlCommandBuilder this line would fail.
        myDataAdapter.Update(ds, myTableName)

        myConn.Close()
    End Function 'SelectRows
    
23.2.3.2.3.2. C#

The following example shows how to use the MySqlCommandBuilder class with C#:

    public static DataSet SelectRows(string myConnection, string mySelectQuery, string myTableName)
    {
      MySqlConnection myConn = new MySqlConnection(myConnection);
      MySqlDataAdapter myDataAdapter = new MySqlDataAdapter();
      myDataAdapter.SelectCommand = new MySqlCommand(mySelectQuery, myConn);
      MySqlCommandBuilder cb = new MySqlCommandBuilder(myDataAdapter);

      myConn.Open();

      DataSet ds = new DataSet();
      myDataAdapter.Fill(ds, myTableName);

      //code to modify data in DataSet here

      //Without the MySqlCommandBuilder this line would fail
      myDataAdapter.Update(ds, myTableName);

      myConn.Close();

      return ds;
    }  
    

23.2.3.3. The MySqlConnection Class

A MySqlConnection object represents a session to a MySQL Server data source. When you create an instance of MySqlConnection, all properties are set to their initial values. For a list of these values, see the MySqlConnection constructor.

If the MySqlConnection goes out of scope, it is not closed. Therefore, you must explicitly close the connection by calling Close or Dispose.

23.2.3.3.1. Properties

The following properties are available:

  • ConnectionString: Gets or sets the string used to connect to a MySQL Server database.

  • ConnectionTimeout: Gets the time to wait while trying to establish a connection before terminating the attempt and generating an error.

  • Database: Gets the name of the current database or the database to be used after a connection is opened.

  • DataSource: Gets the name of the MySQL server to which to connect.

  • ServerThread: Returns the id of the server thread this connection is executing on.

  • ServerVersion: Gets a string containing the version of the MySQL server to which the client is connected.

  • State: Gets the current state of the connection.

  • UseConnection: Indicates if this connection should use compression when communicating with the server.

23.2.3.3.2. Methods

The following methods are available:

  • BeginTransaction: Begins a database transaction.

  • ChangeDatabase: Changes the current database for an open MySqlConnection.

  • Close: Closes the connection to the database. This is the preferred method of closing any open connection.

  • CreateCommand: Creates and returns a MySqlCommand object associated with the MySqlConnection.

  • Dispose: Releases the resources used by the MySqlConnection.

  • Open: Opens a database connection with the property settings specified by the ConnectionString.

  • Ping: Pings the MySQL server.

23.2.3.3.3. Usage

The following example creates a MySqlCommand and a MySqlConnection. The MySqlConnection is opened and set as the Connection for the MySqlCommand. The example then calls ExecuteNonQuery, and closes the connection. To accomplish this, the ExecuteNonQuery is passed a connection string and a query string that is a SQL INSERT statement.

23.2.3.3.3.1. VB.NET

The following example shows how to use the MySqlConnection class with VB.NET:

Public Sub InsertRow(myConnectionString As String)
    ' If the connection string is null, use a default.
    If myConnectionString = "" Then
        myConnectionString = "Database=Test;Data Source=localhost;User Id=username;Password=pass"
    End If
    Dim myConnection As New MySqlConnection(myConnectionString)
    Dim myInsertQuery As String = "INSERT INTO Orders (id, customerId, amount) Values(1001, 23, 30.66)"
    Dim myCommand As New MySqlCommand(myInsertQuery)
    myCommand.Connection = myConnection
    myConnection.Open()
    myCommand.ExecuteNonQuery()
    myCommand.Connection.Close()
End Sub
      
23.2.3.3.3.2. C#

The following example shows how to use the MySqlConnection class with C#:

public void InsertRow(string myConnectionString) 
{
    // If the connection string is null, use a default.
    if(myConnectionString == "") 
    {
        myConnectionString = "Database=Test;Data Source=localhost;User Id=username;Password=pass";
    }
    MySqlConnection myConnection = new MySqlConnection(myConnectionString);
    string myInsertQuery = "INSERT INTO Orders (id, customerId, amount) Values(1001, 23, 30.66)";
    MySqlCommand myCommand = new MySqlCommand(myInsertQuery);
    myCommand.Connection = myConnection;
    myConnection.Open();
    myCommand.ExecuteNonQuery();
    myCommand.Connection.Close();
}

      

23.2.3.4. The MySqlDataAdapter Class

The MySQLDataAdapter serves as a bridge between a DataSet and MySQL for retrieving and saving data. The MySQLDataAdapter provides this bridge by mapping Fill, which changes the data in the DataSet to match the data in the data source, and Update, which changes the data in the data source to match the data in the DataSet, using the appropriate SQL statements against the data source.

When the MySQLDataAdapter fills a DataSet, it will create the necessary tables and columns for the returned data if they do not already exist. However, primary key information will not be included in the implicitly created schema unless the MissingSchemaAction property is set to AddWithKey. You may also have the MySQLDataAdapter create the schema of the DataSet, including primary key information, before filling it with data using FillSchema.

MySQLDataAdapter is used in conjunction with MySqlConnection and MySqlCommand to increase performance when connecting to a MySQL database.

The MySQLDataAdapter also includes the SelectCommand, InsertCommand, DeleteCommand, UpdateCommand, and TableMappings properties to facilitate the loading and updating of data.

23.2.3.4.1. Properties

The following properties are available:

  • AcceptChangesDuringFill: Gets or sets a value indicating whether AcceptChanges is called on a DataRow after it is added to the DataTable during any of the Fill operations.

  • ContinueUpdateOnError: Gets or sets a value that specifies whether to generate an exception when an error is encountered during a row update.

  • DeleteCommand: Gets or sets a SQL statement or stored procedure used to delete records from the data set.

  • InsertCommand: Gets or sets a SQL statement or stored procedure used to insert records into the data set.

  • MissingMappingAction: Determines the action to take when incoming data does not have a matching table or column.

  • MissingSchemaAction: Determines the action to take when existing DataSet schema does not match incoming data.

  • SelectCommand: Gets or sets a SQL statement or stored procedure used to select records in the data source.

  • TableMappings: Gets a collection that provides the master mapping between a source table and a DataTable.

  • UpdateCommand: Gets or sets a SQL statement or stored procedure used to updated records in the data source.

23.2.3.4.2. Methods

The following methods are available:

  • Fill: Adds or refreshes rows in the DataSet to match those in the data source using the DataSet name, and creates a DataTable named "Table".

  • FillSchema: Adds a DataTable named "Table" to the specified DataSet and configures the schema to match that in the data source based on the specified SchemaType.

  • GetFillParameters: Gets the parameters set by the user when executing an SQL SELECT statement.

  • Update: Calls the respective INSERT, UPDATE, or DELETE statements for each inserted, updated, or deleted row in the specified DataSet.

23.2.3.4.3. Usage

The following example creates a MySqlCommand and a MySqlConnection. The MySqlConnection is opened and set as the Connection for the MySqlCommand. The example then calls ExecuteNonQuery, and closes the connection. To accomplish this, the ExecuteNonQuery is passed a connection string and a query string that is a SQL INSERT statement.

23.2.3.4.3.1. VB.NET

The following example shows how to use the MySqlDataAdapter class with VB.NET:

Public Function SelectRows(dataSet As DataSet, connection As String, query As String) As DataSet
    Dim conn As New MySqlConnection(connection)
    Dim adapter As New MySqlDataAdapter()
    adapter.SelectCommand = new MySqlCommand(query, conn)
    adapter.Fill(dataset)
    Return dataset
End Function 
23.2.3.4.3.2. C#

The following example shows how to use the MySqlDataAdapter class with C#:

public DataSet SelectRows(DataSet dataset,string connection,string query) 
{
    MySqlConnection conn = new MySqlConnection(connection);
    MySqlDataAdapter adapter = new MySqlDataAdapter();
    adapter.SelectCommand = new MySqlCommand(query, conn);
    adapter.Fill(dataset);
    return dataset;
}   
  

23.2.3.5. The MySqlDataReader Class

The MySqlDataReader class provides a means of reading a forward-only stream of rows from a MySQL database.

To create a MySQLDataReader, you must call the ExecuteReader method of the MySqlCommand object, rather than directly using a constructor.

While the MySqlDataReader is in use, the associated MySqlConnection is busy serving the MySqlDataReader, and no other operations can be performed on the MySqlConnection other than closing it. This is the case until the Close method of the MySqlDataReader is called.

IsClosed and RecordsAffected are the only properties that you can call after the MySqlDataReader is closed. Though the RecordsAffected property may be accessed at any time while the MySqlDataReader exists, always call Close before returning the value of RecordsAffected to ensure an accurate return value.

For optimal performance, MySqlDataReader avoids creating unnecessary objects or making unnecessary copies of data. As a result, multiple calls to methods such as GetValue return a reference to the same object. Use caution if you are modifying the underlying value of the objects returned by methods such as GetValue.

23.2.3.5.1. Properties

The following properties are available:

  • Depth: Gets a value indicating the depth of nesting for the current row. This method is not supported currently and always returns 0.

  • FieldCount: Gets the number of columns in the current row.

  • HasRows: Gets a value indicating whether the MySqlDataReader contains one or more rows.

  • IsClosed: Gets a value indicating whether the data reader is closed.

  • Item: Gets the value of a column in its native format. In C#, this property is the indexer for the MySqlDataReader class.

  • RecordsAffected: Gets the number of rows changed, inserted, or deleted by execution of the SQL statement.

23.2.3.5.2. Methods

The following methods are available:

  • Close: Closes the MySqlDataReader object.

  • GetBoolean: Gets the value of the specified column as a Boolean.

  • GetByte: Gets the value of the specified column as a byte.

  • GetBytes: Reads a stream of bytes from the specified column offset into the buffer an array starting at the given buffer offset.

  • GetChar: Gets the value of the specified column as a single character.

  • GetChars: Reads a stream of characters from the specified column offset into the buffer as an array starting at the given buffer offset.

  • GetDataTypeName: Gets the name of the source data type.

  • GetDateTime: Gets the value of the specified column as a DateTime object.

  • GetDecimal: Gets the value of the specified column as a Decimal object.

  • GetDouble: Gets the value of the specified column as a double-precision floating point number.

  • GetFieldType: Gets the Type that is the data type of the object.

  • GetFloat: Gets the value of the specified column as a single-precision floating point number.

  • GetGuid: Gets the value of the specified column as a GUID.

  • GetInt16: Gets the value of the specified column as a 16-bit signed integer.

  • GetInt32: Gets the value of the specified column as a 32-bit signed integer.

  • GetInt64: Gets the value of the specified column as a 64-bit signed integer.

  • GetMySqlDateTime: Gets the value of the specified column as a MySqlDateTime object.

  • GetName: Gets the name of the specified column.

  • GetOrdinal: Gets the column ordinal, given the name of the column.

  • GetSchemaTable: Returns a DataTable that describes the column metadata of the MySqlDataReader.

  • GetString: Gets the value of the specified column as a String object.

  • GetTimeSpan: Gets the value of the specified column as a TimeSpan object.

  • GetUInt16: Gets the value of the specified column as a 16-bit unsigned integer.

  • GetUInt32: Gets the value of the specified column as a 32-bit unsigned integer.

  • GetUInt64: Gets the value of the specified column as a 64-bit unsigned integer.

  • GetValue: Gets the value of the specified column in its native format.

  • GetValues: Gets all attribute columns in the collection for the current row.

  • IsDBNull: Gets a value indicating whether the column contains non-existent or missing values.

  • NextResult: Advances the data reader to the next result, when reading the results of batch SQL statements.

  • Read: Advances the MySqlDataReader to the next record.

23.2.3.5.3. Usage

The following example creates a MySqlConnection, a MySqlCommand, and a MySqlDataReader. The example reads through the data, writing it out to the console. Finally, the example closes the MySqlDataReader, then the MySqlConnection

23.2.3.5.3.1. VB.NET

The following example shows how to use the MySqlDataReader class with VB.NET:

Public Sub ReadMyData(myConnString As String)
    Dim mySelectQuery As String = "SELECT OrderID, CustomerID FROM Orders"
    Dim myConnection As New MySqlConnection(myConnString)
    Dim myCommand As New MySqlCommand(mySelectQuery, myConnection)
    myConnection.Open()
    Dim myReader As MySqlDataReader
    myReader = myCommand.ExecuteReader()
    ' Always call Read before accessing data.
    While myReader.Read()
        Console.WriteLine((myReader.GetInt32(0) & ", " & myReader.GetString(1)))
    End While
    ' always call Close when done reading.
    myReader.Close()
    ' Close the connection when done with it.
    myConnection.Close()
End Sub 'ReadMyData       
      
23.2.3.5.3.2. C#

The following example shows how to use the MySqlDataReader class with C#:

public void ReadMyData(string myConnString) {
    string mySelectQuery = "SELECT OrderID, CustomerID FROM Orders";
    MySqlConnection myConnection = new MySqlConnection(myConnString);
    MySqlCommand myCommand = new MySqlCommand(mySelectQuery,myConnection);
    myConnection.Open();
    MySqlDataReader myReader;
    myReader = myCommand.ExecuteReader();
    // Always call Read before accessing data.
    while (myReader.Read()) {
       Console.WriteLine(myReader.GetInt32(0) + ", " + myReader.GetString(1));
    }
    // always call Close when done reading.
    myReader.Close();
    // Close the connection when done with it.
    myConnection.Close();
 }     
      

23.2.3.6. The MySqlException Class

This class is created whenever the MySql Data Provider encounters an error generated from the server.

Any open connections are not automatically closed when an exception is thrown. If the client application determines that the exception is fatal, it should close any open MySqlDataReader objects or MySqlConnection objects.

23.2.3.6.1. Properties

The following properties are available:

  • HelpLink: Gets or sets a link to the help file associated with this exception.

  • InnerException: Gets the Exception instance that caused the current exception.

  • IsFatal: True if this exception was fatal and cause the closing of the connection, false otherwise.

  • Message: Gets a message that describes the current exception.

  • Number: Gets a number that identifies the type of error.

  • Source: Gets or sets the name of the application or the object that causes the error.

  • StackTrace: Gets a string representation of the frames on the call stack at the time the current exception was thrown.

  • TargetSite: Gets the method that throws the current exception.

23.2.3.6.2. Methods

The MySqlException class has no methods.

23.2.3.6.3. Usage

The following example generates a MySqlException due to a missing server, and then displays the exception.

23.2.3.6.3.1. VB.NET

This example demonstrates how to use the MySqlException class with VB.NET:

Public Sub ShowException()
     Dim mySelectQuery As String = "SELECT column1 FROM table1"
     Dim myConnection As New MySqlConnection ("Data Source=localhost;Database=Sample;")
     Dim myCommand As New MySqlCommand(mySelectQuery, myConnection)

     Try
         myCommand.Connection.Open()
     Catch e As MySqlException
        MessageBox.Show( e.Message )
     End Try
 End Sub       
      
23.2.3.6.3.2. C#

This example demonstrates how to use the MySqlException class with C#:

public void ShowException() 
{
   string mySelectQuery = "SELECT column1 FROM table1";
   MySqlConnection myConnection =
      new MySqlConnection("Data Source=localhost;Database=Sample;");
   MySqlCommand myCommand = new MySqlCommand(mySelectQuery,myConnection);

   try 
   {
      myCommand.Connection.Open();
   }
   catch (MySqlException e) 
   {
        MessageBox.Show( e.Message );
   }
}
    

23.2.3.7. The MySqlHelper Class

Helper class that makes it easier to work with the provider. Developers can use the methods of this class to automatically perform common tasks.

23.2.3.7.1. Properties

The MySqlHelper class has no properties.

23.2.3.7.2. Methods

The following methods are available:

  • ExecuteDataRow: Executes a single SQL command and returns the first row of the resultset. A new MySqlConnection object is created, opened, and closed during this method.

  • ExecuteDataset: Executes a single SQL command and returns the resultset in a DataSet. A new MySqlConnection object is created, opened, and closed during this method.

  • ExecuteNonQuery: Executes a single command against a MySQL database. The MySqlConnection is assumed to be open when the method is called and remains open after the method completes.

  • ExecuteReader: Overloaded. Executes a single command against a MySQL database.

  • ExecuteScalar: Execute a single command against a MySQL database.

  • UpdateDataSet: Updates the given table with data from the given DataSet.

23.2.3.8. The MySqlTransaction Class

Represents a SQL transaction to be made in a MySQL database.

23.2.3.8.1. Properties

The following properties are available:

  • Connection: Gets the MySqlConnection object associated with the transaction, or a null reference (Nothing in Visual Basic) if the transaction is no longer valid.

  • IsolationLevel: Specifies the IsolationLevel for this transaction.

23.2.3.8.2. Methods

The following methods are available:

  • Commit: Commits the database transaction.

  • Rollback: Rolls back a transaction from a pending state.

23.2.3.8.3. Usage

The following example creates a MySqlConnection and a MySqlTransaction. It also demonstrates how to use the BeginTransaction, Commit, and Rollback methods.

23.2.3.8.3.1. VB.NET

The following example shows how to use the MySqlTransaction class with VB.NET:

Public Sub RunTransaction(myConnString As String)
    Dim myConnection As New MySqlConnection(myConnString)
    myConnection.Open()
    
    Dim myCommand As MySqlCommand = myConnection.CreateCommand()
    Dim myTrans As MySqlTransaction
    
    ' Start a local transaction
    myTrans = myConnection.BeginTransaction()
    ' Must assign both transaction object and connection
    ' to Command object for a pending local transaction
    myCommand.Connection = myConnection
    myCommand.Transaction = myTrans
    
    Try
      myCommand.CommandText = "Insert into Region (RegionID, RegionDescription) VALUES (100, 'Description')"
      myCommand.ExecuteNonQuery()
      myCommand.CommandText = "Insert into Region (RegionID, RegionDescription) VALUES (101, 'Description')"
      myCommand.ExecuteNonQuery()
      myTrans.Commit()
      Console.WriteLine("Both records are written to database.")
    Catch e As Exception
      Try
        myTrans.Rollback()
      Catch ex As MySqlException
        If Not myTrans.Connection Is Nothing Then
          Console.WriteLine("An exception of type " & ex.GetType().ToString() & _
                            " was encountered while attempting to roll back the transaction.")
        End If
      End Try
    
      Console.WriteLine("An exception of type " & e.GetType().ToString() & _
                      "was encountered while inserting the data.")
      Console.WriteLine("Neither record was written to database.")
    Finally
      myConnection.Close()
    End Try
End Sub 'RunTransaction       
      
23.2.3.8.3.2. C#

The following example shows how to use the MySqlTransaction class with C#:

public void RunTransaction(string myConnString) 
 {
    MySqlConnection myConnection = new MySqlConnection(myConnString);
    myConnection.Open();

    MySqlCommand myCommand = myConnection.CreateCommand();
    MySqlTransaction myTrans;

    // Start a local transaction
    myTrans = myConnection.BeginTransaction();
    // Must assign both transaction object and connection
    // to Command object for a pending local transaction
    myCommand.Connection = myConnection;
    myCommand.Transaction = myTrans;

    try
    {
      myCommand.CommandText = "Insert into Region (RegionID, RegionDescription) VALUES (100, 'Description')";
      myCommand.ExecuteNonQuery();
      myCommand.CommandText = "Insert into Region (RegionID, RegionDescription) VALUES (101, 'Description')";
      myCommand.ExecuteNonQuery();
      myTrans.Commit();
      Console.WriteLine("Both records are written to database.");
    }
    catch(Exception e)
    {
      try
      {
        myTrans.Rollback();
      }
      catch (MySqlException ex)
      {
        if (myTrans.Connection != null)
        {
          Console.WriteLine("An exception of type " + ex.GetType() +
                            " was encountered while attempting to roll back the transaction.");
        }
      }
    
      Console.WriteLine("An exception of type " + e.GetType() +
                        " was encountered while inserting the data.");
      Console.WriteLine("Neither record was written to database.");
    }
    finally 
    {
      myConnection.Close();
    }
}       
      

23.2.4. Using MySQL Connector/NET

23.2.4.1. Introduction

In this section we will cover some of the more common use cases for Connector/NET, including BLOB handling, date handling, and using Connector/NET with common tools such as Crystal Reports.

23.2.4.2. Connecting to MySQL Using MySQL Connector/NET

23.2.4.2.1. Introduction

All interaction between a .NET application and the MySQL server is routed through a MySqlConnection object. Before your application can interact with the server, a MySqlConnection object must be instanced, configured, and opened.

Even when using the MySqlHelper class, a MySqlConnection object is created by the helper class.

In this section, we will describe how to connect to MySQL using the MySqlConnection object.

23.2.4.2.2. Creating a Connection String

The MySqlConnection object is configured using a connection string. A connection string contains sever key/value pairs, separated by semicolons. Each key/value pair is joined with an equals sign.

The following is a sample connection string:

    Server=127.0.0.1;Uid=root;Pwd=12345;Database=test;
    

In this example, the MySqlConnection object is configured to connect to a MySQL server at 127.0.0.1, with a username of root and a password of 12345. The default database for all statements will be the test database.

The following options are typically used (a full list of options is available in the API documentation):

  • Server: The name or network address of the instance of MySQL to which to connect. The default is localhost. Aliases include host, Data Source, DataSource, Address, Addr and Network Address.

  • Uid: The MySQL user account to use when connecting. Aliases include User Id, Username and User name.

  • Pwd: The password for the MySQL account being used. Alias Password can also be used.

  • Database: The default database that all statements are applied to. Default is mysql. Alias Initial Catalog can also be used.

  • Port: The port MySQL is using to listen for connections. Default is 3306. Specify -1 for this value to use a named pipe connection.

23.2.4.2.3. Opening a Connection

Once you have created a connection string it can be used to open a connection to the MySQL server.

The following code is used to create a MySqlConnection object, assign the connection string, and open the connection.

[VB]

Dim conn As New MySql.Data.MySqlClient.MySqlConnection
Dim myConnectionString as String

myConnectionString = "server=127.0.0.1;" _
            & "uid=root;" _
            & "pwd=12345;" _
            & "database=test;"

Try
  conn.ConnectionString = myConnectionString
  conn.Open()

Catch ex As MySql.Data.MySqlClient.MySqlException
  MessageBox.Show(ex.Message)
End Try
  

[C#]

MySql.Data.MySqlClient.MySqlConnection conn;
string myConnectionString;
    
myConnectionString = "server=127.0.0.1;uid=root;" +
    "pwd=12345;database=test;";
  
try
{
    conn = new MySql.Data.MySqlClient.MySqlConnection();
    conn.ConnectionString = myConnectionString;
    conn.Open();
}
catch (MySql.Data.MySqlClient.MySqlException ex)
{
    MessageBox.Show(ex.Message);
}

You can also pass the connection string to the constructor of the MySqlConnection class:

[VB]

Dim myConnectionString as String

myConnectionString = "server=127.0.0.1;" _
              & "uid=root;" _
              & "pwd=12345;" _
              & "database=test;" 

Try
    Dim conn As New MySql.Data.MySqlClient.MySqlConnection(myConnectionString)
    conn.Open()
Catch ex As MySql.Data.MySqlClient.MySqlException
   MessageBox.Show(ex.Message)
End Try
  

[C#]

MySql.Data.MySqlClient.MySqlConnection conn;
string myConnectionString;

myConnectionString = "server=127.0.0.1;uid=root;" +
    "pwd=12345;database=test;";

try
{
    conn = new MySql.Data.MySqlClient.MySqlConnection(myConnectionString);
    conn.Open();
}
catch (MySql.Data.MySqlClient.MySqlException ex)
{
    MessageBox.Show(ex.Message);
}

Once the connection is open it can be used by the other MySQL Connector/NET classes to communicate with the MySQL server.

23.2.4.2.4. Handling Connection Errors

Because connecting to an external server is unpredictable, it is important to add error handling to your .NET application. When there is an error connecting, the MySqlConnection class will return a MySqlException object. This object has two properties that are of interest when handling errors:

  • Message: A message that describes the current exception.

  • Number: The MySQL error number.

When handling errors, you can your application's response based on the error number. The two most common error numbers when connecting are as follows:

  • 0: Cannot connect to server.

  • 1045: Invalid username and/or password.

The following code shows how to adapt the application's response based on the actual error:

[VB]

Dim myConnectionString as String

myConnectionString = "server=127.0.0.1;" _
          & "uid=root;" _
          & "pwd=12345;" _
          & "database=test;" 

Try
    Dim conn As New MySql.Data.MySqlClient.MySqlConnection(myConnectionString)
    conn.Open()
Catch ex As MySql.Data.MySqlClient.MySqlException
    Select Case ex.Number
        Case 0
            MessageBox.Show("Cannot connect to server. Contact administrator")
        Case 1045
            MessageBox.Show("Invalid username/password, please try again")
    End Select
End Try
  

[C#]

MySql.Data.MySqlClient.MySqlConnection conn;
string myConnectionString;

myConnectionString = "server=127.0.0.1;uid=root;" +  
    "pwd=12345;database=test;";

try
{
    conn = new MySql.Data.MySqlClient.MySqlConnection(myConnectionString);
    conn.Open();
}
    catch (MySql.Data.MySqlClient.MySqlException ex)
{
    switch (ex.Number)
    {
        case 0:
            MessageBox.Show("Cannot connect to server.  Contact administrator");
        case 1045:
            MessageBox.Show("Invalid username/password, please try again");
    }
}
  

23.2.4.3. Using the MySQL Connector/NET with Prepared Statements

23.2.4.3.1. Introduction

As of MySQL 4.1, it is possible to use prepared statements with MySQL Connector/NET. Use of prepared statements can provide significant performance improvements on queries that are executed more than once.

Prepared execution is faster than direct execution for statements executed more than once, primarily because the query is parsed only once. In the case of direct execution, the query is parsed every time it is executed. Prepared execution also can provide a reduction of network traffic because for each execution of the prepared statement, it is necessary only to send the data for the parameters.

Another advantage of prepared statements is that it uses a binary protocol that makes data transfer between client and server more efficient.

23.2.4.3.2. Preparing Statements in MySQL Connector/NET

To prepare a statement, create a command object and set the .CommandText property to your query.

After entering your statement, call the .Prepare method of the MySqlCommand object. After the statement is prepared, add parameters for each of the dynamic elements in the query.

After you enter your query and enter parameters, execute the statement using the .ExecuteNonQuery(), .ExecuteScalar(), or .ExecuteReader methods.

For subsequent executions, you need only modify the values of the parameters and call the execute method again, there is no need to set the .CommandText property or redefine the parameters.

[VB]

Dim conn As New MySqlConnection
Dim cmd As New MySqlCommand
  
conn.ConnectionString = strConnection

Try
   conn.Open()
   cmd.Connection = conn
 
   cmd.CommandText = "INSERT INTO myTable VALUES(NULL, ?number, ?text)"
   cmd.Prepare()

   cmd.Parameters.Add("?number", 1)
   cmd.Parameters.Add("?text", "One")

   For i = 1 To 1000
       cmd.Parameters("?number").Value = i
       cmd.Parameters("?text").Value = "A string value"

       cmd.ExecuteNonQuery()
     Next 
Catch ex As MySqlException
    MessageBox.Show("Error " & ex.Number & " has occurred: " & ex.Message, "Error", MessageBoxButtons.OK, MessageBoxIcon.Error)
End Try
  

[C#]

MySql.Data.MySqlClient.MySqlConnection conn;
MySql.Data.MySqlClient.MySqlCommand cmd;
  
conn = new MySql.Data.MySqlClient.MySqlConnection();
cmd = new MySql.Data.MySqlClient.MySqlCommand();

conn.ConnectionString = strConnection;

try
{
    conn.Open();
    cmd.Connection = conn;

    cmd.CommandText = "INSERT INTO myTable VALUES(NULL, ?number, ?text)";
    cmd.Prepare();

    cmd.Parameters.Add("?number", 1);
    cmd.Parameters.Add("?text", "One");

    for (int i=1; i <= 1000; i++)
    {
        cmd.Parameters["?number"].Value = i;
        cmd.Parameters["?text"].Value = "A string value";

        cmd.ExecuteNonQuery();
    }
}
catch (MySql.Data.MySqlClient.MySqlException ex)
{
    MessageBox.Show("Error " + ex.Number + " has occurred: " + ex.Message,
        "Error", MessageBoxButtons.OK, MessageBoxIcon.Error);
}

23.2.4.4. Accessing Stored Procedures with MySQL Connector/NET

23.2.4.4.1. Introduction

With the release of MySQL version 5 the MySQL server now supports stored procedures with the SQL 2003 stored procedure syntax.

A stored procedure is a set of SQL statements that can be stored in the server. Once this has been done, clients don't need to keep reissuing the individual statements but can refer to the stored procedure instead.

Stored procedures can be particularly useful in situations such as the following:

  • When multiple client applications are written in different languages or work on different platforms, but need to perform the same database operations.

  • When security is paramount. Banks, for example, use stored procedures for all common operations. This provides a consistent and secure environment, and procedures can ensure that each operation is properly logged. In such a setup, applications and users would not get any access to the database tables directly, but can only execute specific stored procedures.

MySQL Connector/NET supports the calling of stored procedures through the MySqlCommand object. Data can be passed in and our of a MySQL stored procedure through use of the MySqlCommand.Parameters collection.

This section will not provide in-depth information on creating Stored Procedures, for such information please refer to the Stored Procedures section of the MySQL Reference Manual.

A sample application demonstrating how to use stored procedures with MySQL Connector/NET can be found in the Samples directory of your MySQL Connector/NET installation.

23.2.4.4.2. Creating Stored Procedures from MySQL Connector/NET

Stored procedures in MySQL can be created using a variety of tools. First, stored procedures can be created using the mysql command-line client. Second, stored procedures can be created using the MySQL Query Browser GUI client. Finally, stored procedures can be created using the .ExecuteNonQuery method of the MySqlCommand object:

[VB]

Dim conn As New MySqlConnection
Dim cmd As New MySqlCommand

conn.ConnectionString = "server=127.0.0.1;" _
    & "uid=root;" _
    & "pwd=12345;" _
    & "database=test"

Try
    conn.Open()
    cmd.Connection = conn

    cmd.CommandText = "CREATE PROCEDURE add_emp(" _
        & "IN fname VARCHAR(20), IN lname VARCHAR(20), IN bday DATETIME, OUT empno INT) " _
        & "BEGIN INSERT INTO emp(first_name, last_name, birthdate) " _
        & "VALUES(fname, lname, DATE(bday)); SET empno = LAST_INSERT_ID(); END"
 
    cmd.ExecuteNonQuery()
Catch ex As MySqlException
    MessageBox.Show("Error " & ex.Number & " has occurred: " & ex.Message, "Error", MessageBoxButtons.OK, MessageBoxIcon.Error)
End Try

[C#]

MySql.Data.MySqlClient.MySqlConnection conn;
MySql.Data.MySqlClient.MySqlCommand cmd;

conn = new MySql.Data.MySqlClient.MySqlConnection();
cmd = new MySql.Data.MySqlClient.MySqlCommand();

conn.ConnectionString = "server=127.0.0.1;uid=root;" +
    "pwd=12345;database=test;";

try
{
    conn.Open();
    cmd.Connection = conn;

    cmd.CommandText = "CREATE PROCEDURE add_emp(" +
        "IN fname VARCHAR(20), IN lname VARCHAR(20), IN bday DATETIME, OUT empno INT) " +
        "BEGIN INSERT INTO emp(first_name, last_name, birthdate) " +
        "VALUES(fname, lname, DATE(bday)); SET empno = LAST_INSERT_ID(); END";

    cmd.ExecuteNonQuery();
}
catch (MySql.Data.MySqlClient.MySqlException ex)
{
MessageBox.Show("Error " + ex.Number + " has occurred: " + ex.Message,
    "Error", MessageBoxButtons.OK, MessageBoxIcon.Error);
}

It should be noted that, unlike the command-line and GUI clients, you are not required to specify a special delimiter when creating stored procedures in MySQL Connector/NET.

23.2.4.4.3. Calling a Stored Procedure from MySQL Connector/NET

To call a stored procedure using MySQL Connector/NET, create a MySqlCommand object and pass the stored procedure name as the .CommandText property. Set the .CommandType property to CommandType.StoredProcedure.

After the stored procedure is named, create one MySqlCommand parameter for every parameter in the stored procedure. IN parameters are defined with the parameter name and the object containing the value, OUT parameters are defined with the parameter name and the datatype that is expected to be returned. All parameters need the parameter direction defined.

After defining parameters, call the stored procedure by using the MySqlCommand.ExecuteNonQuery() method:

[VB]

Dim conn As New MySqlConnection
Dim cmd As New MySqlCommand

conn.ConnectionString = "server=127.0.0.1;" _
    & "uid=root;" _
    & "pwd=12345;" _
    & "database=test"

Try
    conn.Open()
    cmd.Connection = conn

    cmd.CommandText = "add_emp"
    cmd.CommandType = CommandType.StoredProcedure

    cmd.Parameters.Add("?lname", 'Jones')
    cmd.Parameters("?lname").Direction = ParameterDirection.Input

    cmd.Parameters.Add("?fname", 'Tom')
    cmd.Parameters("?fname").Direction = ParameterDirection.Input

    cmd.Parameters.Add("?bday", #12/13/1977 2:17:36 PM#)
    cmd.Parameters("?bday").Direction = ParameterDirection.Input

    cmd.Parameters.Add("?empno", MySqlDbType.Int32)
    cmd.Parameters("?empno").Direction = ParameterDirection.Output

    cmd.ExecuteNonQuery()

    MessageBox.Show(cmd.Parameters("?empno").Value)
Catch ex As MySqlException
    MessageBox.Show("Error " & ex.Number & " has occurred: " & ex.Message, "Error", MessageBoxButtons.OK, MessageBoxIcon.Error)
End Try

[C#]

MySql.Data.MySqlClient.MySqlConnection conn;
MySql.Data.MySqlClient.MySqlCommand cmd;

conn = new MySql.Data.MySqlClient.MySqlConnection();
cmd = new MySql.Data.MySqlClient.MySqlCommand();

conn.ConnectionString = "server=127.0.0.1;uid=root;" +
    "pwd=12345;database=test;";

try
{
    conn.Open();
    cmd.Connection = conn;

    cmd.CommandText = "add_emp";
    cmd.CommandType = CommandType.StoredProcedure;

    cmd.Parameters.Add("?lname", "Jones");
    cmd.Parameters("?lname").Direction = ParameterDirection.Input;

    cmd.Parameters.Add("?fname", "Tom");
    cmd.Parameters("?fname").Direction = ParameterDirection.Input;

    cmd.Parameters.Add("?bday", DateTime.Parse("12/13/1977 2:17:36 PM"));
    cmd.Parameters("?bday").Direction = ParameterDirection.Input;

    cmd.Parameters.Add("?empno", MySqlDbType.Int32);
    cmd.Parameters("?empno").Direction = ParameterDirection.Output;

    cmd.ExecuteNonQuery();

    MessageBox.Show(cmd.Parameters("?empno").Value);
}
catch (MySql.Data.MySqlClient.MySqlException ex)
{
    MessageBox.Show("Error " + ex.Number + " has occurred: " + ex.Message,
      "Error", MessageBoxButtons.OK, MessageBoxIcon.Error);
}

Once the stored procedure is called, the values of output parameters can be retrieved by using the .Value property of the MySqlConnector.Parameters collection.

23.2.4.5. Handling BLOB Data With Connector/NET

23.2.4.5.1. Introduction

One common use for MySQL is the storage of binary data in BLOB columns. MySQL supports four different BLOB datatypes: TINYBLOB, BLOB, MEDIUMBLOB, and LONGBLOB.

Data stored in a BLOB column can be accessed using Connector/NET and manipulated using client-side code. There are no special requirements for using Connector/NET with BLOB data.

Simple code examples will be presented within this section, and a full sample application can be found in the Samples directory of the MySQL Connector/NET installation.

23.2.4.5.2. Preparing the MySQL Server

The first step is using MySQL with BLOB data is to configure the server. Let's start by creating a table to be accessed. In my file tables, I usually have four columns: an AUTO_INCREMENT column of appropriate size (UNSIGNED SMALLINT) to serve as a primary key to identify the file, a VARCHAR column that stores the filename, an UNSIGNED MEDIUMINT column that stores the size of the file, and a MEDIUMBLOB column that stores the file itself. For this example, I will use the following table definition:

CREATE TABLE file(
file_id SMALLINT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
file_name VARCHAR(64) NOT NULL,
file_size MEDIUMINT UNSIGNED NOT NULL,
file MEDIUMBLOB NOT NULL);

After creating a table, you may need to modify the max_allowed_packet system variable. This variable determines how large of a packet (i.e. a single row) can be sent to the MySQL server. By default, the server will only accept a maximum size of 1 meg from our client application. If you do not intend to exceed 1 meg, this should be fine. If you do intend to exceed 1 meg in your file transfers, this number has to be increased.

The max_allowed_packet option can be modified using MySQL Administrator's Startup Variables screen. Adjust the Maximum allowed option in the Memory section of the Networking tab to an appropriate setting. After adjusting the value, click the Apply Changes button and restart the server using the Service Control screen of MySQL Administrator. You can also adjust this value directly in the my.cnf file (add a line that reads max_allowed_packet=xxM), or use the SET max_allowed_packet=xxM; syntax from within MySQL.

Try to be conservative when setting max_allowed_packet, as transfers of BLOB data can take some time to complete. Try to set a value that will be adequate for your intended use and increase the value if necessary.

23.2.4.5.3. Writing a File to the Database

To write a file to a database we need to convert the file to a byte array, then use the byte array as a parameter to an INSERT query.

The following code opens a file using a FileStream object, reads it into a byte array, and inserts it into the file table:

[VB]

Dim conn As New MySqlConnection
Dim cmd As New MySqlCommand

Dim SQL As String

Dim FileSize As UInt32
Dim rawData() As Byte
Dim fs As FileStream

conn.ConnectionString = "server=127.0.0.1;" _
    & "uid=root;" _
    & "pwd=12345;" _
    & "database=test"

Try
    fs = New FileStream("c:\image.png", FileMode.Open, FileAccess.Read)
    FileSize = fs.Length
    
    rawData = New Byte(FileSize) {}
    fs.Read(rawData, 0, FileSize)
    fs.Close()
    
    conn.Open()
    
    SQL = "INSERT INTO file VALUES(NULL, ?FileName, ?FileSize, ?File)"
    
    cmd.Connection = conn
    cmd.CommandText = SQL
    cmd.Parameters.Add("?FileName", strFileName)
    cmd.Parameters.Add("?FileSize", FileSize)
    cmd.Parameters.Add("?File", rawData)
    
    cmd.ExecuteNonQuery()
    
    MessageBox.Show("File Inserted into database successfully!", _
    "Success!", MessageBoxButtons.OK, MessageBoxIcon.Asterisk)
    
    conn.Close()
Catch ex As Exception
    MessageBox.Show("There was an error: " & ex.Message, "Error", _
        MessageBoxButtons.OK, MessageBoxIcon.Error)
End Try
  

[C#]

MySql.Data.MySqlClient.MySqlConnection conn;
MySql.Data.MySqlClient.MySqlCommand cmd;

conn = new MySql.Data.MySqlClient.MySqlConnection();
cmd = new MySql.Data.MySqlClient.MySqlCommand();

string SQL;
UInt32 FileSize;
byte[] rawData;
FileStream fs;

conn.ConnectionString = "server=127.0.0.1;uid=root;" +
    "pwd=12345;database=test;";

try
{
    fs = new FileStream(@"c:\image.png", FileMode.Open, FileAccess.Read);
    FileSize = fs.Length;

    rawData = new byte[FileSize];
    fs.Read(rawData, 0, FileSize);
    fs.Close();

    conn.Open();

    SQL = "INSERT INTO file VALUES(NULL, ?FileName, ?FileSize, ?File)";

    cmd.Connection = conn;
    cmd.CommandText = SQL;
    cmd.Parameters.Add("?FileName", strFileName);
    cmd.Parameters.Add("?FileSize", FileSize);
    cmd.Parameters.Add("?File", rawData);

    cmd.ExecuteNonQuery();

    MessageBox.Show("File Inserted into database successfully!",
        "Success!", MessageBoxButtons.OK, MessageBoxIcon.Asterisk);

    conn.Close();
}
catch (MySql.Data.MySqlClient.MySqlException ex)
{
    MessageBox.Show("Error " + ex.Number + " has occurred: " + ex.Message,
        "Error", MessageBoxButtons.OK, MessageBoxIcon.Error);
}
 

The Read method of the FileStream object is used to load the file into a byte array which is sized according to the Length property of the FileStream object.

After assigning the byte array as a parameter of the MySqlCommand object, the ExecuteNonQuery method is called and the BLOB is inserted into the file table.

23.2.4.5.4. Reading a BLOB from the Database to a File on Disk

Once a file is loaded into the file table, we can use the MySqlDataReader class to retrieve it.

The following code retrieves a row from the file table, then loads the data into a FileStream object to be written to disk:

[VB]

Dim conn As New MySqlConnection
Dim cmd As New MySqlCommand
Dim myData As MySqlDataReader
Dim SQL As String
Dim rawData() As Byte
Dim FileSize As UInt32
Dim fs As FileStream

conn.ConnectionString = "server=127.0.0.1;" _
    & "uid=root;" _
    & "pwd=12345;" _
    & "database=test"

SQL = "SELECT file_name, file_size, file FROM file"

Try
    conn.Open()
    
    cmd.Connection = conn
    cmd.CommandText = SQL
    
    myData = cmd.ExecuteReader
    
    If Not myData.HasRows Then Throw New Exception("There are no BLOBs to save")
    
    myData.Read()
    
    FileSize = myData.GetUInt32(myData.GetOrdinal("file_size"))
    rawData = New Byte(FileSize) {}
    
    myData.GetBytes(myData.GetOrdinal("file"), 0, rawData, 0, FileSize)
    
    fs = New FileStream("C:\newfile.png", FileMode.OpenOrCreate, FileAccess.Write)
    fs.Write(rawData, 0, FileSize)
    fs.Close()
    
    MessageBox.Show("File successfully written to disk!", "Success!", MessageBoxButtons.OK, MessageBoxIcon.Asterisk)
    
    myData.Close()
    conn.Close()
Catch ex As Exception
    MessageBox.Show("There was an error: " & ex.Message, "Error", MessageBoxButtons.OK, MessageBoxIcon.Error)
End Try
  

[C#]

MySql.Data.MySqlClient.MySqlConnection conn;
MySql.Data.MySqlClient.MySqlCommand cmd;
MySql.Data.MySqlClient.MySqlDataReader myData;

conn = new MySql.Data.MySqlClient.MySqlConnection();
cmd = new MySql.Data.MySqlClient.MySqlCommand();

string SQL;
UInt32 FileSize;
byte[] rawData;
FileStream fs;

conn.ConnectionString = "server=127.0.0.1;uid=root;" +
    "pwd=12345;database=test;";

SQL = "SELECT file_name, file_size, file FROM file";

try
{
    conn.Open();

    cmd.Connection = conn;
    cmd.CommandText = SQL;

    myData = cmd.ExecuteReader();

    if (! myData.HasRows)
        throw new Exception("There are no BLOBs to save");

    myData.Read();

    FileSize = myData.GetUInt32(myData.GetOrdinal("file_size"));
    rawData = new byte[FileSize];

    myData.GetBytes(myData.GetOrdinal("file"), 0, rawData, 0, FileSize);

    fs = new FileStream(@"C:\newfile.png", FileMode.OpenOrCreate, FileAccess.Write);
    fs.Write(rawData, 0, FileSize);
    fs.Close();

    MessageBox.Show("File successfully written to disk!",
        "Success!", MessageBoxButtons.OK, MessageBoxIcon.Asterisk);

    myData.Close();
    conn.Close();
}
catch (MySql.Data.MySqlClient.MySqlException ex)
{
    MessageBox.Show("Error " + ex.Number + " has occurred: " + ex.Message,
        "Error", MessageBoxButtons.OK, MessageBoxIcon.Error);
}
 

After connecting, the contents of the file table are loaded into a MySqlDataReader object. The GetBytes method of the MySqlDataReader is used to load the BLOB into a byte array, which is then written to disk using a FileStream object.

The GetOrdinal method of the MySqlDataReader can be used to determine the integer index of a named column. Use of the GetOrdinal method prevents errors if the column order of the SELECT query is changed.

23.2.4.6. Using MySQL Connector/NET with Crystal Reports

23.2.4.6.1. Introduction

Crystal Reports is a common tool used by Windows application developers to perform reporting an document generation. In this section we will show how to use Crystal Reports XI with MySQL and Connector/NET.

Complete sample applications are available in the CrystalDemo subdirectory of the Samples directory of your MySQL Connector/NET installation.

23.2.4.6.2. Creating a Data Source

When creating a report in Crystal Reports there are two options for accessing the MySQL data while designing your report.

The first option is to use Connector/ODBC as an ADO data source when designing your report. You will be able to browse your database and choose tables and fields using drag and drop to build your report. The disadvantage of this approach is that additional work must be performed within your application to produce a dataset that matches the one expected by your report.

The second option is to create a dataset in VB.NET and save it as XML. This XML file can then be used to design a report. This works quite well when displaying the report in your application, but is less versatile at design time because you must choose all relevant columns when creating the dataset. If you forget a column you must re-create the dataset before the column can be added to the report.

The following code can be used to create a dataset from a query and write it to disk:

[VB]

Dim myData As New DataSet
Dim conn As New MySqlConnection
Dim cmd As New MySqlCommand
Dim myAdapter As New MySqlDataAdapter

conn.ConnectionString = "server=127.0.0.1;" _
    & "uid=root;" _
    & "pwd=12345;" _
    & "database=world"

Try
    conn.Open()
    cmd.CommandText = "SELECT city.name AS cityName, city.population AS CityPopulation, " _ 
        & "country.name, country.population, country.continent " _
        & "FROM country, city ORDER BY country.continent, country.name"
    cmd.Connection = conn
    
    myAdapter.SelectCommand = cmd
    myAdapter.Fill(myData)
    
    myData.WriteXml("C:\dataset.xml", XmlWriteMode.WriteSchema)
Catch ex As Exception
    MessageBox.Show(ex.Message, "Report could not be created", MessageBoxButtons.OK, MessageBoxIcon.Error)
End Try
 

[C#]

DataSet myData = new DataSet();
MySql.Data.MySqlClient.MySqlConnection conn;
MySql.Data.MySqlClient.MySqlCommand cmd;
MySql.Data.MySqlClient.MySqlDataAdapter myAdapter;

conn = new MySql.Data.MySqlClient.MySqlConnection();
cmd = new MySql.Data.MySqlClient.MySqlCommand();
myAdapter = new MySql.Data.MySqlClient.MySqlDataAdapter();

conn.ConnectionString = "server=127.0.0.1;uid=root;" +
  "pwd=12345;database=test;";
  
try
{
  cmd.CommandText = "SELECT city.name AS cityName, city.population AS CityPopulation, " +
  "country.name, country.population, country.continent " +
  "FROM country, city ORDER BY country.continent, country.name";
  cmd.Connection = conn;
  
  myAdapter.SelectCommand = cmd;
  myAdapter.Fill(myData);
  
  myData.WriteXml(@"C:\dataset.xml", XmlWriteMode.WriteSchema);
}
catch (MySql.Data.MySqlClient.MySqlException ex)
{
  MessageBox.Show(ex.Message, "Report could not be created",
  MessageBoxButtons.OK, MessageBoxIcon.Error);
}

The resulting XML file can be used as an ADO.NET XML datasource when designing your report.

If you choose to design your reports using Connector/ODBC, it can be downloaded from dev.mysql.com.

23.2.4.6.3. Creating the Report

For most purposes the Standard Report wizard should help with the initial creation of a report. To start the wizard, open Crystal Reports and choose the New > Standard Report option from the File menu.

The wizard will first prompt you for a data source. If you are using Connector/ODBC as your data source, use the OLEDB provider for ODBC option from the OLE DB (ADO) tree instead of the ODBC (RDO) tree when choosing a data source. If using a saved dataset, choose the ADO.NET (XML) option and browse to your saved dataset.

The remainder of the report creation process is done automatically by the wizard.

After the report is created, choose the Report Options... entry of the File menu. Un-check the Save Data With Report option. This prevents saved data from interfering with the loading of data within our application.

23.2.4.6.4. Displaying the Report

To display a report we first populate a dataset with the data needed for the report, then load the report and bind it to the dataset. Finally we pass the report to the crViewer control for display to the user.

The following references are needed in a project that displays a report:

  • CrytalDecisions.CrystalReports.Engine

  • CrystalDecisions.ReportSource

  • CrystalDecisions.Shared

  • CrystalDecisions.Windows.Forms

The following code assumes that you created your report using a dataset saved using the code shown in Creating a Data Source and have a crViewer control on your form named myViewer.

[VB]

Imports CrystalDecisions.CrystalReports.Engine
Imports System.Data
Imports MySql.Data.MySqlClient

Dim myReport As New ReportDocument
Dim myData As New DataSet
Dim conn As New MySqlConnection
Dim cmd As New MySqlCommand
Dim myAdapter As New MySqlDataAdapter

conn.ConnectionString = _
    "server=127.0.0.1;" _
    & "uid=root;" _
    & "pwd=12345;" _
    & "database=test"

Try
    conn.Open()
    
    cmd.CommandText = "SELECT city.name AS cityName, city.population AS CityPopulation, " _ 
        & "country.name, country.population, country.continent " _
        & "FROM country, city ORDER BY country.continent, country.name"
    cmd.Connection = conn
    
    myAdapter.SelectCommand = cmd
    myAdapter.Fill(myData)
    
    myReport.Load(".\world_report.rpt")
    myReport.SetDataSource(myData)
    myViewer.ReportSource = myReport
Catch ex As Exception
    MessageBox.Show(ex.Message, "Report could not be created", MessageBoxButtons.OK, MessageBoxIcon.Error)
End Try

[C#]

using CrystalDecisions.CrystalReports.Engine;
using System.Data;
using MySql.Data.MySqlClient;

ReportDocument myReport = new ReportDocument();
DataSet myData = new DataSet();
MySql.Data.MySqlClient.MySqlConnection conn;
MySql.Data.MySqlClient.MySqlCommand cmd;
MySql.Data.MySqlClient.MySqlDataAdapter myAdapter;

conn = new MySql.Data.MySqlClient.MySqlConnection();
cmd = new MySql.Data.MySqlClient.MySqlCommand();
myAdapter = new MySql.Data.MySqlClient.MySqlDataAdapter();

conn.ConnectionString = "server=127.0.0.1;uid=root;" +
    "pwd=12345;database=test;";

try
{
    cmd.CommandText = "SELECT city.name AS cityName, city.population AS CityPopulation, " +
        "country.name, country.population, country.continent " +
        "FROM country, city ORDER BY country.continent, country.name";
    cmd.Connection = conn;

    myAdapter.SelectCommand = cmd;
    myAdapter.Fill(myData);

    myReport.Load(@".\world_report.rpt");
    myReport.SetDataSource(myData);
    myViewer.ReportSource = myReport;
}
catch (MySql.Data.MySqlClient.MySqlException ex)
{
    MessageBox.Show(ex.Message, "Report could not be created",
        MessageBoxButtons.OK, MessageBoxIcon.Error);
}

A new dataset it generated using the same query used to generate the previously saved dataset. Once the dataset is filled, a ReportDocument is used to load the report file and bind it to the dataset. The ReportDocument is the passed as the ReportSource of the crViewer.

This same approach is taken when a report is created from a single table using Connector/ODBC. The dataset replaces the table used in the report and the report is displayed properly.

When a report is created from multiple tables using Connector/ODBC, a dataset with multiple tables must be created in our application. This allows each table in the report data source to be replaced with a report in the dataset.

We populate a dataset with multiple tables by providing multiple SELECT statements in our MySqlCommand object. These SELECT statements are based on the SQL query shown in Crystal Reports in the Database menu's Show SQL Query option. Assume the following query:

SELECT `country`.`Name`, `country`.`Continent`, `country`.`Population`, `city`.`Name`, `city`.`Population`
FROM `world`.`country` `country` LEFT OUTER JOIN `world`.`city` `city` ON `country`.`Code`=`city`.`CountryCode`
ORDER BY `country`.`Continent`, `country`.`Name`, `city`.`Name`

This query is converted to two SELECT queries and displayed with the following code:

[VB]

Imports CrystalDecisions.CrystalReports.Engine
Imports System.Data
Imports MySql.Data.MySqlClient

Dim myReport As New ReportDocument
Dim myData As New DataSet
Dim conn As New MySqlConnection
Dim cmd As New MySqlCommand
Dim myAdapter As New MySqlDataAdapter

conn.ConnectionString = "server=127.0.0.1;" _
    & "uid=root;" _
    & "pwd=12345;" _
    & "database=world"

Try
    conn.Open()
    cmd.CommandText = "SELECT name, population, countrycode FROM city ORDER BY countrycode, name; " _
        & "SELECT name, population, code, continent FROM country ORDER BY continent, name"
    cmd.Connection = conn
    
    myAdapter.SelectCommand = cmd
    myAdapter.Fill(myData)
    
    myReport.Load(".\world_report.rpt")
    myReport.Database.Tables(0).SetDataSource(myData.Tables(0))
    myReport.Database.Tables(1).SetDataSource(myData.Tables(1))
    myViewer.ReportSource = myReport
Catch ex As Exception
    MessageBox.Show(ex.Message, "Report could not be created", MessageBoxButtons.OK, MessageBoxIcon.Error)
End Try

[C#]

using CrystalDecisions.CrystalReports.Engine;
using System.Data;
using MySql.Data.MySqlClient;

ReportDocument myReport = new ReportDocument();
DataSet myData = new DataSet();
MySql.Data.MySqlClient.MySqlConnection conn;
MySql.Data.MySqlClient.MySqlCommand cmd;
MySql.Data.MySqlClient.MySqlDataAdapter myAdapter;

conn = new MySql.Data.MySqlClient.MySqlConnection();
cmd = new MySql.Data.MySqlClient.MySqlCommand();
myAdapter = new MySql.Data.MySqlClient.MySqlDataAdapter();

conn.ConnectionString = "server=127.0.0.1;uid=root;" +
    "pwd=12345;database=test;";

try
{
    cmd.CommandText = "SELECT name, population, countrycode FROM city ORDER " +
        "BY countrycode, name; SELECT name, population, code, continent FROM " +
        "country ORDER BY continent, name";
    cmd.Connection = conn;

    myAdapter.SelectCommand = cmd;
    myAdapter.Fill(myData);

    myReport.Load(@".\world_report.rpt");
    myReport.Database.Tables(0).SetDataSource(myData.Tables(0));
    myReport.Database.Tables(1).SetDataSource(myData.Tables(1));
    myViewer.ReportSource = myReport;
}
catch (MySql.Data.MySqlClient.MySqlException ex)
{
    MessageBox.Show(ex.Message, "Report could not be created",
        MessageBoxButtons.OK, MessageBoxIcon.Error);
}  
 

It is important to order the SELECT queries in alphabetical order, as this is the order the report will expect its source tables to be in. One SetDataSource statement is needed for each table in the report.

This approach can cause performance problems because Crystal Reports must bind the tables together on the client-side, which will be slower than using a pre-saved dataset.

23.2.4.7. Handling Date and Time Information in MySQL Connector/NET

23.2.4.7.1. Introduction

MySQL and the .NET languages handle date and time information differently, with MySQL allowing dates that cannot be represented by a .NET data type, such as '0000-00-00 00:00:00'. These differences can cause problems if not properly handled.

In this section we will demonstrate how to properly handle date and time information when using MySQL Connector/NET.

23.2.4.7.2. Problems when Using Invalid Dates

The differences in date handling can cause problems for developers who use invalid dates. Invalid MySQL dates cannot be loaded into native .NET DateTime objects, including NULL dates.

Because of this issue, .NET DataSet objects cannot be populated by the Fill method of the MySqlDataAdapter class as invalid dates will cause a System.ArgumentOutOfRangeException exception to occur.

23.2.4.7.3. Restricting Invalid Dates

The best solution to the date problem is to restrict users from entering invalid dates. This can be done on either the client or the server side.

Restricting invalid dates on the client side is as simple as always using the .NET DateTime class to handle dates. The DateTime class will only allow valid dates, ensuring that the values in your database are also valid. The disadvantage of this is that it is not useful in a mixed environment where .NET and non .NET code are used to manipulate the database, as each application must perform its own date validation.

Users of MySQL 5.0.2 and higher can use the new traditional SQL mode to restrict invalid date values. For information on using the traditional SQL mode, see http://dev.mysql.com/doc/mysql/en/server-sql-mode.html.

23.2.4.7.4. Handling Invalid Dates

While it is strongly recommended that you avoid the use of invalid dates within your .NET application, it is possible to use invalid dates by means of the MySqlDateTime datatype.

The MySqlDateTime datatype supports the same date values that are supported by the MySQL server. The default behavior of MySQL Connector/NET is to return a .NET DateTime object for valid date values, and return an error for invalid dates. This default can be modified to cause MySQL Connector/NET to return MySqlDateTime objects for invalid dates.

To instruct MySQL Connector/NET to return a MySqlDateTime object for invalid dates, add the following line to your connection string:

  Allow Zero Datetime=True
  

Please note that the use of the MySqlDateTime class can still be problematic. The following are some known issues:

  1. Data binding for invalid dates can still cause errors (zero dates like 0000-00-00 do not seem to have this problem).

  2. The ToString method return a date formatted in the standard MySQL format (for example, 2005-02-23 08:50:25). This differs from the ToString behavior of the .NET DateTime class.

  3. The MySqlDateTime class supports NULL dates, while the .NET DateTime class does not. This can cause errors when trying to convert a MySQLDateTime to a DateTime if you do not check for NULL first.

Because of the known issues, the best recommendation is still to use only valid dates in your application.

23.2.4.7.5. Handling NULL Dates

The .NET DateTime datatype cannot handle NULL values. As such, when assigning values from a query to a DateTime variable, you must first check whether the value is in fact NULL.

When using a MySqlDataReader, use the .IsDBNull method to check whether a value is NULL before making the assignment:

[VB]

If Not myReader.IsDBNull(myReader.GetOrdinal("mytime")) Then
    myTime = myReader.GetDateTime(myReader.GetOrdinal("mytime"))
Else
    myTime = DateTime.MinValue
End If
  

[C#]

if (! myReader.IsDBNull(myReader.GetOrdinal("mytime")))
    myTime = myReader.GetDateTime(myReader.GetOrdinal("mytime"));
else
    myTime = DateTime.MinValue;
  

NULL values will work in a dataset and can be bound to form controls without special handling.

23.2.5. MySQL Connector/NET Change History

23.2.5.1. Version 2.0.0

  • Fixed an exception when trying to use a stored procedure when Connection.Database is not populated. (Bug #11450)

  • Certain malformed queries will trigger a "Connection must be valid and open" error message. (Bug #11490)

23.2.5.2. Version 1.0.7

  • A #42000Query was empty exception occurred when executing a query built with MySqlCommandBuilder, if the query string ended with a semicolon. (Bug #14631)

  • Implemented the MySqlCommandBuilder.DeriveParameters method that is used to discover the parameters for a stored procedure. (Bug #13632)

  • Added support for the cp932 character set. (Bug #13806)

  • Calling a stored procedure where a parameter contained special characters (such as '@') would produce an exception. Note that ANSI_QUOTES had to be enabled to make this possible. (Bug #13753)

  • A statement that contained multiple references to the same parameter could not be prepared. (Bug #13541)

  • The Ping() method did not update the State property of the Connection object. (Bug #13658)

23.2.5.3. Version 1.0.6

  • The nant build sequence had problems. (Bug #12978)

  • Serializing a parameter failed if the first value passed in was NULL. (Bug #13276)

  • Field names that contained the following characters caused errors: ()%<>/ (Bug #13036)

  • The MySQL Connector/NET 1.0.5 installer would not install alongside MySQL Connector/NET 1.0.4. (Bug #12835)

  • MySQL Connector/NET 1.0.5 could not connect on Mono. (Bug #13345)

23.2.5.4. Version 1.0.5

  • With multiple hosts in the connection string, MySQL Connector/NET would not connect to the last host in the list. (Bug #12628)

  • MySQL Connector/NET interpreted the new decimal data type as a byte array. (Bug #11294)

  • The cp1250 character set was not supported. (Bug #11621)

  • Connection could fail when .NET thread pool had no available worker threads. (Bug #10637)

  • Decimal parameters caused syntax errors. (Bug #11550, Bug #10486, Bug #10152)

  • A call to a stored procedure caused an exception if the stored procedure had no parameters. (Bug #11542)

  • Certain malformed queries would trigger a Connection must be valid and open error message. (Bug #11490)

  • The MySqlCommandBuilder class could not handle queries that referenced tables in a database other than the default database. (Bug #8382)

  • MySQL Connector/NET could not work properly with certain regional settings. (WL#8228)

  • Trying to use a stored procedure when Connection.Database was not populated generated an exception. (Bug #11450)

  • Trying to read a TIMESTAMP column generated an exception. (Bug #7951)

  • Parameters were not recognised when they were separated by linefeeds. (Bug #9722)

  • Calling MySqlConnection.clone when a connection string had not yet been set on the original connection would generate an error. (Bug #10281)

  • Added support to call a stored function from MySQL Connector/NET. (Bug #10644)

  • MySQL Connector/NET could not connect to MySQL 4.1.14. (Bug #12771)

  • The ConnectionString property could not be set when a MySqlConnection object was added with the designer. (Bug #12551, Bug #8724)

23.2.5.5. Version 1.0.4 1-20-05

  • Bug #7243 calling prepare causing exception [fixed]

  • Fixed another small problem with prepared statements

  • Bug #7258 MySqlCommand.Connection returns an IDbConnection [fixed]

  • Bug #7345 MySqlAdapter.Fill method throws Error message : Non-negative number required [fixed]

  • Bug #7478 Clone method bug in MySqlCommand [fixed]

  • Bug #7612 MySqlDataReader.GetString(index) returns non-Null value when field is Null [fixed]

  • Bug #7755 MySqlReader.GetInt32 throws exception if column is unsigned [fixed]

  • Bug #7704 GetBytes is working no more [fixed]

  • Bug #7724 Quote character \222 not quoted in EscapeString [fixed]

  • Fixed problem that causes named pipes to not work with some blob functionality

  • Fixed problem with shared memory connections

  • Bug #7436 Problem with Multiple resultsets... [fixed]

  • Added or filled out several more topics in the API reference documentation

23.2.5.6. Version 1.0.3-gamma 12-10-04

  • Made MySQL the default named pipe name

  • Now SHOW COLLATION is used upon connection to retrieve the full list of charset ids

  • Fixed Invalid character set index: 200 (Bug #6547)

  • Installer now includes options to install into GAC and create Start Menu items

  • Bug #6863 - Int64 Support in MySqlCommand Parameters [fixed]

  • Connections now do not have to give a database on the connection string

  • Bug #6770 - MySqlDataReader.GetChar(int i) throws IndexOutOfRange Exception [fixed]

  • Fixed problem where multiple resultsets having different numbers of columns would cause a problem

  • Bug #6983 Exception stack trace lost when re-throwing exceptions [fixed]

  • Fixed major problem with detecting null values when using prepared statements

  • Bug #6902 Errors in parsing stored procedure parameters [fixed]

  • Bug #6668 Integer "out" parameter from stored procedure returned as string [fixed]

  • Bug #7032 MySqlDateTime in Datatables sorting by Text, not Date. [fixed]

  • Bug #7133 Invalid query string when using inout parameters [fixed]

  • Bug #6831 Test suite fails with MySQL 4.0 because of case sensitivity of table names [fixed]

  • Bug #7132 Inserting DateTime causes System.InvalidCastException to be thrown [fixed]

  • Bug #6879 InvalidCast when using DATE_ADD-function [fixed]

  • Bug #6634 An Open Connection has been Closed by the Host System [fixed]

  • Added ServerThread property to MySqlConnection to expose server thread id

  • Added Ping method to MySqlConnection

  • Changed the name of the test suite to MySql.Data.Tests.dll

23.2.5.7. Version 1.0.2-gamma 04-11-15

  • Fixed problem with MySqlBinary where string values could not be used to update extended text columns

  • Fixed Installation directory ignored using custom installation (Bug #6329)

  • Fixed problem where setting command text leaves the command in a prepared state

  • Fixed double type handling in MySqlParameter(string parameterName, object value) (Bug #6428)

  • Fixed Zero date "0000-00-00" is returned wrong when filling Dataset (Bug #6429)

  • Fixed problem where calling stored procedures might cause an "Illegal mix of collations" problem.

  • Added charset connection string option

  • Fixed #HY000 Illegal mix of collations (latin1_swedish_ci,IMPLICIT) and (utf8_general_ (Bug #6322)

  • Added the TableEditor CS and VB sample

  • Fixed Charset-map for UCS-2 (Bug #6541)

  • Updated the installer to include the new samples

  • Fixed Long inserts take very long time (Bu #5453)

  • Fixed Objects not being disposed (Bug #6649)

  • Provider is now using character set specified by server as default

23.2.5.8. Version 1.0.1-beta2 04-10-27

  • Fixed BUG #5602 Possible bug in MySqlParameter(string, object) constructor

  • Fixed BUG #5458 Calling GetChars on a longtext column throws an exception

  • Fixed BUG #5474 cannot run a stored procedure populating mysqlcommand.parameters

  • Fixed BUG #5469 Setting DbType throws NullReferenceException

  • Fixed problem where connector was not issuing a CMD_QUIT before closing the socket

  • Fixed BUG #5392 MySqlCommand sees "?" as parameters in string literals

  • Fixed problem with ConnectionInternal where a key might be added more than once

  • CP1252 is now used for Latin1 only when the server is 4.1.2 and later

  • Fixed BUG #5388 DataReader reports all rows as NULL if one row is NULL

  • Virtualized driver subsystem so future releases could easily support client or embedded server support

  • Field buffers being reused to decrease memory allocations and increase speed

  • Fixed problem where using old syntax while using the interfaces caused problems

  • Using PacketWriter instead of Packet for writing to streams

  • Refactored compression code into CompressedStream to clean up NativeDriver

  • Added test case for resetting the command text on a prepared command

  • Fixed problem where MySqlParameterCollection.Add() would throw unclear exception when given a null value (Bug #5621)

  • Fixed construtor initialize problems in MySqlCommand() (Bug #5613)

  • Fixed Parsing the ';' char (Bug #5876)

  • Fixed missing Reference in DbType setter (Bug #5897)

  • Fixed System.OverflowException when using YEAR datatype (Bug #6036)

  • Added Aggregate function test (wasn't really a bug)

  • Fixed serializing of floating point parameters (double, numeric, single, decimal) (Bug #5900)

  • IsNullable error (Bug #5796)

  • Fixed problem where connection lifetime on the connect string was not being respected

  • Fixed problem where Min Pool Size was not being respected

  • Fixed MySqlDataReader and 'show tables from ...' behavior (Bug #5256)

  • Implemented SequentialAccess

  • Fixed MySqlDateTime sets IsZero property on all subseq.records after first zero found (Bug #6006)

  • Fixed Can't display Chinese correctly (Bug #5288)

  • Fixed Russian character support as well

  • Fixed Method TokenizeSql() uses only a limited set of valid characters for parameters (Bug #6217)

  • Fixed NET Connector source missing resx files (Bug #6216)

  • Fixed DBNull Values causing problems with retrieving/updating queries. (Bug #5798)

  • Fixed Yet Another "object reference not set to an instance of an object" (Bug #5496)

  • Fixed problem in PacketReader where it could try to allocate the wrong buffer size in EnsureCapacity

  • Fixed GetBoolean returns wrong values (Bug #6227)

  • Fixed IndexOutOfBounds when reading BLOB with DataReader with GetString(index) (Bug #6230)

23.2.5.9. Version 1.0.0 04-09-01

  • Fixed BUG# 3889 Thai encoding not correctly supported

  • Updated many of the test cases

  • Fixed problem with using compression

  • Bumped version number to 1.0.0 for beta 1 release

  • Added COPYING.rtf file for use in installer

  • Removed all of the XML comment warnings (I'll clean them up better later)

  • Removed some last references to ByteFX

23.2.5.10. Version 0.9.0 04-08-30

  • Added test fixture for prepared statements

  • All type classes now implement a SerializeBinary method for sending their data to a PacketWriter

  • Added PacketWriter class that will enable future low-memory large object handling

  • Fixed many small bugs in running prepared statements and stored procedures

  • Changed command so that an exception will not be throw in executing a stored procedure with parameters in old syntax mode

  • SingleRow behavior now working right even with limit

  • GetBytes now only works on binary columns

  • Logger now truncates long sql commands so blob columns don't blow out our log

  • host and database now have a default value of "" unless otherwise set

  • FIXED BUG# 5214 Connection Timeout seems to be ignored

  • Added test case for bug# 5051: GetSchema not working correctly

  • Fixed problem where GetSchema would return false for IsUnique when the column is key

  • MySqlDataReader GetXXX methods now using the field level MySqlValue object and not performing conversions

  • FIXED BUG# 5097: DataReader returning NULL for time column

  • Added test case for LOAD DATA LOCAL INFILE

  • Added replacetext custom nant task

  • Added CommandBuilderTest fixture

  • Added Last One Wins feature to CommandBuilder

  • Fixed persist security info case problem

  • Fixed GetBool so that 1, true, "true", and "yes" all count as trueWL# 2024 Make parameter mark configurable

  • Added the "old syntax" connection string parameter to allow use of @ parameter marker

  • Fixed Bug #4658 MySqlCommandBuilder

  • Fixed Bug #4864 ByteFX.MySqlClient caches passwords if 'Persist Security Info' is false

  • Updated license banner in all source files to include FLOSS exception

  • Added new .Types namespace and implementations for most current MySql types

  • Added MySqlField41 as a subclass of MySqlField

  • Changed many classes to now use the new .Types types

  • Changed type enum int to Int32, short to Int16, and bigint to Int64

  • Added dummy types UInt16, UInt32, and UInt64 to allow an unsigned parameter to be made

  • Connections are now reset when they are pulled from the connection pool

  • Refactored auth code in driver so it can be used for both auth and reset

  • Added UserReset test in PoolingTests.cs

  • Connections are now reset using COM_CHANGE_USER when pulled from the pool

  • Implemented SingleResultSet behavior

  • Implemented support of unicode

  • Added char set mappings for utf-8 and ucs-2

  • fixed Bug #4520 time fields overflow using bytefx .net mysql driver

  • Modified time test in data type test fixture to check for time spans where hours > 24

  • Fixed Bug #4505 Wrong string with backslash escaping in ByteFx.Data.MySqlClient.MySqlParameter

  • Added code to Parameter test case TestQuoting to test for backslashes

  • Fixed Bug #4486 mysqlcommandbuilder fails with multi-word column names

  • Fixed bug in TokenizeSql where underscore would terminate character capture in parameter name

  • Added test case for spaces in column names

  • Fixed bug# 4324 - MySqlDataReader.GetBytes don't works correctly

  • Added GetBytes() test case to DataReader test fixture

  • Now reading all server variables in InternalConnection.Configure into Hashtable

  • Now using string[] for index map in CharSetMap

  • Added CRInSQL test case for carriage returns in SQL

  • setting maxPacketSize to default value in Driver.ctor

  • Fixed bug #4442 - Setting MySqlDbType on a parameter doesn't set generic type

  • Removed obsolete column types Long and LongLong

  • Fixed bug# 4071 - Overflow exception thrown when using "use pipe" on connection string

  • Changed "use pipe" keyword to "pipe name" or just "pipe"

  • Allow reading multiple resultsets from a single query

  • Added flags attribute to ServerStatusFlags enum

  • Changed name of ServerStatus enum to ServerStatusFlags

  • Fixed BUG #4386 - Inserted data row doesn't update properly

  • Fixed bug #4074 - Error processing show create table

  • Change Packet.ReadLenInteger to ReadPackedLong and added packet.ReadPackedInteger that alwasy reads integers packed with 2,3,4

  • Added syntax.cs test fixture to test various SQL syntax bugs

  • Fixed bug# 4149 Improper handling of time values. Now time value of 00:00:00 is not treated as null.

  • Moved all test suite files into TestSuite folder

  • Fixed bug where null column would move the result packet pointer backward

  • Added new nant build script

  • Fixed BUG #3917 - clear tablename so it will be regen'ed properly during the next GenerateSchema.

  • Fixed bug #3915 - GetValues was always returning zero and was also always trying to copy all fields rather than respecting the size of the array passed in.

  • Implemented shared memory access protocol

  • Implemented prepared statements for MySQL 4.1

  • Implemented stored procedures for MySQL 5.0

  • Renamed MySqlInternalConnection to InternalConnection

  • SQL is now parsed as chars, fixes problems with other languages

  • Added logging and allow batch connection string options

  • Fixed bug #3888 - RowUpdating event not set when setting the DataAdapter property

  • Fixed bug in char set mapping

  • Implemented 4.1 authentication

  • Improved open/auth code in driver

  • Improved how connection bits are set during connection

  • Database name is now passed to server during initial handshake

  • Changed namespace for client to MySql.Data.MySqlClient

  • Changed assembly name of client to MySql.Data.dll

  • Changed license text in all source files to GPL

  • Added the MySqlClient.build Nant file

  • Removed the mono batch files

  • Moved some of the unused files into notused folder so nant build file can use wildcards

  • Implemented shared memory accesss

  • Major revamp in code structure

  • Prepared statements now working for MySql 4.1.1 and later

  • Finished implementing auth for 4.0, 4.1.0, and 4.1.1

  • Changed namespace from MySQL.Data.MySQLClient back to MySql.Data.MySqlClient

  • Fixed bug in CharSetMapping where it was trying to use text names as ints

  • Changed namespace to MySQL.Data.MySQLClient

  • Integrated auth changes from UC2004

  • Fixed bug where calling any of the GetXXX methods on a datareader before or after reading data would not throw the appropriate exception (thanks Luca Morelli <morelli.luca@iol.it>)

  • Added TimeSpan code in parameter.cs to properly serialize a timespan object to mysql time format (thanks Gianluca Colombo <g.colombo@alfi.it>)

  • Added TimeStamp to parameter serialization code. Prevented DataAdatper updates from working right (thanks MIchael King)

  • Fixed a misspelling in MySqlHelper.cs (thanks Patrick Kristiansen)

23.2.5.11. Version 0.76

  • Driver now using charset number given in handshake to create encoding

  • Changed command editor to point to MySqlClient.Design

  • Fixed bug in Version.isAtLeast

  • Changed DBConnectionString to support changes done to MySqlConnectionString

  • Removed SqlCommandEditor and DataAdapterPreviewDialog

  • Using new long return values in many places

  • Integrated new CompressedStream class

  • Changed ConnectionString and added attributes to allow it to be used in MySqlClient.Design

  • Changed packet.cs to support newer lengths in ReadLenInteger

  • changed other classes to use new properties and fields of MySqlConnectionString

  • ConnectionInternal is now using PING to see if the server is alive

  • Moved toolbox bitmaps into resource/

  • Changed field.cs to allow values to come directly from row buffer

  • Changed to use the new driver.Send syntax

  • Using a new packet queueing system

  • started work handling the "broken" compression packet handling

  • Fixed bug in StreamCreator where failure to connect to a host would continue to loop infinitly (thanks Kevin Casella)

  • Improved connectstring handling

  • Moved designers into Pro product

  • Removed some old commented out code from command.cs

  • Fixed a problem with compression

  • Fixed connection object where an exception throw prior to the connection opening would not leave the connection in the connecting state (thanks Chris Cline )

  • Added GUID support

  • Fixed sequence out of order bug (thanks Mark Reay)

23.2.5.12. Version 0.75

  • Enum values now supported as parameter values (thanks Philipp Sumi)

  • Year datatype now supported

  • fixed compression

  • Fixed bug where a parameter with a TimeSpan as the value would not serialize properly

  • Fixed bug where default ctor would not set default connection string values

  • Added some XML comments to some members

  • Work to fix/improve compression handling

  • Improved ConnectionString handling so that it better matches the standard set by SqlClient.

  • A MySqlException is now thrown if a username is not included in the connection string

  • Localhost is now used as the default if not specified on the connection string

  • An exception is now thrown if an attempt is made to set the connection string while the connection is open

  • Small changes to ConnectionString docs

  • Removed MultiHostStream and MySqlStream. Replaced it with Common/StreamCreator

  • Added support for Use Pipe connection string value

  • Added Platform class for easier access to platform utility functions

  • Fixed small pooling bug where new connection was not getting created after IsAlive fails

  • Added Platform.cs and StreamCreator.cs

  • Fixed Field.cs to properly handle 4.1 style timestamps

  • Changed Common.Version to Common.DBVersion to avoid name conflict

  • Fixed field.cs so that text columns return the right field type (thanks beni27@gmx.net)

  • Added MySqlError class to provide some reference for error codes (thanks Geert Veenstra)

23.2.5.13. Version 0.74

  • Added Unix socket support (thanks Mohammad DAMT [md@mt.web.id])

  • only calling Thread.Sleep when no data is available

  • improved escaping of quote characters in parameter data

  • removed misleading comments from parameter.cs

  • fixed pooling bug

  • same pooling bug fixed again!! ;-)

  • Fixed ConnectionSTring editor dialog (thanks marco p (pomarc))

  • UserId now supported in connection strings (thanks Jeff Neeley)

  • Attempting to create a parameter that is not input throws an exception (thanks Ryan Gregg)

  • Added much documentation

  • checked in new MultiHostStream capability. Big thanks to Dan Guisinger for this. he originally submitted the code and idea of supporting multiple machines on the connect string.

  • Added alot of documentation. Still alot to do.

  • Fixed speed issue with 0.73

  • changed to Thread.Sleep(0) in MySqlDataStream to help optimize the case where it doesn't need to wait (thanks Todd German)

  • Prepopulating the idlepools to MinPoolSize

  • Fixed MySqlPool deadlock condition as well as stupid bug where CreateNewPooledConnection was not ever adding new connections to the pool. Also fixed MySqlStream.ReadBytes and ReadByte to not use TicksPerSecond which does not appear to always be right. (thanks Matthew J. Peddlesden)

  • Fix for precision and scale (thanks Matthew J. Peddlesden)

  • Added Thread.Sleep(1) to stream reading methods to be more cpu friendly (thanks Sean McGinnis)

  • Fixed problem where ExecuteReader would sometime return null (thanks Lloyd Dupont )

  • Fixed major bug with null field handling (thanks Naucki)

  • enclosed queries for max_allowed_packet and characterset inside try catch (and set defaults)

  • fixed problem where socket was not getting closed properly (thanks Steve!)

  • Fixed problem where ExecuteNonQuery was not always returning the right value

  • Fixed InternalConnection to not use @@session.max_allowed_packet but use @@max_allowed_packet. (Thanks Miguel)

  • Added many new XML doc lines

  • Fixed sql parsing to not send empty queries (thanks Rory)

  • Fixed problem where the reader was not unpeeking the packet on close

  • Fixed problem where user variables were not being handled (thanks Sami Vaaraniemi)

  • Fixed loop checking in the MySqlPool (thanks Steve M. Brown)

  • Fixed ParameterCollection.Add method to match SqlClient (thanks Joshua Mouch)

  • Fixed ConnectionSTring parsing to handle no and yes for boolean and not lowercase values (thanks Naucki)

  • Added InternalConnection class, changes to pooling

  • Implemented Persist Security Info

  • Added security.cs and version.cs to project

  • Fixed DateTime handling in Parameter.cs (thanks Burkhard Perkens-Golomb)

  • Fixed parameter serialization where some types would throw a cast exception

  • Fixed DataReader to convert all returned values to prevent casting errors (thanks Keith Murray)

  • Added code to Command.ExecuteReader to return null if the initial SQL command throws an exception (thanks Burkhard Perkens-Golomb)

  • Fixed ExecuteScalar bug introduced with restructure

  • Restructure to allow for LOCAL DATA INFILE and better sequencing of packets

  • Fixed several bugs related to restructure.

  • Early work done to support more secure passwords in Mysql 4.1. Old passwords in 4.1 not supported yet

  • Parameters appearing after system parameters are now handled correctly (Adam M. (adammil))

  • strings can now be assigned directly to blob fields (Adam M.)

  • Fixed float parameters (thanks Pent)

  • Improved Parameter ctor and ParameterCollection.Add methods to better match SqlClient (thx Joshua Mouch )

  • Corrected Connection.CreateCommand to return a MySqlCommand type

  • Fixed connection string designer dialog box problem (thanks Abraham Guyt)

  • Fixed problem with sending commands not always reading the response packet (thanks Joshua Mouch )

  • Fixed parameter serialization where some blobs types were not being handled (thanks Sean McGinnis )

  • Removed spurious MessageBox.show from DataReader code (thanks Joshua Mouch )

  • Fixed a nasty bug in the split sql code (thanks everyone! :-) )

23.2.5.14. Version 0.71

  • Fixed bug in MySqlStream where too much data could attempt to be read (thanks Peter Belbin)

  • Implemented HasRows (thanks Nash Pherson)

  • Fixed bug where tables with more than 252 columns cause an exception ( thanks Joshua Kessler )

  • Fixed bug where SQL statements ending in ; would cause a problem ( thanks Shane Krueger )

  • Fixed bug in driver where error messsages were getting truncated by 1 character (thanks Shane Krueger)

  • Made MySqlException serializable (thanks Mathias Hasselmann)

23.2.5.15. Version 0.70

  • Updated some of the character code pages to be more accurate

  • Fixed problem where readers could be opened on connections that had readers open

  • Release of 0.70

  • Moved test to separate assembly MySqlClientTests

  • Fixed stupid problem in driver with sequence out of order (Thanks Peter Belbin)

  • Added some pipe tests

  • Increased default max pool size to 50

  • Compiles with Mono 0-24

  • Fixed connection and data reader dispose problems

  • Added String datatype handling to parameter serialization

  • Fixed sequence problem in driver that occured after thrown exception (thanks Burkhard Perkens-Golomb)

  • Added support for CommandBehavior.SingleRow to DataReader

  • Fixed command sql processing so quotes are better handled (thanks Theo Spears)

  • Fixed parsing of double, single, and decimal values to account for non-English separators. You still have to use the right syntax if you using hard coded sql, but if you use parameters the code will convert floating point types to use '.' appropriately internal both into the server and out. [ Thanks anonymous ]

  • Added MySqlStream class to simplify timeOuts and driver coding.

  • Fixed DataReader so that it is closed properly when the associated connection is closed. [thanks smishra]

  • Made client more SqlClient compliant so that DataReaders have to be closed before the connection can be used to run another command

  • Improved DBNull.Value handling in the fields

  • Added several unit tests

  • Fixed MySqlException so that the base class is actually called :-o

  • Improved driver coding

  • Fixed bug where NextResult was returning false on the last resultset

  • Added more tests for MySQL

  • Improved casting problems by equating unsigned 32bit values to Int64 and usigned 16bit values to Int32, etc

  • Added new ctor for MySqlParameter for (name, type, size, srccol)

  • Fixed bug in MySqlDataReader where it didn't check for null fieldlist before returning field count

  • Started adding MySqlClient unit tests (added MySqlClient/Tests folder and some test cases)

  • Fixed some things in Connection String handling

  • Moved INIT_DB to MySqlPool. I may move it again, this is in preparation of the conference.

  • Fixed bug inside CommandBuilder that prevented inserts from happening properly

  • Reworked some of the internals so that all three execute methods of Command worked properly

  • FIxed many small bugs found during benchmarking

  • The first cut of CoonectionPooling is working. "min pool size" and "max pool size" are respected.

  • Work to enable multiple resultsets to be returned

  • Character sets are handled much more intelligently now. The driver queries MySQL at startup for the default character set. That character set is then used for conversions if that code page can be loaded. If not, then the default code page for the current OS is used.

  • Added code to save the inferred type in the name,value ctor of Parameter

  • Also, inferred type if value of null parameter is changed using Value property

  • Converted all files to use proper Camel case. MySQL is now MySql in all files. PgSQL is now PgSql

  • Added attribute to PgSql code to prevent designer from trying to show

  • Added MySQLDbType property to Parameter object and added proper conversion code to convert from DbType to MySQLDbType)

  • Removed unused ObjectToString method from MySQLParameter.cs

  • Fixed Add(..) method in ParameterCollection so that it doesn't use Add(name, value) instead.

  • Fixed IndexOf and Contains in ParameterCollection to be aware that parameter names are now stored without @

  • Fixed Command.ConvertSQLToBytes so it only allows characters that can be in MySQL variable names

  • Fixed DataReader and Field so that blob fields read their data from Field.cs and GetBytes works right

  • Added simple query builder editor to CommandText property of MySQLCommand

  • Fixed CommandBuilder and Parameter serialization to account for Parameters not storing @ in their names

  • Removed MySQLFieldType enum from Field.cs. Now using MySQLDbType enum

  • Added Designer attribute to several classes to prevent designer view when using VS.Net

  • Fixed Initial catalog typo in ConnectionString designer

  • Removed 3 parameter ctor for MySQLParameter that conflicted with (name, type, value)

  • changed MySQLParameter so paramName is now stored without leading @ (this fixed null inserts when using designer)

  • Changed TypeConverter for MySQLParameter to use the ctor with all properties

23.2.5.16. Version 0.68

  • Fixed sequence issue in driver

  • Added DbParametersEditor to make parameter editing more like SqlClient

  • Fixed Command class so that parameters can be edited using the designer

  • Update connection string designer to support Use Compression flag

  • Fixed string encoding so that European characters like ä will work correctly

  • Creating base classes to aid in building new data providers

  • Added support for UID key in connection string

  • Field, parameter, command now using DBNull.Value instead of null

  • CommandBuilder using DBNull.Value

  • CommandBuilder now builds insert command correctly when an auto_insert field is not present

  • Field now uses typeof keyword to return System.Types (performance)

23.2.5.17. Version 0.65

  • MySQLCommandBuilder now implemented

  • Transaction support now implemented (not all table types support this)

  • GetSchemaTable fixed to not use xsd (for Mono)

  • Driver is now Mono-compatible!!

  • TIME data type now supported

  • More work to improve Timestamp data type handling

  • Changed signatures of all classes to match corresponding SqlClient classes

23.2.5.18. Version 0.60

  • Protocol compression using SharpZipLib (www.icsharpcode.net)

  • Named pipes on Windows now working properly

  • Work done to improve Timestamp data type handling

  • Implemented IEnumerable on DataReader so DataGrid would work

23.2.5.19. Version 0.50

  • Speed increased dramatically by removing bugging network sync code

  • Driver no longer buffers rows of data (more ADO.Net compliant)

  • Conversion bugs related to TIMESTAMP and DATETIME fields fixed

23.3. 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-3.0 "Type 4" driver, which means that is is pure Java, implements version 3.0 of the JDBC specification, and communicates directly with the MySQL server using the MySQL protocol.

This document is arranged for a beginning JDBC developer. If you are already experienced with using JDBC, you might consider starting with the section "Installing Connector/J".

While 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, Spring's JDBC templates or Ibatis SQL Maps 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:

23.3.1. Basic JDBC concepts

This section provides some general JDBC background.

23.3.1.1. Connecting to MySQL using the DriverManager Interface

When you are using JDBC outside of an application server, the DriverManager class manages the establishment of Connections.

The DriverManager needs to be told which JDBC drivers it should try to make Connections with. The easiest way to do this is to use Class.forName() on the class that implements the java.sql.Driver interface. With MySQL Connector/J, the name of this class is com.mysql.jdbc.Driver. 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.

The following section of Java code shows how you might register MySQL Connector/J from the main() method of your application:

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

// Notice, do not import com.mysql.jdbc.*
// or you will have problems!

public class LoadDriver {
    public static void main(String[] args) {
        try {
            // The newInstance() call is a work around for some
            // broken Java implementations

            Class.forName("com.mysql.jdbc.Driver").newInstance();
        } catch (Exception ex) {
            // handle the error
        }
}

After the driver has been registered with the DriverManager, you can obtain a Connection instance that is connected to a particular database by calling DriverManager.getConnection():

Example 23.1. Obtaining a Connection From the DriverManager

This example shows how you can obtain a Connection instance from the DriverManager. There are a few different signatures for the getConnection() method. You should see the API documentation that comes with your JDK for more specific information on how to use them.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

    ... try {
            Connection conn = DriverManager.getConnection("jdbc:mysql://localhost/test?user=monty&password=greatsqldb");

            // Do something with the Connection

           ....
        } catch (SQLException ex) {
            // handle any errors
            System.out.println("SQLException: " + ex.getMessage());
            System.out.println("SQLState: " + ex.getSQLState());
            System.out.println("VendorError: " + ex.getErrorCode());
        }

Once a Connection is established, it can be used to create Statements and PreparedStatements, as well as retrieve metadata about the database. This is explained in the following sections.

23.3.1.2. Using Statements to Execute SQL

Statements allow you to execute basic SQL queries and retrieve the results through the ResultSet class which is described later.

To create a Statement instance, you call the createStatement() method on the Connection object you have retrieved via one of the DriverManager.getConnection() or DataSource.getConnection() methods described earlier.

Once you have a Statement instance, you can execute a SELECT query by calling the executeQuery(String) method with the SQL you want to use.

To update data in the database use the executeUpdate(String SQL) method. This method returns the number of rows affected by the update statement.

If you don't know ahead of time whether the SQL statement will be a SELECT or an UPDATE/INSERT, then you can use the execute(String SQL) method. This method will return true if the SQL query was a SELECT, or false if an UPDATE/INSERT/DELETE query. If the query was a SELECT query, you can retrieve the results by calling the getResultSet() method. If the query was an UPDATE/INSERT/DELETE query, you can retrieve the affected rows count by calling getUpdateCount() on the Statement instance.

Example 23.2. Using java.sql.Statement to Execute a SELECT Query

// assume conn is an already created JDBC connection
Statement stmt = null;
ResultSet rs = null;

try {
    stmt = conn.createStatement();
    rs = stmt.executeQuery("SELECT foo FROM bar");

    // or alternatively, if you don't know ahead of time that
    // the query will be a SELECT...

    if (stmt.execute("SELECT foo FROM bar")) {
        rs = stmt.getResultSet();
    }

    // Now do something with the ResultSet ....
} finally {
    // it is a good idea to release
    // resources in a finally{} block
    // in reverse-order of their creation
    // if they are no-longer needed

    if (rs != null) {
        try {
            rs.close();
        } catch (SQLException sqlEx) { // ignore }

        rs = null;
    }

    if (stmt != null) {
        try {
            stmt.close();
        } catch (SQLException sqlEx) { // ignore }

        stmt = null;
    }
}

23.3.1.3. Using CallableStatements to Execute Stored Procedures

Starting with MySQL server version 5.0 when used with Connector/J 3.1.1 or newer, the java.sql.CallableStatement interface is fully implemented with the exception of the getParameterMetaData() method.

MySQL's stored procedure syntax is documented in the "Stored Procedures and Functions" section of the MySQL Reference Manual.

Connector/J exposes stored procedure functionality through JDBC's CallableStatement interface.

The following example shows a stored procedure that returns the value of inOutParam incremented by 1, and the string passed in via inputParam as a ResultSet :

Example 23.3. Stored Procedure Example

CREATE PROCEDURE demoSp(IN inputParam VARCHAR(255), INOUT inOutParam INT)
BEGIN
    DECLARE z INT;
    SET z = inOutParam + 1;
    SET inOutParam = z;

    SELECT inputParam;

    SELECT CONCAT('zyxw', inputParam);
END

To use the demoSp procedure with Connector/J, follow these steps:

  1. Prepare the callable statement by using Connection.prepareCall() .

    Notice that you have to use JDBC escape syntax, and that the parentheses surrounding the parameter placeholders are not optional:

    Example 23.4. Using Connection.prepareCall()

    import java.sql.CallableStatement;
    
    ...
    
        //
        // Prepare a call to the stored procedure 'demoSp'
        // with two parameters
        //
        // Notice the use of JDBC-escape syntax ({call ...})
        //
    
        CallableStatement cStmt = conn.prepareCall("{call demoSp(?, ?)}");
    
    
    
        cStmt.setString(1, "abcdefg");

    Note

    Connection.prepareCall() 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 Connection.prepareCall() by reusing CallableStatement instances in your code.

  2. Register the output parameters (if any exist)

    To retrieve the values of output parameters (parameters specified as OUT or INOUT when you created the stored procedure), JDBC requires that they be specified before statement execution using the various registerOutputParameter() methods in the CallableStatement interface:

    Example 23.5. Registering Output Parameters

    import java.sql.Types;
    
    ...
        //
        // Connector/J supports both named and indexed
        // output parameters. You can register output
        // parameters using either method, as well
        // as retrieve output parameters using either
        // method, regardless of what method was
        // used to register them.
        //
        // The following examples show how to use
        // the various methods of registering
        // output parameters (you should of course
        // use only one registration per parameter).
        //
    
        //
        // Registers the second parameter as output
        //
    
        cStmt.registerOutParameter(2);
    
        //
        // Registers the second parameter as output, and
        // uses the type 'INTEGER' for values returned from
        // getObject()
        //
    
        cStmt.registerOutParameter(2, Types.INTEGER);
    
        //
        // Registers the named parameter 'inOutParam'
        //
    
        cStmt.registerOutParameter("inOutParam");
    
        //
        // Registers the named parameter 'inOutParam', and
        // uses the type 'INTEGER' for values returned from
        // getObject()
        //
    
        cStmt.registerOutParameter("inOutParam", Types.INTEGER);
    
    ...

  3. Set the input parameters (if any exist)

    Input and in/out parameters are set as for PreparedStatement objects. However, CallableStatement also supports setting parameters by name:

    Example 23.6. Setting CallableStatement Input Parameters

    ...
    
        //
        // Set a parameter by index
        //
    
        cStmt.setString(1, "abcdefg");
    
        //
        // Alternatively, set a parameter using
        // the parameter name
        //
    
        cStmt.setString("inputParameter", "abcdefg");
    
        //
        // Set the 'in/out' parameter using an index
        //
    
        cStmt.setInt(2, 1);
    
        //
        // Alternatively, set the 'in/out' parameter
        // by name
        //
    
        cStmt.setInt("inOutParam", 1);
    
    ...

  4. Execute the CallableStatement , and retrieve any result sets or output parameters.

    While CallableStatement supports calling any of the Statement execute methods ( executeUpdate(), executeQuery() or execute() ), the most flexible method to call is execute(), as you do not need to know ahead of time if the stored procedure returns result sets:

    Example 23.7. Retrieving Results and Output Parameter Values

    ...
    
        boolean hadResults = cStmt.execute();
    
        //
        // Process all returned result sets
        //
    
        while (hadResults) {
            ResultSet rs = cStmt.getResultSet();
    
            // process result set
            ...
    
            hadResults = cStmt.getMoreResults();
        }
    
        //
        // Retrieve output parameters
        //
        // Connector/J supports both index-based and
        // name-based retrieval
        //
    
        int outputValue = cStmt.getInt(1); // index-based
    
        outputValue = cStmt.getInt("inOutParam"); // name-based
    
    ...

23.3.1.4. Retrieving AUTO_INCREMENT Column Values

Before version 3.0 of the JDBC API, there was no standard way of retrieving key values from databases that supported 'auto increment' or identity columns. With older JDBC drivers for MySQL, you could always use a MySQL- specific method on the Statement interface, or issue the query 'SELECT LAST_INSERT_ID()' after issuing an 'INSERT' to a table that had an AUTO_INCREMENT key. Using the MySQL-specific method call isn't portable, and issuing a 'SELECT' to get the AUTO_INCREMENT 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 AUTO_INCREMENT values. First, we demonstrate the use of the new JDBC-3.0 method 'getGeneratedKeys()' which is now the preferred method to use if you need to retrieve AUTO_INCREMENT keys and have access to JDBC-3.0. The second example shows how you can retrieve the same value using a standard 'SELECT LAST_INSERT_ID()' query. The final example shows how updatable result sets can retrieve the AUTO_INCREMENT value when using the method 'insertRow()'.

Example 23.8. Retrieving AUTO_INCREMENT Column Values using Statement.getGeneratedKeys()

   Statement stmt = null;
   ResultSet rs = null;

   try {

    //
    // Create a Statement instance that we can use for
    // 'normal' result sets assuming you have a
    // Connection 'conn' to a MySQL database already
    // available

    stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
                                java.sql.ResultSet.CONCUR_UPDATABLE);

    //
    // Issue the DDL queries for the table for this example
    //

    stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
    stmt.executeUpdate(
            "CREATE TABLE autoIncTutorial ("
            + "priKey INT NOT NULL AUTO_INCREMENT, "
            + "dataField VARCHAR(64), PRIMARY KEY (priKey))");

    //
    // Insert one row that will generate an AUTO INCREMENT
    // key in the 'priKey' field
    //

    stmt.executeUpdate(
            "INSERT INTO autoIncTutorial (dataField) "
            + "values ('Can I Get the Auto Increment Field?')",
            Statement.RETURN_GENERATED_KEYS);

    //
    // Example of using Statement.getGeneratedKeys()
    // to retrieve the value of an auto-increment
    // value
    //

    int autoIncKeyFromApi = -1;

    rs = stmt.getGeneratedKeys();

    if (rs.next()) {
        autoIncKeyFromApi = rs.getInt(1);
    } else {

        // throw an exception from here
    }

    rs.close();

    rs = null;

    System.out.println("Key returned from getGeneratedKeys():"
        + autoIncKeyFromApi);
} finally {

    if (rs != null) {
        try {
            rs.close();
        } catch (SQLException ex) {
            // ignore
        }
    }

    if (stmt != null) {
        try {
            stmt.close();
        } catch (SQLException ex) {
            // ignore
        }
    }
}

Example 23.9. Retrieving AUTO_INCREMENT Column Values using 'SELECT LAST_INSERT_ID()'

   Statement stmt = null;
   ResultSet rs = null;

   try {

    //
    // Create a Statement instance that we can use for
    // 'normal' result sets.

    stmt = conn.createStatement();

    //
    // Issue the DDL queries for the table for this example
    //

    stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
    stmt.executeUpdate(
            "CREATE TABLE autoIncTutorial ("
            + "priKey INT NOT NULL AUTO_INCREMENT, "
            + "dataField VARCHAR(64), PRIMARY KEY (priKey))");

    //
    // Insert one row that will generate an AUTO INCREMENT
    // key in the 'priKey' field
    //

    stmt.executeUpdate(
            "INSERT INTO autoIncTutorial (dataField) "
            + "values ('Can I Get the Auto Increment Field?')");

    //
    // Use the MySQL LAST_INSERT_ID()
    // function to do the same thing as getGeneratedKeys()
    //

    int autoIncKeyFromFunc = -1;
    rs = stmt.executeQuery("SELECT LAST_INSERT_ID()");

    if (rs.next()) {
        autoIncKeyFromFunc = rs.getInt(1);
    } else {
        // throw an exception from here
    }

    rs.close();

    System.out.println("Key returned from " + "'SELECT LAST_INSERT_ID()': "
        + autoIncKeyFromFunc);

} finally {

    if (rs != null) {
        try {
            rs.close();
        } catch (SQLException ex) {
            // ignore
        }
    }

    if (stmt != null) {
        try {
            stmt.close();
        } catch (SQLException ex) {
            // ignore
        }
    }
}
   

Example 23.10. Retrieving AUTO_INCREMENT Column Values in Updatable ResultSets

   Statement stmt = null;
   ResultSet rs = null;

   try {

    //
    // Create a Statement instance that we can use for
    // 'normal' result sets as well as an 'updatable'
    // one, assuming you have a Connection 'conn' to
    // a MySQL database already available
    //

    stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
                                java.sql.ResultSet.CONCUR_UPDATABLE);

    //
    // Issue the DDL queries for the table for this example
    //

    stmt.executeUpdate("DROP TABLE IF EXISTS autoIncTutorial");
    stmt.executeUpdate(
            "CREATE TABLE autoIncTutorial ("
            + "priKey INT NOT NULL AUTO_INCREMENT, "
            + "dataField VARCHAR(64), PRIMARY KEY (priKey))");

    //
    // Example of retrieving an AUTO INCREMENT key
    // from an updatable result set
    //

    rs = stmt.executeQuery("SELECT priKey, dataField "
       + "FROM autoIncTutorial");

    rs.moveToInsertRow();

    rs.updateString("dataField", "AUTO INCREMENT here?");
    rs.insertRow();

    //
    // the driver adds rows at the end
    //

    rs.last();

    //
    // We should now be on the row we just inserted
    //

    int autoIncKeyFromRS = rs.getInt("priKey");

    rs.close();

    rs = null;

    System.out.println("Key returned for inserted row: "
        + autoIncKeyFromRS);

} finally {

    if (rs != null) {
        try {
            rs.close();
        } catch (SQLException ex) {
            // ignore
        }
    }

    if (stmt != null) {
        try {
            stmt.close();
        } catch (SQLException ex) {
            // ignore
        }
    }
}


   

When you run the example code above, you should get the following output: Key returned from getGeneratedKeys(): 1 Key returned from 'SELECT LAST_INSERT_ID()': 1 Key returned for inserted row: 2 You should be aware, that at times, it can be tricky to use the 'SELECT LAST_INSERT_ID()' 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 'getGeneratedKeys()' method is scoped by the Statement instance, so it can be used even if other queries happen on the same connection, but not on the same Statement instance.

23.3.2. Installing Connector/J

Use the following instructions to install Connector/J

23.3.2.1. Required Software Versions

23.3.2.1.1. Java Versions Supported

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

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 (-Xverify:none), as 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.

23.3.2.1.2. MySQL Server Version Guidelines

MySQL Connector/J supports all known MySQL server versions. Some features (foreign keys, updatable result sets) require more recent versions of MySQL to operate.

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.

While 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.

23.3.2.1.3. Installing the Driver and Configuring the CLASSPATH

MySQL Connector/J is distributed as a .zip or .tar.gz archive containing the sources, the class files a class-file only "binary" .jar archive named "mysql-connector-java-[version]-bin.jar", and starting with Connector/J 3.1.8 a "debug" build of the driver in a file named "mysql-connector-java-[version]-bin-g.jar".

Starting with Connector/J 3.1.9, we don't ship the .class files "unbundled", they are only available in the JAR archives that ship with the driver.

You should not use the "debug" build of the driver unless instructed do 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 src/lib/aspectjrt.jar file that comes with the Connector/J distribution.

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

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 enviornment variable, or by directly specifying it with the commandline switch -cp when starting your JVM

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.

Example 23.11. Setting the CLASSPATH Under UNIX

The following command works for 'csh' under UNIX:

$ setenv CLASSPATH /path/to/mysql-connector-java-[version]-bin.jar:$CLASSPATH

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.

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 "Using Connector/J with J2EE and Other Java Frameworks", however the authoritative source for JDBC connection pool configuration information for your particular application server is the documentation for that application server.

If you are developing servlets and/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.

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. The various MysqlDataSource classes support the following parameters (through standard "set" mutators):

  • user

  • password

  • serverName (see the previous section about fail-over hosts)

  • databaseName

  • port

23.3.2.2. Upgrading from an Older Version

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.

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.

23.3.2.2.1. Upgrading from MySQL Connector/J 3.0 to 3.1

Connector/J 3.1 is designed to be backwards-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.

  • 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'.

  • Server-side Prepared Statements - 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).

    Starting with version 3.1.7, the driver scans SQL you are preparing via all variants of Connection.prepareStatement() 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 'emulateUnsupportedPstmts=false' in your JDBC URL.

    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:

    useServerPrepStmts=false

  • 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.

    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 ' zeroDateTimeBehavior ' configuration property. The allowable values are: 'exception' (the default), which throws a SQLException with a 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'.

    Starting with Connector/J 3.1.7, ResultSet.getString() can be decoupled from this behavior via ' noDatetimeStringSync=true ' (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 noDatetimeStringSync and useTimezone at the same time.

  • New SQLState Codes - Connector/J 3.1 uses SQL:1999 SQLState codes returned by the MySQL server (if supported), which are different than the "legacy" X/Open state codes that Connector/J 3.0 uses. If connected to a MySQL server older than MySQL-4.1.0 (the oldest version to return SQLStates as part of the error code), the driver will use a built-in mapping. You can revert to the old mapping by using the following configuration property:

    useSqlStateCodes=false

  • 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.

    To store strings in MySQL with LOB behavior, use one of the TEXT types, which the driver will treat as a java.sql.Clob.

  • Starting with Connector/J 3.1.8 a "debug" build of the driver in a file named "mysql-connector-java-[version]-bin-g.jar" is shipped alongside the normal "binary" jar file that is named "mysql-connector-java-[version]-bin.jar".

    Starting with Connector/J 3.1.9, we don't ship the .class files "unbundled", they are only available in the JAR archives that ship with the driver.

    You should not use the "debug" build of the driver unless instructed do 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 src/lib/aspectjrt.jar file that comes with the Connector/J distribution.

23.3.2.2.2. JDBC-Specific Issues When Upgrading to MySQL Server Version 4.1 or Newer
  • Using the UTF-8 Character Encoding - 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.

    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:

    useOldUTF8Behavior=true

  • Server-side Prepared Statements - 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:

    useServerPrepStmts=false

23.3.3. JDBC Reference

23.3.3.1. Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J

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 backwards-compatible with MM.MySQL. You should use this class name when registering the driver, or when otherwise configuring software to use MySQL Connector/J.

The JDBC URL format for MySQL Connector/J is as follows, with items in square brackets ([, ]) being optional:

jdbc:mysql://[host][,failoverhost...][:port]/[database][?propertyName1][=propertyValue1][&propertyName2][=propertyValue2]...

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.

jdbc:mysql://[host:port],[host:port].../[database][?propertyName1][=propertyValue1][&propertyName2][=propertyValue2]...

If the database is not specified, the connection will be made with no 'current' database. In this case, you will need to either call the 'setCatalog()' 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.

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

The fail-over functionality has the following behavior:

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.

If the URL property "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 state, so queries that would modify data will have exceptions thrown (the query will never be processed by the MySQL server).

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.

Configuration Properties can be set in one of the following ways:

  • Using the set*() methods on MySQL implementations of java.sql.DataSource (which is the preferred method when using implementations of java.sql.DataSource):

    • com.mysql.jdbc.jdbc2.optional.MysqlDataSource

    • com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource

  • As a key/value pair in the java.util.Properties instance passed to DriverManager.getConnection() or Driver.connect()

  • 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

    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.

The properties are listed in the following table:

Table 23.1. Connection Properties

Property NameDefinitionRequired?Default ValueSince Version
Connection/Authentication
userThe user to connect asNo all
passwordThe password to use when connectingNo all
socketFactoryThe 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.Nocom.mysql.jdbc.StandardSocketFactory3.0.3
connectTimeoutTimeout for socket connect (in milliseconds), with 0 being no timeout. Only works on JDK-1.4 or newer. Defaults to '0'.No03.0.1
socketTimeoutTimeout on network socket operations (0, the default means no timeout).No03.0.1
useConfigsLoad 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.No 3.1.5
interactiveClientSet the CLIENT_INTERACTIVE flag, which tells MySQL to timeout connections based on INTERACTIVE_TIMEOUT instead of WAIT_TIMEOUTNofalse3.1.0
propertiesTransformAn implementation of com.mysql.jdbc.ConnectionPropertiesTransform that the driver will use to modify URL properties passed to the driver before attempting a connectionNo 3.1.4
useCompressionUse zlib compression when communicating with the server (true/false)? Defaults to 'false'.Nofalse3.0.17
High Availability and Clustering
autoReconnectShould the driver try to re-establish stale and/or dead connections? If enabled the driver will throw an exception for a queries issued on a stale or dead connection, which belong to the current transaction, but will attempt reconnect before the next query issued on the connection in a new transaction. The use of this feature is not recommended, because it has side effects related to session state and data consistency when applications don'thandle SQLExceptions properly, and is only designed to be used when you are unable to configure your application to handle SQLExceptions resulting from dead and/or stale connections properly. Alternatively, investigate setting the MySQL server variable "wait_timeout"to some high value rather than the default of 8 hours.Nofalse1.1
autoReconnectForPoolsUse a reconnection strategy appropriate for connection pools (defaults to 'false')Nofalse3.1.3
failOverReadOnlyWhen failing over in autoReconnect mode, should the connection be set to 'read-only'?Notrue3.0.12
reconnectAtTxEndIf autoReconnect is set to true, should the driver attempt reconnectionsat the end of every transaction?Nofalse3.0.10
roundRobinLoadBalanceWhen autoReconnect is enabled, and failoverReadonly is false, should we pick hosts to connect to on a round-robin basis?Nofalse3.1.2
queriesBeforeRetryMasterNumber 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.No503.0.2
secondsBeforeRetryMasterHow 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 30No303.0.2
enableDeprecatedAutoreconnectAuto-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.Nofalse3.2.1
Security
allowMultiQueriesAllow the use of ';' to delimit multiple queries during one statement (true/false, defaults to 'false'Nofalse3.1.1
useSSLUse SSL when communicating with the server (true/false), defaults to 'false'Nofalse3.0.2
requireSSLRequire SSL connection if useSSL=true? (defaults to 'false').Nofalse3.1.0
allowUrlInLocalInfileShould the driver allow URLs in 'LOAD DATA LOCAL INFILE' statements?Nofalse3.1.4
paranoidTake measures to prevent exposure sensitive information in error messages and clear data structures holding sensitive data when possible? (defaults to 'false')Nofalse3.0.1
Performance Extensions
metadataCacheSizeThe number of queries to cacheResultSetMetadata for if cacheResultSetMetaData is set to 'true' (default 50)No503.1.1
prepStmtCacheSizeIf prepared statement caching is enabled, how many prepared statements should be cached?No253.0.10
prepStmtCacheSqlLimitIf prepared statement caching is enabled, what's the largest SQL the driver will cache the parsing for?No2563.0.10
maintainTimeStatsShould the driver maintain various internal timers to enable idle time calculations as well as more verbose error messages when the connection to the server fails? Setting this property to false removes at least two calls to System.getCurrentTimeMillis() per query.Notrue3.1.9
blobSendChunkSizeChunk to use when sending BLOB/CLOBs via ServerPreparedStatementsNo10485763.1.9
cacheCallableStmtsShould the driver cache the parsing stage of CallableStatementsNofalse3.1.2
cachePrepStmtsShould the driver cache the parsing stage of PreparedStatements of client-side prepared statements, the "check" for suitability of server-side prepared and server-side prepared statements themselves?Nofalse3.0.10
cacheResultSetMetadataShould the driver cache ResultSetMetaData for Statements and PreparedStatements? (Req. JDK-1.4+, true/false, default 'false')Nofalse3.1.1
cacheServerConfigurationShould the driver cache the results of 'SHOW VARIABLES' and 'SHOW COLLATION' on a per-URL basis?Nofalse3.1.5
dontTrackOpenResourcesThe 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.Nofalse3.1.7
dynamicCalendarsShould the driver retrieve the default calendar when required, or cache it per connection/session?Nofalse3.1.5
elideSetAutoCommitsIf 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)?Nofalse3.1.3
holdResultsOpenOverStatementCloseShould the driver close result sets on Statement.close() as required by the JDBC specification?Nofalse3.1.7
locatorFetchBufferSizeIf 'emulateLocators' is configured to 'true', what size buffer should be used when fetching BLOB data for getBinaryInputStream?No10485763.2.1
useFastIntParsingUse internal String->Integer conversion routines to avoid excessive object creation?Notrue3.1.4
useLocalSessionStateShould 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?Nofalse3.1.7
useNewIOShould the driver use the java.nio.* interfaces for network communication (true/false), defaults to 'false'Nofalse3.1.0
useReadAheadInputUse newer, optimized non-blocking, buffered input stream when reading from the server?Notrue3.1.5
Debuging/Profiling
loggerThe 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)Nocom.mysql.jdbc.log.StandardLogger3.1.1
profileSQLTrace queries and their execution/fetch times to the configured logger (true/false) defaults to 'false'Nofalse3.1.0
reportMetricsIntervalMillisIf 'gatherPerfMetrics' is enabled, how often should they be logged (in ms)?No300003.1.2
maxQuerySizeToLogControls the maximum length/size of a query that will get logged when profiling or tracingNo20483.1.3
packetDebugBufferSizeThe maximum number of packets to retain when 'enablePacketDebug' is trueNo203.1.3
slowQueryThresholdMillisIf 'logSlowQueries' is enabled, how long should a query (in ms) before it is logged as 'slow'?No20003.1.2
useUsageAdvisorShould the driver issue 'usage' warnings advising proper and efficient usage of JDBC and MySQL Connector/J to the log (true/false, defaults to 'false')?Nofalse3.1.1
autoGenerateTestcaseScriptShould the driver dump the SQL it is executing, including server-side prepared statements to STDERR?Nofalse3.1.9
dumpQueriesOnExceptionShould the driver dump the contents of the query sent to the server in the message for SQLExceptions?Nofalse3.1.3
enablePacketDebugWhen enabled, a ring-buffer of 'packetDebugBufferSize' packets will be kept, and dumped when exceptions are thrown in key areas in the driver's codeNofalse3.1.3
explainSlowQueriesIf '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?Nofalse3.1.2
logSlowQueriesShould queries that take longer than 'slowQueryThresholdMillis' be logged?Nofalse3.1.2
traceProtocolShould trace-level network protocol be logged?Nofalse3.1.2
Miscellaneous
useUnicodeShould 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'Nofalse1.1g
characterEncodingIf 'useUnicode' is set to true, what character encoding should the driver use when dealing with strings? (defaults is to 'autodetect')No 1.1g
characterSetResultsCharacter set to tell the server to return results as.No 3.0.13
connectionCollationIf set, tells the server to use this collation via 'set collation_connection'No 3.0.13
sessionVariablesA comma-separated list of name/value pairs to be sent as SET SESSION ... to the server when the driver connects.No 3.1.8
allowNanAndInfShould the driver allow NaN or +/- INF values in PreparedStatement.setDouble()?Nofalse3.1.5
autoDeserializeShould the driver automatically detect and de-serialize objects stored in BLOB fields?Nofalse3.1.5
capitalizeTypeNamesCapitalize type names in DatabaseMetaData? (usually only useful when using WebObjects, true/false, defaults to 'false')Nofalse2.0.7
clobberStreamingResultsThis 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.Nofalse3.0.9
continueBatchOnErrorShould the driver continue processing batch commands if one statement fails. The JDBC spec allows either way (defaults to 'true').Notrue3.0.3
createDatabaseIfNotExistCreates the database given in the URL if it doesn't yet exist. Assumes the configured user has permissions to create databases.Nofalse3.1.9
emptyStringsConvertToZeroShould the driver allow conversions from empty string fields to numeric values of '0'?Notrue3.1.8
emulateLocatorsN/ANofalse3.1.0
emulateUnsupportedPstmtsShould the driver detect prepared statements that are not supported by the server, and replace them with client-side emulated versions?Notrue3.1.7
ignoreNonTxTablesIgnore non-transactional table warning for rollback? (defaults to 'false').Nofalse3.0.9
jdbcCompliantTruncationShould 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)?Notrue3.1.2
maxRowsThe maximum number of rows to return (0, the default means return all rows).No-1all versions
noDatetimeStringSyncDon't ensure that ResultSet.getDatetimeType().toString().equals(ResultSet.getString())Nofalse3.1.7
nullCatalogMeansCurrentWhen 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)Notrue3.1.8
nullNamePatternMatchesAllShould 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)Notrue3.1.8
pedanticFollow the JDBC spec to the letter.Nofalse3.0.0
relaxAutoCommitIf 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')?Nofalse2.0.13
retainStatementAfterResultSetCloseShould the driver retain the Statement reference in a ResultSet after ResultSet.close() has been called. This is not JDBC-compliant after JDBC-4.0.Nofalse3.1.11
rollbackOnPooledCloseShould the driver issue a rollback() when the logical connection in a pool is closed?Notrue3.0.15
runningCTS13Enables workarounds for bugs in Sun's JDBC compliance testsuite version 1.3Nofalse3.1.7
serverTimezoneOverride detection/mapping of timezone. Used when timezone from server doesn't map to Java timezoneNo 3.0.2
strictFloatingPointUsed only in older versions of compliance testNofalse3.0.0
strictUpdatesShould the driver do strict checking (all primary keys selected) of updatable result sets (true, false, defaults to 'true')?Notrue3.0.4
tinyInt1isBitShould the driver treat the datatype TINYINT(1) as the BIT type (because the server silently converts BIT -> TINYINT(1) when creating tables)?Notrue3.0.16
transformedBitIsBooleanIf 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?Nofalse3.1.9
ultraDevHackCreate PreparedStatements for prepareCall() when required, because UltraDev is broken and issues a prepareCall() for _all_ statements? (true/false, defaults to 'false')Nofalse2.0.3
useHostsInPrivilegesAdd '@hostname' to users in DatabaseMetaData.getColumn/TablePrivileges() (true/false), defaults to 'true'.Notrue3.0.2
useOldUTF8BehaviorUse the UTF-8 behavior the driver did when communicating with 4.0 and older serversNofalse3.1.6
useOnlyServerErrorMessagesDon't prepend 'standard' SQLState error messages to error messages returned by the server.Notrue3.0.15
useServerPrepStmtsUse server-side prepared statements if the server supports them? (defaults to 'true').Notrue3.1.0
useSqlStateCodesUse SQL Standard state codes instead of 'legacy' X/Open/SQL state codes (true/false), default is 'true'Notrue3.1.3
useStreamLengthsInPrepStmtsHonor stream length parameter in PreparedStatement/ResultSet.setXXXStream() method calls (true/false, defaults to 'true')?Notrue3.0.2
useTimezoneConvert time/date types between client and server timezones (true/false, defaults to 'false')?Nofalse3.0.2
useUnbufferedInputDon't use BufferedInputStream for reading data from the serverNotrue3.0.11
yearIsDateTypeShould the JDBC driver treat the MySQL type "YEAR" as a java.sql.Date, or as a SHORT?Notrue3.1.9
zeroDateTimeBehaviorWhat 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'.Noexception3.1.4

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.

Adding the following property 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 com.mysql.jdbc.NamedPipeSocketFactory , or com.mysql.jdbc.StandardSocketFactory .

23.3.3.2. JDBC API Implementation Notes

MySQL Connector/J passes all of the tests in the publicly-available version of Sun's JDBC compliance testsuite. However, in many places the JDBC specification is vague about how certain functionality should be implemented, or the specification allows leeway in implementation.

This section gives details on a interface-by-interface level about how certain implementation decisions may affect how you use MySQL Connector/J.

  • Blob

    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.

    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(), etc) on it.

  • CallableStatement

    Starting with Connector/J 3.1.1, stored procedures are supported when connecting to MySQL version 5.0 or newer via the CallableStatement interface. Currently, the getParameterMetaData() method of CallableStatement is not supported.

  • Clob

    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.

  • Connection

    Unlike older versions of MM.MySQL the 'isClosed()' method does not "ping" 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.

  • DatabaseMetaData

    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 table types support foreign keys, the driver will transparently support them as well.

  • Driver

  • PreparedStatement

    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.

    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.

    Take care when using a server-side prepared statement with "large" parameters that are set via setBinaryStream(), setAsciiStream(), setUnicodeStream(), setBlob(), or setClob(). If you want to re-execute the statement with any "large" parameter changed to a non-"large" parameter, it is necessary to call clearParameters() and set all parameters again. The reason for this is as follows:

    • 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).

    • 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.

    • If a parameter changes from "large" to non-"large", the driver must reset the server-side state of the prepared statement to allow the parameter that is being changed to take the place of the prior "large" value. This removes all of the 'large' data that has already been sent to the server, thus requiring the data to be re-sent, via the setBinaryStream(), setAsciiStream(), setUnicodeStream(), setBlob() or setClob() methods.

    Consequently, if you want to change the "type" of a parameter to a non-"large" one, you must call clearParameters() and set all parameters of the prepared statement again before it can be re-executed.

  • ResultSet

    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.

    To enable this functionality, you need to create a Statement instance in the following manner:

    stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY,
                  java.sql.ResultSet.CONCUR_READ_ONLY);
    stmt.setFetchSize(Integer.MIN_VALUE);

    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 "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.

    The earliest the locks these statements hold can be released (whether they be MyISAM table-level locks or row-level locks in some other storage engine such as InnoDB) is when the statement completes.

    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.

    Therefore, if using "streaming" 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.

  • ResultSetMetaData

    The "isAutoIncrement()" method only works when using MySQL servers 4.0 and newer.

  • Statement

    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.

    MySQL does not support SQL cursors, and the JDBC driver doesn't emulate them, so "setCursorName()" has no effect.

23.3.3.3. Java, JDBC and MySQL Types

MySQL Connector/J is flexible in the way it handles conversions between MySQL data types and Java data types.

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.

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".

The conversions that are always guaranteed to work are listed in the following table:

Table 23.2. Conversion Table

These MySQL Data TypesCan always be converted to these Java types
CHAR, VARCHAR, BLOB, TEXT, ENUM, and SETjava.lang.String, java.io.InputStream, java.io.Reader, java.sql.Blob, java.sql.Clob
FLOAT, REAL, DOUBLE PRECISION, NUMERIC, DECIMAL, TINYINT, SMALLINT, MEDIUMINT, INTEGER, BIGINTjava.lang.String, java.lang.Short, java.lang.Integer, java.lang.Long, java.lang.Double, java.math.BigDecimal

Note

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.

DATE, TIME, DATETIME, TIMESTAMPjava.lang.String, java.sql.Date, java.sql.Timestamp

The ResultSet.getObject() method uses the following type conversions between MySQL and Java types, following the JDBC specification where appropriate:

Table 23.3. MySQL Types to Java Types for ResultSet.getObject()

MySQL Type NameReturned as Java Class
BIT(1) (new in MySQL-5.0)java.lang.Boolean
BIT( > 1) (new in MySQL-5.0)byte[]
TINYINTjava.lang.Boolean if the configuration property "tinyInt1isBit" is set to "true" (the default) and the storage size is "1", or java.lang.Integer if not.
BOOL , BOOLEANSee TINYINT , above as these are aliases for TINYINT(1) , currently.
SMALLINT[(M)] [UNSIGNED]java.lang.Integer (regardless if UNSIGNED or not)
MEDIUMINT[(M)] [UNSIGNED]java.lang.Integer (regardless if UNSIGNED or not)
INT,INTEGER[(M)] [UNSIGNED]java.lang.Integer , if UNSIGNED java.lang.Long
BIGINT[(M)] [UNSIGNED]java.lang.Long , if UNSIGNED java.math.BigInteger
FLOAT[(M,D)]java.lang.Float
DOUBLE[(M,B)]java.lang.Double
DECIMAL[(M[,D])]java.math.BigDecimal
DATEjava.sql.Date
DATETIMEjava.sql.Timestamp
TIMESTAMP[(M)]java.sql.Timestamp
TIMEjava.sql.Time
YEAR[(2|4)]java.sql.Date (with the date set two January 1st, at midnight)
CHAR(M)java.lang.String (unless the character set for the column is BINARY , then byte[] is returned.
VARCHAR(M) [BINARY]java.lang.String (unless the character set for the column is BINARY , then byte[] is returned.
BINARY(M)byte[]
VARBINARY(M)byte[]
TINYBLOBbyte[]
TINYTEXTjava.lang.String
BLOBbyte[]
TEXTjava.lang.String
MEDIUMBLOBbyte[]
MEDIUMTEXTjava.lang.String
LONGBLOBbyte[]
LONGTEXTjava.lang.String
ENUM('value1','value2',...)java.lang.String
SET('value1','value2',...)java.lang.String

23.3.3.4. Using Character Sets and Unicode

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 Statement.execute(), Statement.executeUpdate(), Statement.executeQuery() as well as all PreparedStatement and CallableStatement parameters with the exclusion of parameters set using setBytes(), setBinaryStream(), setAsiiStream(), setUnicodeStream() and setBlob() .

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 useUnicode and characterEncoding properties.

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 ResultSets .

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 ' character_set ' for server versions older than 4.1.0 and ' character_set_server ' for server versions 4.1.0 and newer. See the "Server Character Set and Collation" section in the MySQL server manual for more information.

To override the automatically-detected encoding on the client side, use the characterEncoding property in the URL used to connect to the server.

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 23.4. MySQL to Java Encoding Name Translations

MySQL Character Set NameJava-Style Character Encoding Name
usa7US-ASCII
big5Big5
gbkGBK
sjisSJIS
gb2312EUC_CN
ujisEUC_JP
euc_krEUC_KR
latin1ISO8859_1
latin1_deISO8859_1
german1ISO8859_1
danishISO8859_1
latin2ISO8859_2
czechISO8859_2
hungarianISO8859_2
croatISO8859_2
greekISO8859_7
hebrewISO8859_8
latin5ISO8859_9
latvianISO8859_13
latvian1ISO8859_13
estoniaISO8859_13
dosCp437
pclatin2Cp852
cp866Cp866
koi8_ruKOI8_R
tis620TIS620
win1250Cp1250
win1250chCp1250
win1251Cp1251
cp1251Cp1251
win1251ukrCp1251
cp1257Cp1257
macromanMacRoman
macceMacCentralEurope
utf8UTF-8
ucs2UnicodeBig

Warning

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.

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 characterEncoding property.

23.3.3.5. Connecting Securely Using SSL

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:

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@example.com, CN=Walrus, O=MySQL AB, L=Orenburg, ST=Some
-State, C=RU
Issuer: EMAILADDRESS=walrus@example.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().

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
 ...

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.

23.3.3.6. Using Master/Slave Replication with ReplicationConnection

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 Connection.getReadOnly() .

An application signals that it wants a transaction to be read-only by calling Connection.setReadOnly(true), 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 "sticky" 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 Connection.setReadOnly(false) and the driver will ensure that further calls are sent to the "master" MySQL server. The driver takes care of propagating the current state of autocommit, isolation level, and catalog between all of the connections that it uses to accomplish this load balancing functionality.

To enable this functionality, use the " com.mysql.jdbc.ReplicationDriver " 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, ReplicationDriver does not currently work with java.sql.DriverManager -based connection creation unless it is the only MySQL JDBC driver registered with the DriverManager .

Here is a short, simple example of how ReplicationDriver might be used in a standalone application.

import java.sql.Connection;
import java.sql.ResultSet;
import java.util.Properties;

import com.mysql.jdbc.ReplicationDriver;

public class ReplicationDriverDemo {

    public static void main(String[] args) throws Exception {
        ReplicationDriver driver = new ReplicationDriver();

        Properties props = new Properties();

        // We want this for failover on the slaves
        props.put("autoReconnect", "true");

        // We want to load balance between the slaves
        props.put("roundRobinLoadBalance", "true");

        props.put("user", "foo");
        props.put("password", "bar");

        //
        // Looks like a normal MySQL JDBC url, with a comma-separated list
        // of hosts, the first being the 'master', the rest being any number
        // of slaves that the driver will load balance against
        //

        Connection conn =
            driver.connect("jdbc:mysql://master,slave1,slave2,slave3/test",
                props);

        //
        // Perform read/write work on the master
        // by setting the read-only flag to "false"
        //

        conn.setReadOnly(false);
        conn.setAutoCommit(false);
        conn.createStatement().executeUpdate("UPDATE some_table ....");
        conn.commit();

        //
        // Now, do a query from a slave, the driver automatically picks one
        // from the list
        //

        conn.setReadOnly(true);

        ResultSet rs = conn.createStatement().executeQuery("SELECT a,b,c FROM some_other_table");

         .......
    }
}

23.3.4. Using Connector/J with J2EE and Other Java Frameworks

This section describes how to use Connector/J in several contexts.

23.3.4.1. General J2EE Concepts

This section provides general background on J2EE concepts that pertain to use of Connector/J.

23.3.4.1.1. Understanding Connection Pooling

Connection pooling is a technique of creating and managing a pool of connections that are ready for use by any thread that needs them.

This technique of "pooling" 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.

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.

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.

Connection pooling can greatly increase the performance of your Java application, while reducing overall resource usage. The main benefits to connection pooling are:

  • Reduced connection creation time

    While 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."

  • Simplified programming model

    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.

  • Controlled resource usage

    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.

Remember that each connection to MySQL has overhead (memory, CPU, context switches, etc) on both the client and server side. Every connection limits how many resources there are available to your application as well as the MySQL server. Many of these resources will be used whether or not the connection is actually doing any useful work!

Connection pools can be tuned to maximize performance, while keeping resource utilization below the point where your application will start to fail rather than just run slower.

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.

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 23.12. Using a Connection Pool with a J2EE Application Server

import java.sql.Connection;
import java.sql.SQLException;
import java.sql.Statement;

import javax.naming.InitialContext;
import javax.sql.DataSource;


public class MyServletJspOrEjb {

    public void doSomething() throws Exception {
        /*
         * Create a JNDI Initial context to be able to
         *  lookup  the DataSource
         *
         * In production-level code, this should be cached as
         * an instance or static variable, as it can
         * be quite expensive to create a JNDI context.
         *
         * Note: This code only works when you are using servlets
         * or EJBs in a J2EE application server. If you are
         * using connection pooling in standalone Java code, you
         * will have to create/configure datasources using whatever
         * mechanisms your particular connection pooling library
         * provides.
         */

        InitialContext ctx = new InitialContext();

         /*
          * Lookup the DataSource, which will be backed by a pool
          * that the application server provides. DataSource instances
          * are also a good candidate for caching as an instance
          * variable, as JNDI lookups can be expensive as well.
          */

        DataSource ds = (DataSource)ctx.lookup("java:comp/env/jdbc/MySQLDB");

        /*
         * The following code is what would actually be in your
         * Servlet, JSP or EJB 'service' method...where you need
         * to work with a JDBC connection.
         */

        Connection conn = null;
        Statement stmt = null;

        try {
            conn = ds.getConnection();

            /*
             * Now, use normal JDBC programming to work with
             * MySQL, making sure to close each resource when you're
             * finished with it, which allows the connection pool
             * resources to be recovered as quickly as possible
             */

            stmt = conn.createStatement();
            stmt.execute("SOME SQL QUERY");

            stmt.close();
            stmt = null;

            conn.close();
            conn = null;
        } finally {
            /*
             * close any jdbc instances here that weren't
             * explicitly closed during normal code path, so
             * that we don't 'leak' resources...
             */

            if (stmt != null) {
                try {
                    stmt.close();
                } catch (sqlexception sqlex) {
                    // ignore -- as we can't do anything about it here
                }

                stmt = null;
            }

            if (conn != null) {
                try {
                    conn.close();
                } catch (sqlexception sqlex) {
                    // ignore -- as we can't do anything about it here
                }

                conn = null;
            }
        }
    }
}

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.

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, etc), connections, and anything created by them (statements, result sets, etc) 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 (buffers, locks, sockets, etc) may be tied up for some time, or worst case, may be tied up forever.

What's the Best Size for my Connection Pool?

As with all other configuration rules-of-thumb, the answer is "It depends." While 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.

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.

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 backwards from there to determine what values of minimum and maximum pooled connections give the best performance for your particular application.

23.3.4.2. Using Connector/J with Tomcat

The following instructions are based on the instructions for Tomcat-5.x, available at http://jakarta.apache.org/tomcat/tomcat-5.0-doc/jndi-datasource-examples-howto.html which is current at the time this document was written.

First, install the .jar file that comes with Connector/J in $CATALINA_HOME/common/lib so that it is available to all applications installed in the container.

Next, Configure the JNDI DataSource by adding a declaration resource to $CATALINA_HOME/conf/server.xml in the context that defines your web application:

<Context ....>

  ...

  <Resource name="jdbc/MySQLDB"
               auth="Container"
               type="javax.sql.DataSource"/>

  <!-- The name you used above, must match _exactly_ here!

       The connection pool will be bound into JNDI with the name
       "java:/comp/env/jdbc/MySQLDB"
  -->

  <ResourceParams name="jdbc/MySQLDB">
    <parameter>
      <name>factory</name>
      <value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
    </parameter>

    <!-- Don't set this any higher than max_connections on your
         MySQL server, usually this should be a 10 or a few 10's
         of connections, not hundreds or thousands -->

    <parameter>
      <name>maxActive</name>
      <value>10</value>
    </parameter>

    <!-- You don't want to many idle connections hanging around
         if you can avoid it, only enough to soak up a spike in
         the load -->

    <parameter>
      <name>maxIdle</name>
      <value>5</value>
    </parameter>

    <!-- Don't use autoReconnect=true, it's going away eventually
         and it's a crutch for older connection pools that couldn't
         test connections. You need to decide if your application is
         supposed to deal with SQLExceptions (hint, it should), and
         how much of a performance penalty you're willing to pay
         to ensure 'freshness' of the connection -->

    <parameter>
      <name>validationQuery</name>
      <value>SELECT 1</value>
    </parameter>

   <!-- The most conservative approach is to test connections
        before they're given to your application. For most applications
        this is okay, the query used above is very small and takes
        no real server resources to process, other than the time used
        to traverse the network.

        If you have a high-load application you'll need to rely on
        something else. -->

    <parameter>
      <name>testOnBorrow</name>
      <value>true</value>
    </parameter>

   <!-- Otherwise, or in addition to testOnBorrow, you can test
        while connections are sitting idle -->

    <parameter>
      <name>testWhileIdle</name>
      <value>true</value>
    </parameter>

    <!-- You have to set this value, otherwise even though
         you've asked connections to be tested while idle,
         the idle evicter thread will never run -->

    <parameter>
      <name>timeBetweenEvictionRunsMillis</name>
      <value>10000</value>
    </parameter>

    <!-- Don't allow connections to hang out idle too long,
         never longer than what wait_timeout is set to on the
         server...A few minutes or even fraction of a minute
         is sometimes okay here, it depends on your application
         and how much spikey load it will see -->

    <parameter>
      <name>minEvictableIdleTimeMillis</name>
      <value>60000</value>
    </parameter>

    <!-- Username and password used when connecting to MySQL -->

    <parameter>
     <name>username</name>
     <value>someuser</value>
    </parameter>

    <parameter>
     <name>password</name>
     <value>somepass</value>
    </parameter>

    <!-- Class name for the Connector/J driver -->

    <parameter>
       <name>driverClassName</name>
       <value>com.mysql.jdbc.Driver</value>
    </parameter>

    <!-- The JDBC connection url for connecting to MySQL, notice
         that if you want to pass any other MySQL-specific parameters
         you should pass them here in the URL, setting them using the
         parameter tags above will have no effect, you will also
         need to use &amp; to separate parameter values as the
         ampersand is a reserved character in XML -->

    <parameter>
      <name>url</name>
      <value>jdbc:mysql://localhost:3306/test</value>
    </parameter>

  </ResourceParams>
</Context>

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:

Error: java.sql.SQLException: Cannot load JDBC driver class 'null ' SQL
state: null 

23.3.4.3. Using Connector/J with JBoss

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 lib directory for your server configuration (which is usually called "default"). Then, in the same configuration directory, in the subdirectory named "deploy", 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:

<datasources>
    <local-tx-datasource>
        <!-- This connection pool will be bound into JNDI with the name
             "java:/MySQLDB" -->

        <jndi-name>MySQLDB</jndi-name>
        <connection-url>jdbc:mysql://localhost:3306/dbname</connection-url>
        <driver-class>com.mysql.jdbc.Driver</driver-class>
        <user-name>user</user-name>
        <password>pass</password>

        <min-pool-size>5</min-pool-size>

        <!-- Don't set this any higher than max_connections on your
         MySQL server, usually this should be a 10 or a few 10's
         of connections, not hundreds or thousands -->

        <max-pool-size>20</max-pool-size>

        <!-- Don't allow connections to hang out idle too long,
         never longer than what wait_timeout is set to on the
         server...A few minutes is usually okay here,
         it depends on your application
         and how much spikey load it will see -->

        <idle-timeout-minutes>5</idle-timeout-minutes>

        <!-- If you're using Connector/J 3.1.8 or newer, you can use
             our implementation of these to increase the robustness
             of the connection pool. -->

        <exception-sorter-class-name>com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter</exception-sorter-class-name>
        <valid-connection-checker-class-name>com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker</valid-connection-checker-class-name>

    </local-tx-datasource>
</datasources> 

23.3.5. Diagnosing Connector/J Problems

This section describes how to solve problems that you may encounter when using Connector/J.

23.3.5.1. Common Problems and Solutions

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.

24.3.5.1.1:

Question:

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 just fine with the MySQL command-line client.

Answer:

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.

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, logged in as a user that can grant privileges, 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 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.

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.

Warning

If you don't understand what the 'GRANT' command does, or how it works, you should read and understand the 'General Security Issues and the MySQL Access Privilege System' section of the MySQL manual before attempting to change privileges.

Changing privileges and permissions improperly in MySQL can potentially cause your server installation to not have optimal security properties.

24.3.5.1.2:

Question:

My application throws a SQLException 'No Suitable Driver'. Why is this happening?

Answer:

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").

24.3.5.1.3:

Question:

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 

Answer:

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 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.

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 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 "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 to (by default, 3306).

24.3.5.1.4:

Question:

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

Answer:

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").

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.

The following (simplistic) example shows what code that can handle these exceptions might look like:

Example 23.13. Example of transaction with retry logic

public void doBusinessOp() throws SQLException {
        Connection conn = null;
        Statement stmt = null;
        ResultSet rs = null;

        //
        // How many times do you want to retry the transaction
        // (or at least _getting_ a connection)?
        //
        int retryCount = 5;

        boolean transactionCompleted = false;

        do {
            try {
                conn = getConnection(); // assume getting this from a
                                        // javax.sql.DataSource, or the
                                        // java.sql.DriverManager

                conn.setAutoCommit(false);

                //
                // Okay, at this point, the 'retry-ability' of the
                // transaction really depends on your application logic,
                // whether or not you're using autocommit (in this case
                // not), and whether you're using transacational storage
                // engines
                //
                // For this example, we'll assume that it's _not_ safe
                // to retry the entire transaction, so we set retry count
                // to 0 at this point
                //
                // If you were using exclusively transaction-safe tables,
                // or your application could recover from a connection going
                // bad in the middle of an operation, then you would not
                // touch 'retryCount' here, and just let the loop repeat
                // until retryCount == 0.
                //
                retryCount = 0;

                stmt = conn.createStatement();

                String query = "SELECT foo FROM bar ORDER BY baz";

                rs = stmt.executeQuery(query);

                while (rs.next()) {
                }

                rs.close();
                rs = null;

                stmt.close();
                stmt = null;

                conn.commit();
                conn.close();
                conn = null;

                transactionCompleted = true;
            } catch (SQLException sqlEx) {

                //
                // The two SQL states that are 'retry-able' are 08S01
                // for a communications error, and 41000 for deadlock.
                //
                // Only retry if the error was due to a stale connection,
                // communications problem or deadlock
                //

                String sqlState = sqlEx.getSQLState();

                if ("08S01".equals(sqlState) || "41000".equals(sqlState)) {
                    retryCount--;
                } else {
                    retryCount = 0;
                }
            } finally {
                if (rs != null) {
                    try {
                        rs.close();
                    } catch (SQLException sqlEx) {
                        // You'd probably want to log this . . .
                    }
                }

                if (stmt != null) {
                    try {
                        stmt.close();
                    } catch (SQLException sqlEx) {
                        // You'd probably want to log this as well . . .
                    }
                }

                if (conn != null) {
                    try {
                        //
                        // If we got here, and conn is not null, the
                        // transaction should be rolled back, as not
                        // all work has been done

                        try {
                            conn.rollback();
                        } finally {
                            conn.close();
                        }
                    } catch (SQLException sqlEx) {
                        //
                        // If we got an exception here, something
                        // pretty serious is going on, so we better
                        // pass it up the stack, rather than just
                        // logging it. . .

                        throw sqlEx;
                    }
                }
            }
        } while (!transactionCompleted && (retryCount > 0));
    }

24.3.5.1.5:

Question:

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

Answer:

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 all of the primary key(s) and the query can only span one table (i.e. no joins). This is outlined in the JDBC specification.

23.3.5.2. How to Report Bugs or Problems

The normal place to report bugs is http://bugs.mysql.com/, 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.

If you have found a sensitive security bug in MySQL, you can send email to security@mysql.com.

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.

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.

If you have a repeatable bug report, please report it to the bugs database at http://bugs.mysql.com/.

Any bug that we are able to repeat has a high chance of being fixed in the next MySQL release.

To report other problems, you can use one of the MySQL mailing lists.

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.

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.

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

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.

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.

If at all possible, you should create a repeatable, stanalone testcase that doesn't involve any third-party classes.

To streamline this process, we ship a base class for testcases with Connector/J, named ' com.mysql.jdbc.util.BaseBugReport '. To create a testcase for Connector/J using this class, create your own class that inherits from com.mysql.jdbc.util.BaseBugReport and override the methods setUp(), tearDown() and runTest ().

In the setUp() method, create code that creates your tables, and populates them with any data needed to demonstrate the bug.

In the runTest () method, create code that demonstrates the bug using the tables and data you created in the 'setUp' method.

In the tearDown() method, drop any tables you created in the setUp() method.

In any of the above three methods, you should use one of the variants of the getConnection () method to create a JDBC connection to MySQL:

  • 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.

  • getNewConnection() - Use this if you need to get a new connection for your bug report (i.e. there's more than one connection involved).

  • getConnection(String url) - Returns a connection using the given URL.

  • getConnection(String url, Properties props) - Returns a connection using the given URL and properties.

If you need to use a JDBC URL that is different than 'jdbc:mysql:///test', then override the method getUrl() as well.

Use the assertTrue(boolean expression) and assertTrue(String failureMessage, boolean expression) 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).

Finally, create a main () method that creates a new instance of your testcase, and calls the run method:

public static void main(String[] args) throws Exception {
      new MyBugReport().run();
 }

Once you have finished your testcase, and have verified that it demonstrates the bug you are reporting, upload it with your bug report to http://bugs.mysql.com/.

23.3.6. Changelog

# Changelog
# $Id: CHANGES,v 1.38.4.206 2005/05/12 15:25:54 mmatthews Exp $

05-17-05 - Version 3.2.1-alpha

    - Autoreconnect functionality (i.e. autoReconnect=true) is now deprecated.
      An exception will be thrown if you try and use it, use 
      'enableDeprecatedAutoreconnect=true' to still use autoReconnect. However
      this feature will be removed in Connector/J 3.3, see the manual for 
      solutions that don't require autoReconnect to be used.

    - Driver now checks if server variable 'init_connect' is set, and if so
      checks autocommit setting, and applies it.
  
    - If connected to server > 5.0.x, and Statement.setFetchSize( > 0), the
      driver will try and use server prepared statements and fetch
      statements using result set 'cursors'.
  
    - ServerPreparedStatements now correctly 'stream' BLOB/CLOB data to the
      server. You can configure the threshold chunk size using the
      JDBC URL property 'blobSendChunkSize' (the default is one megabyte).
  
    - Support sql mode NO_BACKSLASH_ESCAPES with non-server-side prepared
      statements.

12-23-04 - Version 3.2.0-alpha

    - Fixed incorrect return values from DatabaseMetaData.supportsCatalogIn*().
    
    - Support for 'cursor' based result sets when using ServerPreparedStatements
      and MySQL 5.0 or newer. Result set needs to be forward-only, and a non-zero
      fetch size for this feature to be enabled.
      
    - Refactoring of where logic for prepared statement, server-prepared 
      statement lives.

10-07-05 - Version 3.1.11-stable

    - Fixed BUG#11629 - Spurious "!" on console when character
      encoding is "utf8".
      
    - Fixed statements generated for testcases missing ";" for
      "plain" statements.
      
    - Fixed BUG#11663 - Incorrect generation of testcase scripts 
      for server-side prepared statements.
      
    - Fixed regression caused by fix for BUG#11552 that caused driver
      to return incorrect values for unsigned integers when those 
      integers where within the range of the positive signed type.
    
    - Moved source code to svn repo.
    
    - Fixed BUG#11797 - Escape tokenizer doesn't respect stacked single quotes
      for escapes.
  
    - GEOMETRY type not recognized when using server-side prepared statements.
    
    - Fixed BUG#11879 -- ReplicationConnection won't switch to slave, throws 
      "Catalog can't be null" exception.
      
    - Fixed BUG#12218, properties shared between master and slave with 
      replication connection.
      
    - Fixed BUG#10630, Statement.getWarnings() fails with NPE if statement 
      has been closed.
      
    - Only get char[] from SQL in PreparedStatement.ParseInfo() when needed.
    
    - Fixed BUG#12104 - Geometry types not handled with server-side prepared 
      statements.
      
    - Fixed BUG#11614 - StringUtils.getBytes() doesn't work when using 
      multibyte character encodings and a length in  _characters_ is 
      specified.
      
    - Fixed BUG#11798 - Pstmt.setObject(...., Types.BOOLEAN) throws exception.
    
    - Fixed BUG#11976 - maxPerformance.properties mis-spells 
      "elideSetAutoCommits".
  
    - Fixed BUG#11575 -- DBMD.storesLower/Mixed/UpperIdentifiers()
      reports incorrect values for servers deployed on Windows.
  
    - Fixed BUG#11190 - ResultSet.moveToCurrentRow() fails to work when 
      preceeded by a call to ResultSet.moveToInsertRow().
  
    - Fixed BUG#11115, VARBINARY data corrupted when using server-side
      prepared statements and .setBytes().

    - Fixed BUG#12229 - explainSlowQueries hangs with server-side
      prepared statements.
  
    - Fixed BUG#11498 - Escape processor didn't honor strings demarcated
      with double quotes.
  
    - Lifted restriction of changing streaming parameters with server-side
      prepared statements. As long as _all_ streaming parameters were set
      before execution, .clearParameters() does not have to be called. 
      (due to limitation of client/server protocol, prepared statements
       can not reset _individual_ stream data on the server side).
   
    - Reworked Field class, *Buffer, and MysqlIO to be aware of field
      lengths > Integer.MAX_VALUE.
  
    - Updated DBMD.supportsCorrelatedQueries() to return true for versions > 
      4.1, supportsGroupByUnrelated() to return true and 
      getResultSetHoldability() to return HOLD_CURSORS_OVER_COMMIT.
  
    - Fixed BUG#12541 - Handling of catalog argument in 
      DatabaseMetaData.getIndexInfo(), which also means changes to the following
      methods in DatabaseMetaData:
  
    - getBestRowIdentifier()
    - getColumns()
    - getCrossReference()
    - getExportedKeys()
    - getImportedKeys()
    - getIndexInfo()
    - getPrimaryKeys()
    - getProcedures() (and thus indirectly getProcedureColumns())
    - getTables()
  
      The "catalog" argument in all of these methods now behaves in the following
      way:
  
        - Specifying NULL means that catalog will not be used to filter the
          results (thus all databases will be searched), unless you've
          set "nullCatalogMeansCurrent=true" in your JDBC URL properties.
      
        - Specifying "" means "current" catalog, even though this isn't quite
          JDBC spec compliant, it's there for legacy users.
      
        - Specifying a catalog works as stated in the API docs.
    
        - Made Connection.clientPrepare() available from "wrapped" connections
          in the jdbc2.optional package (connections built by 
          ConnectionPoolDataSource instances).
      
    - Added Connection.isMasterConnection() for clients to be able to determine
      if a multi-host master/slave connection is connected to the first host
      in the list.
      
    - Fixed BUG#12753 - Tokenizer for "=" in URL properties was causing
      sessionVariables=.... to be parameterized incorrectly.

    - Fixed BUG#11781, foreign key information that is quoted is 
      parsed incorrectly when DatabaseMetaData methods use that
      information.
      
    - The "sendBlobChunkSize" property is now clamped to "max_allowed_packet"
      with consideration of stream buffer size and packet headers to avoid
      PacketTooBigExceptions when "max_allowed_packet" is similar in size
      to the default "sendBlobChunkSize" which is 1M.
      
    - CallableStatement.clearParameters() now clears resources associated
      with INOUT/OUTPUT parameters as well as INPUT parameters.
      
    - Fixed BUG#12417 - Connection.prepareCall() is database name 
      case-sensitive (on Windows systems).
      
    - Fixed BUG#12752 - Cp1251 incorrectly mapped to win1251 for 
      servers newer than 4.0.x.
      
    - Fixed BUG#12970 - java.sql.Types.OTHER returned for 
      BINARY and VARBINARY columns when using 
      DatabaseMetaData.getColumns(). 
  
    - ServerPreparedStatement.getBinding() now checks if the statement
      is closed before attempting to reference the list of parameter
      bindings, to avoid throwing a NullPointerException.
      
    - Fixed BUG#13277 - ResultSetMetaData from 
      Statement.getGeneratedKeys() caused NullPointerExceptions to be
      thrown whenever a method that required a connection reference
      was called.
      
    - Backport of Field class, ResultSetMetaData.getColumnClassName(),
      and ResultSet.getObject(int) changes from 5.0 branch to fix
      behavior surrounding VARCHAR BINARY/VARBINARY and related
      types.
      
    - Fixed NullPointerException when converting "catalog" parameter
      in many DatabaseMetaDataMethods to byte[]s (for the result set)
      when the parameter is null. ("null" isn't technically allowed
      by the JDBC specification, but we've historically allowed it).
      
    - Backport of VAR[BINARY|CHAR] [BINARY] types detection from 
      5.0 branch.
    
    - Read response in MysqlIO.sendFileToServer(), even if the 
      local file can't be opened, otherwise next query issued
      will fail, because it's reading the response to the empty
      LOAD DATA INFILE packet sent to the server.
      
    - Workaround for BUG#13374 - ResultSet.getStatement() 
      on closed result set returns NULL (as per JDBC 4.0 spec,
      but not backwards-compatible). Set the connection property
      "retainStatementAfterResultSetClose" to "true" to be able
      to retrieve a ResultSet's statement after the ResultSet has
      been closed via .getStatement() (the default is "false", to
      be JDBC-compliant and to reduce the chance that code using
      JDBC leaks Statement instances).
      
    - Fixed BUG#13453 - URL configuration parameters don't allow
      '&' or '=' in their values. The JDBC driver now parses 
      configuration parameters as if they are encoded using the 
      application/x-www-form-urlencoded format as specified
      by java.net.URLDecoder - 
      http://java.sun.com/j2se/1.5.0/docs/api/java/net/URLDecoder.html
      
      If the '%' character is present in a configuration property,
      it must now be represented as %25, which is the encoded form
      of '%' when using application/x-www-form-urlencoded encoding.
      
    - The configuration property "sessionVariables" now allows you to
      specify variables that start with the "@" sign.
      
    - Fixed BUG#13043 - when 'gatherPerfMetrics' is enabled for 
      servers older than 4.1.0, a NullPointerException is thrown from 
      the constructor of ResultSet if the query doesn't use any tables.

06-23-05 - Version 3.1.10-stable

    - Fixed connecting without a database specified raised an exception
      in MysqlIO.changeDatabaseTo().
  
    - Initial implemention of ParameterMetadata for 
      PreparedStatement.getParameterMetadata(). Only works fully
      for CallableStatements, as current server-side prepared statements
      return every parameter as a VARCHAR type.
    
06-22-05 - Version 3.1.9-stable

    - Overhaul of character set configuration, everything now
      lives in a properties file.
  
    - Driver now correctly uses CP932 if available on the server
      for Windows-31J, CP932 and MS932 java encoding names, 
      otherwise it resorts to SJIS, which is only a close 
      approximation. Currently only MySQL-5.0.3 and newer (and
      MySQL-4.1.12 or .13, depending on when the character set
      gets backported) can reliably support any variant of CP932.

    - Fixed BUG#9064 - com.mysql.jdbc.PreparedStatement.ParseInfo 
      does unnecessary call to toCharArray().

    - Fixed Bug#10144 - Memory leak in ServerPreparedStatement if 
      serverPrepare() fails.
 
    - Actually write manifest file to correct place so it ends up
      in the binary jar file.

    - Added "createDatabaseIfNotExist" property (default is "false"),
      which will cause the driver to ask the server to create the 
      database specified in the URL if it doesn't exist. You must have
      the appropriate privileges for database creation for this to
      work.

    - Fixed BUG#10156 - Unsigned SMALLINT treated as signed for ResultSet.getInt(),
      fixed all cases for UNSIGNED integer values and server-side prepared statements,
      as well as ResultSet.getObject() for UNSIGNED TINYINT.
 
    - Fixed BUG#10155, double quotes not recognized when parsing 
      client-side prepared statements.
  
    - Made enableStreamingResults() visible on 
      com.mysql.jdbc.jdbc2.optional.StatementWrapper.
  
    - Made ServerPreparedStatement.asSql() work correctly so auto-explain
      functionality would work with server-side prepared statements.
  
    - Made JDBC2-compliant wrappers public in order to allow access to
      vendor extensions.
  
    - Cleaned up logging of profiler events, moved code to dump a profiler
      event as a string to com.mysql.jdbc.log.LogUtils so that third
      parties can use it.
  
    - DatabaseMetaData.supportsMultipleOpenResults() now returns true. The
      driver has supported this for some time, DBMD just missed that fact.
  
    - Fixed BUG#10310 - Driver doesn't support {?=CALL(...)} for calling
      stored functions. This involved adding support for function retrieval
      to DatabaseMetaData.getProcedures() and getProcedureColumns() as well.
      
    - Fixed BUG#10485, SQLException thrown when retrieving YEAR(2) 
      with ResultSet.getString(). The driver will now always treat YEAR types
      as java.sql.Dates and return the correct values for getString(). 
      Alternatively, the "yearIsDateType" connection property can be set to
      "false" and the values will be treated as SHORTs.
  
    - The datatype returned for TINYINT(1) columns when "tinyInt1isBit=true" 
      (the default) can be switched between Types.BOOLEAN and Types.BIT
      using the new configuration property "transformedBitIsBoolean", which
      defaults to "false". If set to "false" (the default), 
      DatabaseMetaData.getColumns() and ResultSetMetaData.getColumnType() 
      will return Types.BOOLEAN for TINYINT(1) columns. If "true", 
      Types.BOOLEAN will be returned instead. Irregardless of this configuration
      property, if "tinyInt1isBit" is enabled, columns with the type TINYINT(1)
      will be returned as java.lang.Boolean instances from 
      ResultSet.getObject(..), and ResultSetMetaData.getColumnClassName()
      will return "java.lang.Boolean".

    - Fixed BUG#10496 - SQLException is thrown when using property 
      "characterSetResults" with cp932 or eucjpms.
      
    - Reorganized directory layout, sources now in "src" folder,
      don't pollute parent directory when building, now output goes
      to "./build", distribution goes to "./dist".
      
    - Added support/bug hunting feature that generates .sql test
      scripts to STDERR when "autoGenerateTestcaseScript" is set
      to "true".
      
    - Fixed BUG#10850 - 0-length streams not sent to server when
      using server-side prepared statements.
    
    - Setting "cachePrepStmts=true" now causes the Connection to also 
      cache the check the driver performs to determine if a prepared 
      statement can be server-side or not, as well as caches server-side
      prepared statements for the lifetime of a connection. As before,
      the "prepStmtCacheSize" parameter controls the size of these
      caches.
      
    - Try to handle OutOfMemoryErrors more gracefully. Although not
      much can be done, they will in most cases close the connection
      they happened on so that further operations don't run into 
      a connection in some unknown state. When an OOM has happened, 
      any further operations on the connection will fail with a 
      "Connection closed" exception that will also list the OOM exception
      as the reason for the implicit connection close event.
      
    - Don't send COM_RESET_STMT for each execution of a server-side
      prepared statement if it isn't required.
      
    - Driver detects if you're running MySQL-5.0.7 or later, and does
      not scan for "LIMIT ?[,?]" in statements being prepared, as the
      server supports those types of queries now.
      
    - Fixed BUG#11115, Varbinary data corrupted when using server-side
      prepared statements and ResultSet.getBytes().
      
    - Connection.setCatalog() is now aware of the "useLocalSessionState"
      configuration property, which when set to true will prevent
      the driver from sending "USE ..." to the server if the requested
      catalog is the same as the current catalog.
      
    - Added the following configuration bundles, use one or many via
      the "useConfigs" configuration property:
    
        * maxPerformance -- maximum performance without being reckless
        * solarisMaxPerformance -- maximum performance for Solaris,
                                   avoids syscalls where it can
        * 3-0-Compat -- Compatibility with Connector/J 3.0.x functionality
        
    - Added "maintainTimeStats" configuration property (defaults to "true"),
      which tells the driver whether or not to keep track of the last query time
      and the last successful packet sent to the server's time. If set to
      false, removes two syscalls per query.
    
    - Fixed BUG#11259, autoReconnect ping causes exception on connection 
      startup.
      
    - Fixed BUG#11360 Connector/J dumping query into SQLException twice
    
    - Fixed PreparedStatement.setClob() not accepting null as a parameter.
    
    - Fixed BUG#11411 - Production package doesn't include JBoss integration 
      classes.
      
    - Removed nonsensical "costly type conversion" warnings when using 
      usage advisor.


04-14-05 - Version 3.1.8-stable

    - Fixed DatabaseMetaData.getTables() returning views when they were
      not asked for as one of the requested table types.

    - Added support for new precision-math DECIMAL type in MySQL >= 5.0.3.

    - Fixed ResultSet.getTime() on a NULL value for server-side prepared
      statements throws NPE.

    - Made Connection.ping() a public method.

    - Fixed Bug#8868, DATE_FORMAT() queries returned as BLOBs from getObject().

    - ServerPreparedStatements now correctly 'stream' BLOB/CLOB data to the
      server. You can configure the threshold chunk size using the
      JDBC URL property 'blobSendChunkSize' (the default is one megabyte).

    - BlobFromLocator now uses correct identifier quoting when generating
      prepared statements.

    - Server-side session variables can be preset at connection time by
      passing them as a comma-delimited list for the connection property
      'sessionVariables'.

    - Fixed regression in ping() for users using autoReconnect=true.

    - Fixed BUG#9040 - PreparedStatement.addBatch() doesn't work with server-side
      prepared statements and streaming BINARY data.

    - Fixed BUG#8800 - DBMD.supportsMixedCase*Identifiers() returns wrong
      value on servers running on case-sensitive filesystems.

    - Fixed BUG#9206, can not use 'UTF-8' for characterSetResults
      configuration property.

    - Fixed BUG#9236, a continuation of BUG#8868, where functions used in queries
      that should return non-string types when resolved by temporary tables suddenly
      become opaque binary strings (work-around for server limitation). Also fixed
      fields with type of CHAR(n) CHARACTER SET BINARY to return correct/matching
      classes for RSMD.getColumnClassName() and ResultSet.getObject().

    - Fixed BUG#8792 - DBMD.supportsResultSetConcurrency() not returning
      true for forward-only/read-only result sets (we obviously support this).

    - Fixed BUG#8803, 'DATA_TYPE' column from DBMD.getBestRowIdentifier()
      causes ArrayIndexOutOfBoundsException when accessed (and in fact, didn't
      return any value).

    - Check for empty strings ('') when converting char/varchar column data to numbers,
      throw exception if 'emptyStringsConvertToZero' configuration property is set
      to 'false' (for backwards-compatibility with 3.0, it is now set to 'true'
      by default, but will most likely default to 'false' in 3.2).

    - Fixed BUG#9320 - PreparedStatement.getMetaData() inserts blank row in database
      under certain conditions when not using server-side prepared statements.

    - Connection.canHandleAsPreparedStatement() now makes 'best effort' to distinguish
      LIMIT clauses with placeholders in them from ones without in order to have fewer
      false positives when generating work-arounds for statements the server cannot
      currently handle as server-side prepared statements.

    - Fixed build.xml to not compile log4j logging if log4j not available.

    - Added support for the c3p0 connection pool's (http://c3p0.sf.net/)
      validation/connection checker interface which uses the lightweight
      'COM_PING' call to the server if available. To use it, configure your
      c3p0 connection pool's 'connectionTesterClassName' property to use
      'com.mysql.jdbc.integration.c3p0.MysqlConnectionTester'.

    - Better detection of LIMIT inside/outside of quoted strings so that
      the driver can more correctly determine whether a prepared statement
      can be prepared on the server or not.

    - Fixed BUG#9319 - Stored procedures with same name in
      different databases confuse the driver when it tries to determine
      parameter counts/types.

    - Added finalizers to ResultSet and Statement implementations to be JDBC
      spec-compliant, which requires that if not explicitly closed, these
      resources should be closed upon garbage collection.

    - Fixed BUG#9682 - Stored procedures with DECIMAL parameters with
      storage specifications that contained "," in them would fail.

    - PreparedStatement.setObject(int, Object, int type, int scale) now
      uses scale value for BigDecimal instances.

    - Fixed BUG#9704 - Statement.getMoreResults() could throw NPE when
      existing result set was .close()d.

    - The performance metrics feature now gathers information about
      number of tables referenced in a SELECT.

    - The logging system is now automatically configured. If the value has
      been set by the user, via the URL property "logger" or the system
      property "com.mysql.jdbc.logger", then use that, otherwise, autodetect
      it using the following steps:

         Log4j, if it's available,
         Then JDK1.4 logging,
         Then fallback to our STDERR logging.

    - Fixed BUG#9778, DBMD.getTables() shouldn't return tables if views
      are asked for, even if the database version doesn't support views.

    - Fixed driver not returning 'true' for '-1' when ResultSet.getBoolean()
      was called on result sets returned from server-side prepared statements.

    - Added a Manifest.MF file with implementation information to the .jar
      file.

    - More tests in Field.isOpaqueBinary() to distinguish opaque binary (i.e.
      fields with type CHAR(n) and CHARACTER SET BINARY) from output of
      various scalar and aggregate functions that return strings.

    - Fixed BUG#9917 - Should accept null for catalog (meaning use current)
      in DBMD methods, even though it's not JDBC-compliant for legacy's sake.
      Disable by setting connection property "nullCatalogMeansCurrent" to "false"
      (which will be the default value in C/J 3.2.x).

    - Fixed BUG#9769 - Should accept null for name patterns in DBMD (meaning "%"),
      even though it isn't JDBC compliant, for legacy's sake. Disable by setting
      connection property "nullNamePatternMatchesAll" to "false" (which will be
      the default value in C/J 3.2.x).

02-18-05 - Version 3.1.7-stable

    - Fixed BUG#7686, Timestamp key column data needed "_binary'"
      stripped for UpdatableResultSet.refreshRow().

    - Fixed BUG#7715 - Timestamps converted incorrectly to strings
      with Server-side prepared statements and updatable result sets.

    - Detect new sql_mode variable in string form (it used to be
      integer) and adjust quoting method for strings appropriately.

    - Added 'holdResultsOpenOverStatementClose' property (default is
      false), that keeps result sets open over statement.close() or new
      execution on same statement (suggested by Kevin Burton).

    - Fixed BUG#7952 -- Infinite recursion when 'falling back' to master
      in failover configuration.

    - Disable multi-statements (if enabled) for MySQL-4.1 versions prior
      to version 4.1.10 if the query cache is enabled, as the server
      returns wrong results in this configuration.

    - Fixed duplicated code in configureClientCharset() that prevented
      useOldUTF8Behavior=true from working properly.

    - Removed 'dontUnpackBinaryResults' functionality, the driver now
      always stores results from server-side prepared statements as-is
      from the server and unpacks them on demand.

    - Fixed BUG#8096 where emulated locators corrupt binary data
      when using server-side prepared statements.

    - Fixed synchronization issue with
      ServerPreparedStatement.serverPrepare() that could cause
      deadlocks/crashes if connection was shared between threads.

    - By default, the driver now scans SQL you are preparing via all
      variants of Connection.prepareStatement() 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 (BUG#4718). You can
      disable this by passing 'emulateUnsupportedPstmts=false' in your
      JDBC URL.

    - Remove _binary introducer from parameters used as in/out
      parameters in CallableStatement.

    - Always return byte[]s for output parameters registered as *BINARY.

    - Send correct value for 'boolean' "true" to server for
      PreparedStatement.setObject(n, "true", Types.BIT).

    - Fixed bug with Connection not caching statements from
      prepareStatement() when the statement wasn't a server-side
      prepared statement.

    - Choose correct 'direction' to apply time adjustments when both
      client and server are in GMT timezone when using
      ResultSet.get(..., cal) and PreparedStatement.set(...., cal).

    - Added 'dontTrackOpenResources' option (default is false, to be
      JDBC compliant), which helps with memory use for non-well-behaved
      apps (i.e applications which don't close Statements when they
      should).

    - Fixed BUG#8428 - ResultSet.getString() doesn't maintain format
      stored on server, bug fix only enabled when 'noDatetimeStringSync'
      property is set to 'true' (the default is 'false').

    - Fixed NPE in ResultSet.realClose() when using usage advisor and
      result set was already closed.

    - Fixed BUG#8487 - PreparedStatements not creating streaming result
      sets.

    - Don't pass NULL to String.valueOf() in
      ResultSet.getNativeConvertToString(), as it stringifies it (i.e.
      returns "null"), which is not correct for the method in question.

    - Fixed BUG#8484 - ResultSet.getBigDecimal() throws exception
      when rounding would need to occur to set scale. The driver now
      chooses a rounding mode of 'half up' if non-rounding
      BigDecimal.setScale() fails.

    - Added 'useLocalSessionState' configuration property, when set to
      'true' the JDBC driver trusts that the application is well-behaved
      and only sets autocommit and transaction isolation levels using
      the methods provided on java.sql.Connection, and therefore can
      manipulate these values in many cases without incurring
      round-trips to the database server.

    - Added enableStreamingResults() to Statement for connection pool
      implementations that check Statement.setFetchSize() for
      specification-compliant values. Call Statement.setFetchSize(>=0)
      to disable the streaming results for that statement.

    - Added support for BIT type in MySQL-5.0.3. The driver will treat
      BIT(1-8) as the JDBC standard BIT type (which maps to
      java.lang.Boolean), as the server does not currently send enough
      information to determine the size of a bitfield when < 9 bits are
      declared. BIT(>9) will be treated as VARBINARY, and will return
      byte[] when getObject() is called.

12-23-04 - Version 3.1.6-stable

    - Fixed hang on SocketInputStream.read() with Statement.setMaxRows() and
      multiple result sets when driver has to truncate result set directly,
      rather than tacking a 'LIMIT n' on the end of it.

    - Fixed BUG#7026 - DBMD.getProcedures() doesn't respect catalog parameter.

12-02-04 - Version 3.1.5-gamma

    - Fix comparisons made between string constants and dynamic strings that
      are either toUpperCase()d or toLowerCase()d to use Locale.ENGLISH, as
      some locales 'override' case rules for English. Also use
      StringUtils.indexOfIgnoreCase() instead of .toUpperCase().indexOf(),
      avoids creating a very short-lived transient String instance.

    - Fixed BUG#5235 - Server-side prepared statements did not honor
      'zeroDateTimeBehavior' property, and would cause class-cast
      exceptions when using ResultSet.getObject(), as the all-zero string
      was always returned.

    - Fixed batched updates with server prepared statements weren't looking if
      the types had changed for a given batched set of parameters compared
      to the previous set, causing the server to return the error
      'Wrong arguments to mysql_stmt_execute()'.

    - Handle case when string representation of timestamp contains trailing '.'
      with no numbers following it.

    - Fixed BUG#5706 - Inefficient detection of pre-existing string instances
      in ResultSet.getNativeString().

    - Don't throw exceptions for Connection.releaseSavepoint().

    - Use a per-session Calendar instance by default when decoding dates
      from ServerPreparedStatements (set to old, less performant behavior by
      setting property 'dynamicCalendars=true').

    - Added experimental configuration property 'dontUnpackBinaryResults',
      which delays unpacking binary result set values until they're asked for,
      and only creates object instances for non-numerical values (it is set
      to 'false' by default). For some usecase/jvm combinations, this is
      friendlier on the garbage collector.

    - Fixed BUG#5729 - UNSIGNED BIGINT unpacked incorrectly from
      server-side prepared statement result sets.

    - Fixed BUG#6225 - ServerSidePreparedStatement allocating short-lived
      objects un-necessarily.

    - Removed un-wanted new Throwable() in ResultSet constructor due to bad
      merge (caused a new object instance that was never used for every result
      set created) - Found while profiling for BUG#6359.

    - Fixed too-early creation of StringBuffer in EscapeProcessor.escapeSQL(),
      also return String when escaping not needed (to avoid unnecssary object
      allocations). Found while profiling for BUG#6359.

    - Use null-safe-equals for key comparisons in updatable result sets.

    - Fixed BUG#6537, SUM() on Decimal with server-side prepared statement ignores
      scale if zero-padding is needed (this ends up being due to conversion to DOUBLE
      by server, which when converted to a string to parse into BigDecimal, loses all
      'padding' zeros).

    - Use DatabaseMetaData.getIdentifierQuoteString() when building DBMD
      queries.

    - Use 1MB packet for sending file for LOAD DATA LOCAL INFILE if that
      is < 'max_allowed_packet' on server.

    - Fixed BUG#6399, ResultSetMetaData.getColumnDisplaySize() returns incorrect
      values for multi-byte charsets.

    - Make auto-deserialization of java.lang.Objects stored in BLOBs
      configurable via 'autoDeserialize' property (defaults to 'false').

    - Re-work Field.isOpaqueBinary() to detect 'CHAR(n) CHARACTER SET BINARY'
      to support fixed-length binary fields for ResultSet.getObject().

    - Use our own implementation of buffered input streams to get around
      blocking behavior of java.io.BufferedInputStream. Disable this with
      'useReadAheadInput=false'.

    - Fixed BUG#6348, failing to connect to the server when one of the
      addresses for the given host name is IPV6 (which the server does
      not yet bind on). The driver now loops through _all_ IP addresses
      for a given host, and stops on the first one that accepts() a
      socket.connect().

09-04-04 - Version 3.1.4-beta

    - Fixed BUG#4510 - connector/j 3.1.3 beta does not handle integers
      correctly (caused by changes to support unsigned reads in
      Buffer.readInt() -> Buffer.readShort()).

    - Added support in DatabaseMetaData.getTables() and getTableTypes()
      for VIEWs which are now available in MySQL server version 5.0.x.

    - Fixed BUG#4642 -- ServerPreparedStatement.execute*() sometimes
      threw ArrayIndexOutOfBoundsException when unpacking field metadata.

    - Optimized integer number parsing, enable 'old' slower integer parsing
      using JDK classes via 'useFastIntParsing=false' property.

    - Added 'useOnlyServerErrorMessages' property, which causes message text
      in exceptions generated by the server to only contain the text sent by
      the server (as opposed to the SQLState's 'standard' description, followed
      by the server's error message). This property is set to 'true' by default.

    - Fixed BUG#4689 - ResultSet.wasNull() does not work for primatives if a
      previous null was returned.

    - Track packet sequence numbers if enablePacketDebug=true, and throw an
      exception if packets received out-of-order.

    - Fixed BUG#4482, ResultSet.getObject() returns wrong type for strings
      when using prepared statements.

    - Calling MysqlPooledConnection.close() twice (even though an application
      error), caused NPE. Fixed.

    - Fixed BUG#5012 -- ServerPreparedStatements dealing with return of
      DECIMAL type don't work.

    - Fixed BUG#5032 -- ResultSet.getObject() doesn't return
      type Boolean for pseudo-bit types from prepared statements on 4.1.x
      (shortcut for avoiding extra type conversion when using binary-encoded
      result sets obscurred test in getObject() for 'pseudo' bit type)

    - You can now use URLs in 'LOAD DATA LOCAL INFILE' statements, and the
      driver will use Java's built-in handlers for retreiving the data and
      sending it to the server. This feature is not enabled by default,
      you must set the 'allowUrlInLocalInfile' connection property to 'true'.

    - The driver is more strict about truncation of numerics on
      ResultSet.get*(), and will throw a SQLException when truncation is
      detected. You can disable this by setting 'jdbcCompliantTruncation' to
      false (it is enabled by default, as this functionality is required
      for JDBC compliance).

    - Added three ways to deal with all-zero datetimes when reading them from
      a ResultSet, 'exception' (the default), which throws a SQLException
      with a 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'.

    - Fixed ServerPreparedStatement to read prepared statement metadata off
      the wire, even though it's currently a placeholder instead of using
      MysqlIO.clearInputStream() which didn't work at various times because
      data wasn't available to read from the server yet. This fixes sporadic
      errors users were having with ServerPreparedStatements throwing
      ArrayIndexOutOfBoundExceptions.

    - Use com.mysql.jdbc.Message's classloader when loading resource bundle,
      should fix sporadic issues when the caller's classloader can't locate
      the resource bundle.

07-07-04 - Version 3.1.3-beta

    - Mangle output parameter names for CallableStatements so they
      will not clash with user variable names.

    - Added support for INOUT parameters in CallableStatements.

    - Fix for BUG#4119, null bitmask sent for server-side prepared
      statements was incorrect.

    - Use SQL Standard SQL states by default, unless 'useSqlStateCodes'
      property is set to 'false'.

    - Added packet debuging code (see the 'enablePacketDebug' property
      documentation).

    - Added constants for MySQL error numbers (publicly-accessible,
      see com.mysql.jdbc.MysqlErrorNumbers), and the ability to
      generate the mappings of vendor error codes to SQLStates
      that the driver uses (for documentation purposes).

    - Externalized more messages (on-going effort).

    - Fix for BUG#4311 - Error in retrieval of mediumint column with
      prepared statements and binary protocol.

    - Support new timezone variables in MySQL-4.1.3 when
      'useTimezone=true'

    - Support for unsigned numerics as return types from prepared statements.
      This also causes a change in ResultSet.getObject() for the 'bigint unsigned'
      type, which used to return BigDecimal instances, it now returns instances
      of java.lang.BigInteger.

06-09-04 - Version 3.1.2-alpha

    - Fixed stored procedure parameter parsing info when size was
      specified for a parameter (i.e. char(), varchar()).

    - Enabled callable statement caching via 'cacheCallableStmts'
      property.

    - Fixed case when no output parameters specified for a
      stored procedure caused a bogus query to be issued
      to retrieve out parameters, leading to a syntax error
      from the server.

    - Fixed case when no parameters could cause a NullPointerException
      in CallableStatement.setOutputParameters().

    - Removed wrapping of exceptions in MysqlIO.changeUser().

    - Fixed sending of split packets for large queries, enabled nio
      ability to send large packets as well.

    - Added .toString() functionality to ServerPreparedStatement,
      which should help if you're trying to debug a query that is
      a prepared statement (it shows SQL as the server would process).

    - Added 'gatherPerformanceMetrics' property, along with properties
      to control when/where this info gets logged (see docs for more
      info).

    - ServerPreparedStatements weren't actually de-allocating
      server-side resources when .close() was called.

    - Added 'logSlowQueries' property, along with property
      'slowQueriesThresholdMillis' to control when a query should
      be considered 'slow'.

    - Correctly map output parameters to position given in
      prepareCall() vs. order implied during registerOutParameter() -
      fixes BUG#3146.

    - Correctly detect initial character set for servers >= 4.1.0

    - Cleaned up detection of server properties.

    - Support placeholder for parameter metadata for server >= 4.1.2

    - Fix for BUG#3539 getProcedures() does not return any procedures in
      result set

    - Fix for BUG#3540 getProcedureColumns() doesn't work with wildcards
      for procedure name

    - Fixed BUG#3520 -- DBMD.getSQLStateType() returns incorrect value.

    - Added 'connectionCollation' property to cause driver to issue
      'set collation_connection=...' query on connection init if default
      collation for given charset is not appropriate.

    - Fixed DatabaseMetaData.getProcedures() when run on MySQL-5.0.0 (output of
    'show procedure status' changed between 5.0.1 and 5.0.0.

    - Fixed BUG#3804 -- getWarnings() returns SQLWarning instead of DataTruncation

    - Don't enable server-side prepared statements for server version 5.0.0 or 5.0.1,
    as they aren't compatible with the '4.1.2+' style that the driver uses (the driver
    expects information to come back that isn't there, so it hangs).

02-14-04 - Version 3.1.1-alpha

    - Fixed bug with UpdatableResultSets not using client-side
    prepared statements.

    - Fixed character encoding issues when converting bytes to
      ASCII when MySQL doesn't provide the character set, and
      the JVM is set to a multi-byte encoding (usually affecting
      retrieval of numeric values).

    - Unpack 'unknown' data types from server prepared statements
      as Strings.

    - Implemented long data (Blobs, Clobs, InputStreams, Readers)
      for server prepared statements.

    - Implemented Statement.getWarnings() for MySQL-4.1 and newer
      (using 'SHOW WARNINGS').

    - Default result set type changed to TYPE_FORWARD_ONLY
      (JDBC compliance).

    - Centralized setting of result set type and concurrency.

    - Re-factored how connection properties are set and exposed
      as DriverPropertyInfo as well as Connection and DataSource
      properties.

    - Support for NIO. Use 'useNIO=true' on platforms that support
      NIO.

    - Support for SAVEPOINTs (MySQL >= 4.0.14 or 4.1.1).

    - Support for mysql_change_user()...See the changeUser() method
      in com.mysql.jdbc.Connection.

    - Reduced number of methods called in average query to be more
      efficient.

    - Prepared Statements will be re-prepared on auto-reconnect. Any errors
      encountered are postponed until first attempt to re-execute the
      re-prepared statement.

    - Ensure that warnings are cleared before executing queries
      on prepared statements, as-per JDBC spec (now that we support
      warnings).

    - Support 'old' profileSql capitalization in ConnectionProperties.
      This property is deprecated, you should use 'profileSQL' if possible.

    - Optimized Buffer.readLenByteArray() to return shared empty byte array
      when length is 0.

    - Allow contents of PreparedStatement.setBlob() to be retained
      between calls to .execute*().

    - Deal with 0-length tokens in EscapeProcessor (caused by callable
      statement escape syntax).

    - Check for closed connection on delete/update/insert row operations in
      UpdatableResultSet.

    - Fix support for table aliases when checking for all primary keys in
      UpdatableResultSet.

    - Removed useFastDates connection property.

    - Correctly initialize datasource properties from JNDI Refs, including
      explicitly specified URLs.

    - DatabaseMetaData now reports supportsStoredProcedures() for
      MySQL versions >= 5.0.0

    - Fixed stack overflow in Connection.prepareCall() (bad merge).

    - Fixed IllegalAccessError to Calendar.getTimeInMillis() in DateTimeValue
      (for JDK < 1.4).

    - Fix for BUG#1673, where DatabaseMetaData.getColumns() is not
      returning correct column ordinal info for non '%' column name patterns.

    - Merged fix of datatype mapping from MySQL type 'FLOAT' to
      java.sql.Types.REAL from 3.0 branch.

    - Detect collation of column for RSMD.isCaseSensitive().

    - Fixed sending of queries > 16M.

    - Added named and indexed input/output parameter support to CallableStatement.
      MySQL-5.0.x or newer.

    - Fixed NullPointerException in ServerPreparedStatement.setTimestamp(),
      as well as year and month descrepencies in
      ServerPreparedStatement.setTimestamp(), setDate().

    - Added ability to have multiple database/JVM targets for compliance
      and regression/unit tests in build.xml.

    - Fixed NPE and year/month bad conversions when accessing some
      datetime functionality in ServerPreparedStatements and their
      resultant result sets.

    - Display where/why a connection was implicitly closed (to
      aid debugging).

    - CommunicationsException implemented, that tries to determine
      why communications was lost with a server, and displays
      possible reasons when .getMessage() is called.

    - Fixed BUG#2359, NULL values for numeric types in binary
      encoded result sets causing NullPointerExceptions.

    - Implemented Connection.prepareCall(), and DatabaseMetaData.
      getProcedures() and getProcedureColumns().

    - Reset 'long binary' parameters in ServerPreparedStatement when
      clearParameters() is called, by sending COM_RESET_STMT to the
      server.

    - Merged prepared statement caching, and .getMetaData() support
      from 3.0 branch.

    - Fixed off-by-1900 error in some cases for
      years in TimeUtil.fastDate/TimeCreate() when unpacking results
      from server-side prepared statements.

    - Fixed BUG#2502 -- charset conversion issue in getTables().

    - Implemented multiple result sets returned from a statement
      or stored procedure.

    - Fixed BUG#2606 -- Server side prepared statements not returning
      datatype 'YEAR' correctly.

    - Enabled streaming of result sets from server-side prepared
      statements.

    - Fixed BUG#2623 -- Class-cast exception when using
      scrolling result sets and server-side prepared statements.

    - Merged unbuffered input code from 3.0.

    - Fixed ConnectionProperties that weren't properly exposed
      via accessors, cleaned up ConnectionProperties code.

    - Fixed BUG#2671, NULL fields not being encoded correctly in
      all cases in server side prepared statements.

    - Fixed rare buffer underflow when writing numbers into buffers
      for sending prepared statement execution requests.

    - Use DocBook version of docs for shipped versions of drivers.

02-18-03 - Version 3.1.0-alpha

    - Added 'requireSSL' property.

    - Added 'useServerPrepStmts' property (default 'false'). The
      driver will use server-side prepared statements when the
      server version supports them (4.1 and newer) when this
      property is set to 'true'. It is currently set to 'false'
      by default until all bind/fetch functionality has been
      implemented. Currently only DML prepared statements are
      implemented for 4.1 server-side prepared statements.

    - Track open Statements, close all when Connection.close()
      is called (JDBC compliance).

06-23-05 - Version 3.0.17-ga

    - Fixed BUG#5874, Timestamp/Time conversion goes in the wrong 'direction'
      when useTimeZone='true' and server timezone differs from client timezone.

    - Fixed BUG#7081, DatabaseMetaData.getIndexInfo() ignoring 'unique'
      parameter.

    - Support new protocol type 'MYSQL_TYPE_VARCHAR'.

    - Added 'useOldUTF8Behavoior' configuration property, which causes
      JDBC driver to act like it did with MySQL-4.0.x and earlier when
      the character encoding is 'utf-8' when connected to MySQL-4.1 or
      newer.

    - Fixed BUG#7316 - Statements created from a pooled connection were
      returning physical connection instead of logical connection when
      getConnection() was called.

    - Fixed BUG#7033 - PreparedStatements don't encode Big5 (and other
      multi-byte) character sets correctly in static SQL strings.

    - Fixed BUG#6966, connections starting up failed-over (due to down master)
      never retry master.

    - Fixed BUG#7061, PreparedStatement.fixDecimalExponent() adding extra
      '+', making number unparseable by MySQL server.

    - Fixed BUG#7686, Timestamp key column data needed "_binary'" stripped for
      UpdatableResultSet.refreshRow().

    - Backported SQLState codes mapping from Connector/J 3.1, enable with
      'useSqlStateCodes=true' as a connection property, it defaults to
      'false' in this release, so that we don't break legacy applications (it
      defaults to 'true' starting with Connector/J 3.1).

    - Fixed BUG#7601, PreparedStatement.fixDecimalExponent() adding extra
      '+', making number unparseable by MySQL server.

    - Escape sequence {fn convert(..., type)} now supports ODBC-style types
      that are prepended by 'SQL_'.

    - Fixed duplicated code in configureClientCharset() that prevented
      useOldUTF8Behavior=true from working properly.

    - Handle streaming result sets with > 2 billion rows properly by fixing
      wraparound of row number counter.

    - Fixed BUG#7607 - MS932, SHIFT_JIS and Windows_31J not recog. as
      aliases for sjis.

    - Fixed BUG#6549 (while fixing #7607), adding 'CP943' to aliases for
      sjis.

    - Fixed BUG#8064, which requires hex escaping of binary data when using
      multi-byte charsets with prepared statements.

    - Fixed BUG#8812, NON_UNIQUE column from DBMD.getIndexInfo() returned
      inverted value.

    - Workaround for server BUG#9098 - default values of CURRENT_* for
      DATE/TIME/TIMESTAMP/TIMESTAMP columns can't be distinguished from
      'string' values, so UpdatableResultSet.moveToInsertRow() generates
      bad SQL for inserting default values.

    - Fixed BUG#8629 - 'EUCKR' charset is sent as 'SET NAMES euc_kr' which
      MySQL-4.1 and newer doesn't understand.

    - DatabaseMetaData.supportsSelectForUpdate() returns correct value based
      on server version.

    - Use hex escapes for PreparedStatement.setBytes() for double-byte charsets
      including 'aliases' Windows-31J, CP934, MS932.

    - Added support for the "EUC_JP_Solaris" character encoding, which maps
      to a MySQL encoding of "eucjpms" (backported from 3.1 branch). This only
      works on servers that support eucjpms, namely 5.0.3 or later.

11-15-04 - Version 3.0.16-ga

    - Re-issue character set configuration commands when re-using pooled
      connections and/or Connection.changeUser() when connected to MySQL-4.1
      or newer.

    - Fixed ResultSetMetaData.isReadOnly() to detect non-writable columns
      when connected to MySQL-4.1 or newer, based on existence of 'original'
      table and column names.

    - Fixed BUG#5664, ResultSet.updateByte() when on insert row
      throws ArrayOutOfBoundsException.

    - Fixed DatabaseMetaData.getTypes() returning incorrect (i.e. non-negative)
      scale for the 'NUMERIC' type.

    - Fixed BUG#6198, off-by-one bug in Buffer.readString(string).

    - Made TINYINT(1) -> BIT/Boolean conversion configurable via 'tinyInt1isBit'
      property (default 'true' to be JDBC compliant out of the box).

    - Only set 'character_set_results' during connection establishment if
      server version >= 4.1.1.

    - Fixed regression where useUnbufferedInput was defaulting to 'false'.

    - Fixed BUG#6231, ResultSet.getTimestamp() on a column with TIME in it
      fails.

09-04-04 - Version 3.0.15-production

    - Fixed BUG#4010 - StringUtils.escapeEasternUnicodeByteStream is still
      broken for GBK

    - Fixed BUG#4334 - Failover for autoReconnect not using port #'s for any
      hosts, and not retrying all hosts. (WARN: This required a change to
      the SocketFactory connect() method signature, which is now

       public Socket connect(String host, int portNumber, Properties props)

      therefore any third-party socket factories will have to be changed
      to support this signature.

    - Logical connections created by MysqlConnectionPoolDataSource will
      now issue a rollback() when they are closed and sent back to the pool.
      If your application server/connection pool already does this for you, you
      can set the 'rollbackOnPooledClose' property to false to avoid the
      overhead of an extra rollback().

    - Removed redundant calls to checkRowPos() in ResultSet.

    - Fixed BUG#4742, 'DOUBLE' mapped twice in DBMD.getTypeInfo().

    - Added FLOSS license exemption.

    - Fixed BUG#4808, calling .close() twice on a PooledConnection causes NPE.

    - Fixed BUG#4138 and BUG#4860, DBMD.getColumns() returns incorrect JDBC
      type for unsigned columns. This affects type mappings for all numeric
      types in the RSMD.getColumnType() and RSMD.getColumnTypeNames() methods
      as well, to ensure that 'like' types from DBMD.getColumns() match up
      with what RSMD.getColumnType() and getColumnTypeNames() return.

    - 'Production' - 'GA' in naming scheme of distributions.

    - Fix for BUG#4880, RSMD.getPrecision() returning 0 for non-numeric types
      (should return max length in chars for non-binary types, max length
      in bytes for binary types). This fix also fixes mapping of
      RSMD.getColumnType() and RSMD.getColumnTypeName() for the BLOB types based
      on the length sent from the server (the server doesn't distinguish between
      TINYBLOB, BLOB, MEDIUMBLOB or LONGBLOB at the network protocol level).

    - Fixed BUG#5022 - ResultSet should release Field[] instance in .close().

    - Fixed BUG#5069 -- ResultSet.getMetaData() should not return
      incorrectly-initialized metadata if the result set has been closed, but
      should instead throw a SQLException. Also fixed for getRow() and
      getWarnings() and traversal methods by calling checkClosed() before
      operating on instance-level fields that are nullified during .close().

    - Parse new timezone variables from 4.1.x servers.

    - Use _binary introducer for PreparedStatement.setBytes() and
      set*Stream() when connected to MySQL-4.1.x or newer to avoid
      misinterpretation during character conversion.

05-28-04 - Version 3.0.14-production

    - Fixed URL parsing error

05-27-04 - Version 3.0.13-production

    - Fixed BUG#3848 - Using a MySQLDatasource without server name fails

    - Fixed BUG#3920 - "No Database Selected" when using
    MysqlConnectionPoolDataSource.

    - Fixed BUG#3873 - PreparedStatement.getGeneratedKeys() method returns only
    1 result for batched insertions

05-18-04 - Version 3.0.12-production

    - Add unsigned attribute to DatabaseMetaData.getColumns() output
    in the TYPE_NAME column.

    - Added 'failOverReadOnly' property, to allow end-user to configure
    state of connection (read-only/writable) when failed over.

    - Backported 'change user' and 'reset server state' functionality
      from 3.1 branch, to allow clients of MysqlConnectionPoolDataSource
      to reset server state on getConnection() on a pooled connection.

    - Don't escape SJIS/GBK/BIG5 when using MySQL-4.1 or newer.

    - Allow 'url' parameter for MysqlDataSource and MysqlConnectionPool
      DataSource so that passing of other properties is possible from
      inside appservers.

    - Map duplicate key and foreign key errors to SQLState of
      '23000'.

    - Backport documentation tooling from 3.1 branch.

    - Return creating statement for ResultSets created by
      getGeneratedKeys() (BUG#2957)

    - Allow java.util.Date to be sent in as parameter to
      PreparedStatement.setObject(), converting it to a Timestamp
      to maintain full precision (BUG#3103).

    - Don't truncate BLOBs/CLOBs when using setBytes() and/or
      setBinary/CharacterStream() (BUG#2670).

    - Dynamically configure character set mappings for field-level
      character sets on MySQL-4.1.0 and newer using 'SHOW COLLATION'
      when connecting.

    - Map 'binary' character set to 'US-ASCII' to support DATETIME
      charset recognition for servers >= 4.1.2

    - Use 'SET character_set_results" during initialization to allow any
      charset to be returned to the driver for result sets.

    - Use charsetnr returned during connect to encode queries before
      issuing 'SET NAMES' on MySQL >= 4.1.0.

    - Add helper methods to ResultSetMetaData (getColumnCharacterEncoding()
      and getColumnCharacterSet()) to allow end-users to see what charset
      the driver thinks it should be using for the column.

    - Only set character_set_results for MySQL >= 4.1.0.

    - Fixed BUG#3511, StringUtils.escapeSJISByteStream() not covering all
      eastern double-byte charsets correctly.

    - Renamed StringUtils.escapeSJISByteStream() to more appropriate
      escapeEasternUnicodeByteStream().

    - Fixed BUG#3554 - Not specifying database in URL caused MalformedURL
      exception.

    - Auto-convert MySQL encoding names to Java encoding names if used
      for characterEncoding property.

    - Added encoding names that are recognized on some JVMs to fix case
      where they were reverse-mapped to MySQL encoding names incorrectly.

    - Use junit.textui.TestRunner for all unit tests (to allow them to be
      run from the command line outside of Ant or Eclipse).

    - Fixed BUG#3557 - UpdatableResultSet not picking up default values
      for moveToInsertRow().

    - Fixed BUG#3570 - inconsistent reporting of column type. The server
      still doesn't return all types for *BLOBs *TEXT correctly, so the
      driver won't return those correctly.

    - Fixed BUG#3520 -- DBMD.getSQLStateType() returns incorrect value.

    - Fixed regression in PreparedStatement.setString() and eastern character
      encodings.

    - Made StringRegressionTest 4.1-unicode aware.

02-19-04 - Version 3.0.11-stable

    - Trigger a 'SET NAMES utf8' when encoding is forced to 'utf8' _or_
    'utf-8' via the 'characterEncoding' property. Previously, only the
    Java-style encoding name of 'utf-8' would trigger this.

    - AutoReconnect time was growing faster than exponentially (BUG#2447).

    - Fixed failover always going to last host in list (BUG#2578)

    - Added 'useUnbufferedInput' parameter, and now use it by default
      (due to JVM issue
      http://developer.java.sun.com/developer/bugParade/bugs/4401235.html)

    - Detect 'on/off' or '1','2','3' form of lower_case_table_names on
      server.

    - Return 'java.lang.Integer' for TINYINT and SMALLINT types from
      ResultSetMetaData.getColumnClassName() (fix for BUG#2852).

    - Return 'java.lang.Double' for FLOAT type from ResultSetMetaData.
      getColumnClassName() (fix for BUG#2855).

    - Return '[B' instead of java.lang.Object for BINARY, VARBINARY and
      LONGVARBINARY types from ResultSetMetaData.getColumnClassName()
      (JDBC compliance).

    - Issue connection events on all instances created from a
      ConnectionPoolDataSource.

01-13-04 - Version 3.0.10-stable

    - Don't count quoted id's when inside a 'string' in PreparedStatement
      parsing (fix for BUG#1511).

    - 'Friendlier' exception message for PacketTooLargeException
       (BUG#1534).

    - Backported fix for aliased tables and UpdatableResultSets in
      checkUpdatability() method from 3.1 branch.

    - Fix for ArrayIndexOutOfBounds exception when using Statement.setMaxRows()
      (BUG#1695).

    - Fixed BUG#1576, dealing with large blobs and split packets not being
      read correctly.

    - Fixed regression of Statement.getGeneratedKeys() and REPLACE statements.

    - Fixed BUG#1630, subsequent call to ResultSet.updateFoo() causes NPE if
      result set is not updatable.

    - Fix for 4.1.1-style auth with no password.

    - Fix for BUG#1731, Foreign Keys column sequence is not consistent in
      DatabaseMetaData.getImported/Exported/CrossReference().

    - Fix for BUG#1775 - DatabaseMetaData.getSystemFunction() returning
      bad function 'VResultsSion'.

    - Fix for BUG#1592 -- cross-database updatable result sets
      are not checked for updatability correctly.

    - DatabaseMetaData.getColumns() should return Types.LONGVARCHAR for
      MySQL LONGTEXT type.

    - ResultSet.getObject() on TINYINT and SMALLINT columns should return
      Java type 'Integer' (BUG#1913)

    - Added 'alwaysClearStream' connection property, which causes the driver
      to always empty any remaining data on the input stream before
      each query.

    - Added more descriptive error message 'Server Configuration Denies
      Access to DataSource', as well as retrieval of message from server.

    - Autoreconnect code didn't set catalog upon reconnect if it had been
      changed.

    - Implement ResultSet.updateClob().

    - ResultSetMetaData.isCaseSensitive() returned wrong value for CHAR/VARCHAR
      columns.

    - Fix for BUG#1933 -- Connection property "maxRows" not honored.

    - Fix for BUG#1925 -- Statements being created too many times in
      DBMD.extractForeignKeyFromCreateTable().

    - Fix for BUG#1914 -- Support escape sequence {fn convert ... }

    - Fix for BUG#1958 -- ArrayIndexOutOfBounds when parameter number ==
      number of parameters + 1.

    - Fix for BUG#2006 -- ResultSet.findColumn() should use first matching
      column name when there are duplicate column names in SELECT query
      (JDBC-compliance).

    - Removed static synchronization bottleneck from
      PreparedStatement.setTimestamp().

    - Removed static synchronization bottleneck from instance factory
      method of SingleByteCharsetConverter.

    - Enable caching of the parsing stage of prepared statements via
      the 'cachePrepStmts', 'prepStmtCacheSize' and 'prepStmtCacheSqlLimit'
      properties (disabled by default).

    - Speed up parsing of PreparedStatements, try to use one-pass whenever
      possible.

    - Fixed security exception when used in Applets (applets can't
      read the system property 'file.encoding' which is needed
      for LOAD DATA LOCAL INFILE).

    - Use constants for SQLStates.

    - Map charset 'ko18_ru' to 'ko18r' when connected to MySQL-4.1.0 or
      newer.

    - Ensure that Buffer.writeString() saves room for the \0.

    - Fixed exception 'Unknown character set 'danish' on connect w/ JDK-1.4.0

    - Fixed mappings in SQLError to report deadlocks with SQLStates of '41000'.

    - 'maxRows' property would affect internal statements, so check it for all
      statement creation internal to the driver, and set to 0 when it is not.

10-07-03 - Version 3.0.9-stable

    - Faster date handling code in ResultSet and PreparedStatement (no longer
      uses Date methods that synchronize on static calendars).

    - Fixed test for end of buffer in Buffer.readString().

    - Fixed ResultSet.previous() behavior to move current
      position to before result set when on first row
      of result set (bugs.mysql.com BUG#496)

    - Fixed Statement and PreparedStatement issuing bogus queries
      when setMaxRows() had been used and a LIMIT clause was present
      in the query.

    - Fixed BUG#661 - refreshRow didn't work when primary key values
      contained values that needed to be escaped (they ended up being
      doubly-escaped).

    - Support InnoDB contraint names when extracting foreign key info
      in DatabaseMetaData BUG#517 and BUG#664
      (impl. ideas from Parwinder Sekhon)

    - Backported 4.1 protocol changes from 3.1 branch (server-side SQL
      states, new field info, larger client capability flags,
      connect-with-database, etc).

    - Fix UpdatableResultSet to return values for getXXX() when on
      insert row (BUG#675).

    - The insertRow in an UpdatableResultSet is now loaded with
      the default column values when moveToInsertRow() is called
      (BUG#688)

    - DatabaseMetaData.getColumns() wasn't returning NULL for
      default values that are specified as NULL.

    - Change default statement type/concurrency to TYPE_FORWARD_ONLY
      and CONCUR_READ_ONLY (spec compliance).

    - Don't try and reset isolation level on reconnect if MySQL doesn't
      support them.

    - Don't wrap SQLExceptions in RowDataDynamic.

    - Don't change timestamp TZ twice if useTimezone==true (BUG#774)

    - Fixed regression in large split-packet handling (BUG#848).

    - Better diagnostic error messages in exceptions for 'streaming'
      result sets.

    - Issue exception on ResultSet.getXXX() on empty result set (wasn't
      caught in some cases).

    - Don't hide messages from exceptions thrown in I/O layers.

    - Don't fire connection closed events when closing pooled connections, or
      on PooledConnection.getConnection() with already open connections (BUG#884).

    - Clip +/- INF (to smallest and largest representative values for the type in
      MySQL) and NaN (to 0) for setDouble/setFloat(), and issue a warning on the
      statement when the server does not support +/- INF or NaN.

    - Fix for BUG#879, double-escaping of '\' when charset is SJIS or GBK and '\'
      appears in non-escaped input.

    - When emptying input stream of unused rows for 'streaming' result sets,
      have the current thread yield() every 100 rows in order to not monopolize
      CPU time.

    - Fixed BUG#1099, DatabaseMetaData.getColumns() getting confused about the
      keyword 'set' in character columns.

    - Fixed deadlock issue with Statement.setMaxRows().

    - Fixed CLOB.truncate(), BUG#1130

    - Optimized CLOB.setChracterStream(), BUG#1131

    - Made databaseName, portNumber and serverName optional parameters
      for MysqlDataSourceFactory (BUG#1246)

    - Fix for BUG#1247 -- ResultSet.get/setString mashing char 127

    - Backported auth. changes for 4.1.1 and newer from 3.1 branch.

    - Added com.mysql.jdbc.util.BaseBugReport to help creation of testcases
      for bug reports.

    - Added property to 'clobber' streaming results, by setting the
      'clobberStreamingResults' property to 'true' (the default is 'false').
      This will cause a 'streaming' 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.

05-23-03 - Version 3.0.8-stable

    - Allow bogus URLs in Driver.getPropertyInfo().

    - Return list of generated keys when using multi-value INSERTS
      with Statement.getGeneratedKeys().

    - Use JVM charset with filenames and 'LOAD DATA [LOCAL] INFILE'

    - Fix infinite loop with Connection.cleanup().

    - Changed Ant target 'compile-core' to 'compile-driver', and
      made testsuite compilation a separate target.

    - Fixed result set not getting set for Statement.executeUpdate(),
      which affected getGeneratedKeys() and getUpdateCount() in
      some cases.

    - Unicode character 0xFFFF in a string would cause the driver to
      throw an ArrayOutOfBoundsException (Bug #378)

    - Return correct amount of generated keys when using 'REPLACE'
      statements.

    - Fix problem detecting server character set in some cases.

    - Fix row data decoding error when using _very_ large packets.

    - Optimized row data decoding.

    - Issue exception when operating on an already-closed
      prepared statement.

    - Fixed SJIS encoding bug, thanks to Naoto Sato.

    - Optimized usage of EscapeProcessor.

    - Allow multiple calls to Statement.close()

04-08-03 - Version 3.0.7-stable

    - Fixed MysqlPooledConnection.close() calling wrong event type.

    - Fixed StringIndexOutOfBoundsException in PreparedStatement.
      setClob().

    - 4.1 Column Metadata fixes

    - Remove synchronization from Driver.connect() and
      Driver.acceptsUrl().

    - IOExceptions during a transaction now cause the Connection to
      be closed.

    - Fixed missing conversion for 'YEAR' type in ResultSetMetaData.
      getColumnTypeName().

    - Don't pick up indexes that start with 'pri' as primary keys
      for DBMD.getPrimaryKeys().

    - Throw SQLExceptions when trying to do operations on a forcefully
      closed Connection (i.e. when a communication link failure occurs).

    - You can now toggle profiling on/off using
      Connection.setProfileSql(boolean).

    - Fixed charset issues with database metadata (charset was not
      getting set correctly).

    - Updatable ResultSets can now be created for aliased tables/columns
      when connected to MySQL-4.1 or newer.

    - Fixed 'LOAD DATA LOCAL INFILE' bug when file > max_allowed_packet.

    - Fixed escaping of 0x5c ('\') character for GBK and Big5 charsets.

    - Fixed ResultSet.getTimestamp() when underlying field is of type DATE.

    - Ensure that packet size from alignPacketSize() does not
      exceed MAX_ALLOWED_PACKET (JVM bug)

    - Don't reset Connection.isReadOnly() when autoReconnecting.

02-18-03 - Version 3.0.6-stable

    - Fixed ResultSetMetaData to return "" when catalog not known.
      Fixes NullPointerExceptions with Sun's CachedRowSet.

    - Fixed DBMD.getTypeInfo() and DBMD.getColumns() returning
      different value for precision in TEXT/BLOB types.

    - Allow ignoring of warning for 'non transactional tables' during
      rollback (compliance/usability) by setting 'ignoreNonTxTables'
      property to 'true'.

    - Fixed SQLExceptions getting swallowed on initial connect.

    - Fixed Statement.setMaxRows() to stop sending 'LIMIT' type queries
      when not needed (performance)

    - Clean up Statement query/method mismatch tests (i.e. INSERT not
      allowed with .executeQuery()).

    - More checks added in ResultSet traversal method to catch
      when in closed state.

    - Fixed ResultSetMetaData.isWritable() to return correct value.

    - Add 'window' of different NULL sorting behavior to
      DBMD.nullsAreSortedAtStart (4.0.2 to 4.0.10, true, otherwise,
      no).

    - Implemented Blob.setBytes(). You still need to pass the
      resultant Blob back into an updatable ResultSet or
      PreparedStatement to persist the changes, as MySQL does
      not support 'locators'.

    - Backported 4.1 charset field info changes from Connector/J 3.1

01-22-03 - Version 3.0.5-gamma

    - Fixed Buffer.fastSkipLenString() causing ArrayIndexOutOfBounds
      exceptions with some queries when unpacking fields.

    - Implemented an empty TypeMap for Connection.getTypeMap() so that
      some third-party apps work with MySQL (IBM WebSphere 5.0 Connection
      pool).

    - Added missing LONGTEXT type to DBMD.getColumns().

    - Retrieve TX_ISOLATION from database for
      Connection.getTransactionIsolation() when the MySQL version
      supports it, instead of an instance variable.

    - Quote table names in DatabaseMetaData.getColumns(),
      getPrimaryKeys(), getIndexInfo(), getBestRowIdentifier()

    - Greatly reduce memory required for setBinaryStream() in
      PreparedStatements.

    - Fixed ResultSet.isBeforeFirst() for empty result sets.

    - Added update options for foreign key metadata.


01-06-03 - Version 3.0.4-gamma

    - Added quoted identifiers to database names for
      Connection.setCatalog.

    - Added support for quoted identifiers in PreparedStatement
      parser.

    - Streamlined character conversion and byte[] handling in
      PreparedStatements for setByte().

    - Reduce memory footprint of PreparedStatements by sharing
      outbound packet with MysqlIO.

    - Added 'strictUpdates' property to allow control of amount
      of checking for 'correctness' of updatable result sets. Set this
      to 'false' if you want faster updatable result sets and you know
      that you create them from SELECTs on tables with primary keys and
      that you have selected all primary keys in your query.

    - Added support for 4.0.8-style large packets.

    - Fixed PreparedStatement.executeBatch() parameter overwriting.

12-17-02 - Version 3.0.3-dev

    - Changed charsToByte in SingleByteCharConverter to be non-static

    - Changed SingleByteCharConverter to use lazy initialization of each
      converter.

    - Fixed charset handling in Fields.java

    - Implemented Connection.nativeSQL()

    - More robust escape tokenizer -- recognize '--' comments, and allow
      nested escape sequences (see testsuite.EscapeProcessingTest)

    - DBMD.getImported/ExportedKeys() now handles multiple foreign keys
      per table.

    - Fixed ResultSetMetaData.getPrecision() returning incorrect values
      for some floating point types.

    - Fixed ResultSetMetaData.getColumnTypeName() returning BLOB for
      TEXT and TEXT for BLOB types.

    - Fixed Buffer.isLastDataPacket() for 4.1 and newer servers.

    - Added CLIENT_LONG_FLAG to be able to get more column flags
      (isAutoIncrement() being the most important)

    - Because of above, implemented ResultSetMetaData.isAutoIncrement()
      to use Field.isAutoIncrement().

    - Honor 'lower_case_table_names' when enabled in the server when
      doing table name comparisons in DatabaseMetaData methods.

    - Some MySQL-4.1 protocol support (extended field info from selects)

    - Use non-aliased table/column names and database names to fullly
      qualify tables and columns in UpdatableResultSet (requires
      MySQL-4.1 or newer)

    - Allow user to alter behavior of Statement/
      PreparedStatement.executeBatch() via 'continueBatchOnError' property
      (defaults to 'true').

    - Check for connection closed in more Connection methods
      (createStatement, prepareStatement, setTransactionIsolation,
      setAutoCommit).

    - More robust implementation of updatable result sets. Checks that
      _all_ primary keys of the table have been selected.

    - 'LOAD DATA LOCAL INFILE ...' now works, if your server is configured
      to allow it. Can be turned off with the 'allowLoadLocalInfile'
      property (see the README).

    - Substitute '?' for unknown character conversions in single-byte
      character sets instead of '\0'.

    - NamedPipeSocketFactory now works (only intended for Windows), see
      README for instructions.

11-08-02 - Version 3.0.2-dev

    - Fixed issue with updatable result sets and PreparedStatements not
      working

    - Fixed ResultSet.setFetchDirection(FETCH_UNKNOWN)

    - Fixed issue when calling Statement.setFetchSize() when using
      arbitrary values

    - Fixed incorrect conversion in ResultSet.getLong()

    - Implemented ResultSet.updateBlob().

    - Removed duplicate code from UpdatableResultSet (it can be inherited
      from ResultSet, the extra code for each method to handle updatability
      I thought might someday be necessary has not been needed).

    - Fixed "UnsupportedEncodingException" thrown when "forcing" a
      character encoding via properties.

    - Fixed various non-ASCII character encoding issues.

    - Added driver property 'useHostsInPrivileges'. Defaults to true.
      Affects whether or not '@hostname' will be used in
      DBMD.getColumn/TablePrivileges.

    - All DBMD result set columns describing schemas now return NULL
      to be more compliant with the behavior of other JDBC drivers
      for other databases (MySQL does not support schemas).

    - Added SSL support. See README for information on how to use it.

    - Properly restore connection properties when autoReconnecting
      or failing-over, including autoCommit state, and isolation level.

    - Use 'SHOW CREATE TABLE' when possible for determining foreign key
      information for DatabaseMetaData...also allows cascade options for
      DELETE information to be returned

    - Escape 0x5c character in strings for the SJIS charset.

    - Fixed start position off-by-1 error in Clob.getSubString()

    - Implemented Clob.truncate()

    - Implemented Clob.setString()

    - Implemented Clob.setAsciiStream()

    - Implemented Clob.setCharacterStream()

    - Added com.mysql.jdbc.MiniAdmin class, which allows you to send
      'shutdown' command to MySQL server...Intended to be used when 'embedding'
      Java and MySQL server together in an end-user application.

    - Added 'connectTimeout' parameter that allows users of JDK-1.4 and newer
      to specify a maxium time to wait to establish a connection.

    - Failover and autoReconnect only work when the connection is in a
      autoCommit(false) state, in order to stay transaction safe

    - Added 'queriesBeforeRetryMaster' property that specifies how many
      queries to issue when failed over before attempting to reconnect
      to the master (defaults to 50)

    - Fixed DBMD.supportsResultSetConcurrency() so that it returns true
      for ResultSet.TYPE_SCROLL_INSENSITIVE and ResultSet.CONCUR_READ_ONLY or
      ResultSet.CONCUR_UPDATABLE

    - Fixed ResultSet.isLast() for empty result sets (should return false).

    - PreparedStatement now honors stream lengths in setBinary/Ascii/Character
      Stream() unless you set the connection property
      'useStreamLengthsInPrepStmts' to 'false'.

    - Removed some not-needed temporary object creation by using Strings
      smarter in EscapeProcessor, Connection and DatabaseMetaData classes.

09-21-02 - Version 3.0.1-dev

    - Fixed ResultSet.getRow() off-by-one bug.

    - Fixed RowDataStatic.getAt() off-by-one bug.

    - Added limited Clob functionality (ResultSet.getClob(),
      PreparedStatemtent.setClob(),
      PreparedStatement.setObject(Clob).

    - Added socketTimeout parameter to URL.

    - Connection.isClosed() no longer "pings" the server.

    - Connection.close() issues rollback() when getAutoCommit() == false

    - Added "paranoid" parameter...sanitizes error messages removing
      "sensitive" information from them (i.e. hostnames, ports,
      usernames, etc.), as well as clearing "sensitive" data structures
      when possible.

    - Fixed ResultSetMetaData.isSigned() for TINYINT and BIGINT.

    - Charsets now automatically detected. Optimized code for single-byte
      character set conversion.

    - Implemented ResultSet.getCharacterStream()

    - Added "LOCAL TEMPORARY" to table types in DatabaseMetaData.getTableTypes()

    - Massive code clean-up to follow Java coding conventions (the time had come)


07-31-02 - Version 3.0.0-dev

    - !!! LICENSE CHANGE !!! The driver is now GPL. If you need
      non-GPL licenses, please contact me <mark@mysql.com>

    - JDBC-3.0 functionality including
      Statement/PreparedStatement.getGeneratedKeys() and
      ResultSet.getURL()

    - Performance enchancements - driver is now 50-100% faster
      in most situations, and creates fewer temporary objects

    - Repackaging...new driver name is "com.mysql.jdbc.Driver",
      old name still works, though (the driver is now provided
      by MySQL-AB)

    - Better checking for closed connections in Statement
      and PreparedStatement.

    - Support for streaming (row-by-row) result sets (see README)
      Thanks to Doron.

    - Support for large packets (new addition to MySQL-4.0 protocol),
      see README for more information.

    - JDBC Compliance -- Passes all tests besides stored procedure tests


    - Fix and sort primary key names in DBMetaData (SF bugs 582086 and 582086)

    - Float types now reported as java.sql.Types.FLOAT (SF bug 579573)

    - ResultSet.getTimestamp() now works for DATE types (SF bug 559134)

    - ResultSet.getDate/Time/Timestamp now recognizes all forms of invalid
      values that have been set to all zeroes by MySQL (SF bug 586058)

    - Testsuite now uses Junit (which you can get from www.junit.org)

    - The driver now only works with JDK-1.2 or newer.

    - Added multi-host failover support (see README)

    - General source-code cleanup.

    - Overall speed improvements via controlling transient object
      creation in MysqlIO class when reading packets

    - Performance improvements in  string handling and field
      metadata creation (lazily instantiated) contributed by
      Alex Twisleton-Wykeham-Fiennes


05-16-02 - Version 2.0.14

    - More code cleanup

    - PreparedStatement now releases resources on .close() (SF bug 553268)

    - Quoted identifiers not used if server version does not support them. Also,
      if server started with --ansi or --sql-mode=ANSI_QUOTES then '"' will be
      used as an identifier quote, otherwise '`' will be used.

    - ResultSet.getDouble() now uses code built into JDK to be more precise (but slower)

    - LogicalHandle.isClosed() calls through to physical connection

    - Added SQL profiling (to STDERR). Set "profileSql=true" in your JDBC url.
      See README for more information.

    - Fixed typo for relaxAutoCommit parameter.

04-24-02 - Version 2.0.13

    - More code cleanup.

    - Fixed unicode chars being read incorrectly (SF bug 541088)

    - Faster blob escaping for PrepStmt

    - Added set/getPortNumber() to DataSource(s) (SF bug 548167)

    - Added setURL() to MySQLXADataSource (SF bug 546019)

    - PreparedStatement.toString() fixed (SF bug 534026)

    - ResultSetMetaData.getColumnClassName() now implemented

    - Rudimentary version of Statement.getGeneratedKeys() from JDBC-3.0
      now implemented (you need to be using JDK-1.4 for this to work, I
      believe)

    - DBMetaData.getIndexInfo() - bad PAGES fixed (SF BUG 542201)

04-07-02 - Version 2.0.12

    - General code cleanup.

    - Added getIdleFor() method to Connection and MysqlLogicalHandle.

    - Relaxed synchronization in all classes, should fix 520615 and 520393.

    - Added getTable/ColumnPrivileges() to DBMD (fixes 484502).

    - Added new types to getTypeInfo(), fixed existing types thanks to
      Al Davis and Kid Kalanon.

    - Added support for BIT types (51870) to PreparedStatement.

    - Fixed getRow() bug (527165) in ResultSet

    - Fixes for ResultSet updatability in PreparedStatement.
    - Fixed timezone off by 1-hour bug in PreparedStatement (538286, 528785).

    - ResultSet: Fixed updatability (values being set to null
      if not updated).

    - DataSources - fixed setUrl bug (511614, 525565),
      wrong datasource class name (532816, 528767)

    - Added identifier quoting to all DatabaseMetaData methods
      that need them (should fix 518108)

    - Added support for YEAR type (533556)

    - ResultSet.insertRow() should now detect auto_increment fields
      in most cases and use that value in the new row. This detection
      will not work in multi-valued keys, however, due to the fact that
      the MySQL protocol does not return this information.

    - ResultSet.refreshRow() implemented.

    - Fixed testsuite.Traversal afterLast() bug, thanks to Igor Lastric.

01-27-02 - Version 2.0.11

    - Fixed missing DELETE_RULE value in
      DBMD.getImported/ExportedKeys() and getCrossReference().

    - Full synchronization of Statement.java.

    - More changes to fix "Unexpected end of input stream"
      errors when reading BLOBs. This should be the last fix.

01-24-02 - Version 2.0.10

     - Fixed spurious "Unexpected end of input stream" errors in
       MysqlIO (bug 507456).

     - Fixed null-pointer-exceptions when using
       MysqlConnectionPoolDataSource with Websphere 4 (bug 505839).

01-13-02 - Version 2.0.9

     - Ant build was corrupting included jar files, fixed
       (bug 487669).

     - Fixed extra memory allocation in MysqlIO.readPacket()
       (bug 488663).

     - Implementation of DatabaseMetaData.getExported/ImportedKeys() and
       getCrossReference().

     - Full synchronization on methods modifying instance and class-shared
       references, driver should be entirely thread-safe now (please
       let me know if you have problems)

     - DataSource implementations moved to org.gjt.mm.mysql.jdbc2.optional
       package, and (initial) implementations of PooledConnectionDataSource
       and XADataSource are in place (thanks to Todd Wolff for the
       implementation and testing of PooledConnectionDataSource with
       IBM WebSphere 4).

     - Added detection of network connection being closed when reading packets
       (thanks to Todd Lizambri).

     - Fixed quoting error with escape processor (bug 486265).

     - Report batch update support through DatabaseMetaData (bug 495101).

     - Fixed off-by-one-hour error in PreparedStatement.setTimestamp()
       (bug 491577).

     - Removed concatenation support from driver (the '||' operator),
       as older versions of VisualAge seem to be the only thing that
       use it, and it conflicts with the logical '||' operator. You will
       need to start mysqld with the "--ansi" flag to use the '||'
       operator as concatenation (bug 491680)

     - Fixed casting bug in PreparedStatement (bug 488663).

11-25-01 - Version 2.0.8

     - Batch updates now supported (thanks to some inspiration
       from Daniel Rall).

     - XADataSource/ConnectionPoolDataSource code (experimental)

     - PreparedStatement.setAnyNumericType() now handles positive
       exponents correctly (adds "+" so MySQL can understand it).

     - DatabaseMetaData.getPrimaryKeys() and getBestRowIdentifier()
       are now more robust in identifying primary keys (matches
       regardless of case or abbreviation/full spelling of Primary Key
       in Key_type column).

10-24-01 - Version 2.0.7

     - PreparedStatement.setCharacterStream() now implemented

     - Fixed dangling socket problem when in high availability
       (autoReconnect=true) mode, and finalizer for Connection will
       close any dangling sockets on GC.

     - Fixed ResultSetMetaData.getPrecision() returning one
       less than actual on newer versions of MySQL.

     - ResultSet.getBlob() now returns null if column value
       was null.

     - Character sets read from database if useUnicode=true
       and characterEncoding is not set. (thanks to
       Dmitry Vereshchagin)

     - Initial transaction isolation level read from
       database (if avaialable) (thanks to Dmitry Vereshchagin)

     - Fixed DatabaseMetaData.supportsTransactions(), and
       supportsTransactionIsolationLevel() and getTypeInfo()
       SQL_DATETIME_SUB and SQL_DATA_TYPE fields not being
       readable.

     - Fixed PreparedStatement generating SQL that would end
       up with syntax errors for some queries.

     - Fixed ResultSet.isAfterLast() always returning false.

     - Fixed timezone issue in PreparedStatement.setTimestamp()
       (thanks to Erik Olofsson)

     - Captialize type names when "captializeTypeNames=true"
       is passed in URL or properties (for WebObjects, thanks
       to Anjo Krank)

     - Updatable result sets now correctly handle NULL
       values in fields.

     - PreparedStatement.setDouble() now uses full-precision
       doubles (reverting a fix made earlier to truncate them).

     - PreparedStatement.setBoolean() will use 1/0 for values
       if your MySQL Version >= 3.21.23.

06-16-01 - Version 2.0.6

     - Fixed PreparedStatement parameter checking

     - Fixed case-sensitive column names in ResultSet.java

06-13-01 - Version 2.0.5

     - Fixed ResultSet.getBlob() ArrayIndex out-of-bounds

     - Fixed ResultSetMetaData.getColumnTypeName for TEXT/BLOB

     - Fixed ArrayIndexOutOfBounds when sending large BLOB queries
       (Max size packet was not being set)

     - Added ISOLATION level support to Connection.setIsolationLevel()

     - Fixed NPE on PreparedStatement.executeUpdate() when all columns
       have not been set.

     - Fixed data parsing of TIMESTAMPs with 2-digit years

     - Added Byte to PreparedStatement.setObject()

     - ResultSet.getBoolean() now recognizes '-1' as 'true'

     - ResultSet has +/-Inf/inf support

     - ResultSet.insertRow() works now, even if not all columns are
       set (they will be set to "NULL")

     - DataBaseMetaData.getCrossReference() no longer ArrayIndexOOB

     - getObject() on ResultSet correctly does TINYINT->Byte and
       SMALLINT->Short

12-03-00 - Version 2.0.3

     - Implemented getBigDecimal() without scale component
       for JDBC2.

     - Fixed composite key problem with updateable result sets.

     - Added detection of -/+INF for doubles.

     - Faster ASCII string operations.

     - Fixed incorrect detection of MAX_ALLOWED_PACKET, so sending
       large blobs should work now.

     - Fixed off-by-one error in java.sql.Blob implementation code.

     - Added "ultraDevHack" URL parameter, set to "true" to allow
       (broken) Macromedia UltraDev to use the driver.

04-06-00 - Version 2.0.1

     - Fixed RSMD.isWritable() returning wrong value.
       Thanks to Moritz Maass.

     - Cleaned up exception handling when driver connects

     - Columns that are of type TEXT now return as Strings
       when you use getObject()

     - DatabaseMetaData.getPrimaryKeys() now works correctly wrt
       to key_seq. Thanks to Brian Slesinsky.

     - No escape processing is done on PreparedStatements anymore
       per JDBC spec.

     - Fixed many JDBC-2.0 traversal, positioning bugs, especially
       wrt to empty result sets. Thanks to Ron Smits, Nick Brook,
       Cessar Garcia and Carlos Martinez.

     - Fixed some issues with updatability support in ResultSet when
       using multiple primary keys.

02-21-00 - Version 2.0pre5

     - Fixed Bad Handshake problem.

01-10-00 - Version 2.0pre4

     - Fixes to ResultSet for insertRow() - Thanks to
       Cesar Garcia

     - Fix to Driver to recognize JDBC-2.0 by loading a JDBC-2.0
       class, instead of relying on JDK version numbers. Thanks
       to John Baker.

     - Fixed ResultSet to return correct row numbers

     - Statement.getUpdateCount() now returns rows matched,
       instead of rows actually updated, which is more SQL-92
       like.

10-29-99

     - Statement/PreparedStatement.getMoreResults() bug fixed.
       Thanks to Noel J. Bergman.

     - Added Short as a type to PreparedStatement.setObject().
       Thanks to Jeff Crowder

     - Driver now automagically configures maximum/preferred packet
       sizes by querying server.

     - Autoreconnect code uses fast ping command if server supports
       it.

     - Fixed various bugs wrt. to packet sizing when reading from
       the server and when alloc'ing to write to the server.

08-17-99 - Version 2.0pre

     - Now compiles under JDK-1.2. The driver supports both JDK-1.1
       and JDK-1.2 at the same time through a core set of classes.
       The driver will load the appropriate interface classes at
       runtime by figuring out which JVM version you are using.

     - Fixes for result sets with all nulls in the first row.
       (Pointed out by Tim Endres)

     - Fixes to column numbers in SQLExceptions in ResultSet
       (Thanks to Blas Rodriguez Somoza)

     - The database no longer needs to specified to connect.
       (Thanks to Christian Motschke)

07-04-99 - Version 1.2b

     - Better Documentation (in progress), in doc/mm.doc/book1.html

     - DBMD now allows null for a column name pattern (not in
       spec), which it changes to '%'.

     - DBMD now has correct types/lengths for getXXX().

     - ResultSet.getDate(), getTime(), and getTimestamp() fixes.
       (contributed by Alan Wilken)

     - EscapeProcessor now handles \{ \} and { or } inside quotes
       correctly. (thanks to Alik for some ideas on how to fix it)

     - Fixes to properties handling in Connection.
       (contributed by Juho Tikkala)

     - ResultSet.getObject() now returns null for NULL columns
       in the table, rather than bombing out.
       (thanks to Ben Grosman)

     - ResultSet.getObject() now returns Strings for types
       from MySQL that it doesn't know about. (Suggested by
       Chris Perdue)

     - Removed DataInput/Output streams, not needed, 1/2 number
       of method calls per IO operation.

     - Use default character encoding if one is not specified. This
       is a work-around for broken JVMs, because according to spec,
       EVERY JVM must support "ISO8859_1", but they don't.

     - Fixed Connection to use the platform character encoding
       instead of "ISO8859_1" if one isn't explicitly set. This
       fixes problems people were having loading the character-
       converter classes that didn't always exist (JVM bug).
       (thanks to Fritz Elfert for pointing out this problem)

     - Changed MysqlIO to re-use packets where possible to reduce
       memory usage.

     - Fixed escape-processor bugs pertaining to {} inside
       quotes.

04-14-99 - Version 1.2a

     - Fixed character-set support for non-Javasoft JVMs
       (thanks to many people for pointing it out)

     - Fixed ResultSet.getBoolean() to recognize 'y' & 'n'
       as well as '1' & '0' as boolean flags.
       (thanks to Tim Pizey)

     - Fixed ResultSet.getTimestamp() to give better performance.
       (thanks to Richard Swift)

     - Fixed getByte() for numeric types.
       (thanks to Ray Bellis)

     - Fixed DatabaseMetaData.getTypeInfo() for DATE type.
       (thanks to Paul Johnston)

     - Fixed EscapeProcessor for "fn" calls.
       (thanks to Piyush Shah at locomotive.org)

     - Fixed EscapeProcessor to not do extraneous work if there
       are no escape codes.
       (thanks to Ryan Gustafson)

     - Fixed Driver to parse URLs of the form "jdbc:mysql://host:port"
       (thanks to Richard Lobb)

03-24-99 - Version 1.1i

     - Fixed Timestamps for PreparedStatements

     - Fixed null pointer exceptions in RSMD and RS

     - Re-compiled with jikes for valid class files (thanks ms!)

03-08-99 - Version 1.1h

     - Fixed escape processor to deal with un-matched { and }
       (thanks to Craig Coles)

     - Fixed escape processor to create more portable (between
       DATETIME and TIMESTAMP types) representations so that
       it will work with BETWEEN clauses.
       (thanks to Craig Longman)

     - MysqlIO.quit() now closes the socket connection. Before,
       after many failed connections some OS's would run out
       of file descriptors. (thanks to Michael Brinkman)

     - Fixed NullPointerException in Driver.getPropertyInfo.
       (thanks to Dave Potts)

     - Fixes to MysqlDefs to allow all *text fields to be
       retrieved as Strings.
       (thanks to Chris at Leverage)

     - Fixed setDouble in PreparedStatement for large numbers
       to avoid sending scientific notation to the database.
       (thanks to J.S. Ferguson)

     - Fixed getScale() and getPrecision() in RSMD.
       (contrib'd by James Klicman)

     - Fixed getObject() when field was DECIMAL or NUMERIC
       (thanks to Bert Hobbs)

     - DBMD.getTables() bombed when passed a null table-name
       pattern. Fixed. (thanks to Richard Lobb)

     - Added check for "client not authorized" errors during
       connect. (thanks to Hannes Wallnoefer)

02-19-99 - Version 1.1g

     - Result set rows are now byte arrays. Blobs and Unicode
       work bidriectonally now. The useUnicode and encoding
       options are implemented now.

     - Fixes to PreparedStatement to send binary set by
       setXXXStream to be sent un-touched to the MySQL server.

     - Fixes to getDriverPropertyInfo().

12-31-98 - Version 1.1f

     - Changed all ResultSet fields to Strings, this should allow
       Unicode to work, but your JVM must be able to convert
       between the character sets. This should also make reading
       data from the server be a bit quicker, because there is now
       no conversion from StringBuffer to String.

     - Changed PreparedStatement.streamToString() to be more
       efficient (code from Uwe Schaefer).

     - URL parsing is more robust (throws SQL exceptions on errors
       rather than NullPointerExceptions)

     - PreparedStatement now can convert Strings to Time/Date values
       via setObject() (code from Robert Currey).

     - IO no longer hangs in Buffer.readInt(), that bug was
       introduced in 1.1d when changing to all byte-arrays for
       result sets. (Pointed out by Samo Login)

11-03-98 - Version 1.1b

     - Fixes to DatabaseMetaData to allow both IBM VA and J-Builder
       to work. Let me know how it goes. (thanks to Jac Kersing)

     - Fix to ResultSet.getBoolean() for NULL strings
       (thanks to Barry Lagerweij)

     - Beginning of code cleanup, and formatting. Getting ready
       to branch this off to a parallel JDBC-2.0 source tree.

     - Added "final" modifier to critical sections in MysqlIO and
       Buffer to allow compiler to inline methods for speed.

9-29-98

     - If object references passed to setXXX() in PreparedStatement are
       null, setNull() is automatically called for you. (Thanks for the
       suggestion goes to Erik Ostrom)

     - setObject() in PreparedStatement will now attempt to write a
       serialized  representation of the object to the database for
       objects of Types.OTHER and objects of unknown type.

     - Util now has a static method readObject() which given a ResultSet
       and a column index will re-instantiate an object serialized in
       the above manner.

9-02-98 - Vesion 1.1

     - Got rid of "ugly hack" in MysqlIO.nextRow(). Rather than
       catch an exception, Buffer.isLastDataPacket() was fixed.

     - Connection.getCatalog() and Connection.setCatalog()
       should work now.

     - Statement.setMaxRows() works, as well as setting
       by property maxRows. Statement.setMaxRows() overrides
       maxRows set via properties or url parameters.

     - Automatic re-connection is available. Because it has
       to "ping" the database before each query, it is
       turned off by default. To use it, pass in "autoReconnect=true"
       in the connection URL. You may also change the number of
       reconnect tries, and the initial timeout value via
       "maxReconnects=n" (default 3) and "initialTimeout=n"
       (seconds, default 2) parameters. The timeout is an
       exponential backoff type of timeout. For example, if you have
       initial timeout of 2 seconds, and maxReconnects of 3, then the
       driver will timeout 2 seconds, 4 seconds, then 16 seconds between
       each re-connection attempt.

8-24-98 - Version 1.0

     - Fixed handling of blob data in Buffer.java

     - Fixed bug with authentication packet being
       sized too small.

     - The JDBC Driver is now under the LPGL

8-14-98 -

     - Fixed Buffer.readLenString() to correctly
          read data for BLOBS.

     - Fixed PreparedStatement.stringToStream to
          correctly read data for BLOBS.

     - Fixed PreparedStatement.setDate() to not
       add a day.
       (above fixes thanks to Vincent Partington)

     - Added URL parameter parsing (?user=... etc).


8-04-98 - Version 0.9d

     - Big news! New package name. Tim Endres from ICE
       Engineering is starting a new source tree for
       GNU GPL'd Java software. He's graciously given
       me the org.gjt.mm package directory to use, so now
       the driver is in the org.gjt.mm.mysql package scheme.
       I'm "legal" now. Look for more information on Tim's
       project soon.

     - Now using dynamically sized packets to reduce
       memory usage when sending commands to the DB.

     - Small fixes to getTypeInfo() for parameters, etc.

     - DatabaseMetaData is now fully implemented. Let me
       know if these drivers work with the various IDEs
       out there. I've heard that they're working with
       JBuilder right now.

     - Added JavaDoc documentation to the package.

     - Package now available in .zip or .tar.gz.

7-28-98 - Version 0.9

     - Implemented getTypeInfo().
       Connection.rollback() now throws an SQLException
       per the JDBC spec.

     - Added PreparedStatement that supports all JDBC API
       methods for PreparedStatement including InputStreams.
       Please check this out and let me know if anything is
       broken.

     - Fixed a bug in ResultSet that would break some
       queries that only returned 1 row.

     - Fixed bugs in DatabaseMetaData.getTables(),
       DatabaseMetaData.getColumns() and
       DatabaseMetaData.getCatalogs().

     - Added functionality to Statement that allows
       executeUpdate() to store values for IDs that are
       automatically generated for AUTO_INCREMENT fields.
       Basically, after an executeUpdate(), look at the
       SQLWarnings for warnings like "LAST_INSERTED_ID =
       'some number', COMMAND = 'your SQL query'".

       If you are using AUTO_INCREMENT fields in your
       tables and are executing a lot of executeUpdate()s
       on one Statement, be sure to clearWarnings() every
       so often to save memory.

7-06-98 - Version 0.8

     - Split MysqlIO and Buffer to separate classes. Some
       ClassLoaders gave an IllegalAccess error for some
       fields in those two classes. Now mm.mysql works in
       applets and all classloaders.

       Thanks to Joe Ennis <jce@mail.boone.com> for pointing
       out the problem and working on a fix with me.

7-01-98 - Version 0.7

     - Fixed DatabaseMetadata problems in getColumns() and
       bug in switch statement in the Field constructor.

       Thanks to Costin Manolache <costin@tdiinc.com> for
       pointing these out.

5-21-98 - Version 0.6

     - Incorporated efficiency changes from
       Richard Swift <Richard.Swift@kanatek.ca> in
       MysqlIO.java and ResultSet.java

     - We're now 15% faster than gwe's driver.

     - Started working on DatabaseMetaData.

       The following methods are implemented:
        * getTables()
        * getTableTypes()
        * getColumns
        * getCatalogs()

23.4. MySQL Connector/MXJ

23.4.1. Introduction

MySQL Connector/MXJ is a Java Utility package for deploying and managing a MySQL database. Connector/MXJ may be bundled in to an existing Java application or may be deployed as a JMX MBean. Deploying and using MySQL can be as easy as adding an additional parameter to the JDBC connection url, which will result in the database being started when the first connection is made. This makes it easy for Java developers to deploy applications which require a database by reducing installation barriers for their end-users.

MySQL Connector/MXJ makes the MySQL database appear to be a java-based component. It does this by determining what platform the system is running on, selecting the appropriate binary, and launching the executable. It will also optionally deploy an initial database, with any specified parameters.

As a JMX MBean, MySQL Connector/MXJ requires a JMX v1.2 compliant MBean container, such as JBoss version 4. The MBean will uses the standard JMX management APIs to present (and allow the setting of) parameters which are appropriate for that platform.

Included are instructions for use with a JDBC driver and deploying as a JMX MBean to JBoss.

You can download sources and binaries from: http://dev.mysql.com/downloads/connector/mxj/

This an beta release and feedback is welcome and encouraged.

Please send questions or comments to java@lists.mysql.com.

23.4.2. Support Platforms:

  • Linux, i386

  • Windows NT, x86

  • Windows 2000, x86

  • Windows XP, x86

  • Solaris 9, SPARC 32

23.4.3. JUnit Test Requirements

The best way to ensure that your platform is supported is to run the JUnit tests.

The first thing to do is make sure that the components will work on the platform. Since the ''MysqldResource'' class is really a wrapper for a native version of MySQL, not all platforms are supported. At the time of this writing, Linux on the i386 architecture has been tested and seems to work quite well, as does OS X v10.3. There has been limited testing on Windows and Solaris.

Requirements:

  1. JDK-1.4 or newer (or the JRE if you aren't going to be compiling the source or JSPs).

  2. MySQL Connector/J version 3.1 or newer (from http://dev.mysql.com/downloads/connector/j/ ) installed and available via your CLASSPATH.

  3. The javax.management classes for JMX version 1.2.1, these are present in the following application servers:

  4. Junit 3.8.1 (from http://www.junit.org/)

If building from source, All of the requirements from above, plus:

  1. Ant version 1.5 or newer (download from http://ant.apache.org/)

23.4.4. Running the JUnit Tests

  1. The tests attempt to launch MySQL on the port 3336. If you have a MySQL running, it may conflict, but this isn't very likely since thedefault port for MySQL is 3306. However, You may set the "c-mxj_test_port" Java property to a port of your choosing. Alternatively, you may wish to start by shutting down any instances of MySQL you have running on the target machine.

    The tests surpress output to the console by default. For verbose output, you may set the "c-mxj_test_silent" Java property to "false".

  2. In order to run the JUnit test suite, the $CLASSPATH must include the following:

    • JUnit

    • JMX

    • Connector/J

    • MySQL Connector/MXJ

  3. If connector-mxj.jar is not present in your download, unzip MySQL Connector/MXJ source archive.

    cd mysqldjmx
    ant dist
         

    Then add $TEMP/cmxj/stage/connector-mxj/connector-mxj.jar to the CLASSPATH.

  4. if you have junit, execute the unit tests. From the command line, type:

    java junit.textui.TestRunner com.mysql.management.AllTestsSuite
        

    The output should look something like this:

    .........................................
    .........................................
    ..........
    Time: 259.438
    
    OK (101 tests)
      

    Note that the tests are a bit slow near the end, so please be patient.

23.4.5. Running as part of the JDBC Driver

A feature of the MySQL Connector/J JDBC driver is the ability to specify a ''SocketFactory'' as a parameter in the JDBC connection string. MySQL Connector/MXJ includes a custom SocketFactory. The SocketFactory will, upon the first connection, deploy and launch the MySQL database. The SocketFactory also exposes a ''shutdown'' method.

To try it specify the ''socketFactory'' parameter on the JDBC connection string with a value equal to ''com.mysql.management.driverlaunched.ServerLauncherSocketFactory''

In the following example, we have a program which creates a connection, executes a query, and prints the result to the System.out. The MySQL database will be deployed and started as part of the connection process, and shutdown as part of the finally block.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;

import com.mysql.management.driverlaunched.ServerLauncherSocketFactory;

public class ConnectorMXJTestExample {
    public static void main(String[] args) throws Exception {
        String hostColonPort = "localhost:3336";
        
        String driver = com.mysql.jdbc.Driver.class.getName();
        String url = "jdbc:mysql://" + hostColonPort + "/" + "?"
                + "socketFactory="
                + ServerLauncherSocketFactory.class.getName();
        String userName = "root";
        String password = "";

        Class.forName(driver);
        Connection conn = null;
        try {
            conn = DriverManager.getConnection(url, userName, password);
            Statement stmt = conn.createStatement();
            ResultSet rs = stmt.executeQuery("SELECT VERSION()");
            rs.next();
            String version = rs.getString(1);
            rs.close();
            stmt.close();

            System.out.println("------------------------");
            System.out.println(version);
            System.out.println("------------------------");
        } finally {
            try {
                conn.close();
            } catch (Exception e) {
                e.printStackTrace();
            }
            ServerLauncherSocketFactory.shutdown(hostColonPort);
        }
    }
}
  

To run the above program, be sure to have connector-mxj.jar and Connector/J in the CLASSPATH. Then type:

java ConnectorMXJTestExample
  

Of course there are many options we may wish to set for a MySQL database. These options may be specified as part of the JDBC connection string simply by prefixing each server option with ''server.''. In the following example we set three driver parameters and two server parameters:

        String url = "jdbc:mysql://" + hostColonPort + "/" 
                + "?"
                + "socketFactory="
                + ServerLauncherSocketFactory.class.getName();
                + "&"
                + "cacheServerConfiguration=true"
                + "&"
                + "useLocalSessionState=true"
                + "&"
                + "server.basedir=/opt/myapp/db"
                + "&"
                + "server.datadir=/mnt/bigdisk/myapp/data";
  

23.4.6. Running within a Java Object

Have a java application and wish to "embed" a MySQL database, make use of the com.mysql.management.MysqldResource class directly. This class may be instantiated with the default (no argument) constructor, or by passing in a java.io.File object representing the directory you wish the server to be "unzipped" into. It may also be instantiated with printstreams for "stdout" and "stderr" for logging.

Once instantiated, a java.util.Map, the object will be able to provide a java.util.Map of server options appropriate for the platform and version of MySQL which you will be using.

The MysqldResource will allow you to "start" MySQL with a java.util.Map of server options which you provide, as well as "shutdown" the database. The following example shows a simplistic way to embed MySQL in an applicaiton using plain java objects:

import com.mysql.management.MysqldResource;

 ...

    public void startMySQL() {
        File baseDir = new File(ourAppDir, "mysql");
        mysqldResource = new MysqldResource(baseDir);
        Map options = new HashMap();
        options.put("port", "3336");
        String threadName = "OurApp MySQL";
        mysqldResource.start(threadName, options);
    }
    
    public void stopMySQL() {
        if (mysqldResource != null) {
            mysqldResource.shutdown();
        }
        mysqldResource = null;
    }
    
    public java.sql.Connection getConnection() throws Exception {
        String db = "test";
        String url = "jdbc:mysql://localhost:3336/" + db;
        String userName = "root";
        String password = "";
        Class.forName(com.mysql.jdbc.Driver.class.getName());
        return DriverManager.getConnection(url, userName, password);
    }
  

23.4.7. The MysqldResource API

Constructors:

  • public MysqldResource(File baseDir, PrintStream out, PrintStream err);

    Allows the setting of the "basedir" to deploy the MySQL files to, as well as out put streams for standard out and standard err.

  • public MysqldResource(File baseDir);

    Allows the setting of the "basedir" to deploy the MySQL files to. Output for standard out and standard err are directed to System.out and System.err.

  • public MysqldResource();

    The basedir is defaulted to a subdirectory of the java.io.tempdir. Output for standard out and standard err are directed to System.out and System.err;

MysqldResource API includes the following methods:

  • void start(String threadName, Map mysqldArgs);

    Deploys and starts MySQL. The "threadName" string is used to name the thread which actually performs the execution of the MySQL command line. The map is the set of arguments and their values to be passed to the command line.

  • void shutdown();

    Shuts down the MySQL instance managed by the MysqldResource object.

  • Map getServerOptions();

    Returns a map of all the options and their current (or default, if not running) options available for the MySQL database.

  • boolean isRunning();

    Returns true if the MySQL database is running.

  • boolean isReadyForConnections();

    Returns true once the database reports that is is ready for connections.

  • void setKillDelay(int millis);

    The default "Kill Delay" is 30 seconds. This represents the amount of time to wait between the initial request to shutdown and issuing a "force kill" if the database has not shutdown by itself.

  • void addCompletionListenser(Runnable listener);

    Allows for applications to be notified when the server process completes. Each ''listener'' will be fired off in its own thread.

  • String getVersion();

    returns the version of MySQL.

  • void setVersion(int MajorVersion, int minorVersion, int patchLevel);

    The standard distribution comes with only one version of MySQL packaged. However, it is possible to package multiple versions, and specify which version to use.

23.4.8. Running within a JMX Agent (custom)

If you are not using the SUN Reference implementation of the JMX libraries, you should skip this section. Or, if you are deploying to JBoss, you also may wish to skip to the next section.

We want to see the MysqldDynamicMBean in action inside of a JMX agent. In the com.mysql.management.jmx.sunri package is a custom JMX agent with two MBeans:

  1. the MysqldDynamicMBean, and

  2. a com.sun.jdmk.comm.HtmlAdaptorServer, which provides a web interface for manipulating the beans inside of a JMX agent.

When this very simple agent is started, it will allow a MySQL database to be started and stopped with a web browser.

  1. Complete the testing of the platform as above.

    • current JDK, JUnit, Connector/J, MySQL Connector/MXJ

    • this section requires the SUN reference implementation of JMX

    • PATH, JAVA_HOME, ANT_HOME, CLASSPATH

  2. If not building from source, skip to next step

    rebuild with the "sunri.present"

    ant -Dsunri.present=true dist 
    re-run tests:
    java junit.textui.TestRunner com.mysql.management.AllTestsSuite
    
  3. launch the test agent from the command line:

    java com.mysql.management.jmx.sunri.MysqldTestAgentSunHtmlAdaptor &
         
  4. from a browser:

    http://localhost:9092/
         
  5. under MysqldAgent,

    select "name=mysqld"
         
  6. Observe the MBean View

  7. scroll to the bottom of the screen press the startMysqld button

  8. click Back to MBean View

  9. scroll to the bottom of the screen press stopMysqld button

  10. kill the java process running the Test Agent (jmx server)

23.4.9. Deployment in a standard JMX Agent environment (JBoss)

Once there is confidence that the MBean will function on the platform, deploying the MBean inside of a standard JMX Agent is the next step. Included are instructions for deploying to JBoss.

  1. Ensure a current version of java development kit (v1.4.x), see above.

    • Ensure JAVA_HOME is set (JBoss requires JAVA_HOME)

    • Ensure JAVA_HOME/bin is in the PATH (You will NOT need to set your CLASSPATH, nor will you need any of the jars used in the previous tests).

  2. Ensure a current version of JBoss (v4.0RC1 or better)

    http://www.jboss.org/index.html
    select "Downloads"
    select "jboss-4.0.zip"
    pick a mirror
    unzip ~/dload/jboss-4.0.zip
    create a JBOSS_HOME environment variable set to the unzipped directory
    unix only:
    cd $JBOSS_HOME/bin
    chmod +x *.sh
    
  3. Deploy (copy) the connector-mxj.jar to $JBOSS_HOME/server/default/lib.

  4. Deploy (copy) mysql-connector-java-3.1.4-beta-bin.jar to $JBOSS_HOME/server/default/lib.

  5. Create a mxjtest.war directory in $JBOSS_HOME/server/default/deploy.

  6. Deploy (copy) index.jsp to $JBOSS_HOME/server/default/deploy/mxjtest.war.

  7. Create a mysqld-service.xml file in $JBOSS_HOME/server/default/deploy.

    <?xml version="1.0" encoding="UTF-8"?>
     <server>
      <mbean code="com.mysql.management.jmx.jboss.JBossMysqldDynamicMBean"
         name="mysql:type=service,name=mysqld">
      <attribute name="datadir">/tmp/xxx_data_xxx</attribute>
      <attribute name="autostart">true</attribute>
      </mbean>
     </server>
         
  8. Start jboss:

    • on unix: $JBOSS_HOME/bin/run.sh

    • on windows: %JBOSS_HOME%\bin\run.bat

    Be ready: JBoss sends a lot of output to the screen.

  9. When JBoss seems to have stopped sending output to the screen, open a web browser to: http://localhost:8080/jmx-console

  10. Scroll down to the bottom of the page in the mysql section, select the bulleted mysqld link.

  11. Observe the JMX MBean View page. MySQL should already be running.

  12. (If "autostart=true" was set, you may skip this step.) Scroll to the bottom of the screen. You may press the Invoke button to stop (or start) MySQL observe Operation completed successfully without a return value. Click Back to MBean View

  13. To confirm MySQL is running, open a web browser to http://localhost:8080/mxjtest/ and you should see that

    SELECT 1

    returned with a result of

    1
  14. Guided by the $JBOSS_HOME/server/default/deploy/mxjtest.war/index.jsp you will be able to use MySQL in your Web Application. There is a test database and a root user (no password) ready to expirement with. Try creating a table, inserting some rows, and doing some selects.

  15. Shut down MySQL. MySQL will be stopped automatically when JBoss is stopped, or: from the browser, scroll down to the bottom of the MBean View press the stop service Invoke button to halt the service. Observe Operation completed successfully without a return value. Using ps or task manager see that MySQL is no longer running

As of 1.0.6-beta version is the ability to have the MBean start the MySQL database upon start up. Also, we've taken advantage of the JBoss life-cycle extension methods so that the database will gracefully shut down when JBoss is shutdown.

23.4.10. Installation

If you've worked through the above sections, you've arleady performed these steps. But we list them here for quick reference.

Driver Launched:

  1. Download and unzip Connector/MXJ, add connector-mxj.jar to the CLASSPATH

  2. To the JDBC connection string add the following parameter: "socketFactory=" + ServerLauncherSocketFactory.class.getName()

JBoss:

  1. Download Connector/MXJ copy the connector-mxj.jar file to the $JBOSS_HOME/server/default/lib diretory.

  2. Download Connector/J copy the connector-mxj.jar file to the $JBOSS_HOME/server/default/lib diretory.

  3. Create an MBean service xml file in the $JBOSS_HOME/server/default/deploy directory with any attributes set, for instance the datadir and autostart.

  4. Set the JDBC parameters of your web application to use: String driver = "com.mysql.jdbc.Driver"; String url = "jdbc:mysql:///test?propertiesTransform="+ "com.mysql.management.jmx.ConnectorMXJPropertiesTransform"; String user = "root"; String password = ""; Class.forName(driver); Connection conn = DriverManager.getConnection(url, user, password);

You may wish to create a separate users and database table spaces for each application, rather than using "root and test".

We highly suggest having a routine backup procedure for backing up the database files in the datadir.