Chapter 18. Connectors
Prev |  | Next

## Chapter 18. Connectors

This chapter describes MySQL Connectors, drivers that provide connectivity to the MySQL server for client programs. There are currently five MySQL Connectors:

- Connector/ODBC provides driver support for connecting to a MySQL server using the Open Database Connectivity (ODBC) API. Support is available for ODBC connectivity from Windows, Unix and Mac OS X platforms.

- Connector/NET enables developers to create .NET applications that use data stored in a MySQL database. Connector/NET implements a fully-functional ADO.NET interface and provides support for use with ADO.NET aware tools. Applications that want to use Connector/NET can be written in any of the supported .NET languages.

- The MySQL Visual Studio Plugin works with Connector/NET and Visual Studio 2005. The plugin is a MySQL DDEX Provider, which means that you can use the schema and data manipulation tools within Visual Studio to create and edit objects within a MySQL database.

- Connector/J provides driver support for connecting to MySQL from a Java application using the standard Java Database Connectivity (JDBC) API.

- Connector/MXJ is a tool that enables easy deployment and management of MySQL server and database through your Java application.

- Connector/PHP is a Windows-only connector for PHP that provides the `mysql` and `mysqli` extensions for use with MySQL 5.0.18 and later.

For information on connecting to a MySQL server using other languages and interfaces than those detailed above, including Perl, Python and PHP for other platforms and environments, please refer to the Chapter 17, APIs and Libraries chapter.

## 18.1. MySQL Connector/ODBC

The MySQL Connector/ODBC is the name for the family of MySQL ODBC drivers (previously called MyODBC drivers) that provide access to a MySQL database using the industry standard Open Database Connectivity (ODBC) API. This reference covers Connector/ODBC 3.51, a version of the API that provides ODBC 3.5x compliant access to a MySQL database.

The manual for versions of Connector/ODBC older than 3.51 can be located in the corresponding binary or source distribution.

For more information on the ODBC API standard and how to use it, 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/.

Typically, you need to install Connector/ODBC only on Windows machines. For Unix and Mac OS X you can use the native MySQL network or named pipe to communicate with your MySQL database. You may need Connector/ODBC for Unix or Mac OS X if you have an application that requires an ODBC interface to communicate with the database. Applications that require ODBC to communicate with MySQL include ColdFusion, Microsoft Office, and Filemaker Pro.

If you want to install the Connector/ODBC connector on a Unix host, then you must also install an ODBC manager.

Key topics:

- For help installing Connector/ODBC see Section 18.1.2, “Connector/ODBC Installation”.

- For more information on connecting to a MySQL database from a Windows host using Connector/ODBC see Section 18.1.4.2, “Step-by-step Guide to Connecting to a MySQL Database through Connector/ODBC”.

- If you want to use Microsoft Access as an interface to a MySQL database using Connector/ODBC see Section 18.1.4.4, “Using Connector/ODBC and Microsoft Access”.

- General tips on using Connector/ODBC, including obtaining the last auto increment ID see Section 18.1.6.1, “Connector/ODBC General Functionality”.

- For tips and common questions on using Connector/ODBC with specific application see Section 18.1.6.2, “Connector/ODBC Application Specific Tips”.

- For a general list of Frequently Asked Questions see Section 18.1.6.3, “Connector/ODBC Errors and Resolutions”.

- Additional support when using Connector/ODBC is available, see Section 18.1.7, “Connector/ODBC Support”.

### 18.1.1. Introduction to Connector/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/.

#### 18.1.1.1. Connector/ODBC Versions

There are currently two version of Connector/ODBC available:

- Connector/ODBC 5.0, currently in beta status, has been designed to extend the functionality of the Connector/ODBC 3.51 driver and incorporate full support for the functionality in the MySQL 5.0 server release, including stored procedures and views. Applications using Connector/ODBC 3.51 will be compatible with Connector/ODBC 5.0, while being able to take advantage of the new features. Features and functionality of the Connector/ODBC 5.0 driver are not currently included in this guide.

- Connector/ODBC 3.51 is the current release of the 32-bit ODBC driver, also known as the MySQL ODBC 3.51 driver. This version is enhanced compared to the older Connector/ODBC 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.

- MyODBC 2.50 is the previous version of the 32-bit ODBC driver from MySQL AB that is based on ODBC 2.50 specification level 0 (with level 1 and 2 features). Information about the MyODBC 2.50 driver is included in this guide for the purposes of comparison only.

### Note

From this section onward, the primary focus of this guide is the Connector/ODBC 3.51 driver. More information about the MyODBC 2.50 driver in the documentation included in the installation packages for that version. If there is a specific issue (error or known problem) that only affects the 2.50 version, it may be included here for reference.

### Note

Version numbers for MySQL products are formatted as X.X.X. However, Windows tools (Control Panel, properties display) may show the version numbers as XX.XX.XX. For example, the official MySQL formatted version number 5.0.9 may be displayed by Windows tools as 5.00.09. The two versions are the same; only the number display format is different.

#### 18.1.1.2. General Information About ODBC and Connector/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 Connector/ODBC is given at Section 18.1.5.1, “Connector/ODBC API Reference”. For general information about ODBC, see http://www.microsoft.com/data/.

##### 18.1.1.2.1. Connector/ODBC Architecture

The Connector/ODBC architecture is based on five components, as shown in the following diagram:

- Application:

  The Application uses the ODBC API to access the data from the MySQL server. The ODBC API in turn uses the communicates with the Driver Manager. 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). The DSN is a configuration string that identifies a given database driver, database, database host and optionally authentication information that enables an ODBC application to connect to a database using a standardized reference.

    Because the database connectivity information is identified by the DSN, any ODBC compliant application can connect to the data source using the same DSN reference. This eliminates the need to separately configure each application that needs access to a given database; instead you instruct the application to use a pre-configured DSN.

  - Loading and unloading of the driver required to access a specific database as defined within the DSN. For example, if you have configured a DSN that connects to a MySQL database then the driver manager will load the Connector/ODBC driver to enable the ODBC API to communicate with the MySQL host.

  - Processes ODBC function calls or passes them to the driver for processing.

- Connector/ODBC Driver:

  The Connector/ODBC driver is a library that implements the functions supported by 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 MySQL.

- DSN Configuration:

  The ODBC configuration file 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 according to the definition in the DSN. The driver uses this to read connection parameters based on the DSN specified. For more information, Section 18.1.3, “Connector/ODBC Configuration”.

- MySQL Server:

  The MySQL database where the information is stored. The database is used as the source of the data (during queries) and the destination for data (during inserts and updates).

##### 18.1.1.2.2. ODBC Driver Managers

An ODBC Driver Manager is a library that manages communication between the ODBC-aware application and any drivers. Its main functionality includes:

- Resolving Data Source Names (DSN).

- Driver loading and unloading.

- Processing ODBC function calls or passing them to the driver.

Both Windows and Mac OS X include ODBC driver managers with the operating system. Most ODBC Driver Manager implementations also include an administration application that makes the configuration of DSN and drivers easier. Examples and information on these managers, including Unix ODBC driver managers are listed below:

- Microsoft Windows ODBC Driver Manager (`odbc32.dll`), http://www.microsoft.com/data/.

- Mac OS X includes `ODBC Administrator`, a GUI application that provides a simpler configuration mechanism for the Unix iODBC Driver Manager. You can configure DSN and driver information either through ODBC Administrator or through the iODBC configuration files. This also means that you can test ODBC Administrator configurations using the `iodbctest` command. http://www.apple.com.

- `unixODBC` Driver Manager for Unix (`libodbc.so`). See http://www.unixodbc.org, for more information. The `unixODBC` Driver Manager includes the Connector/ODBC driver 3.51 in the installation package, starting with version `unixODBC` 2.1.2.

- `iODBC` ODBC Driver Manager for Unix (`libiodbc.so`), see http://www.iodbc.org, for more information.

### 18.1.2. Connector/ODBC Installation

You can install the Connector/ODBC drivers using two different methods, a binary installation and a source installation. The binary installation is the easiest and most straightforward method of installation. Using the source installation methods should only be necessary on platforms where a binary installation package is not available, or in situations where you want to customize or modify the installation process or Connector/ODBC drivers before installation.

#### 18.1.2.1. Where to Get Connector/ODBC

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

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

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

#### 18.1.2.2. Supported Platforms

Connector/ODBC can be used on all major platforms supported by MySQL. You can install it on:

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

- All Unix-like Operating Systems, including: AIX, Amiga, BSDI, DEC, FreeBSD, HP-UX 10/11, Linux, NetBSD, OpenBSD, OS/2, SGI Irix, Solaris, SunOS, SCO OpenServer, SCO UnixWare, Tru64 Unix

- Mac OS X and Mac OS X Server

If a binary distribution is not available for a particular platform, see Section 18.1.2.4, “Installing Connector/ODBC from a source distribution”, to build the driver from the original source code. You can contribute the binaries you create to MySQL by sending a mail message to `<myodbc@lists.mysql.com>`, so that it becomes available for other users.

#### 18.1.2.3. Installing Connector/ODBC from a binary distribution

Using a binary distribution offers the most straightforward method for installing Connector/ODBC. If you want more control over the driver, the installation location and or to customize elements of the driver you will need to build and install from the source. See the Section 18.1.2.4, “Installing Connector/ODBC from a source distribution”.

##### 18.1.2.3.1. Installing Connector/ODBC from a Binary Distribution on Windows

Before installing the Connector/ODBC drivers on Windows you should ensure that your Microsoft Data Access Components (MDAC) are up to date. You can obtain the latest version from the Microsoft Data Access and Storage Web site.

There are three available distribution types to use when installing for Windows. The contents in each case are identical, it is only the installation method which is different.

- Zipped installer consists of a Zipped package containing a standalone installation application. To install from this package, you must unzip the installer, and then run the installation application. See Section 18.1.2.3.1.1, “Installing the Windows Connector/ODBC Driver using an installer” to complete the installation.

- MSI installer, an installation file that can be used with the installer included in Windows 2000, Windows XP and Windows Server 2003. See Section 18.1.2.3.1.1, “Installing the Windows Connector/ODBC Driver using an installer” to complete the installation.

- Zipped DLL package, containing the DLL files that need must be manually installed. See Section 18.1.2.3.1.2, “Installing the Windows Connector/ODBC Driver using the Zipped DLL package” to complete the installation.

###### 18.1.2.3.1.1. Installing the Windows Connector/ODBC Driver using an installer

The installer packages offer a very simple method for installing the Connector/ODBC drivers. If you have downloaded the zipped installer then you must extract the installer application. The basic installation process is identical for both installers.

You should follow these steps to complete the installation:

1. Double click on the standalone installer that you extracted, or the MSI file you downloaded.

2. The MySQL Connector/ODBC 3.51 - Setup Wizard will start. Click the Next button to begin the installation process.

3. You will need to choose the installation type. The Typical installation provides the standard files you will need to connect to a MySQL database using ODBC. The Complete option installs all the available files, including debug and utility components. It is recommended you choose one of these two options to complete the installation. If choose one of these methods, click Next and then proceed to step 5.

   You may also choose a Custom installation, which enables you to select the individual components that you want to install. You have chosen this method, click Next and then proceed to step 4.

4. If you have chosen a custom installation, use the popups to select which components to install and then click Next to install the necessary files.

5. Once the files have copied to your machine, the installation is complete. Click Finish to exit the installer.

Now the installation is complete, you can continue to configure your ODBC connections using Section 18.1.3, “Connector/ODBC Configuration”.

###### 18.1.2.3.1.2. Installing the Windows Connector/ODBC Driver using the Zipped DLL package

If you have downloaded the Zipped DLL package then you must install the individual files required for Connector/ODBC operation manually. Once you have unzipped the installation files, you can either perform this operation by hand, executing each statement individually, or you can use the included Batch file to perform an installation to the default locations.

To install using the Batch file:

1. Unzip the Connector/ODBC Zipped DLL package.

2. Open a Command Prompt.

3. Change to the directory created when you unzipped the Connector/ODBC Zipped DLL package.

4. Run `Install.bat:`

       C:\> Install.bat

   This will copy the necessary files into the default location, and then register the Connector/ODBC driver with the Windows ODBC manager.

If you want to copy the files to an alternative location - for example, to run or test different versions of the Connector/ODBC driver on the same machine, then you must copy the files by hand. It is however not recommended to install these files in a non-standard location. To copy the files by hand to the default installation location use the following steps:

1. Unzip the Connector/ODBC Zipped DLL package.

2. Open a Command Prompt.

3. Change to the directory created when you unzipped the Connector/ODBC Zipped DLL package.

4. Copy the library files to a suitable directory. The default is to copy them into the default Windows system directory `\Windows\System32`:

       C:\> copy lib\myodbc3S.dll \Windows\System32
       C:\> copy lib\myodbc3S.lib \Windows\System32
       C:\> copy lib\myodbc3.dll \Windows\System32
       C:\> copy lib\myodbc3.lib \Windows\System32

5. Copy the Connector/ODBC tools. These must be placed into a directory that is in the system `PATH`. The default is to install these into the Windows system directory `\Windows\System32`:

       C:\> copy bin\myodbc3i.exe \Windows\System32
       C:\> copy bin\myodbc3m.exe \Windows\System32
       C:\> copy bin\myodbc3c.exe \Windows\System32

6. Optionally copy the help files. For these files to be accessible through the help system, they must be installed in the Windows system directory:

       C:\> copy doc\*.hlp \Windows\System32

7. Finally, you must register the Connector/ODBC driver with the ODBC manager:

       C:\> myodbc3i -a -d -t"MySQL ODBC 3.51 Driver;\
         DRIVER=myodbc3.dll;SETUP=myodbc3S.dll"

   You must change the references to the DLL files and command location in the above statement if you have not installed these files into the default location.

###### 18.1.2.3.1.3. Handling Installation Errors

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 reason for the error is that another application is currently using the ODBC system. Windows may not allow you to complete the installation. In most cases, you can continue by pressing `Ignore` to copy the rest of the Connector/ODBC 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 the Connector/ODBC drivers, and re-boot to normal mode.

##### 18.1.2.3.2. Installing Connector/ODBC from a Binary Distribution on Unix

There are two methods available for installing Connector/ODBC on Unix from a binary distribution. For most Unix environments you will need to use the tarball distribution. For Linux systems, there is also an RPM distribution available.

###### 18.1.2.3.2.1. Installing Connector/ODBC 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 that demonstrate the process using the Linux version of the tarball:

    shell> su root
    shell> gunzip mysql-connector-odbc-3.51.11-i686-pc-linux.tar.gz
    shell> tar xvf mysql-connector-odbc-3.51.11-i686-pc-linux.tar
    shell> cd mysql-connector-odbc-3.51.11-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 18.1.3.4, “Configuring a Connector/ODBC DSN on Unix”, to configure the DSN for Connector/ODBC. For more information, refer to the `INSTALL-BINARY` file that comes with your distribution.

###### 18.1.2.3.2.2. Installing Connector/ODBC from an RPM Distribution

To install or upgrade Connector/ODBC from an RPM distribution on Linux, simply download the RPM distribution of the latest version of Connector/ODBC 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 mysql-connector-odbc-3.51.12.i386.rpm

If the driver exists, upgrade it like this:

    shell> su root
    shell> rpm -Uvh mysql-connector-odbc-3.51.12.i386.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 18.1.3.4, “Configuring a Connector/ODBC DSN on Unix”.

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

    shell> su root
    shell> rpm -e mysql-connector-odbc

##### 18.1.2.3.3. Installing Connector/ODBC on Mac OS X

Mac OS X is based on the FreeBSD operating system, and you can normally use the MySQL network port for connecting to MySQL servers on other hosts. Installing the Connector/ODBC driver enables you to connect to MySQL databases on any platform through the ODBC interface. You should only need to install the Connector/ODBC driver when your application requires an ODBC interface. Applications that require or can use ODBC (and therefore the Connector/ODBC driver) include ColdFusion, Filemaker Pro, 4th Dimension and many other applications.

Mac OS X includes its own ODBC manager, based on the `iODBC` manager. Mac OS X includes an administration tool that provides easier administration of ODBC drivers and configuration, updating the underlying `iODBC` configuration files.

###### 18.1.2.3.3.1. Installing the Connector/ODBC Driver

You can install Connector/ODBC on a Mac OS X or Mac OS X Server computer by using the binary distribution. The package is available as a compressed disk image (`.dmg`) file. To install Connector/ODBC on your computer using this method, follow these steps:

1. Download the file to your computer and double-click on the downloaded image file.

2. Within the disk image you will find an installer package (with the `.pkg` extension). Double click on this file to start the Mac OS X installer.

3. You will be presented with the installer welcome message. Click the Continue button to begin the installation process.

4. Please take the time to read the Important Information as it contains guidance on how to complete the installation process. Once you have read the notice and collected the necessary information, click Continue.

5. Connector/ODBC drivers are made available under the GNU General Public License. Please read the license if you are not familiar with it before continuing installation. Click Continue to approve the license (you will be asked to confirm that decision) and continue the installation.

6. Choose a location to install the Connector/ODBC drivers and the ODBC Administrator application. You must install the files onto a drive with an operating system and you may be limited in the choices available. Select the drive you want to use, and then click Continue.

7. The installer will automatically select the files that need to be installed on your machine. Click Install to continue. The installer will copy the necessary files to your machine. A progress bar will be shown indicating the installation progress.

8. When installation has been completed you will get a window like the one shown below. Click Close to close and quit the installer.

#### 18.1.2.4. Installing Connector/ODBC from a source distribution

Installing Connector/ODBC from a source distribution gives you greater flexibility in the contents and installation location of the Connector/ODBC components. It also enables you to build and install Connector/ODBC on platforms where a pre-compiled binary is not available.

Connector/ODBC sources are available either as a downloadable package, or through the revision control system used by the Connector/ODBC developers.

##### 18.1.2.4.1. Installing Connector/ODBC from a Source Distribution on Windows

You should only need to install Connector/ODBC from source on Windows if you want to change or modify the source or installation. If you are unsure whether to install from source, please use the binary installation detailed in Section 18.1.2.3.1, “Installing Connector/ODBC from a Binary Distribution on Windows”.

Installing Connector/ODBC from source on Windows requires a number of different tools and packages:

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

- Suitable C compiler, such as Microsoft Visual C++ or the C compiler included with Microsoft Visual Studio.

- Compatible `make` tool. Microsoft's `nmake` is used in the examples in this section.

- MySQL client libraries and include files from MySQL 4.0.0 or higher. (Preferably MySQL 4.0.16 or higher). This is required because Connector/ODBC 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/.

###### 18.1.2.4.1.1. Building Connector/ODBC 3.51

Connector/ODBC source distributions include `Makefiles` that require the nmake or other `make` utility. 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 directory 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 Subversion tree for compiling, all Windows-specific `Makefiles` are named as `Win_Makefile*`.

###### 18.1.2.4.1.2. 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

###### 18.1.2.4.1.3. 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.

##### 18.1.2.4.2. Installing Connector/ODBC from a Source Distribution on Unix

You need the following tools to build MySQL from source on Unix:

- A working ANSI C++ compiler. gcc 2.95.2 or later, egcs 1.0.2 or later or egcs 2.91.66, SGI C++, and SunPro C++ are some of the compilers that are known to work.

- A good make program. GNU make is always recommended and is sometimes required.

- MySQL client libraries and include files from MySQL 4.0.0 or higher. (Preferably MySQL 4.0.16 or higher). This is required because Connector/ODBC 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/.

  If you have built your own MySQL server and/or client libraries from source then you must have used the `--enable-thread-safe-client` option to `configure` when the libraries were built.

  You should also ensure that the `libmysqlclient` library were built and installed as a shared library.

- A compatible ODBC manager must be installed. Connector/ODBC is known to work with the `iODBC` and `unixODBC` managers. See Section 18.1.1.2.2, “ODBC Driver Managers”, for more information.

- If you are using a character set that isn't compiled into the MySQL client library 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. See Chapter 10, Character Set Support, for more information on character set support.

Once you have all the required files, unpack the source files to a separate directory, you then have to run configure and build the library using make.

###### 18.1.2.4.2.1. Typical configure Options

The configure script gives you a great deal of control over how you configure your Connector/ODBC 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 Connector/ODBC, 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 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 `unixODBC`).

   - 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 Connector/ODBC 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

###### 18.1.2.4.2.2. Additional configure Options

There are a number of other options that you need, or want, to set when configuring the Connector/ODBC driver before it is built.

- 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 the driver thread-safe library `libmyodbc3_r.so` from by linking with MySQL thread-safe client library `libmysqlclient_r.so` (The extensions are OS dependent).

  If the compilation with the thread-safe option fails, it may be because the correct thread-libraries on the system could not be located. You should set the value of `LIBS` to point to the correct thread library for your system.

      LIBS="-lpthread" ./configure ..

- You can enable or disable the shared and static versions of Connector/ODBC using these options:

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

- 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` option when you run configure.

- This option is available only for source trees that have been obtained from the Subversion repository. This option does not apply to the packaged source distributions.

  By default, the driver is built with the `--without-docs` option. If you would like the documentation to be built, then execute configure with:

      --with-docs

###### 18.1.2.4.2.3. Building and Compilation

To build the driver libraries, you have to just execute make.

    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 `<myodbc@lists.mysql.com>` for further assistance.

###### 18.1.2.4.2.4. Building Shared Libraries

On most platforms, MySQL does not build or support `.so` (shared) client libraries by default. This is based on our experience of problems when building shared libraries.

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 mysql-connector-odbc-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 the Connector/ODBC library installation 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

###### 18.1.2.4.2.5. 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 Connector/ODBC 3.51:

- `libmyodbc3.so`

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

- `libmyodbc3.a`

For thread-safe Connector/ODBC 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.

###### 18.1.2.4.2.6. Testing Connector/ODBC on Unix

To run the basic samples provided in the distribution with the libraries that you built, use the following command:

    shell> make test

Before running the tests, create the DSN 'myodbc3' in `odbc.ini` and set the environment variable `ODBCINI` to the correct `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.

###### 18.1.2.4.2.7. Building Connector/ODBC from Source on Mac OS X

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

###### 18.1.2.4.2.8. Building Connector/ODBC from Source on HP-UX

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 determine whether you need to have set the MySQL client library path using the `SHLIB_PATH` environment variable. For static versions, ignore all shared-library options and run configure with the `--disable-shared` option.

###### 18.1.2.4.2.9. Building Connector/ODBC from Source on AIX

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'.

##### 18.1.2.4.3. Installing Connector/ODBC from the Development Source Tree

Caution: You should read this section only if you are interested in helping us test our new code. If you just want to get MySQL Connector/ODBC up and running on your system, you should use a standard release distribution.

To be able to access the Connector/ODBC source tree, you must have Subversion installed. Subversion is freely available from http://subversion.tigris.org/.

To build from the source trees, you need the following tools:

- autoconf 2.52 (or newer)

- automake 1.4 (or newer)

- libtool 1.4 (or newer)

- m4

The most recent development source tree is available from our public Subversion trees at http://dev.mysql.com/tech-resources/sources.html.

To checkout out the Connector/ODBC sources, change to the directory where you want the copy of the Connector/ODBC tree to be stored, then use the following command:

    shell> svn co http://svn.mysql.com/svnpublic/connector-odbc3

You should now have a copy of the entire Connector/ODBC source tree in the directory `connector-odbc3`. To build from this source tree on Unix or Linux follow these steps:

    shell> cd connector-odbc3
    shell> aclocal
    shell> autoheader
    shell> autoconf
    shell> automake;
    shell> ./configure  # Add your favorite options here
    shell> make

For more information on how to build, refer to the `INSTALL` file located in the same directory. For more information on options to configure, see Section 18.1.2.4.2.1, “Typical configure Options”

When the build is done, run make install to install the Connector/ODBC 3.51 driver on your system.

If you have gotten to the make stage and the distribution does not compile, please report it to `<myodbc@lists.mysql.com>`.

On Windows, make use of Windows Makefiles `WIN-Makefile` and `WIN-Makefile_debug` in building the driver. For more information, see Section 18.1.2.4.1, “Installing Connector/ODBC from a Source Distribution on Windows”.

After the initial checkout operation to get the source tree, you should run svn update periodically update your source according to the latest version.

### 18.1.3. Connector/ODBC Configuration

Before you connect to a MySQL database using the Connector/ODBC driver you must configure an ODBC Data Source Name. The DSN associates the various configuration parameters required to communicate with a database to a specific name. You use the DSN in an application to communicate with the database, rather than specifying individual parameters within the application itself. DSN information can be user specific, system specific, or provided in a special file. ODBC data source names are configured in different ways, depending on your platform and ODBC driver.

#### 18.1.3.1. Data Source Names

A Data Source Name associates the configuration parameters for communicating with a specific database. Generally a DSN consists of the following parameters:

- Name
- Hostname
- Database Name
- Login
- Password

In addition, different ODBC drivers, including Connector/ODBC, may accept additional driver-specific options and parameters.

There are three types of DSN:

- A System DSN is a global DSN definition that is available to any user and application on a particular system. A System DSN can normally only be configured by a systems administrator, or by a user who has specific permissions that let them create System DSNs.

- A User DSN is specific to an individual user, and can be used to store database connectivity information that the user regularly uses.

- A File DSN uses a simple file to define the DSN configuration. File DSNs can be shared between users and machines and are therefore more practical when installing or deploying DSN information as part of an application across many machines.

DSN information is stored in different locations depending on your platform and environment.

#### 18.1.3.2. Configuring a Connector/ODBC DSN on Windows

The `ODBC Data Source Administrator` within Windows enables you to create DSNs, check driver installation and configure ODBC systems such as tracing (used for debugging) and connection pooling.

Different editions and versions of Windows store the `ODBC Data Source Administrator` in different locations depending on the version of Windows that you are using.

To open the `ODBC Data Source Administrator` in Windows Server 2003:

1. On the `Start` menu, choose `Administrative Tools`, and then click `Data Sources (ODBC)`.

To open the `ODBC Data Source Administrator` in Windows 2000 Server or Windows 2000 Professional:

1. On the `Start` menu, choose `Settings`, and then click `Control Panel`.

2. In `Control Panel`, click `Administrative Tools`.

3. In `Administrative Tools`, click `Data Sources (ODBC)`.

To open the `ODBC Data Source Administrator` on Windows XP:

1. On the `Start` menu, click `Control Panel`.

2. In the `Control Panel` when in `Category View` click `Performance and Maintenance` and then click `Administrative Tools.`. If you are viewing the `Control Panel` in `Classic View`, click `Administrative Tools`.

3. In `Administrative Tools`, click `Data Sources (ODBC)`.

Irrespective of your Windows version, you should be presented the `ODBC Data Source Administrator` window:

Within Windows XP, you can add the `Administrative Tools` folder to your Start menu to make it easier to locate the ODBC Data Source Administrator. To do this:

1. Right click on the Start menu.

2. Select `Properties`.

3. Click Customize....

4. Select the Advanced tab.

5. Within `Start menu items`, within the `System Administrative Tools` section, select `Display on the All Programs menu`.

Within both Windows Server 2003 and Windows XP you may want to permanently add the `ODBC Data Source Administrator` to your Start menu. To do this, locate the `Data Sources (ODBC)` icon using the methods shown, then right-click on the icon and then choose Pin to Start Menu.

##### 18.1.3.2.1. Adding a Connector/ODBC DSN on Windows

To add and configure a new Connector/ODBC data source on Windows, use the `ODBC Data Source Administrator`:

1. Open the `ODBC Data Source Administrator`.

2. To create a System DSN (which will be available to all users) , select the `System DSN` tab. To create a User DSN, which will be unique only to the current user, click the Add... button.

3. You will need to select the ODBC driver for this DSN.

   Select `MySQL ODBC 3.51 Driver`, then click `Finish`.

4. You now need to configure the specific fields for the DSN you are creating through the `Add Data Source Name` dialog.

   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 some text to help identify the connection.

6. In the `Server` field, enter the name of the MySQL server host that you want to access. By default, it is `localhost`.

7. In the `User` field, enter the user name to use for this connection.

8. In the `Password` field, enter the corresponding password for this connection.

9. The `Database` popup should automatically populate with the list of databases that the user has permissions to access.

10. Click OK to save the DSN.

A completed DSN configuration may look like this:

##### 18.1.3.2.2. Checking Connector/ODBC DSN Configuration on Windows

You can verify the connection using the parameters you have entered by clicking the Test button. If the connection could be made successfully, you will be notified with a `Success; connection was made!` dialog.

If the connection failed, you can obtain more information on the test and why it may have failed by clicking the Diagnostics... button to show additional error messages.

##### 18.1.3.2.3. Connector/ODBC DSN Configuration Options

You can configure a number of options for a specific DSN by using either the Connect Options or Advanced tabs in the DSN configuration dialog.

The Connection Options dialog can be seen below.

The three options you can configure are:

- `Port` sets the TCP/IP port number to use when communicating with MySQL. Communication with MySQL uses port 3306 by default. If your server is configured to use a different TCP/IP port, you must specify that port number here.

- `Socket` sets the name or location of a specific socket or Windows pipe to use when communicating with MySQL.

- `Initial Statement` defines an SQL statement that will be executed when the connection to MySQL is opened. You can use this to set MySQL options for your connection, such as setting the default character set or database to use during your connection.

The Advanced tab enables you to configure Connector/ODBC connection parameters. Refer to Section 18.1.3.5, “Connector/ODBC Connection Parameters”, for information about the meaning of these options.

##### 18.1.3.2.4. Errors and Debugging

This section answers Connector/ODBC connection-related questions.

- While configuring a Connector/ODBC 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.

- On Windows, the default `myodbc3.dll` is compiled for optimal performance. If you want to debug Connector/ODBC 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 Connector/ODBC 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.

#### 18.1.3.3. Configuring a Connector/ODBC DSN on Mac OS X

To configure a DSN on Mac OS X you should use the ODBC Administrator. If you have Mac OS X 10.2 or earlier, refer to Section 18.1.3.4, “Configuring a Connector/ODBC DSN on Unix”. Select whether you want to create a User DSN or a System DSN. If you want to add a System DSN, you may need to authenticate with the system. You must click the padlock and enter a user and password with administrator privileges.

1. Open the ODBC Administrator from the `Utilities` folder in the `Applications` folder.

2. On the User DSN or System DSN panel, click Add.

3. Select the Connector/ODBC driver and click OK.

4. You will be presented with the `Data Source Name` dialog. Enter The `Data Source Name` and an optional `Description` for the DSN.

5. Click Add to add a new keyword/value pair to the panel. You should configure at least four pairs to specify the `server`, `username`, `password` and `database` connection parameters. See Section 18.1.3.5, “Connector/ODBC Connection Parameters”.

6. Click OK to add the DSN to the list of configured data source names.

A completed DSN configuration may look like this:

You can configure additional ODBC options to your DSN by adding further keyword/value pairs and setting the corresponding values. See Section 18.1.3.5, “Connector/ODBC Connection Parameters”.

#### 18.1.3.4. Configuring a Connector/ODBC 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 Connector/ODBC 3.51, respectively:

    ;
    ;  odbc.ini configuration for Connector/ODBC and Connector/ODBC 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  = Connector/ODBC 3.51 Driver DSN
    SERVER       = localhost
    PORT         =
    USER         = root
    Password     =
    Database     = test
    OPTION       = 3
    SOCKET       =

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

Refer to the Section 18.1.3.5, “Connector/ODBC Connection Parameters”, for the list of connection parameters that can be supplied.

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

- ODBCConfig GUI tool(HOWTO: ODBCConfig)

- odbcinst

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

#### 18.1.3.5. Connector/ODBC Connection Parameters

You can specify the parameters in the following tables for Connector/ODBC when configuring a DSN. Users on Windows can use the Options and Advanced panels when configuring a DSN to set these parameters; see the table for information on which options relate to which fields and checkboxes. On Unix and Mac OS X, use the parameter name and value as the keyword/value pair in the DSN configuration. Alternatively, you can set these parameters within the `InConnectionString` argument in the `SQLDriverConnect()` call.

Parameter | Default Value | Comment
`user` | ODBC (on Windows) | The username used to connect to MySQL.
`server` | `localhost` | The hostname of the MySQL server.
`database` |  | The default database.
`option` | 0 | Options that specify how Connector/ODBC should work. See below.
`port` | 3306 | The 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 Connector/ODBC 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 Connector/ODBC connect screen:

Value | Windows Checkbox | Description
1 | Don't Optimized Column Width | The client can't handle that Connector/ODBC returns the real width of a column.
2 | Return Matching Rows | The 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.
4 | Trace Driver Calls To myodbc.log | Make a debug log in `C:\myodbc.log` on Windows, or `/tmp/myodbc.log` on Unix variants.
8 | Allow Big Results | Don't set any packet limit for results and parameters.
16 | Don't Prompt Upon Connect | Don't prompt for questions even if driver would like to prompt.
32 | Enable Dynamic Cursor | Enable or disable the dynamic cursor support. (Not allowed in Connector/ODBC 2.50.)
64 | Ignore # in Table Name | Ignore use of database name in `db_name.tbl_name.col_name`.
128 | User Manager Cursors | Force use of ODBC manager cursors (experimental).
256 | Don't Use Set Locale | Disable the use of extended fetch (experimental).
512 | Pad Char To Full Length | Pad `CHAR` columns to full column length.
1024 | Return Table Names for SQLDescribeCol | `SQLDescribeCol()` returns fully qualified column names.
2048 | Use Compressed Protocol | Use the compressed client/server protocol.
4096 | Ignore Space After Function Names | Tell server to ignore space after function name and before ‘`(`’ (needed by PowerBuilder). This makes all function names keywords.
8192 | Force Use of Named Pipes | Connect with named pipes to a mysqld server running on NT.
16384 | Change BIGINT Columns to Int | Change `BIGINT` columns to `INT` columns (some applications can't handle `BIGINT`).
32768 | No Catalog (exp) | Return 'user' as `Table_qualifier` and `Table_owner` from `SQLTables` (experimental).
65536 | Read Options From `my.cnf` | Read parameters from the `[client]` and `[odbc]` groups from `my.cnf`.
131072 | Safe | Add some extra safety checks (should not be needed but...).
262144 | Disable transaction | Disable transactions.
524288 | Save queries to `myodbc.sql` | Enable query logging to `c:\myodbc.sql`(`/tmp/myodbc.sql`) file. (Enabled only in debug mode.)
1048576 | Don't Cache Result (forward only cursors) | Do 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.
2097152 | Force Use Of Forward Only Cursors | Force 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.
4194304 | Enable auto-reconnect. | Enables auto-reconnection functionality. You should not use this option with transactions, since a auto reconnection during a incomplete transaction may cause corruption. Note that an auto-reconnected connection will not inherit the same settings and environment as the original. This option was enabled in Connector/ODBC 3.5.13.
8388608 | Flag Auto Is Null | When set, this option causes the connection to set the `SQL_AUTO_IS_NULL` option to 1. This disables the standard behavior, but may enable older applications to correctly identify `AUTO_INCREMENT` values. For more information. See `IS NULL` This option was enabled in Connector/ODBC 3.5.13.

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

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

Configuration | Option Value
Microsoft Access, Visual Basic | 3
Driver trace generation (Debug mode) | 4
Microsoft Access (with improved DELETE queries) | 35
Large tables with too many rows | 2049
Sybase PowerBuilder | 135168
Query log generation (Debug mode) | 524288
Generate driver trace as well as query log (Debug mode) | 524292
Large tables with no-cache results | 3145731

#### 18.1.3.6. Connecting Without a Predefined DSN

You can connect to the MySQL server using SQLDriverConnect, by specifying the `DRIVER` name field. Here are the connection strings for Connector/ODBC using DSN-Less connections:

For MyODBC 2.50:

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

For Connector/ODBC 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;"

Note. Note that on Mac OS X you may need to specify the full path to the Connector/ODBC driver library.

Refer to the Section 18.1.3.5, “Connector/ODBC Connection Parameters”, for the list of connection parameters that can be supplied.

#### 18.1.3.7. ODBC Connection Pooling

Connection pooling enables the ODBC driver to re-use existing connections to a given database from a pool of connections, instead of opening a new connection each time the database is accessed. By enabling connection pooling you can improve the overall performance of your application by lowering the time taken to open a connection to a database in the connection pool.

For more information about connection pooling: http://support.microsoft.com/default.aspx?scid=kb;EN-US;q169470.

#### 18.1.3.8. Getting an ODBC Trace File

If you encounter difficulties or problems with Connector/ODBC, you should start by making a log file from the `ODBC Manager` and Connector/ODBC. This is called tracing, and is enabled through the ODBC Manager. The procedure for this differs for Windows, Mac OS X and Unix.

##### 18.1.3.8.1. Enabling ODBC Tracing on Windows

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.

##### 18.1.3.8.2. Enabling ODBC Tracing on Mac OS X

To enable the trace option on Mac OS X 10.3 or later you should use the `Tracing` tab within ODBC Administrator .

1. Open the ODBC Administrator.

2. Select the `Tracing` tab.

3. Select the `Enable Tracing` checkbox.

4. Enter the location where you want to save the Tracing log. If you want to append information to an existing log file, click the Choose... button.

##### 18.1.3.8.3. Enabling ODBC Tracing on Unix

To enable the trace option on Mac OS X 10.2 (or earlier) or Unix you must add the `trace` option to the ODBC configuration:

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.

##### 18.1.3.8.4. Enabling a Connector/ODBC Log

To generate a Connector/ODBC log, do the following:

1. Within Windows, enable the `Trace Connector/ODBC` option flag in the Connector/ODBC 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 Section 18.1.3.2.4, “Errors and Debugging”.

   On Mac OS X, Unix, or if you are using DSN-Less connection, then you need to supply `OPTION=4` in the connection string or set the corresponding keyword/value pair in the DSN.

2. Start your application and try to get it to fail. Then check the Connector/ODBC trace file to find out what could be wrong.

If you need help determining what is wrong, see Section 18.1.7.1, “Connector/ODBC Community Support”.

### 18.1.4. Connector/ODBC Examples

Once you have configured a DSN to provide access to a database, how you access and use that connection is dependent on the application or programming language. As ODBC is a standardized interface, any application or language that supports ODBC can use the DSN and connect to the configured database.

#### 18.1.4.1. Basic Connector/ODBC Application Steps

Interacting with a MySQL server from an applications using the Connector/ODBC typically involves the following operations:

- Configure the Connector/ODBC 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:

#### 18.1.4.2. Step-by-step Guide to Connecting to a MySQL Database through Connector/ODBC

A typical installation situation where you would install Connector/ODBC is when you want to access a database on a Linux or Unix host from a Windows machine.

As an example of the process required to set up access between two machines, the steps below take you through the basic steps. These instructions assume that you want to connect to system ALPHA from system BETA with a username and password of `myuser` and `mypassword`.

On system ALPHA (the MySQL server) 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 BETA using a password of `myuser` to the database `test`:

       GRANT ALL ON test.* to 'myuser'@'BETA' IDENTIFIED BY 'mypassword';

   For more information about MySQL privileges, refer to Section 5.8, “MySQL User Account Management”.

On system BETA (the Connector/ODBC client), follow these steps:

1. Configure a Connector/ODBC DSN using parameters that match the server, database and authentication information that you have just configured on system ALPHA.

   Parameter | Value | Comment
   DSN | remote_test | A name to identify the connection.
   SERVER | ALPHA | The address of the remote server.
   DATABASE | test | The name of the default database.
   USER | myuser | The username configured for access to this database.
   PASSWORD | mypassword | The password for `myuser`.

2. Using an ODBC-capable application, such as Microsoft Office, connect to the MySQL server using the DSN you have just created. If the connection fails, use tracing to examine the connection process. See Section 18.1.3.8, “Getting an ODBC Trace File”, for more information.

#### 18.1.4.3. Connector/ODBC and Third-Party ODBC Tools

Once you have configured your Connector/ODBC DSN, you can access your MySQL database through any application that supports the ODBC interface, including programming languages and third-party applications. This section contains guides and help on using Connector/ODBC with various ODBC-compatible tools and applications, including Microsoft Word, Microsoft Excel and Adobe/Macromedia ColdFusion.

Connector/ODBC has been tested with the following applications:

Publisher | Application | Notes
Adobe | ColdFusion | Formerly Macromedia ColdFusion
Borland | C++ Builder |
| Builder 4 |
| Delphi |
Business Objects | Crystal Reports |
Claris | Filemaker Pro |
Corel | Paradox |
Computer Associates | Visual Objects | Also known as CAVO
| AllFusion ERwin Data Modeler |
Gupta | Team Developer | Previously known as Centura Team Developer; Gupta SQL/Windows
Gensym | G2-ODBC Bridge |
Inline | iHTML |
Lotus | Notes | Versions 4.5 and 4.6
Microsoft | Access |
| Excel |
| Visio Enterprise |
| Visual C++ |
| Visual Basic |
| ODBC.NET | Using C#, Visual Basic, C++
| FoxPro |
| Visual Interdev |
OpenOffice.org | OpenOffice.org |
Perl | DBD::ODBC |
Pervasive Software | DataJunction |
Sambar Technologies | Sambar Server |
SPSS | SPSS |
SoftVelocity | Clarion |
SQLExpress | SQLExpress for Xbase++ |
Sun | StarOffice |
SunSystems | Vision |
Sybase | PowerBuilder |
| PowerDesigner |
theKompany.com | Data Architect |

If you know of any other applications that work with Connector/ODBC, please send mail to `<myodbc@lists.mysql.com>` about them.

#### 18.1.4.4. Using Connector/ODBC and Microsoft Access

You can use MySQL database with Microsoft Access using Connector/ODBC. The MySQL database can be used as an import source, an export source, or as a linked table for direct use within an Access application, so you can use Access as the front-end interface to a MySQL database.

##### 18.1.4.4.1. Exporting Access Data to MySQL

To export a table of data from an Access database 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.

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:

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 Connector/ODBC or Connector/ODBC 3.51 data source that you want to export to. To define a new data source for Connector/ODBC, please Section 18.1.3.2, “Configuring a Connector/ODBC DSN on Windows”.

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

##### 18.1.4.4.2. Importing MySQL Data to Access

To import or link a table or tables from MySQL to Access, follow these 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 source names.

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, 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`.

##### 18.1.4.4.3. Linking MySQL Data to Access Tables

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`.

#### 18.1.4.5. Using Connector/ODBC with Microsoft Word or Excel

You can use Microsoft Word and Microsoft Excel to access information from a MySQL database using Connector/ODBC. Within Microsoft Word, this facility is most useful when importing data for mailmerge, or for tables and data to be included in reports. Within Microsoft Excel, you can execute queries on your MySQL server and import the data directly into an Excel Worksheet, presenting the data as a series of rows and columns.

With both applications, data is accessed and imported into the application using Microsoft Query , which enables you to execute a query though an ODBC source. You use Microsoft Query to build the SQL statement to be executed, selecting the tables, fields, selection criteria and sort order. For example, to insert information from a table in the World test database into an Excel spreadsheet, using the DSN samples shown in Section 18.1.3, “Connector/ODBC Configuration”:

1. Create a new Worksheet.

2. From the `Data` menu, choose `Import External Data`, and then select `New Database Query`.

3. Microsoft Query will start. First, you need to choose the data source, by selecting an existing Data Source Name.

4. Within the `Query Wizard`, you must choose the columns that you want to import. The list of tables available to the user configured through the DSN is shown on the left, the columns that will be added to your query are shown on the right. The columns you choose are equivalent to those in the first section of a `SELECT` query. Click Next to continue.

5. You can filter rows from the query (the equivalent of a `WHERE` clause) using the `Filter Data` dialog. Click Next to continue.

6. Select an (optional) sort order for the data. This is equivalent to using a `ORDER BY` clause in your SQL query. You can select up to three fields for sorting the information returned by the query. Click Next to continue.

7. Select the destination for your query. You can select to return the data Microsoft Excel, where you can choose a worksheet and cell where the data will be inserted; you can continue to view the query and results within Microsoft Query, where you can edit the SQL query and further filter and sort the information returned; or you can create an OLAP Cube from the query, which can then be used directly within Microsoft Excel. Click Finish.

The same process can be used to import data into a Word document, where the data will be inserted as a table. This can be used for mail merge purposes (where the field data is read from a Word table), or where you want to include data and reports within a report or other document.

#### 18.1.4.6. Using Connector/ODBC with Crystal Reports

Crystal Reports can use an ODBC DSN to connect to a database from which you to extract data and information for reporting purposes.

### Note

There is a known issue with certain versions of Crystal Reports where the application is unable to open and browse tables and fields through an ODBC connection. Before using Crystal Reports with MySQL, please ensure that you have update to the latest version, including any outstanding service packs and hotfixes. For more information on this issue, see the Business) Objects Knowledgebase for more information.

For example, to create a simple crosstab report within Crystal Reports XI, you should follow these steps:

1. Create a DSN using the `Data Sources (ODBC)` tool. You can either specify a complete database, including username and password, or you can build a basic DSN and use Crystal Reports to set the username and password.

   For the purposes of this example, a DSN that provides a connection to an instance of the MySQL Sakila sample database has been created.

2. Open Crystal Reports and create a new project, or an open an existing reporting project into which you want to insert data from your MySQL data source.

3. Start the Cross-Tab Report Wizard, either by clicking on the option on the Start Page. Expand the Create New Connection folder, then expand the ODBC (RDO) folder to obtain a list of ODBC data sources.

   You will be asked to select a data source.

4. When you first expand the ODBC (RDO) folder you will be presented the Data Source Selection screen. From here you can select either a pre-configured DSN, open a file-based DSN or enter and manual connection string. For this example, the Sakila DSN will be used.

   If the DSN contains a username/password combination, or you want to use different authentication credentials, click Next to enter the username and password that you want to use. Otherwise, click Finish to continue the data source selection wizard.

5. You will be returned the Cross-Tab Report Creation Wizard. You now need to select the database and tables that you want to include in your report. For our example, we will expand the selected Sakila database. Click the `city` table and use the > button to add the table to the report. Then repeat the action with the `country` table. Alternatively you can select multiple tables and add them to the report.

   Finally, you can select the parent Sakila resource and add of the tables to the report.

   Once you have selected the tables you want to include, click Next to continue.

6. Crystal Reports will now read the table definitions and automatically identify the links between the tables. The identification of links between tables enables Crystal Reports to automatically lookup and summarize information based on all the tables in the database according to your query. If Crystal Reports is unable to perform the linking itself, you can manually create the links between fields in the tables you have selected.

   Click Next to continue the process.

7. You can now select the columns and rows that you wish to include within the Cross-Tab report. Drag and drop or use the > buttons to add fields to each area of the report. In the example shown, we will report on cities, organized by country, incorporating a count of the number of cities within each country. If you want to browse the data, select a field and click the Browse Data... button.

   Click Next to create a graph of the results. Since we are not creating a graph from this data, click Finish to generate the report.

8. The finished report will be shown, a sample of the output from the Sakila sample database is shown below.

Once the ODBC connection has been opened within Crystal Reports, you can browse and add any fields within the available tables into your reports.

#### 18.1.4.7. Connector/ODBC Programming

With a suitable ODBC Manager and the Connector/ODBC driver installed, any programming language or environment that can support ODBC should be able to connect to a MySQL database through Connector/ODBC.

This includes, but is certainly not limited to, Microsoft support languages (including Visual Basic, C# and interfaces such as ODBC.NET), Perl (through the DBI module, and the DBD::ODBC driver).

##### 18.1.4.7.1. Using Connector/ODBC with Visual Basic Using ADO, DAO and RDO

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

###### 18.1.4.7.1.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

###### 18.1.4.7.1.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

###### 18.1.4.7.1.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

##### 18.1.4.7.2. Using Connector/ODBC with .NET

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

###### 18.1.4.7.2.1. Using Connector/ODBC with ODBC.NET and C# (C sharp)

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

    /**
     * @sample    : mycon.cs
     * @purpose   : Demo sample for ODBC.NET using Connector/ODBC
     * @author    : Venu, <myodbc@lists.mysql.com>
     *
     * (C) Copyright MySQL AB, 1995-2006
     *
     **/

    /* 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 Connector/ODBC 3.51
              string MyConString = "DRIVER={MySQL ODBC 3.51 Driver};" +
                "SERVER=localhost;" +
                "DATABASE=test;" +
                "UID=venu;" +
                "PASSWORD=venu;" +
                "OPTION=3";

              //Connect to MySQL using Connector/ODBC
              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) {
                    //Supported only by Connector/ODBC 3.51
                    Console.WriteLine("Data:" + MyDataReader.GetInt32(0) + " " +
                                      MyDataReader.GetString(1) + " " +
                                      MyDataReader.GetInt64(2));
                  }
                  else {
                    //BIGINTs not supported by Connector/ODBC
                    Console.WriteLine("Data:" + MyDataReader.GetInt32(0) + " " +
                                      MyDataReader.GetString(1) + " " +
                                      MyDataReader.GetInt32(2));
                  }
                }

              //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");
                }
            }
        }
      }
    }

###### 18.1.4.7.2.2. Using Connector/ODBC with ODBC.NET and Visual Basic

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 Connector/ODBC
    ' @author    : Venu, <myodbc@lists.mysql.com>
    '
    ' (C) Copyright MySQL AB, 1995-2006
    '
    '

    '
    ' 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

          'Connector/ODBC 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

### 18.1.5. Connector/ODBC Reference

This section provides reference material for the Connector/ODBC API, showing supported functions and methods, supported MySQL column types and the corresponding native type in Connector/ODBC, and the error codes returned by Connector/ODBC when a fault occurs.

#### 18.1.5.1. Connector/ODBC 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 Connector/ODBC. To obtain information about support for a specific function in the driver, an application can call `SQLGetFunctions`.

Note: For backward compatibility, the Connector/ODBC 3.51 driver supports all deprecated functions.

The following tables list Connector/ODBC API calls grouped by task:

Connecting to a data source:

| Connector/ODBC |  |
Function name | 2.50 | 3.51 | Standard | Purpose
`SQLAllocHandle` | No | Yes | ISO 92 | Obtains an environment, connection, statement, or descriptor handle.
`SQLConnect` | Yes | Yes | ISO 92 | Connects to a specific driver by data source name, user ID, and password.
`SQLDriverConnect` | Yes | Yes | ODBC | Connects to a specific driver by connection string or requests that the Driver Manager and driver display connection dialog boxes for the user.
`SQLAllocEnv` | Yes | Yes | Deprecated | Obtains an environment handle allocated from driver.
`SQLAllocConnect` | Yes | Yes | Deprecated | Obtains a connection handle

Obtaining information about a driver and data source:

| Connector/ODBC |  |
Function name | 2.50 | 3.51 | Standard | Purpose
`SQLDataSources` | No | No | ISO 92 | Returns the list of available data sources, handled by the Driver Manager
`SQLDrivers` | No | No | ODBC | Returns the list of installed drivers and their attributes, handles by Driver Manager
`SQLGetInfo` | Yes | Yes | ISO 92 | Returns information about a specific driver and data source.
`SQLGetFunctions` | Yes | Yes | ISO 92 | Returns supported driver functions.
`SQLGetTypeInfo` | Yes | Yes | ISO 92 | Returns information about supported data types.

Setting and retrieving driver attributes:

| Connector/ODBC |  |
Function name | 2.50 | 3.51 | Standard | Purpose
`SQLSetConnectAttr` | No | Yes | ISO 92 | Sets a connection attribute.
`SQLGetConnectAttr` | No | Yes | ISO 92 | Returns the value of a connection attribute.
`SQLSetConnectOption` | Yes | Yes | Deprecated | Sets a connection option
`SQLGetConnectOption` | Yes | Yes | Deprecated | Returns the value of a connection option
`SQLSetEnvAttr` | No | Yes | ISO 92 | Sets an environment attribute.
`SQLGetEnvAttr` | No | Yes | ISO 92 | Returns the value of an environment attribute.
`SQLSetStmtAttr` | No | Yes | ISO 92 | Sets a statement attribute.
`SQLGetStmtAttr` | No | Yes | ISO 92 | Returns the value of a statement attribute.
`SQLSetStmtOption` | Yes | Yes | Deprecated | Sets a statement option
`SQLGetStmtOption` | Yes | Yes | Deprecated | Returns the value of a statement option

Preparing SQL requests:

| Connector/ODBC |  |
Function name | 2.50 | 3.51 | Standard | Purpose
`SQLAllocStmt` | Yes | Yes | Deprecated | Allocates a statement handle
`SQLPrepare` | Yes | Yes | ISO 92 | Prepares an SQL statement for later execution.
`SQLBindParameter` | Yes | Yes | ODBC | Assigns storage for a parameter in an SQL statement.
`SQLGetCursorName` | Yes | Yes | ISO 92 | Returns the cursor name associated with a statement handle.
`SQLSetCursorName` | Yes | Yes | ISO 92 | Specifies a cursor name.
`SQLSetScrollOptions` | Yes | Yes | ODBC | Sets options that control cursor behavior.

Submitting requests:

| Connector/ODBC |  |
Function name | 2.50 | 3.51 | Standard | Purpose
`SQLExecute` | Yes | Yes | ISO 92 | Executes a prepared statement.
`SQLExecDirect` | Yes | Yes | ISO 92 | Executes a statement
`SQLNativeSql` | Yes | Yes | ODBC | Returns the text of an SQL statement as translated by the driver.
`SQLDescribeParam` | Yes | Yes | ODBC | Returns the description for a specific parameter in a statement.
`SQLNumParams` | Yes | Yes | ISO 92 | Returns the number of parameters in a statement.
`SQLParamData` | Yes | Yes | ISO 92 | Used in conjunction with `SQLPutData` to supply parameter data at execution time. (Useful for long data values.)
`SQLPutData` | Yes | Yes | ISO 92 | Sends part or all of a data value for a parameter. (Useful for long data values.)

Retrieving results and information about results:

| Connector/ODBC |  |
Function name | 2.50 | 3.51 | Standard | Purpose
`SQLRowCount` | Yes | Yes | ISO 92 | Returns the number of rows affected by an insert, update, or delete request.
`SQLNumResultCols` | Yes | Yes | ISO 92 | Returns the number of columns in the result set.
`SQLDescribeCol` | Yes | Yes | ISO 92 | Describes a column in the result set.
`SQLColAttribute` | No | Yes | ISO 92 | Describes attributes of a column in the result set.
`SQLColAttributes` | Yes | Yes | Deprecated | Describes attributes of a column in the result set.
`SQLFetch` | Yes | Yes | ISO 92 | Returns multiple result rows.
`SQLFetchScroll` | No | Yes | ISO 92 | Returns scrollable result rows.
`SQLExtendedFetch` | Yes | Yes | Deprecated | Returns scrollable result rows.
`SQLSetPos` | Yes | Yes | ODBC | Positions 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.
`SQLBulkOperations` | No | Yes | ODBC | Performs bulk insertions and bulk bookmark operations, including update, delete, and fetch by bookmark.

Retrieving error or diagnostic information:

| Connector/ODBC |  |
Function name | 2.50 | 3.51 | Standard | Purpose
`SQLError` | Yes | Yes | Deprecated | Returns additional error or status information
`SQLGetDiagField` | Yes | Yes | ISO 92 | Returns additional diagnostic information (a single field of the diagnostic data structure).
`SQLGetDiagRec` | Yes | Yes | ISO 92 | Returns additional diagnostic information (multiple fields of the diagnostic data structure).

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

| Connector/ODBC |  |
Function name | 2.50 | 3.51 | Standard | Purpose
`SQLColumnPrivileges` | Yes | Yes | ODBC | Returns a list of columns and associated privileges for one or more tables.
`SQLColumns` | Yes | Yes | X/Open | Returns the list of column names in specified tables.
`SQLForeignKeys` | Yes | Yes | ODBC | Returns a list of column names that make up foreign keys, if they exist for a specified table.
`SQLPrimaryKeys` | Yes | Yes | ODBC | Returns the list of column names that make up the primary key for a table.
`SQLSpecialColumns` | Yes | Yes | X/Open | Returns 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.
`SQLStatistics` | Yes | Yes | ISO 92 | Returns statistics about a single table and the list of indexes associated with the table.
`SQLTablePrivileges` | Yes | Yes | ODBC | Returns a list of tables and the privileges associated with each table.
`SQLTables` | Yes | Yes | X/Open | Returns the list of table names stored in a specific data source.

Performing transactions:

| Connector/ODBC |  |
Function name | 2.50 | 3.51 | Standard | Purpose
`SQLTransact` | Yes | Yes | Deprecated | Commits or rolls back a transaction
`SQLEndTran` | No | Yes | ISO 92 | Commits or rolls back a transaction.

Terminating a statement:

| Connector/ODBC |  |
Function name | 2.50 | 3.51 | Standard | Purpose
`SQLFreeStmt` | Yes | Yes | ISO 92 | Ends statement processing, discards pending results, and, optionally, frees all resources associated with the statement handle.
`SQLCloseCursor` | Yes | Yes | ISO 92 | Closes a cursor that has been opened on a statement handle.
`SQLCancel` | Yes | Yes | ISO 92 | Cancels an SQL statement.

Terminating a connection:

| Connector/ODBC |  |
Function name | 2.50 | 3.51 | Standard | Purpose
`SQLDisconnect` | Yes | Yes | ISO 92 | Closes the connection.
`SQLFreeHandle` | No | Yes | ISO 92 | Releases an environment, connection, statement, or descriptor handle.
`SQLFreeConnect` | Yes | Yes | Deprecated | Releases connection handle
`SQLFreeEnv` | Yes | Yes | Deprecated | Releases an environment handle

#### 18.1.5.2. Connector/ODBC Data Types

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

Native Value | SQL Type | C Type
`bit` | `SQL_BIT` | `SQL_C_BIT`
`tinyint` | `SQL_TINYINT` | `SQL_C_STINYINT`
`tinyint unsigned` | `SQL_TINYINT` | `SQL_C_UTINYINT`
`bigint` | `SQL_BIGINT` | `SQL_C_SBIGINT`
`bigint unsigned` | `SQL_BIGINT` | `SQL_C_UBIGINT`
`long varbinary` | `SQL_LONGVARBINARY` | `SQL_C_BINARY`
`blob` | `SQL_LONGVARBINARY` | `SQL_C_BINARY`
`longblob` | `SQL_LONGVARBINARY` | `SQL_C_BINARY`
`tinyblob` | `SQL_LONGVARBINARY` | `SQL_C_BINARY`
`mediumblob` | `SQL_LONGVARBINARY` | `SQL_C_BINARY`
`long varchar` | `SQL_LONGVARCHAR` | `SQL_C_CHAR`
`text` | `SQL_LONGVARCHAR` | `SQL_C_CHAR`
`mediumtext` | `SQL_LONGVARCHAR` | `SQL_C_CHAR`
`char` | `SQL_CHAR` | `SQL_C_CHAR`
`numeric` | `SQL_NUMERIC` | `SQL_C_CHAR`
`decimal` | `SQL_DECIMAL` | `SQL_C_CHAR`
`integer` | `SQL_INTEGER` | `SQL_C_SLONG`
`integer unsigned` | `SQL_INTEGER` | `SQL_C_ULONG`
`int` | `SQL_INTEGER` | `SQL_C_SLONG`
`int unsigned` | `SQL_INTEGER` | `SQL_C_ULONG`
`mediumint` | `SQL_INTEGER` | `SQL_C_SLONG`
`mediumint unsigned` | `SQL_INTEGER` | `SQL_C_ULONG`
`smallint` | `SQL_SMALLINT` | `SQL_C_SSHORT`
`smallint unsigned` | `SQL_SMALLINT` | `SQL_C_USHORT`
`real` | `SQL_FLOAT` | `SQL_C_DOUBLE`
`double` | `SQL_FLOAT` | `SQL_C_DOUBLE`
`float` | `SQL_REAL` | `SQL_C_FLOAT`
`double precision` | `SQL_DOUBLE` | `SQL_C_DOUBLE`
`date` | `SQL_DATE` | `SQL_C_DATE`
`time` | `SQL_TIME` | `SQL_C_TIME`
`year` | `SQL_SMALLINT` | `SQL_C_SHORT`
`datetime` | `SQL_TIMESTAMP` | `SQL_C_TIMESTAMP`
`timestamp` | `SQL_TIMESTAMP` | `SQL_C_TIMESTAMP`
`text` | `SQL_VARCHAR` | `SQL_C_CHAR`
`varchar` | `SQL_VARCHAR` | `SQL_C_CHAR`
`enum` | `SQL_VARCHAR` | `SQL_C_CHAR`
`set` | `SQL_VARCHAR` | `SQL_C_CHAR`
`bit` | `SQL_CHAR` | `SQL_C_CHAR`
`bool` | `SQL_CHAR` | `SQL_C_CHAR`

#### 18.1.5.3. Connector/ODBC Error Codes

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

Native Code | SQLSTATE 2 | SQLSTATE 3 | Error Message
500 | 01000 | 01000 | General warning
501 | 01004 | 01004 | String data, right truncated
502 | 01S02 | 01S02 | Option value changed
503 | 01S03 | 01S03 | No rows updated/deleted
504 | 01S04 | 01S04 | More than one row updated/deleted
505 | 01S06 | 01S06 | Attempt to fetch before the result set returned the first row set
506 | 07001 | 07002 | `SQLBindParameter` not used for all parameters
507 | 07005 | 07005 | Prepared statement not a cursor-specification
508 | 07009 | 07009 | Invalid descriptor index
509 | 08002 | 08002 | Connection name in use
510 | 08003 | 08003 | Connection does not exist
511 | 24000 | 24000 | Invalid cursor state
512 | 25000 | 25000 | Invalid transaction state
513 | 25S01 | 25S01 | Transaction state unknown
514 | 34000 | 34000 | Invalid cursor name
515 | S1000 | HY000 | General driver defined error
516 | S1001 | HY001 | Memory allocation error
517 | S1002 | HY002 | Invalid column number
518 | S1003 | HY003 | Invalid application buffer type
519 | S1004 | HY004 | Invalid SQL data type
520 | S1009 | HY009 | Invalid use of null pointer
521 | S1010 | HY010 | Function sequence error
522 | S1011 | HY011 | Attribute can not be set now
523 | S1012 | HY012 | Invalid transaction operation code
524 | S1013 | HY013 | Memory management error
525 | S1015 | HY015 | No cursor name available
526 | S1024 | HY024 | Invalid attribute value
527 | S1090 | HY090 | Invalid string or buffer length
528 | S1091 | HY091 | Invalid descriptor field identifier
529 | S1092 | HY092 | Invalid attribute/option identifier
530 | S1093 | HY093 | Invalid parameter number
531 | S1095 | HY095 | Function type out of range
532 | S1106 | HY106 | Fetch type out of range
533 | S1117 | HY117 | Row value out of range
534 | S1109 | HY109 | Invalid cursor position
535 | S1C00 | HYC00 | Optional feature not implemented
0 | 21S01 | 21S01 | Column count does not match value count
0 | 23000 | 23000 | Integrity constraint violation
0 | 42000 | 42000 | Syntax error or access violation
0 | 42S02 | 42S02 | Base table or view not found
0 | 42S12 | 42S12 | Index not found
0 | 42S21 | 42S21 | Column already exists
0 | 42S22 | 42S22 | Column not found
0 | 08S01 | 08S01 | Communication link failure

### 18.1.6. Connector/ODBC Notes and Tips

Here are some common notes and tips for using Connector/ODBC within different environments, applications and tools. The notes provided here are based on the experiences of Connector/ODBC developers and users.

#### 18.1.6.1. Connector/ODBC General Functionality

This section provides help with common queries and areas of functionality in MySQL and how to use them with Connector/ODBC.

##### 18.1.6.1.1. Obtaining Auto-Increment Values

Obtaining the value of column that uses `AUTO_INCREMENT` after an `INSERT` statement can be achieved in a number of different ways. To obtain the value immediately after an `INSERT`, use a `SELECT` query with the `LAST_INSERT_ID()` function.

For example, using Connector/ODBC you would execute two separate statements, the `INSERT` statement and the `SELECT` query to obtain the auto-increment value.

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

If you do not require the value within your application, but do require the value as part of another `INSERT`, the entire process can be handled by executing the following statements:

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

Certain ODBC applications (including Delphi and Access) may have trouble obtaining the auto-increment value using the previous examples. In this case, try the following statement as an alternative:

    SELECT * FROM tbl WHERE auto IS NULL;

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

##### 18.1.6.1.2. Dynamic Cursor Support

Support for the `dynamic cursor` is provided in Connector/ODBC 3.51, but dynamic cursors are not enabled by default. You can enable this function within Windows by selecting the `Enable Dynamic Cursor` checkbox within the ODBC Data Source Administrator.

On other platforms, you can enable the dynamic cursor by adding `32` to the `OPTION` value when creating the DSN.

##### 18.1.6.1.3. Connector/ODBC Performance

The Connector/ODBC driver has been optimized to provide very fast performance. If you experience problems with the performance of Connector/ODBC, or notice a large amount of disk activity for simple queries, there are a number of aspects you should check:

- Ensure that `ODBC Tracing` is not enabled. With tracing enabled, a lot of information is recorded in the tracing file by the ODBC Manager. You can check, and disable, tracing within Windows using the Tracing panel of the ODBC Data Source Administrator. Within Mac OS X, check the Tracing panel of ODBC Administrator. See Section 18.1.3.8, “Getting an ODBC Trace File”.

- Make sure you are using the standard version of the driver, and not the debug version. The debug version includes additional checks and reporting measures.

- Disable the Connector/ODBC driver trace and query logs. These options are enabled for each DSN, so make sure to examine only the DSN that you are using in your application. Within Windows, you can disable the Connector/ODBC and query logs by modifying the DSN configuration. Within Mac OS X and Unix, ensure that the driver trace (option value 4) and query logging (option value 524288) are not enabled.

##### 18.1.6.1.4. Setting ODBC Query Timeout in Windows

For more information on how to set the query timeout on Microsoft Windows when executing queries through an ODBC connection, read the Microsoft knowledgebase document at http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B153756.

#### 18.1.6.2. Connector/ODBC Application Specific Tips

Most programs should work with Connector/ODBC, but for each of those listed here, there are specific notes and tips to improve or enhance the way you work with Connector/ODBC and these applications.

With all applications you should ensure that you are using the latest Connector/ODBC drivers, ODBC Manager and any supporting libraries and interfaces used by your application. For example, on Windows, using the latest version of Microsoft Data Access Components (MDAC) will improve the compatibility with ODBC in general, and with the Connector/ODBC driver.

##### 18.1.6.2.1. Using Connector/ODBC with Microsoft Applications

The majority of Microsoft applications have been tested with Connector/ODBC, including Microsoft Office, Microsoft Access and the various programming languages supported within ASP and Microsoft Visual Studio.

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

###### 18.1.6.2.1.1. Microsoft Access

To improve the integration between Microsoft Access and MySQL through Connector/ODBC:

- For all versions of Access, you should enable the Connector/ODBC `Return matching rows` option. For Access 2.0, you should additionally enable the `Simulate ODBC 1.0` option.

- You should have a `TIMESTAMP` column in all tables that you want to be able to update. For maximum portability, don't use a length specification in the column declaration (which is unsupported within MySQL in versions earlier than 4.1).

- You should have a primary key in each MySQL table you want to use with Access. If not, new or updated rows may show up as `#DELETED#`.

- Use only `DOUBLE` float fields. Access fails when comparing with single-precision 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 Connector/ODBC 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 may 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 SQL statements that MySQL can't understand. You can fix this by selecting `"Query|SQLSpecific|Pass-Through"` from the Access menu.

- On Windows 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 the MySQL `DATE` column 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.

- 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`).

Some external articles and tips that may be useful when using Access, ODBC and Connector/ODBC:

- Read How to Trap ODBC Login Error Messages in Access

- Optimizing Access ODBC Applications

  - Optimizing for Client/Server Performance

  - Tips for Converting Applications to Using ODBCDirect

  - Tips for Optimizing Queries on Attached SQL Tables

- For a list of tools that can be used with Access and ODBC data sources, refer to converters section for list of available tools.

###### 18.1.6.2.1.2. Microsoft Excel and Column Types

If you have problems importing data into Microsoft Excel, particularly numerical, date, and time values, this is probably because of a bug in Excel, where the column type of the source data is used to determine the data type when that data is inserted into a cell within the worksheet. The result is that Excel incorrectly identifies the content and this affects both the display format and the data when it is used within calculations.

To address this issue, use the `CONCAT()` function in your queries. The use of `CONCAT()` forces Excel to treat the value as a string, which Excel will then parse and usually correctly identify the embedded information.

However, even with this option, some data may be incorrectly formatted, even though the source data remains unchanged. Use the `Format Cells` option within Excel to change the format of the displayed information.

###### 18.1.6.2.1.3. Microsoft 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 Connector/ODBC connect screen. You may also want to select the `Return matching rows` option.

###### 18.1.6.2.1.4. Microsoft Visual InterDev

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 Connector/ODBC connect screen.

###### 18.1.6.2.1.5. Visual Objects

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

###### 18.1.6.2.1.6. Microsoft ADO

When you are coding with the ADO API and Connector/ODBC, 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.

To find the number of rows affected by a specific SQL statement in ADO, use the `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.

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

###### 18.1.6.2.1.7. Using Connector/ODBC with Active Server Pages (ASP)

You should select the `Return matching rows` option in the DSN.

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

- Using MyODBC To Access Your MySQL Database Via ASP

- ASP and MySQL at DWAM.NT

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

###### 18.1.6.2.1.8. Using Connector/ODBC with Visual Basic (ADO, DAO and RDO) and ASP

Some articles that may help with Visual Basic and ASP:

- MySQL BLOB columns and Visual Basic 6 by Mike Hillyer (`<mike@openwin.org>`).

- How to map Visual basic data type to MySQL types by Mike Hillyer (`<mike@openwin.org>`).

##### 18.1.6.2.2. Using Connector/ODBC with Borland Applications

With all Borland applications where the Borland Database Engine (BDE) is used, follow these steps to improve compatibility:

- Update to BDE 3.2 or newer.

- Enable the `Don't optimize column widths` option in the DSN.

- Enabled the `Return matching rows` option in the DSN.

###### 18.1.6.2.2.1. Using Connector/ODBC with 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.

###### 18.1.6.2.2.2. Using Connector/ODBC with Delphi

Also, here is some potentially useful Delphi code that sets up both an ODBC entry and a BDE entry for Connector/ODBC. The BDE entry requires a BDE Alias Editor that is free at a Delphi Super Page near you. (Thanks to Bryan Brunton `<bryan@flesherfab.com>` 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);

###### 18.1.6.2.2.3. Using Connector/ODBC with C++ Builder

Tested with BDE 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`, although this has not been a problem.

##### 18.1.6.2.3. Using Connector/ODBC with ColdFusion

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 Connector/ODBC 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 Connector/ODBC 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 data sources drop-down list, you must build and copy the Connector/ODBC 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 Connector/ODBC driver on ColdFusion applications.

For more information and guides on using ColdFusion and Connector/ODBC, see the following external sites:

- Troubleshooting Data Sources and Database Connectivity for Unix Platforms.

##### 18.1.6.2.4. Using Connector/ODBC with OpenOffice

Open Office (http://www.openoffice.org) How-to: MySQL + OpenOffice. How-to: OpenOffice + MyODBC + unixODBC.

##### 18.1.6.2.5. Using Connector/ODBC with Sambar Server

Sambar Server (http://www.sambarserver.info) How-to: MyODBC + SambarServer + MySQL.

##### 18.1.6.2.6. Using Connector/ODBC with Pervasive Software DataJunction

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

##### 18.1.6.2.7. Using Connector/ODBC with SunSystems Vision

You should select the `Return matching rows` option.

#### 18.1.6.3. Connector/ODBC Errors and Resolutions

The following section details some common errors and their suggested fix or alternative solution. If you are still experiencing problems, use the Connector/ODBC mailing list; see Section 18.1.7.1, “Connector/ODBC Community Support”.

Many problems can be resolved by upgrading your Connector/ODBC drivers to the latest available release. On Windows, you should also make sure that you have the latest versions of the Microsoft Data Access Components (MDAC) installed.

Questions

- 19.1.6.3.1: Are MyODBC 2.50 applications compatible with Connector/ODBC 3.51?

- 19.1.6.3.2: I have installed Connector/ODBC on Windows XP x64 Edition or Windows Server 2003 R2 x64. The installation completed successfully, but the Connector/ODBC driver does not appear in `ODBC Data Source Administrator`.

- 19.1.6.3.3: When connecting or using the Test button in `ODBC Data Source Administrator` I get error 10061 (Cannot connect to server)

- 19.1.6.3.4: The following error is reported when using transactions: `Transactions are not enabled`

- 19.1.6.3.5: The following error is reported when I submit a query: `Cursor not found`

- 19.1.6.3.6: Access reports records as `#DELETED#` when inserting or updating records in linked tables.

- 19.1.6.3.7: How do I handle Write Conflicts or Row Location errors?

- 19.1.6.3.8: Exporting data from Access 97 to MySQL reports a `Syntax Error`.

- 19.1.6.3.9: Exporting data from Microsoft DTS to MySQL reports a `Syntax Error`.

- 19.1.6.3.10: Using ODBC.NET with Connector/ODBC, while fetching empty string (0 length), it starts giving the SQL_NO_DATA exception.

- 19.1.6.3.11: Using `SELECT COUNT(*) FROM `tbl_name`` within Visual Basic and ASP returns an error.

- 19.1.6.3.12: Using the `AppendChunk()` or `GetChunk()` ADO methods, the `Multiple-step operation generated errors. Check each status value` error is returned.

- 19.1.6.3.13: Access Returns `Another user had modified the record that you have modified` while editing records on a Linked Table.

- 19.1.6.3.14: When linking an application directly to the Connector/ODBC library under Unix/Linux, the application crashes.

- 19.1.6.3.15: Applications in the Microsoft Office suite are unable to update tables that have `DATE` or `TIMESTAMP` columns.

Questions and Answers

19.1.6.3.1: Are MyODBC 2.50 applications compatible with Connector/ODBC 3.51?

Applications based on MyODBC 2.50 should work fine with Connector/ODBC 3.51 and later versions. If you find something is not working with the latest version of Connector/ODBC which previously worked under an earlier version, please file a bug report. See Section 18.1.7.2, “How to Report Connector/ODBC Problems or Bugs”.

19.1.6.3.2: I have installed Connector/ODBC on Windows XP x64 Edition or Windows Server 2003 R2 x64. The installation completed successfully, but the Connector/ODBC driver does not appear in `ODBC Data Source Administrator`.

This is not a bug, but is related to the way Windows x64 editions operate with the ODBC driver. On Windows x64 editions, the Connector/ODBC driver is installed in the `%SystemRoot%\SysWOW64` folder. However, the default `ODBC Data Source Administrator` that is available through the `Administrative Tools` or `Control Panel` in Windows x64 Editions is located in the `%SystemRoot%\system32` folder, and only searches this folder for ODBC drivers.

On Windowx x64 editions, you should use the ODBC administration tool located at `%SystemRoot%\SysWOW64\odbcad32.exe`, this will correctly locate the installed Connector/ODBC drivers and enable you to create a Connector/ODBC DSN.

This issue was originally reported as Bug#20301.

19.1.6.3.3: When connecting or using the Test button in `ODBC Data Source Administrator` I get error 10061 (Cannot connect to server)

This error can be raised by a number of different issues, including server problems, network problems, and firewall and port blocking problems. For more information, see Section A.2.2, “`Can't connect to [local] MySQL server`”.

19.1.6.3.4: The following error is reported when using transactions: `Transactions are not enabled`

This error indicates that you are trying to use transactions with a MySQL table that does not support transactions. Transactions are supported within MySQL when using the `InnoDB` database engine. In versions of MySQL before Mysql 5.1 you may also use the `BDB` engine.

You should check the following before continuing:

- Verify that your MySQL server supports a transactional database engine. Use `SHOW ENGINES` to obtain a list of the available engine types.

- Verify that the tables you are updating use a transaction database engine.

- Ensure that you have not enabled the `disable transactions` option in your DSN.

19.1.6.3.5: The following error is reported when I submit a query: `Cursor not found`

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

19.1.6.3.6: Access reports records as `#DELETED#` when inserting or updating records in linked tables.

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 or higher and MySQL 3.23.x or higher, 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 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 Connector/ODBC `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.

- 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-precision 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 Connector/ODBC 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.

19.1.6.3.7: 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.

19.1.6.3.8: Exporting data from Access 97 to MySQL reports a `Syntax Error`.

This error is specific to Access 97 and versions of Connector/ODBC earlier than 3.51.02. Update to the latest version of the Connector/ODBC driver to resolve this problem.

19.1.6.3.9: Exporting data from Microsoft DTS to MySQL reports a `Syntax Error`.

This error occurs only with MySQL tables using the `TEXT` or `VARCHAR` data types. You can fix this error by upgrading your Connector/ODBC driver to version 3.51.02 or higher.

19.1.6.3.10: Using ODBC.NET with Connector/ODBC, while fetching empty string (0 length), it starts giving the SQL_NO_DATA exception.

You can get the patch that addresses this problem from http://support.microsoft.com/default.aspx?scid=kb;EN-US;q319243.

19.1.6.3.11: Using `SELECT COUNT(*) FROM `tbl_name`` within Visual Basic and ASP returns an error.

This error occurs 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).

19.1.6.3.12: Using the `AppendChunk()` or `GetChunk()` ADO methods, the `Multiple-step operation generated errors. Check each status value` error is returned.

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

19.1.6.3.13: Access Returns `Another user had modified the record that you have modified` while editing records on a Linked Table.

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-precision float fields. Some programs may fail when they compare single-precision 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 Connector/ODBC log to help you figure out why things go wrong. For instructions, see Section 18.1.3.8, “Getting an ODBC Trace File”.

19.1.6.3.14: When linking an application directly to the Connector/ODBC library under Unix/Linux, the application crashes.

Connector/ODBC 3.51 under Unix/Linux is not compatible with direct application linking. You must use a driver manager, such as iODBC or unixODBC to connect to an ODBC source.

19.1.6.3.15: Applications in the Microsoft Office suite are unable to update tables that have `DATE` or `TIMESTAMP` columns.

This is a known issue with Connector/ODBC. You must ensure that the field has a default value (rather than `NULL` and that the default value is non-zeo (i.e. the default value is not `0000-00-00 00:00:00`).

### 18.1.7. Connector/ODBC Support

There are many different places where you can get support for using Connector/ODBC. You should always try the Connector/ODBC Mailing List or Connector/ODBC Forum. See Section 18.1.7.1, “Connector/ODBC Community Support”, for help before reporting a specific bug or issue to MySQL.

#### 18.1.7.1. Connector/ODBC Community Support

MySQL AB provides assistance to the user community by means of its mailing lists. For Connector/ODBC-related issues, you can get help from experienced users by using the `<myodbc@lists.mysql.com>` mailing list. Archives are available online at http://lists.mysql.com/myodbc.

For information about subscribing to MySQL mailing lists or to browse list archives, visit http://lists.mysql.com/. See Section 1.7.1, “MySQL Mailing Lists”.

Community support from experienced users is also available through the ODBC Forum. You may also find help from other users in the other MySQL Forums, located at http://forums.mysql.com. See Section 1.7.2, “MySQL Community Support at the MySQL Forums”.

#### 18.1.7.2. How to Report Connector/ODBC Problems or Bugs

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

Check the Connector/ODBC 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 Connector/ODBC 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, “MySQL Mailing Lists”. Please never send the whole Connector/ODBC or ODBC log file!

You should ideally include the following information with the email:

- Operating system and version

- Connector/ODBC version

- ODBC Driver Manager type and version

- MySQL server version

- ODBC trace from Driver Manager

- Connector/ODBC log file from Connector/ODBC 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/myodbc.

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 Connector/ODBC 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 MySQL engineers have 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 another SQL server, you should include an ODBC log file where you perform exactly the same SQL statements so that we can compare the results between the two systems.

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

#### 18.1.7.3. How to Submit a Connector/ODBC Patch

You can send a patch or suggest a better solution for any existing code or problems by sending a mail message to `<myodbc@lists.mysql.com>`.

#### 18.1.7.4. Connector/ODBC Change History

The Connector/ODBC Change History (Changelog) is located with the main Changelog for MySQL. See Section D.6, “MySQL Connector/ODBC (MyODBC) Change History”.

#### 18.1.7.5. Credits

These are the developers that have worked on the Connector/ODBC and Connector/ODBC 3.51 Drivers from MySQL AB.

- Michael (Monty) Widenius

- Venu Anuganti

- Peter Harvey

## 18.2. MySQL Connector/NET

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. Connector/NET is a fully managed ADO.NET driver written in 100% pure C#.

Connector/NET includes full support for:

- MySQL 5.0 features (such as stored procedures)

- MySQL 4.1 features (server-side prepared statements, Unicode, and shared memory access, and so forth)

- 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.

This document is intended as a user's guide to Connector/NET and includes a full syntax reference. Syntax information is also included within the `Documentation.chm` file included with the Connector/NET distribution.

If you are using MySQL 5.0 or later, and Visual Studio as your development environment, you may want also want to use the MySQL Visual Studio Plugin. The plugin acts as a DDEX (Data Designer Extensibility) provider, enabling you to use the data design tools within Visual Studio to manipulate the schema and objects within a MySQL database. For more information, see Section 18.3, “MySQL Visual Studio Plugin”.

### 18.2.1. Connector/NET Versions

There is currently one version of Connector/NET available:

- Connector/NET 1.0 includes support for MySQL 4.0, and MySQL 5.0 features, and full compatibility with the ADO.NET driver interface.

### Note

Version numbers for MySQL products are formatted as X.X.X. However, Windows tools (Control Panel, properties display) may show the version numbers as XX.XX.XX. For example, the official MySQL formatted version number 5.0.9 may be displayed by Windows tools as 5.00.09. The two versions are the same; only the number display format is different.

### 18.2.2. Connector/NET Installation

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 (see http://www.mono-project.com).

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

#### 18.2.2.1. Installing Connector/NET on Windows

On Windows, installation is supported either through a binary installation process or by downloading a Zip file with the Connector/NET components.

Before installing, you should ensure that your system is up to date, including installing the latest version of the .NET Framework.

##### 18.2.2.1.1. Installing Connector/NET using the Installer

Using the installer is the most straightforward method of installing Connector/NET on Windows and the installed components include the source code, test code and full reference documentation.

Connector/NET is installed through the use of a Windows Installer (`.msi`) installation package, which can be used to install 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 Connector/NET version.

To install Connector/NET:

1. Double click on the MSI installer file extracted from the Zip you downloaded. Click Next to start the installation.

2. You must choose the type of installation that you want to perform.

   For most situations, the Typical installation will be suitable. Click the Typical button and proceed to Step 5. A Complete installation installs all the available files. To conduct a Complete installation, click the Complete button and proceed to step 5. If you want to customize your installation, including choosing the components to install and some installation options, click the Custom button and proceed to Step 3.

   The Connector/NET installer will register the connector within the Global Assembly Cache (GAC) - this will make the Connector/NET component available to all applications, not just those where you explicitly reference the Connector/NET component. The installer will also create the necessary links in the Start menu to the documentation and release notes.

3. If you have chosen a custom installation, you can select the individual components that you want to install, including the core interface component, supporting documentation (a CHM file) samples and examples and the source code. Select the items, and their installation level, and then click Next to continue the installation.

   ### Note

   For Connector/NET 1.0.8 or lower and Connector 5.0.4 and lower the installer will attempt to install binaries for both 1.x and 2.x of the .NET Framework. If you only have one version of the framework installed, the connector installation may fail. If this happens, you can choose the framework version to be installed through the custom installation step.

4. You will be given a final opportunity to confirm the installation. Click Install to copy and install the files onto your machine.

5. Once the installation has been completed, click Finish to exit the installer.

Unless you choose otherwise, 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 Connector/NET you are installing. New installations do not overwrite existing versions of Connector/NET.

Depending on your installation type, the installed components will include some or all of the following components:

- `bin` - Connector/NET MySQL libraries for different versions of the .NET environment.

- `docs` - contains a CHM of the Connector/NET documentation.

- `samples` - sample code and applications that use the Connector/NET component.

- `src` - the source code for the Connector/NET component.

You may also use the `/quiet` or `/q` command line option with the `msiexec` tool to install the Connector/NET package automatically (using the default options) with no notification to the user. Using this option you cannot select options and no prompts, messages or dialog boxes will be displayed.

    C:\> msiexec /package conector-net.msi /quiet

To provide a progress bar to the user during automatic installation, but still without presenting the user with a dialog box of the ability to select options, use the `/passive` option.

##### 18.2.2.1.2. Installing Connector/NET using the Zip package

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`. Once downloaded, you can extract the files to a location of your choice.

The .zip file contains the following directories:

- `bin` - Connector/NET MySQL libraries for different versions of the .NET environment.

- `doc` - contains a CHM of the Connector/NET documentation.

- `Samples` - sample code and applications that use the Connector/NET component.

- `mysqlclient` - the source code for the Connector/NET component.

- `testsuite` - the test suite used to verify the operation of the Connector/NET component.

#### 18.2.2.2. Installing Connector/NET on Unix with Mono

There is no installer available for installing the Connector/NET component on your Unix installation. However, the installation is very simple. Before installing, please ensure that you have a working Mono project installation.

Note that you should only install the Connector/NET component on Unix environments where you want to connect to a MySQL server through the Mono project. If you are deploying or developing on a different environment such as Java or Perl then you should use a more appropriate connectivity component. See the Chapter 18, Connectors, or Chapter 17, APIs and Libraries, for more information.

To install Connector/NET on Unix/Mono:

1. Download the `mysql-connector-net-`version`-noinstall.zip` and extract the contents.

2. Copy the `MySql.Data.dll` file to your Mono project installation folder.

3. You must register the Connector/NET component in the Global Assembly Cache using the `gacutil` command:

       shell> gacutil /i MySql.Data.dll

Once installed, applications that are compiled with the Connector/NET component need no further changes. However, you must ensure that when you compile your applications you include the Connector/NET component using the `-r:MySqlData.dll` command line option.

#### 18.2.2.3. Installing Connector/NET using the Source

Caution: You should read this section only if you are interested in helping us test our new code. If you just want to get Connector/NET up and running on your system, you should use a standard release distribution.

To be able to access the Connector/NET source tree, you must have Subversion installed. Subversion is freely available from http://subversion.tigris.org/.

The most recent development source tree is available from our public Subversion trees at http://dev.mysql.com/tech-resources/sources.html.

To checkout out the Connector/NET sources, change to the directory where you want the copy of the Connector/NET tree to be stored, then use the following command:

    shell> svn co
    http://svn.mysql.com/svnpublic/connector-net

A Visual Studio project is included in the source which you can use to build Connector/NET.

### 18.2.3. Connector/NET Examples

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 Connector/NET:

- `MySqlCommand`: Represents an 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 an SQL transaction to be made in a MySQL database.

This section contains basic information and examples for each of the above classes. For a more detailed reference guide please see Section 18.2.4, “Connector/NET Reference”.

#### 18.2.3.1. MySqlCommand

Represents a SQL statement to execute against a MySQL database. This class cannot be inherited.

`MySqlCommand` features the following methods for executing commands at a MySQL database:

Item | Description
ExecuteReader | Executes commands that return rows.
ExecuteNonQuery | Executes commands such as SQL INSERT, DELETE, and UPDATE statements.
ExecuteScalar | Retrieves a single value (for example, an aggregate value) from a database.

You can reset the `CommandText` property and reuse the `MySqlCommand` object. However, you must close the MySqlDataReader before you can execute a new or previous command.

If a MySqlException is generated by the method executing a `MySqlCommand`, the MySqlConnection remains open. It is the responsibility of the programmer to close the connection.

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' on your connection string. If you do this, please be aware that an exception will not be throw if you fail to define a parameter that you intended to use in your SQL.

Examples

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.

Visual Basic example:

      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

C# example:

      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();
    }

##### 18.2.3.1.1. Class MySqlCommand Constructor Form 1

Overload methods for MySqlCommand

Initializes a new instance of the MySqlCommand class.

Examples

The following example creates a MySqlCommand and sets some of its properties.

Note. This example shows how to use one of the overloaded versions of the MySqlCommand constructor. For other examples that might be available, see the individual overload topics.

Visual Basic example:

      Public Sub CreateMySqlCommand()
        Dim myConnection As New MySqlConnection _
            ("Persist Security Info=False;database=test;server=myServer")
        myConnection.Open()
        Dim myTrans As MySqlTransaction = myConnection.BeginTransaction()
        Dim mySelectQuery As String = "SELECT * FROM MyTable"
        Dim myCommand As New MySqlCommand(mySelectQuery, myConnection, myTrans)
        myCommand.CommandTimeout = 20
      End Sub

C# example:

      public void CreateMySqlCommand()
      {
        MySqlConnection myConnection = new MySqlConnection("Persist Security Info=False;
          database=test;server=myServer");
        myConnection.Open();
        MySqlTransaction myTrans = myConnection.BeginTransaction();
        string mySelectQuery = "SELECT * FROM myTable";
        MySqlCommand myCommand = new MySqlCommand(mySelectQuery, myConnection,myTrans);
        myCommand.CommandTimeout = 20;
      }

C++ example:

      public:
      void CreateMySqlCommand()
      {
        MySqlConnection* myConnection = new MySqlConnection(S"Persist Security Info=False;
          database=test;server=myServer");
        myConnection-&gt;Open();
        MySqlTransaction* myTrans = myConnection-&gt;BeginTransaction();
        String* mySelectQuery = S"SELECT * FROM myTable";
        MySqlCommand* myCommand = new MySqlCommand(mySelectQuery, myConnection, myTrans);
        myCommand-&gt;CommandTimeout = 20;
      };

Initializes a new instance of the MySqlCommand class.

The base constructor initializes all fields to their default values. The following table shows initial property values for an instance of `MySqlCommand`.

Properties | Initial Value
`CommandText` | empty string ("")
`CommandTimeout` | 0
`CommandType` | CommandType.Text
`Connection` | Null

You can change the value for any of these properties through a separate call to the property.

Examples

The following example creates a `MySqlCommand` and sets some of its properties.

Visual Basic example:

    Public Sub CreateMySqlCommand()
        Dim myCommand As New MySqlCommand()
        myCommand.CommandType = CommandType.Text
    End Sub

C# example:

    public void CreateMySqlCommand()
    {
       MySqlCommand myCommand = new MySqlCommand();
       myCommand.CommandType = CommandType.Text;
    }

##### 18.2.3.1.2. Class MySqlCommand Constructor Form 2

Initializes a new instance of the `MySqlCommand` class with the text of the query.

Parameters: The text of the query.

When an instance of `MySqlCommand` is created, the following read/write properties are set to initial values.

Properties | Initial Value
`CommandText` | `cmdText`
`CommandTimeout` | 0
`CommandType` | CommandType.Text
`Connection` | Null

You can change the value for any of these properties through a separate call to the property.

Examples

The following example creates a `MySqlCommand` and sets some of its properties.

Visual Basic example:

    Public Sub CreateMySqlCommand()
      Dim sql as String = "SELECT * FROM mytable"
        Dim myCommand As New MySqlCommand(sql)
        myCommand.CommandType = CommandType.Text
    End Sub

C# example:

    public void CreateMySqlCommand()
    {
      string sql = "SELECT * FROM mytable";
      MySqlCommand myCommand = new MySqlCommand(sql);
      myCommand.CommandType = CommandType.Text;
    }

##### 18.2.3.1.3. Class MySqlCommand Constructor Form 3

Initializes a new instance of the `MySqlCommand` class with the text of the query and a `MySqlConnection`.

Parameters: The text of the query.

Parameters: A `MySqlConnection` that represents the connection to an instance of SQL Server.

When an instance of `MySqlCommand` is created, the following read/write properties are set to initial values.

Properties | Initial Value
`CommandText` | `cmdText`
`CommandTimeout` | 0
`CommandType` | CommandType.Text
`Connection` | `connection`

You can change the value for any of these properties through a separate call to the property.

Examples

The following example creates a `MySqlCommand` and sets some of its properties.

Visual Basic example:

    Public Sub CreateMySqlCommand()
      Dim conn as new MySqlConnection("server=myServer")
      Dim sql as String = "SELECT * FROM mytable"
        Dim myCommand As New MySqlCommand(sql, conn)
        myCommand.CommandType = CommandType.Text
    End Sub

C# example:

    public void CreateMySqlCommand()
    {
      MySqlConnection conn = new MySqlConnection("server=myserver")
      string sql = "SELECT * FROM mytable";
      MySqlCommand myCommand = new MySqlCommand(sql, conn);
      myCommand.CommandType = CommandType.Text;
    }

##### 18.2.3.1.4. Class MySqlCommand Constructor Form 4

Initializes a new instance of the `MySqlCommand` class with the text of the query, a `MySqlConnection`, and the `MySqlTransaction`.

Parameters: The text of the query.

Parameters: A `MySqlConnection` that represents the connection to an instance of SQL Server.

Parameters: The `MySqlTransaction` in which the `MySqlCommand` executes.

When an instance of `MySqlCommand` is created, the following read/write properties are set to initial values.

Properties | Initial Value
`CommandText` | `cmdText`
`CommandTimeout` | 0
`CommandType` | CommandType.Text
`Connection` | `connection`

You can change the value for any of these properties through a separate call to the property.

Examples

The following example creates a `MySqlCommand` and sets some of its properties.

Visual Basic example:

    Public Sub CreateMySqlCommand()
      Dim conn as new MySqlConnection("server=myServer")
      conn.Open();
      Dim txn as MySqlTransaction = conn.BeginTransaction()
      Dim sql as String = "SELECT * FROM mytable"
        Dim myCommand As New MySqlCommand(sql, conn, txn)
        myCommand.CommandType = CommandType.Text
    End Sub

C# example:

    public void CreateMySqlCommand()
    {
      MySqlConnection conn = new MySqlConnection("server=myserver")
      conn.Open();
      MySqlTransaction txn = conn.BeginTransaction();
      string sql = "SELECT * FROM mytable";
      MySqlCommand myCommand = new MySqlCommand(sql, conn, txn);
      myCommand.CommandType = CommandType.Text;
    }

##### 18.2.3.1.5. ExecuteNonQuery

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

Returns: Number of rows affected

You can use ExecuteNonQuery to perform any type of database operation, however any resultsets returned will not be available. Any output parameters used in calling a stored procedure will be populated with data and can be retrieved after execution is complete. For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the command. For all other types of statements, the return value is -1.

Examples

The following example creates a MySqlCommand and then executes it using ExecuteNonQuery. The example is passed a string that is a SQL statement (such as UPDATE, INSERT, or DELETE) and a string to use to connect to the data source.

Visual Basic example:

        Public Sub CreateMySqlCommand(myExecuteQuery As String, myConnection As MySqlConnection)
          Dim myCommand As New MySqlCommand(myExecuteQuery, myConnection)
          myCommand.Connection.Open()
          myCommand.ExecuteNonQuery()
          myConnection.Close()
        End Sub

C# example:

        public void CreateMySqlCommand(string myExecuteQuery, MySqlConnection myConnection)
        {
          MySqlCommand myCommand = new MySqlCommand(myExecuteQuery, myConnection);
          myCommand.Connection.Open();
          myCommand.ExecuteNonQuery();
          myConnection.Close();
        }

##### 18.2.3.1.6. ExecuteReader1

Sends the `CommandText` to the `MySqlConnection`Connection, and builds a `MySqlDataReader` using one of the `CommandBehavior` values.

Parameters: One of the `CommandBehavior` values.

When the `CommandType` property is set to `StoredProcedure`, the `CommandText` property should be set to the name of the stored procedure. The command executes this stored procedure when you call `ExecuteReader`.

The `MySqlDataReader` supports a special mode that enables large binary values to be read efficiently. For more information, see the `SequentialAccess` setting for `CommandBehavior`.

While the `MySqlDataReader` is in use, the associated `MySqlConnection` is busy serving the `MySqlDataReader`. While in this state, no other operations can be performed on the `MySqlConnection` other than closing it. This is the case until the `MySqlDataReader.Close` method of the `MySqlDataReader` is called. If the `MySqlDataReader` is created with `CommandBehavior` set to `CloseConnection`, closing the `MySqlDataReader` closes the connection automatically.

Note. When calling ExecuteReader with the SingleRow behavior, you should be aware that using a `limit` clause in your SQL will cause all rows (up to the limit given) to be retrieved by the client. The `MySqlDataReader.Read` method will still return false after the first row but pulling all rows of data into the client will have a performance impact. If the `limit` clause is not necessary, it should be avoided.

Returns: A `MySqlDataReader` object.

##### 18.2.3.1.7. ExecuteReader

Sends the `CommandText` to the `MySqlConnection`Connection and builds a `MySqlDataReader`.

Returns: A `MySqlDataReader` object.

When the `CommandType` property is set to `StoredProcedure`, the `CommandText` property should be set to the name of the stored procedure. The command executes this stored procedure when you call `ExecuteReader`.

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

Examples

The following example creates a `MySqlCommand`, then executes it by passing a string that is a SQL `SELECT` statement, and a string to use to connect to the data source.

Visual Basic example:

    Public Sub CreateMySqlDataReader(mySelectQuery As String, myConnection As MySqlConnection)
        Dim myCommand As New MySqlCommand(mySelectQuery, myConnection)
        myConnection.Open()
        Dim myReader As MySqlDataReader
        myReader = myCommand.ExecuteReader()
        Try
        While myReader.Read()
            Console.WriteLine(myReader.GetString(0))
        End While
    Finally
        myReader.Close
        myConnection.Close
        End Try
    End Sub

C# example:

    public void CreateMySqlDataReader(string mySelectQuery, MySqlConnection myConnection)
     {
        MySqlCommand myCommand = new MySqlCommand(mySelectQuery, myConnection);
        myConnection.Open();
        MySqlDataReader myReader;
        myReader = myCommand.ExecuteReader();
        try
        {
          while(myReader.Read())
          {
            Console.WriteLine(myReader.GetString(0));
          }
        }
        finally
        {
          myReader.Close();
          myConnection.Close();
        }
     }

##### 18.2.3.1.8. Prepare

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

Prepared statements are only supported on MySQL version 4.1 and higher. Calling prepare while connected to earlier versions of MySQL will succeed but will execute the statement in the same way as unprepared.

Examples

The following example demonstrates the use of the `Prepare` method.

Visual Basic example:

      public sub PrepareExample()
        Dim cmd as New MySqlCommand("INSERT INTO mytable VALUES (?val)", myConnection)
        cmd.Parameters.Add( "?val", 10 )
        cmd.Prepare()
        cmd.ExecuteNonQuery()

        cmd.Parameters(0).Value = 20
        cmd.ExecuteNonQuery()
      end sub

C# example:

      private void PrepareExample()
      {
        MySqlCommand cmd = new MySqlCommand("INSERT INTO mytable VALUES (?val)", myConnection);
        cmd.Parameters.Add( "?val", 10 );
        cmd.Prepare();
        cmd.ExecuteNonQuery();

        cmd.Parameters[0].Value = 20;
        cmd.ExecuteNonQuery();
      }

##### 18.2.3.1.9. 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.

Returns: The first column of the first row in the result set, or a null reference if the result set is empty

Use the `ExecuteScalar` method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the `ExecuteReader` method, and then performing the operations necessary to generate the single value using the data returned by a `MySqlDataReader`

A typical `ExecuteScalar` query can be formatted as in the following C# example:

C# example:

    cmd.CommandText = "select count(*) from region";
    Int32 count = (int32) cmd.ExecuteScalar();

Examples

The following example creates a `MySqlCommand` and then executes it using `ExecuteScalar`. The example is passed a string that is a SQL statement that returns an aggregate result, and a string to use to connect to the data source.

Visual Basic example:

    Public Sub CreateMySqlCommand(myScalarQuery As String, myConnection As MySqlConnection)
        Dim myCommand As New MySqlCommand(myScalarQuery, myConnection)
        myCommand.Connection.Open()
        myCommand.ExecuteScalar()
        myConnection.Close()
    End Sub

C# example:

    public void CreateMySqlCommand(string myScalarQuery, MySqlConnection myConnection)
     {
        MySqlCommand myCommand = new MySqlCommand(myScalarQuery, myConnection);
        myCommand.Connection.Open();
        myCommand.ExecuteScalar();
        myConnection.Close();
     }

C++ example:

    public:
        void CreateMySqlCommand(String* myScalarQuery, MySqlConnection* myConnection)
        {
            MySqlCommand* myCommand = new MySqlCommand(myScalarQuery, myConnection);
            myCommand-&gt;Connection-&gt;Open();
            myCommand-&gt;ExecuteScalar();
            myConnection-&gt;Close();
        }

##### 18.2.3.1.10. CommandText

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

Value: The SQL statement or stored procedure to execute. The default is an empty string.

When the `CommandType` property is set to `StoredProcedure`, the `CommandText` property should be set to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command executes this stored procedure when you call one of the Execute methods.

Examples

The following example creates a `MySqlCommand` and sets some of its properties.

Visual Basic example:

    Public Sub CreateMySqlCommand()
        Dim myCommand As New MySqlCommand()
        myCommand.CommandText = "SELECT * FROM Mytable ORDER BY id"
        myCommand.CommandType = CommandType.Text
    End Sub

C# example:

    public void CreateMySqlCommand()
     {
        MySqlCommand myCommand = new MySqlCommand();
        myCommand.CommandText = "SELECT * FROM mytable ORDER BY id";
        myCommand.CommandType = CommandType.Text;
     }

##### 18.2.3.1.11. CommandTimeout

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

Value: The time (in seconds) to wait for the command to execute. The default is 0 seconds.

MySQL currently does not support any method of canceling a pending or executing operation. All commands issues against a MySQL server will execute until completion or exception occurs.

##### 18.2.3.1.12. CommandType

Gets or sets a value indicating how the `CommandText` property is to be interpreted.

Value: One of the `System.Data.CommandType` values. The default is `Text`.

When you set the `CommandType` property to `StoredProcedure`, you should set the `CommandText` property to the name of the stored procedure. The command executes this stored procedure when you call one of the Execute methods.

Examples

The following example creates a `MySqlCommand` and sets some of its properties.

Visual Basic example:

    Public Sub CreateMySqlCommand()
        Dim myCommand As New MySqlCommand()
        myCommand.CommandType = CommandType.Text
    End Sub

C# example:

    public void CreateMySqlCommand()
    {
       MySqlCommand myCommand = new MySqlCommand();
       myCommand.CommandType = CommandType.Text;
    }

##### 18.2.3.1.13. Connection

Gets or sets the `MySqlConnection` used by this instance of the `MySqlCommand`.

Value: The connection to a data source. The default value is a null reference (`Nothing` in Visual Basic).

If you set `Connection` while a transaction is in progress and the `Transaction` property is not null, an `InvalidOperationException` is generated. If the `Transaction` property is not null and the transaction has already been committed or rolled back, `Transaction` is set to null.

Examples

The following example creates a `MySqlCommand` and sets some of its properties.

Visual Basic example:

    Public Sub CreateMySqlCommand()
        Dim mySelectQuery As String = "SELECT * FROM mytable ORDER BY id"
        Dim myConnectString As String = "Persist Security Info=False;database=test;server=myServer"
        Dim myCommand As New MySqlCommand(mySelectQuery)
        myCommand.Connection = New MySqlConnection(myConnectString)
        myCommand.CommandType = CommandType.Text
    End Sub

C# example:

    public void CreateMySqlCommand()
     {
        string mySelectQuery = "SELECT * FROM mytable ORDER BY id";
        string myConnectString = "Persist Security Info=False;database=test;server=myServer";
        MySqlCommand myCommand = new MySqlCommand(mySelectQuery);
        myCommand.Connection = new MySqlConnection(myConnectString);
        myCommand.CommandType = CommandType.Text;
     }

##### 18.2.3.1.14. IsPrepared

Returns true if the statement is prepared.

##### 18.2.3.1.15. Parameters

Get the `MySqlParameterCollection`

Value: The parameters of the SQL statement or stored procedure. The default is an empty collection.

Connector/Net does not support unnamed parameters. Every parameter added to the collection must have an associated name.

Examples

The following example creates a `MySqlCommand` and displays its parameters. To accomplish this, the method is passed a `MySqlConnection`, a query string that is a SQL `SELECT` statement, and an array of `MySqlParameter` objects.

Visual Basic example:

    Public Sub CreateMySqlCommand(myConnection As MySqlConnection, _
    mySelectQuery As String, myParamArray() As MySqlParameter)
        Dim myCommand As New MySqlCommand(mySelectQuery, myConnection)
        myCommand.CommandText = "SELECT id, name FROM mytable WHERE age=?age"
        myCommand.UpdatedRowSource = UpdateRowSource.Both
        myCommand.Parameters.Add(myParamArray)
        Dim j As Integer
        For j = 0 To myCommand.Parameters.Count - 1
           myCommand.Parameters.Add(myParamArray(j))
        Next j
        Dim myMessage As String = ""
        Dim i As Integer
        For i = 0 To myCommand.Parameters.Count - 1
            myMessage += myCommand.Parameters(i).ToString() & ControlChars.Cr
        Next i
        Console.WriteLine(myMessage)
    End Sub

C# example:

    public void CreateMySqlCommand(MySqlConnection myConnection, string mySelectQuery,
      MySqlParameter[] myParamArray)
    {
       MySqlCommand myCommand = new MySqlCommand(mySelectQuery, myConnection);
       myCommand.CommandText = "SELECT id, name FROM mytable WHERE age=?age";
       myCommand.Parameters.Add(myParamArray);
       for (int j=0; j&lt;myParamArray.Length; j++)
       {
          myCommand.Parameters.Add(myParamArray[j]) ;
       }
       string myMessage = "";
       for (int i = 0; i &lt; myCommand.Parameters.Count; i++)
       {
          myMessage += myCommand.Parameters[i].ToString() + "\n";
       }
       MessageBox.Show(myMessage);
    }

##### 18.2.3.1.16. Transaction

Gets or sets the `MySqlTransaction` within which the `MySqlCommand` executes.

Value: The `MySqlTransaction`. The default value is a null reference (`Nothing` in Visual Basic).

You cannot set the `Transaction` property if it is already set to a specific value, and the command is in the process of executing. If you set the transaction property to a `MySqlTransaction` object that is not connected to the same `MySqlConnection` as the `MySqlCommand` object, an exception will be thrown the next time you attempt to execute a statement.

##### 18.2.3.1.17. UpdatedRowSource

Gets or sets how command results are applied to the `DataRow` when used by the `System.Data.Common.DbDataAdapter.Update` method of the `System.Data.Common.DbDataAdapter`.

Value: One of the `UpdateRowSource` values.

The default `System.Data.UpdateRowSource` value is `Both` unless the command is automatically generated (as in the case of the `MySqlCommandBuilder`), in which case the default is `None`.

#### 18.2.3.2. MySqlCommandBuilder

Automatically generates single-table commands used to reconcile changes made to a DataSet with the associated MySQL database. This class cannot be inherited.

The `MySqlDataAdapter` does not automatically generate the SQL statements required to reconcile changes made to a `System.Data.DataSet`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 `MySqlDataAdapter.SelectCommand`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 `MySqlDataAdapter.OnRowUpdating`RowUpdating 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 `MySqlCommand.Connection`Connection, `MySqlCommand.CommandTimeout`CommandTimeout, and `MySqlCommand.Transaction`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 `MySqlDataAdapter.InsertCommand`InsertCommand, `MySqlDataAdapter.UpdateCommand`UpdateCommand, and `MySqlDataAdapter.DeleteCommand`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.

Note. Caution must be used when using MySqlCOmmandBuilder on MySql 4.0 systems. With MySql 4.0, database/schema information is not provided to the connector for a query. This means that a query that pulls columns from two identically named tables in two or more different databases will not cause an exception to be thrown but will not work correctly. Even more dangerous is the situation where your select statement references database X but is executed in database Y and both databases have tables with similar layouts. This situation can cause unwanted changes or deletes. This note does not apply to MySQL versions 4.1 and later.

Examples

The following example uses the `MySqlCommand`, along `MySqlDataAdapter` and `MySqlConnection`, to select rows from a data source. The example is passed an initialized `System.Data.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`.

Visual Basic example:

      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

C# example:

      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;
      }

##### 18.2.3.2.1. Class MySqlCommandBuilder Constructor

Initializes a new instance of the `MySqlCommandBuilder` class.

##### 18.2.3.2.2. Class MySqlCommandBuilder Constructor Form 1

Initializes a new instance of the `MySqlCommandBuilder` class and sets the last one wins property.

Parameters: False to generate change protection code. True otherwise.

The `lastOneWins` parameter indicates whether SQL code should be included with the generated DELETE and UPDATE commands that checks the underlying data for changes. If `lastOneWins` is true then this code is not included and data records could be overwritten in a multi-user or multi-threaded environments. Setting `lastOneWins` to false will include this check which will cause a concurrency exception to be thrown if the underlying data record has changed without our knowledge.

##### 18.2.3.2.3. Class MySqlCommandBuilder Constructor Form 2

Initializes a new instance of the `MySqlCommandBuilder` class with the associated `MySqlDataAdapter` object.

Parameters: The `MySqlDataAdapter` to use.

The `MySqlCommandBuilder` registers itself as a listener for `MySqlDataAdapter.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.

##### 18.2.3.2.4. Class MySqlCommandBuilder Constructor Form 3

Initializes a new instance of the `MySqlCommandBuilder` class with the associated `MySqlDataAdapter` object.

Parameters: The `MySqlDataAdapter` to use.

Parameters: False to generate change protection code. True otherwise.

The `MySqlCommandBuilder` registers itself as a listener for `MySqlDataAdapter.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.

The `lastOneWins` parameter indicates whether SQL code should be included with the generated DELETE and UPDATE commands that checks the underlying data for changes. If `lastOneWins` is true then this code is not included and data records could be overwritten in a multi-user or multi-threaded environments. Setting `lastOneWins` to false will include this check which will cause a concurrency exception to be thrown if the underlying data record has changed without our knowledge.

##### 18.2.3.2.5. DataAdapter

Gets or sets a `MySqlDataAdapter` object for which SQL statements are automatically generated.

Value: A `MySqlDataAdapter` object.

The `MySqlCommandBuilder` registers itself as a listener for `MySqlDataAdapter.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.

##### 18.2.3.2.6. QuotePrefix

Gets or sets the beginning character or characters to use when specifying MySQL database objects (for example, tables or columns) whose names contain characters such as spaces or reserved tokens.

Value: The beginning character or characters to use. The default value is `.

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.

##### 18.2.3.2.7. QuoteSuffix

Gets or sets the beginning character or characters to use when specifying MySQL database objects (for example, tables or columns) whose names contain characters such as spaces or reserved tokens.

Value: The beginning character or characters to use. The default value is `.

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.

##### 18.2.3.2.8. DeriveParameters

##### 18.2.3.2.9. GetDeleteCommand

Gets the automatically generated `MySqlCommand` object required to perform deletions on the database.

Returns: The `MySqlCommand` object generated to handle delete operations.

An application can use the `GetDeleteCommand` method for informational or troubleshooting purposes because it returns the `MySqlCommand` object to be executed.

You can also use `GetDeleteCommand` as the basis of a modified command. For example, you might call `GetDeleteCommand` and modify the `MySqlCommand.CommandTimeout` value, and then explicitly set that on the `MySqlDataAdapter`.

After the SQL statement is first generated, the application must explicitly call `RefreshSchema` if it changes the statement in any way. Otherwise, the `GetDeleteCommand` will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls `System.Data.Common.DataAdapter.Update` or `GetDeleteCommand`.

##### 18.2.3.2.10. GetInsertCommand

Gets the automatically generated `MySqlCommand` object required to perform insertions on the database.

Returns: The `MySqlCommand` object generated to handle insert operations.

An application can use the `GetInsertCommand` method for informational or troubleshooting purposes because it returns the `MySqlCommand` object to be executed.

You can also use the `GetInsertCommand` as the basis of a modified command. For example, you might call `GetInsertCommand` and modify the `MySqlCommand.CommandTimeout` value, and then explicitly set that on the `MySqlDataAdapter`.

After the SQL statement is first generated, the application must explicitly call `RefreshSchema` if it changes the statement in any way. Otherwise, the `GetInsertCommand` will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls `System.Data.Common.DataAdapter.Update` or `GetInsertCommand`.

##### 18.2.3.2.11. GetUpdateCommand

Gets the automatically generated `MySqlCommand` object required to perform updates on the database.

Returns: The `MySqlCommand` object generated to handle update operations.

An application can use the `GetUpdateCommand` method for informational or troubleshooting purposes because it returns the `MySqlCommand` object to be executed.

You can also use `GetUpdateCommand` as the basis of a modified command. For example, you might call `GetUpdateCommand` and modify the `MySqlCommand.CommandTimeout` value, and then explicitly set that on the `MySqlDataAdapter`.

After the SQL statement is first generated, the application must explicitly call `RefreshSchema` if it changes the statement in any way. Otherwise, the `GetUpdateCommand` will be still be using information from the previous statement, which might not be correct. The SQL statements are first generated either when the application calls `System.Data.Common.DataAdapter.Update` or `GetUpdateCommand`.

##### 18.2.3.2.12. RefreshSchema

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

An application should call `RefreshSchema` whenever the `SELECT` statement associated with the `MySqlCommandBuilder` changes.

An application should call `RefreshSchema` whenever the `MySqlDataAdapter.SelectCommand` value of the `MySqlDataAdapter` changes.

#### 18.2.3.3. MySqlConnection

Represents an open connection to a MySQL Server database. This class cannot be inherited.

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 `MySqlConnection.Close` or `MySqlConnection.Dispose`.

Examples

The following example creates a `MySqlCommand` and a `MySqlConnection`. The `MySqlConnection` is opened and set as the `MySqlCommand.Connection` for the `MySqlCommand`. The example then calls `MySqlCommand.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.

Visual Basic example:

      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

C# example:

      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();
      }

##### 18.2.3.3.1. Class MySqlConnection Constructor (Default)

Initializes a new instance of the `MySqlConnection` class.

When a new instance of `MySqlConnection` is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the `ConnectionString` property.

Properties | Initial Value
`ConnectionString` | empty string ("")
`ConnectionTimeout` | 15
`Database` | empty string ("")
`DataSource` | empty string ("")
`ServerVersion` | empty string ("")

You can change the value for these properties only by using the `ConnectionString` property.

Examples

Overload methods for MySqlConnection

Initializes a new instance of the `MySqlConnection` class.

##### 18.2.3.3.2. Class MySqlConnection Constructor Form 1

Initializes a new instance of the `MySqlConnection` class when given a string containing the connection string.

When a new instance of `MySqlConnection` is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the `ConnectionString` property.

Properties | Initial Value
`ConnectionString` | empty string ("")
`ConnectionTimeout` | 15
`Database` | empty string ("")
`DataSource` | empty string ("")
`ServerVersion` | empty string ("")

You can change the value for these properties only by using the `ConnectionString` property.

Examples

Parameters: The connection properties used to open the MySQL database.

##### 18.2.3.3.3. Open

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

Exception: Cannot open a connection without specifying a data source or server.

Exception: A connection-level error occurred while opening the connection.

The `MySqlConnection` draws an open connection from the connection pool if one is available. Otherwise, it establishes a new connection to an instance of MySQL.

Examples

The following example creates a `MySqlConnection`, opens it, displays some of its properties, then closes the connection.

Visual Basic example:

    Public Sub CreateMySqlConnection(myConnString As String)
        Dim myConnection As New MySqlConnection(myConnString)
        myConnection.Open()
        MessageBox.Show("ServerVersion: " + myConnection.ServerVersion _
        + ControlChars.Cr + "State: " + myConnection.State.ToString())
        myConnection.Close()
    End Sub

C# example:

    public void CreateMySqlConnection(string myConnString)
    {
      MySqlConnection myConnection = new MySqlConnection(myConnString);
      myConnection.Open();
      MessageBox.Show("ServerVersion: " + myConnection.ServerVersion +
              "\nState: " + myConnection.State.ToString());
      myConnection.Close();
    }

##### 18.2.3.3.4. Database

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

Returns: The name of the current database or the name of the database to be used after a connection is opened. The default value is an empty string.

The `Database` property does not update dynamically. If you change the current database using a SQL statement, then this property may reflect the wrong value. If you change the current database using the `ChangeDatabase` method, this property is updated to reflect the new database.

Examples

The following example creates a `MySqlConnection` and displays some of its read-only properties.

Visual Basic example:

    Public Sub CreateMySqlConnection()
      Dim myConnString As String = _
        "Persist Security Info=False;database=test;server=localhost;user id=joeuser;pwd=pass"
      Dim myConnection As New MySqlConnection( myConnString )
      myConnection.Open()
      MessageBox.Show( "Server Version: " + myConnection.ServerVersion _
        + ControlChars.NewLine + "Database: " + myConnection.Database )
      myConnection.ChangeDatabase( "test2" )
      MessageBox.Show( "ServerVersion: " + myConnection.ServerVersion _
        + ControlChars.NewLine + "Database: " + myConnection.Database )
      myConnection.Close()
    End Sub

C# example:

    public void CreateMySqlConnection()
    {
      string myConnString =
        "Persist Security Info=False;database=test;server=localhost;user id=joeuser;pwd=pass";
      MySqlConnection myConnection = new MySqlConnection( myConnString );
      myConnection.Open();
      MessageBox.Show( "Server Version: " + myConnection.ServerVersion
        + "\nDatabase: " + myConnection.Database );
      myConnection.ChangeDatabase( "test2" );
      MessageBox.Show( "ServerVersion: " + myConnection.ServerVersion
        + "\nDatabase: " + myConnection.Database );
      myConnection.Close();
    }

##### 18.2.3.3.5. State

Gets the current state of the connection.

Returns: A bitwise combination of the `System.Data.ConnectionState` values. The default is `Closed`.

The allowed state changes are:

- From `Closed` to `Open`, using the `Open` method of the connection object.

- From `Open` to `Closed`, using either the `Close` method or the `Dispose` method of the connection object.

Examples

The following example creates a `MySqlConnection`, opens it, displays some of its properties, then closes the connection.

Visual Basic example:

    Public Sub CreateMySqlConnection(myConnString As String)
        Dim myConnection As New MySqlConnection(myConnString)
        myConnection.Open()
        MessageBox.Show("ServerVersion: " + myConnection.ServerVersion _
        + ControlChars.Cr + "State: " + myConnection.State.ToString())
        myConnection.Close()
    End Sub

C# example:

    public void CreateMySqlConnection(string myConnString)
    {
      MySqlConnection myConnection = new MySqlConnection(myConnString);
      myConnection.Open();
      MessageBox.Show("ServerVersion: " + myConnection.ServerVersion +
              "\nState: " + myConnection.State.ToString());
      myConnection.Close();
    }

##### 18.2.3.3.6. ServerVersion

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

Returns: The version of the instance of MySQL.

Exception: The connection is closed.

Examples

The following example creates a `MySqlConnection`, opens it, displays some of its properties, then closes the connection.

Visual Basic example:

    Public Sub CreateMySqlConnection(myConnString As String)
        Dim myConnection As New MySqlConnection(myConnString)
        myConnection.Open()
        MessageBox.Show("ServerVersion: " + myConnection.ServerVersion _
        + ControlChars.Cr + "State: " + myConnection.State.ToString())
        myConnection.Close()
    End Sub

C# example:

    public void CreateMySqlConnection(string myConnString)
    {
      MySqlConnection myConnection = new MySqlConnection(myConnString);
      myConnection.Open();
      MessageBox.Show("ServerVersion: " + myConnection.ServerVersion +
              "\nState: " + myConnection.State.ToString());
      myConnection.Close();
    }

##### 18.2.3.3.7. Close

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

The `Close` method rolls back any pending transactions. It then releases the connection to the connection pool, or closes the connection if connection pooling is disabled.

An application can call `Close` more than one time. No exception is generated.

Examples

The following example creates a `MySqlConnection`, opens it, displays some of its properties, then closes the connection.

Visual Basic example:

    Public Sub CreateMySqlConnection(myConnString As String)
        Dim myConnection As New MySqlConnection(myConnString)
        myConnection.Open()
        MessageBox.Show("ServerVersion: " + myConnection.ServerVersion _
        + ControlChars.Cr + "State: " + myConnection.State.ToString())
        myConnection.Close()
    End Sub

C# example:

    public void CreateMySqlConnection(string myConnString)
    {
      MySqlConnection myConnection = new MySqlConnection(myConnString);
      myConnection.Open();
      MessageBox.Show("ServerVersion: " + myConnection.ServerVersion +
              "\nState: " + myConnection.State.ToString());
      myConnection.Close();
    }

##### 18.2.3.3.8. CreateCommand

Creates and returns a `MySqlCommand` object associated with the `MySqlConnection`.

Returns: A `MySqlCommand` object.

##### 18.2.3.3.9. BeginTransaction

Begins a database transaction.

Returns: An object representing the new transaction.

Exception: Parallel transactions are not supported.

This command is equivalent to the MySQL BEGIN TRANSACTION command.

You must explicitly commit or roll back the transaction using the `MySqlTransaction.Commit` or `MySqlTransaction.Rollback` method.

Note. If you do not specify an isolation level, the default isolation level is used. To specify an isolation level with the `BeginTransaction` method, use the overload that takes the `iso` parameter.

Examples

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

Visual Basic example:

    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 Test (id, desc) VALUES (100, 'Description')"
          myCommand.ExecuteNonQuery()
          myCommand.CommandText = "Insert into Test (id, desc) 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

C# example:

    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 Test (id, desc) VALUES (100, 'Description')";
          myCommand.ExecuteNonQuery();
          myCommand.CommandText = "insert into Test (id, desc) VALUES (101, 'Description')";
          myCommand.ExecuteNonQuery();
          myTrans.Commit();
          Console.WriteLine("Both records are written to database.");
        }
        catch(Exception e)
        {
          try
          {
            myTrans.Rollback();
          }
          catch (SqlException 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();
        }
    }

##### 18.2.3.3.10. BeginTransaction1

Begins a database transaction with the specified isolation level.

Parameters: The isolation level under which the transaction should run.

Returns: An object representing the new transaction.

Exception: Parallel exceptions are not supported.

This command is equivalent to the MySQL BEGIN TRANSACTION command.

You must explicitly commit or roll back the transaction using the `MySqlTransaction.Commit` or `MySqlTransaction.Rollback` method.

Note. If you do not specify an isolation level, the default isolation level is used. To specify an isolation level with the `BeginTransaction` method, use the overload that takes the `iso` parameter.

Examples

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

Visual Basic example:

    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 Test (id, desc) VALUES (100, 'Description')"
          myCommand.ExecuteNonQuery()
          myCommand.CommandText = "Insert into Test (id, desc) 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

C# example:

    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 Test (id, desc) VALUES (100, 'Description')";
          myCommand.ExecuteNonQuery();
          myCommand.CommandText = "insert into Test (id, desc) VALUES (101, 'Description')";
          myCommand.ExecuteNonQuery();
          myTrans.Commit();
          Console.WriteLine("Both records are written to database.");
        }
        catch(Exception e)
        {
          try
          {
            myTrans.Rollback();
          }
          catch (SqlException 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();
        }
    }

##### 18.2.3.3.11. ChangeDatabase

Changes the current database for an open MySqlConnection.

Parameters: The name of the database to use.

The value supplied in the `database` parameter must be a valid database name. The `database` parameter cannot contain a null value, an empty string, or a string with only blank characters.

When you are using connection pooling against MySQL, and you close the connection, it is returned to the connection pool. The next time the connection is retrieved from the pool, the reset connection request executes before the user performs any operations.

Exception: The database name is not valid.

Exception: The connection is not open.

Exception: Cannot change the database.

Examples

The following example creates a `MySqlConnection` and displays some of its read-only properties.

Visual Basic example:

    Public Sub CreateMySqlConnection()
      Dim myConnString As String = _
        "Persist Security Info=False;database=test;server=localhost;user id=joeuser;pwd=pass"
      Dim myConnection As New MySqlConnection( myConnString )
      myConnection.Open()
      MessageBox.Show( "Server Version: " + myConnection.ServerVersion _
        + ControlChars.NewLine + "Database: " + myConnection.Database )
      myConnection.ChangeDatabase( "test2" )
      MessageBox.Show( "ServerVersion: " + myConnection.ServerVersion _
        + ControlChars.NewLine + "Database: " + myConnection.Database )
      myConnection.Close()
    End Sub

C# example:

    public void CreateMySqlConnection()
    {
      string myConnString =
        "Persist Security Info=False;database=test;server=localhost;user id=joeuser;pwd=pass";
      MySqlConnection myConnection = new MySqlConnection( myConnString );
      myConnection.Open();
      MessageBox.Show( "Server Version: " + myConnection.ServerVersion
        + "\nDatabase: " + myConnection.Database );
      myConnection.ChangeDatabase( "test2" );
      MessageBox.Show( "ServerVersion: " + myConnection.ServerVersion
        + "\nDatabase: " + myConnection.Database );
      myConnection.Close();
    }

##### 18.2.3.3.12. StateChange

Occurs when the state of the connection changes.

The `StateChange` event fires whenever the `State` changes from closed to opened, or from opened to closed. `StateChange` fires immediately after the `MySqlConnection` transitions.

If an event handler throws an exception from within the `StateChange` event, the exception propagates to the caller of the `Open` or `Close` method.

The `StateChange` event is not raised unless you explicitly call `Close` or `Dispose`.

The event handler receives an argument of type `System.Data.StateChangeEventArgs` containing data related to this event. The following `StateChangeEventArgs` properties provide information specific to this event.

Property | Description
`System.Data.StateChangeEventArgs.CurrentState` | Gets the new state of the connection. The connection object will be in the new state already when the event is fired.
`System.Data.StateChangeEventArgs.OriginalState` | Gets the original state of the connection.

##### 18.2.3.3.13. InfoMessage

Occurs when MySQL returns warnings as a result of executing a command or query.

##### 18.2.3.3.14. ConnectionTimeout

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

Exception: The value set is less than 0.

A value of 0 indicates no limit, and should be avoided in a `MySqlConnection.ConnectionString` because an attempt to connect will wait indefinitely.

Examples

The following example creates a MySqlConnection and sets some of its properties in the connection string.

Visual Basic example:

    Public Sub CreateSqlConnection()
      Dim myConnection As New MySqlConnection()
      myConnection.ConnectionString = "Persist Security Info=False;Username=user;Password=pass;database=test1;server=localhost;Connect Timeout=30"
      myConnection.Open()
    End Sub

C# example:

    public void CreateSqlConnection()
    {
      MySqlConnection myConnection = new MySqlConnection();
      myConnection.ConnectionString = "Persist Security Info=False;Username=user;Password=pass;database=test1;server=localhost;Connect Timeout=30";
      myConnection.Open();
    }

##### 18.2.3.3.15. ConnectionString

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

The `ConnectionString` returned may not be exactly like what was originally set but will be indentical in terms of keyword/value pairs. Security information will not be included unless the Persist Security Info value is set to true.

You can use the `ConnectionString` property to connect to a database. The following example illustrates a typical connection string.

    "Persist Security Info=False;database=MyDB;server=MySqlServer;user id=myUser;Password=myPass"

The `ConnectionString` property can be set only when the connection is closed. Many of the connection string values have corresponding read-only properties. When the connection string is set, all of these properties are updated, except when an error is detected. In this case, none of the properties are updated. `MySqlConnection` properties return only those settings contained in the `ConnectionString`.

To connect to a local machine, specify "localhost" for the server. If you do not specify a server, localhost is assumed.

Resetting the `ConnectionString` on a closed connection resets all connection string values (and related properties) including the password. For example, if you set a connection string that includes "Database= MyDb", and then reset the connection string to "Data Source=myserver;User Id=myUser;Password=myPass", the `MySqlConnection.Database` property is no longer set to MyDb.

The connection string is parsed immediately after being set. If errors in syntax are found when parsing, a runtime exception, such as `ArgumentException`, is generated. Other errors can be found only when an attempt is made to open the connection.

The basic format of a connection string consists of a series of keyword/value pairs separated by semicolons. The equal sign (=) connects each keyword and its value. To include values that contain a semicolon, single-quote character, or double-quote character, the value must be enclosed in double quotes. If the value contains both a semicolon and a double-quote character, the value can be enclosed in single quotes. The single quote is also useful if the value begins with a double-quote character. Conversely, the double quote can be used if the value begins with a single quote. If the value contains both single-quote and double-quote characters, the quote character used to enclose the value must be doubled each time it occurs within the value.

To include preceding or trailing spaces in the string value, the value must be enclosed in either single quotes or double quotes. Any leading or trailing spaces around integer, Boolean, or enumerated values are ignored, even if enclosed in quotes. However, spaces within a string literal keyword or value are preserved. Using .NET Framework version 1.1, single or double quotes may be used within a connection string without using delimiters (for example, Data Source= my'Server or Data Source= my"Server), unless a quote character is the first or last character in the value.

To include an equal sign (=) in a keyword or value, it must be preceded by another equal sign. For example, in the hypothetical connection string

    "key==word=value"

the keyword is "key=word" and the value is "value".

If a specific keyword in a keyword= value pair occurs multiple times in a connection string, the last occurrence listed is used in the value set.

Keywords are not case sensitive.

The following table lists the valid names for keyword values within the `ConnectionString`.

Name | Default | Description
`Connect Timeout`, `Connection Timeout` | 15 | The length of time (in seconds) to wait for a connection to the server before terminating the attempt and generating an error.

`Host`, `Server`, `Data Source`, `DataSource`, `Address`, `Addr`, `Network Address`

localhost

The name or network address of the instance of MySQL to which to connect. Multiple hosts can be specified separated by &. This can be useful where multiple MySQL servers are configured for replication and you are not concerned about the precise server you are connecting to. No attempt is made by the provider to synchronize writes to the database so care should be taken when using this option. In Unix environment with Mono, this can be a fully qualified path to MySQL socket filename. With this configuration, the Unix socket will be used instead of TCP/IP socket. Currently only a single socket name can be given so accessing MySQL in a replicated environment using Unix sockets is not currently supported.

`Ignore Prepare` | true | When true, instructs the provider to ignore any calls to MySqlCommand.Prepare(). This option is provided to prevent issues with corruption of the statements when use with server side prepared statements. If you want to use server-side prepare statements, set this option to false. This option was added in Connector/NET 5.0.3.
`Port` | 3306 | The port MySQL is using to listen for connections. Specify -1 for this value to use a named pipe connection (Windows only). This value is ignored if Unix socket is used.
`Protocol` | socket | Specifies the type of connection to make to the server.Values can be: socket or tcp for a socket connection pipe for a named pipe connection unix for a Unix socket connection memory to use MySQL shared memory
`CharSet`, `Character Set` |  | Specifies the character set that should be used to encode all queries sent to the server. Resultsets are still returned in the character set of the data returned.
`Logging` | false | When true, various pieces of information is output to any configured TraceListeners.
`Allow Batch` | true | When true, multiple SQL statements can be sent with one command execution. -Note- Starting with MySQL 4.1.1, batch statements should be separated by the server-defined seperator character. Commands sent to earlier versions of MySQL should be seperated with ';'.
`Encrypt` | false | For Connector/NET 5.0.3 and later, when `true`, SSL encryption is used for all data sent between the client and server if the server has a certificate installed. Recognized values are `true`, `false`, `yes`, and `no`. In versions before 5.0.3, this option had no effect.
`Initial Catalog`, `Database` | mysql | The name of the database to use intially
`Password`, `pwd` |  | The password for the MySQL account being used.
`Persist Security Info` | false | When set to `false` or `no` (strongly recommended), security-sensitive information, such as the password, is not returned as part of the connection if the connection is open or has ever been in an open state. Resetting the connection string resets all connection string values including the password. Recognized values are `true`, `false`, `yes`, and `no`.
`User Id`, `Username`, `Uid`, `User name` |  | The MySQL login account being used.
`Shared Memory Name` | MYSQL | The name of the shared memory object to use for communication if the connection protocol is set to memory.
`Allow Zero Datetime` | false | True to have MySqlDataReader.GetValue() return a MySqlDateTime for date or datetime columns that have illegal values. False will cause a `System.DateTime` object to be returned for legal values and an exception will be thrown for illegal values.
`Convert Zero Datetime` | false | True to have `MySqlDataReader.GetValue()` and `MySqlDataReader.GetDateTime()` return DateTime.MinValue for date or datetime columns that have illegal values.
`Old Syntax`, `OldSyntax` | false | Allows use of '@' symbol as a parameter marker. See `MySqlCommand` for more info. This is for compatibility only. All future code should be written to use the new '?' parameter marker.
`Pipe Name`, `Pipe` | mysql | When set to the name of a named pipe, the `MySqlConnection` will attempt to connect to MySQL on that named pipe.This settings only applies to the Windows platform.

The following table lists the valid names for connection pooling values within the `ConnectionString`. For more information about connection pooling, see Connection Pooling for the MySql Data Provider.

Name | Default | Description

`Connection Lifetime`

0

When a connection is returned to the pool, its creation time is compared with the current time, and the connection is destroyed if that time span (in seconds) exceeds the value specified by `Connection Lifetime`. This is useful in clustered configurations to force load balancing between a running server and a server just brought online. A value of zero (0) causes pooled connections to have the maximum connection timeout.

`Max Pool Size` | 100 | The maximum number of connections allowed in the pool.
`Min Pool Size` | 0 | The minimum number of connections allowed in the pool.
`Pooling` | true | When `true`, the `MySqlConnection` object is drawn from the appropriate pool, or if necessary, is created and added to the appropriate pool. Recognized values are `true`, `false`, `yes`, and `no`.
`Reset Pooled Connections`, `ResetConnections`, `ResetPooledConnections` | true | Specifies whether a ping and a reset should be sent to the server before a pooled connection is returned. Not resetting will yeild faster connection opens but also will not clear out session items such as temp tables.
`Cache Server Configuration`, `CacheServerConfiguration`, `CacheServerConfig` | false | Specifies whether server variables should be updated when a pooled connection is returned. Turning this one will yeild faster opens but will also not catch any server changes made by other connections.

When setting keyword or connection pooling values that require a Boolean value, you can use 'yes' instead of 'true', and 'no' instead of 'false'.

`Note` The MySql Data Provider uses the native socket protocol to communicate with MySQL. Therefore, it does not support the use of an ODBC data source name (DSN) when connecting to MySQL because it does not add an ODBC layer.

`CAUTION` In this release, the application should use caution when constructing a connection string based on user input (for example when retrieving user ID and password information from a dialog box, and appending it to the connection string). The application should ensure that a user cannot embed extra connection string parameters in these values (for example, entering a password as "validpassword;database=somedb" in an attempt to attach to a different database).

Examples

The following example creates a `MySqlConnection` and sets some of its properties

Visual Basic example:

      Public Sub CreateConnection()
        Dim myConnection As New MySqlConnection()
        myConnection.ConnectionString = "Persist Security Info=False;database=myDB;server=myHost;Connect Timeout=30;user id=myUser; pwd=myPass"
        myConnection.Open()
      End Sub 'CreateConnection

C# example:

      public void CreateConnection()
      {
        MySqlConnection myConnection = new MySqlConnection();
        myConnection.ConnectionString = "Persist Security Info=False;database=myDB;server=myHost;Connect Timeout=30;user id=myUser; pwd=myPass";
        myConnection.Open();
      }

Examples

The following example creates a `MySqlConnection` in Unix environment with Mono installed. MySQL socket filename used in this example is "/var/lib/mysql/mysql.sock". The actual filename depends on your MySQL configuration.

Visual Basic example:

      Public Sub CreateConnection()
        Dim myConnection As New MySqlConnection()
        myConnection.ConnectionString = "database=myDB;server=/var/lib/mysql/mysql.sock;user id=myUser; pwd=myPass"
        myConnection.Open()
      End Sub 'CreateConnection

C# example:

      public void CreateConnection()
      {
        MySqlConnection myConnection = new MySqlConnection();
        myConnection.ConnectionString = "database=myDB;server=/var/lib/mysql/mysql.sock;user id=myUser; pwd=myPass";
        myConnection.Open();
      }

#### 18.2.3.4. MySqlDataAdapter

Represents a set of data commands and a database connection that are used to fill a dataset and update a MySQL database. This class cannot be inherited.

The `MySQLDataAdapter`, serves as a bridge between a `System.Data.DataSet` and MySQL for retrieving and saving data. The `MySQLDataAdapter` provides this bridge by mapping `DbDataAdapter.Fill`, which changes the data in the `DataSet` to match the data in the data source, and `DbDataAdapter.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 `System.Data.MissingSchemaAction` property is set to `System.Data.MissingSchemaAction.AddWithKey`. You may also have the `MySQLDataAdapter` create the schema of the `DataSet`, including primary key information, before filling it with data using `System.Data.Common.DbDataAdapter.FillSchema`.

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

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

When an instance of `MySQLDataAdapter` is created, the read/write properties are set to initial values. For a list of these values, see the `MySQLDataAdapter` constructor.

Note. Please be aware that the `DataColumn` class in .NET 1.0 and 1.1 does not allow columns with type of UInt16, UInt32, or UInt64 to be autoincrement columns. If you plan to use autoincremement columns with MySQL, you should consider using signed integer columns.

Examples

The following example creates a `MySqlCommand` and a `MySqlConnection`. The `MySqlConnection` is opened and set as the `MySqlCommand.Connection` for the `MySqlCommand`. The example then calls `MySqlCommand.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.

Visual Basic example:

    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

C# example:

    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;
    }

##### 18.2.3.4.1. Class MySqlDataAdapter Constructor

Overload methods for MySqlDataAdapter

Initializes a new instance of the MySqlDataAdapter class.

When an instance of `MySqlDataAdapter` is created, the following read/write properties are set to the following initial values.

Properties | Initial Value
`MissingMappingAction` | `MissingMappingAction.Passthrough`
`MissingSchemaAction` | `MissingSchemaAction.Add`

You can change the value of any of these properties through a separate call to the property.

Examples

The following example creates a `MySqlDataAdapter` and sets some of its properties.

Visual Basic example:

    Public Sub CreateSqlDataAdapter()
        Dim conn As MySqlConnection = New MySqlConnection("Data Source=localhost;" & _
        "database=test")
        Dim da As MySqlDataAdapter = New MySqlDataAdapter
        da.MissingSchemaAction = MissingSchemaAction.AddWithKey

        da.SelectCommand = New MySqlCommand("SELECT id, name FROM mytable", conn)
        da.InsertCommand = New MySqlCommand("INSERT INTO mytable (id, name) " & _
                                                "VALUES (?id, ?name)", conn)
        da.UpdateCommand = New MySqlCommand("UPDATE mytable SET id=?id, name=?name " & _
                                                "WHERE id=?oldId", conn)
        da.DeleteCommand = New MySqlCommand("DELETE FROM mytable WHERE id=?id", conn)
        da.InsertCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id")
        da.InsertCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name")

        da.UpdateCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id")
        da.UpdateCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name")
        da.UpdateCommand.Parameters.Add("?oldId", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original
        da.DeleteCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original
    End Sub

C# example:

    public static void CreateSqlDataAdapter()
    {
        MySqlConnection conn = new MySqlConnection("Data Source=localhost;database=test");
        MySqlDataAdapter da = new MySqlDataAdapter();
        da.MissingSchemaAction = MissingSchemaAction.AddWithKey;

        da.SelectCommand = new MySqlCommand("SELECT id, name FROM mytable", conn);
        da.InsertCommand = new MySqlCommand("INSERT INTO mytable (id, name) " +
                                                "VALUES (?id, ?name)", conn);
        da.UpdateCommand = new MySqlCommand("UPDATE mytable SET id=?id, name=?name " +
                                                "WHERE id=?oldId", conn);
        da.DeleteCommand = new MySqlCommand("DELETE FROM mytable WHERE id=?id", conn);
        da.InsertCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id");
        da.InsertCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name");

        da.UpdateCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id");
        da.UpdateCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name");
        da.UpdateCommand.Parameters.Add("?oldId", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original;
        da.DeleteCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original;
    }

##### 18.2.3.4.2. Class MySqlDataAdapter Constructor Form 1

Initializes a new instance of the `MySqlDataAdapter` class with the specified `MySqlCommand` as the `SelectCommand` property.

Parameters: `MySqlCommand` that is a SQL `SELECT` statement or stored procedure and is set as the `SelectCommand` property of the `MySqlDataAdapter`.

When an instance of `MySqlDataAdapter` is created, the following read/write properties are set to the following initial values.

Properties | Initial Value
`MissingMappingAction` | `MissingMappingAction.Passthrough`
`MissingSchemaAction` | `MissingSchemaAction.Add`

You can change the value of any of these properties through a separate call to the property.

When `SelectCommand` (or any of the other command properties) is assigned to a previously created `MySqlCommand`, the `MySqlCommand` is not cloned. The `SelectCommand` maintains a reference to the previously created `MySqlCommand` object.

Examples

The following example creates a `MySqlDataAdapter` and sets some of its properties.

Visual Basic example:

    Public Sub CreateSqlDataAdapter()
        Dim conn As MySqlConnection = New MySqlConnection("Data Source=localhost;" & _
        "database=test")
      Dim cmd as new MySqlCommand("SELECT id, name FROM mytable", conn)
        Dim da As MySqlDataAdapter = New MySqlDataAdapter(cmd)
        da.MissingSchemaAction = MissingSchemaAction.AddWithKey

        da.InsertCommand = New MySqlCommand("INSERT INTO mytable (id, name) " & _
                                                "VALUES (?id, ?name)", conn)
        da.UpdateCommand = New MySqlCommand("UPDATE mytable SET id=?id, name=?name " & _
                                                "WHERE id=?oldId", conn)
        da.DeleteCommand = New MySqlCommand("DELETE FROM mytable WHERE id=?id", conn)
        da.InsertCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id")
        da.InsertCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name")

        da.UpdateCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id")
        da.UpdateCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name")
        da.UpdateCommand.Parameters.Add("?oldId", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original
        da.DeleteCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original
    End Sub

C# example:

    public static void CreateSqlDataAdapter()
    {
        MySqlConnection conn = new MySqlConnection("Data Source=localhost;database=test");
        MySqlCommand cmd = new MySqlCommand("SELECT id, name FROM mytable", conn);
        MySqlDataAdapter da = new MySqlDataAdapter(cmd);
        da.MissingSchemaAction = MissingSchemaAction.AddWithKey;

        da.InsertCommand = new MySqlCommand("INSERT INTO mytable (id, name) " +
                                                "VALUES (?id, ?name)", conn);
        da.UpdateCommand = new MySqlCommand("UPDATE mytable SET id=?id, name=?name " +
                                                "WHERE id=?oldId", conn);
        da.DeleteCommand = new MySqlCommand("DELETE FROM mytable WHERE id=?id", conn);
        da.InsertCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id");
        da.InsertCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name");

        da.UpdateCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id");
        da.UpdateCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name");
        da.UpdateCommand.Parameters.Add("?oldId", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original;
        da.DeleteCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original;
    }

##### 18.2.3.4.3. Class MySqlDataAdapter Constructor Form 2

Initializes a new instance of the `MySqlDataAdapter` class with a `SelectCommand` and a `MySqlConnection` object.

Parameters: A `String` that is a SQL `SELECT` statement or stored procedure to be used by the `SelectCommand` property of the `MySqlDataAdapter`.

Parameters: A `MySqlConnection` that represents the connection.

This implementation of the `MySqlDataAdapter` opens and closes a `MySqlConnection` if it is not already open. This can be useful in a an application that must call the `DbDataAdapter.Fill` method for two or more `MySqlDataAdapter` objects. If the `MySqlConnection` is already open, you must explicitly call `MySqlConnection.Close` or `MySqlConnection.Dispose` to close it.

When an instance of `MySqlDataAdapter` is created, the following read/write properties are set to the following initial values.

Properties | Initial Value
`MissingMappingAction` | `MissingMappingAction.Passthrough`
`MissingSchemaAction` | `MissingSchemaAction.Add`

You can change the value of any of these properties through a separate call to the property.

Examples

The following example creates a `MySqlDataAdapter` and sets some of its properties.

Visual Basic example:

    Public Sub CreateSqlDataAdapter()
        Dim conn As MySqlConnection = New MySqlConnection("Data Source=localhost;" & _
        "database=test")
        Dim da As MySqlDataAdapter = New MySqlDataAdapter("SELECT id, name FROM mytable", conn)
        da.MissingSchemaAction = MissingSchemaAction.AddWithKey

        da.InsertCommand = New MySqlCommand("INSERT INTO mytable (id, name) " & _
                                                "VALUES (?id, ?name)", conn)
        da.UpdateCommand = New MySqlCommand("UPDATE mytable SET id=?id, name=?name " & _
                                                "WHERE id=?oldId", conn)
        da.DeleteCommand = New MySqlCommand("DELETE FROM mytable WHERE id=?id", conn)
        da.InsertCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id")
        da.InsertCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name")

        da.UpdateCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id")
        da.UpdateCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name")
        da.UpdateCommand.Parameters.Add("?oldId", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original
        da.DeleteCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original
    End Sub

C# example:

    public static void CreateSqlDataAdapter()
    {
        MySqlConnection conn = new MySqlConnection("Data Source=localhost;database=test");
        MySqlDataAdapter da = new MySqlDataAdapter("SELECT id, name FROM mytable", conn);
        da.MissingSchemaAction = MissingSchemaAction.AddWithKey;

        da.InsertCommand = new MySqlCommand("INSERT INTO mytable (id, name) " +
                                                "VALUES (?id, ?name)", conn);
        da.UpdateCommand = new MySqlCommand("UPDATE mytable SET id=?id, name=?name " +
                                                "WHERE id=?oldId", conn);
        da.DeleteCommand = new MySqlCommand("DELETE FROM mytable WHERE id=?id", conn);
        da.InsertCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id");
        da.InsertCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name");

        da.UpdateCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id");
        da.UpdateCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name");
        da.UpdateCommand.Parameters.Add("?oldId", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original;
        da.DeleteCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original;
    }

##### 18.2.3.4.4. Class MySqlDataAdapter Constructor Form 3

Initializes a new instance of the `MySqlDataAdapter` class with a `SelectCommand` and a connection string.

Parameters: A `string` that is a SQL `SELECT` statement or stored procedure to be used by the `SelectCommand` property of the `MySqlDataAdapter`.

Parameters: The connection string

When an instance of `MySqlDataAdapter` is created, the following read/write properties are set to the following initial values.

Properties | Initial Value
`MissingMappingAction` | `MissingMappingAction.Passthrough`
`MissingSchemaAction` | `MissingSchemaAction.Add`

You can change the value of any of these properties through a separate call to the property.

Examples

The following example creates a `MySqlDataAdapter` and sets some of its properties.

Visual Basic example:

    Public Sub CreateSqlDataAdapter()
        Dim da As MySqlDataAdapter = New MySqlDataAdapter("SELECT id, name FROM mytable", "Data Source=localhost;database=test")
        Dim conn As MySqlConnection = da.SelectCommand.Connection
        da.MissingSchemaAction = MissingSchemaAction.AddWithKey

        da.InsertCommand = New MySqlCommand("INSERT INTO mytable (id, name) " & _
                                                "VALUES (?id, ?name)", conn)
        da.UpdateCommand = New MySqlCommand("UPDATE mytable SET id=?id, name=?name " & _
                                                "WHERE id=?oldId", conn)
        da.DeleteCommand = New MySqlCommand("DELETE FROM mytable WHERE id=?id", conn)
        da.InsertCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id")
        da.InsertCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name")

        da.UpdateCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id")
        da.UpdateCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name")
        da.UpdateCommand.Parameters.Add("?oldId", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original
        da.DeleteCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original
    End Sub

C# example:

    public static void CreateSqlDataAdapter()
    {
        MySqlDataAdapter da = new MySqlDataAdapter("SELECT id, name FROM mytable", "Data Source=localhost;database=test");
        MySqlConnection conn = da.SelectCommand.Connection;
        da.MissingSchemaAction = MissingSchemaAction.AddWithKey;

        da.InsertCommand = new MySqlCommand("INSERT INTO mytable (id, name) " +
                                                "VALUES (?id, ?name)", conn);
        da.UpdateCommand = new MySqlCommand("UPDATE mytable SET id=?id, name=?name " +
                                                "WHERE id=?oldId", conn);
        da.DeleteCommand = new MySqlCommand("DELETE FROM mytable WHERE id=?id", conn);
        da.InsertCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id");
        da.InsertCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name");

        da.UpdateCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id");
        da.UpdateCommand.Parameters.Add("?name", MySqlDbType.VarChar, 40, "name");
        da.UpdateCommand.Parameters.Add("?oldId", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original;
        da.DeleteCommand.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id").SourceVersion = DataRowVersion.Original;
    }

##### 18.2.3.4.5. DeleteCommand

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

Value: A `MySqlCommand` used during `System.Data.Common.DataAdapter.Update` to delete records in the database that correspond to deleted rows in the `DataSet`.

During `System.Data.Common.DataAdapter.Update`, if this property is not set and primary key information is present in the `DataSet`, the `DeleteCommand` can be generated automatically if you set the `SelectCommand` property and use the `MySqlCommandBuilder`. Then, any additional commands that you do not set are generated by the `MySqlCommandBuilder`. This generation logic requires key column information to be present in the `DataSet`.

When `DeleteCommand` is assigned to a previously created `MySqlCommand`, the `MySqlCommand` is not cloned. The `DeleteCommand` maintains a reference to the previously created `MySqlCommand` object.

Examples

The following example creates a `MySqlDataAdapter` and sets the `SelectCommand` and `DeleteCommand` properties. It assumes you have already created a `MySqlConnection` object.

Visual Basic example:

    Public Shared Function CreateCustomerAdapter(conn As MySqlConnection) As MySqlDataAdapter

      Dim da As MySqlDataAdapter = New MySqlDataAdapter()
      Dim cmd As MySqlCommand
      Dim parm As MySqlParameter
      ' Create the SelectCommand.
      cmd = New MySqlCommand("SELECT * FROM mytable WHERE id=?id AND name=?name", conn)
      cmd.Parameters.Add("?id", MySqlDbType.VarChar, 15)
      cmd.Parameters.Add("?name", MySqlDbType.VarChar, 15)
      da.SelectCommand = cmd
      ' Create the DeleteCommand.
      cmd = New MySqlCommand("DELETE FROM mytable WHERE id=?id", conn)
      parm = cmd.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id")
      parm.SourceVersion = DataRowVersion.Original
      da.DeleteCommand = cmd
      Return da
    End Function

C# example:

    public static MySqlDataAdapter CreateCustomerAdapter(MySqlConnection conn)
    {
      MySqlDataAdapter da = new MySqlDataAdapter();
      MySqlCommand cmd;
      MySqlParameter parm;
      // Create the SelectCommand.
      cmd = new MySqlCommand("SELECT * FROM mytable WHERE id=?id AND name=?name", conn);
      cmd.Parameters.Add("?id", MySqlDbType.VarChar, 15);
      cmd.Parameters.Add("?name", MySqlDbType.VarChar, 15);
      da.SelectCommand = cmd;
      // Create the DeleteCommand.
      cmd = new MySqlCommand("DELETE FROM mytable WHERE id=?id", conn);
      parm = cmd.Parameters.Add("?id", MySqlDbType.VarChar, 5, "id");
      parm.SourceVersion = DataRowVersion.Original;
      da.DeleteCommand = cmd;
      return da;
    }

##### 18.2.3.4.6. InsertCommand

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

Value: A `MySqlCommand` used during `System.Data.Common.DataAdapter.Update` to insert records into the database that correspond to new rows in the `DataSet`.

During `System.Data.Common.DataAdapter.Update`, if this property is not set and primary key information is present in the `DataSet`, the `InsertCommand` can be generated automatically if you set the `SelectCommand` property and use the `MySqlCommandBuilder`. Then, any additional commands that you do not set are generated by the `MySqlCommandBuilder`. This generation logic requires key column information to be present in the `DataSet`.

When `InsertCommand` is assigned to a previously created `MySqlCommand`, the `MySqlCommand` is not cloned. The `InsertCommand` maintains a reference to the previously created `MySqlCommand` object.

Note. If execution of this command returns rows, these rows may be added to the `DataSet` depending on how you set the `MySqlCommand.UpdatedRowSource` property of the `MySqlCommand` object.

Examples

The following example creates a `MySqlDataAdapter` and sets the `SelectCommand` and `InsertCommand` properties. It assumes you have already created a `MySqlConnection` object.

Visual Basic example:

    Public Shared Function CreateCustomerAdapter(conn As MySqlConnection) As MySqlDataAdapter

      Dim da As MySqlDataAdapter = New MySqlDataAdapter()
      Dim cmd As MySqlCommand
      Dim parm As MySqlParameter
      ' Create the SelectCommand.
      cmd = New MySqlCommand("SELECT * FROM mytable WHERE id=?id AND name=?name", conn)
      cmd.Parameters.Add("?id", MySqlDbType.VarChar, 15)
      cmd.Parameters.Add("?name", MySqlDbType.VarChar, 15)
      da.SelectCommand = cmd
      ' Create the InsertCommand.
      cmd = New MySqlCommand("INSERT INTO mytable (id,name) VALUES (?id, ?name)", conn)
      cmd.Parameters.Add( "?id", MySqlDbType.VarChar, 15, "id" )
      cmd.Parameters.Add( "?name", MySqlDbType.VarChar, 15, "name" )
      da.InsertCommand = cmd

      Return da
    End Function

C# example:

    public static MySqlDataAdapter CreateCustomerAdapter(MySqlConnection conn)
    {
      MySqlDataAdapter da = new MySqlDataAdapter();
      MySqlCommand cmd;
      MySqlParameter parm;
      // Create the SelectCommand.
      cmd = new MySqlCommand("SELECT * FROM mytable WHERE id=?id AND name=?name", conn);
      cmd.Parameters.Add("?id", MySqlDbType.VarChar, 15);
      cmd.Parameters.Add("?name", MySqlDbType.VarChar, 15);
      da.SelectCommand = cmd;
      // Create the InsertCommand.
      cmd = new MySqlCommand("INSERT INTO mytable (id,name) VALUES (?id,?name)", conn);
      cmd.Parameters.Add("?id", MySqlDbType.VarChar, 15, "id" );
      cmd.Parameters.Add("?name", MySqlDbType.VarChar, 15, "name" );

      da.InsertCommand = cmd;
      return da;
    }

##### 18.2.3.4.7. UpdateCommand

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

Value: A `MySqlCommand` used during `System.Data.Common.DataAdapter.Update` to update records in the database with data from the `DataSet`.

During `System.Data.Common.DataAdapter.Update`, if this property is not set and primary key information is present in the `DataSet`, the `UpdateCommand` can be generated automatically if you set the `SelectCommand` property and use the `MySqlCommandBuilder`. Then, any additional commands that you do not set are generated by the `MySqlCommandBuilder`. This generation logic requires key column information to be present in the `DataSet`.

When `UpdateCommand` is assigned to a previously created `MySqlCommand`, the `MySqlCommand` is not cloned. The `UpdateCommand` maintains a reference to the previously created `MySqlCommand` object.

Note. If execution of this command returns rows, these rows may be merged with the DataSet depending on how you set the `MySqlCommand.UpdatedRowSource` property of the `MySqlCommand` object.

Examples

The following example creates a `MySqlDataAdapter` and sets the `SelectCommand` and `UpdateCommand` properties. It assumes you have already created a `MySqlConnection` object.

Visual Basic example:

    Public Shared Function CreateCustomerAdapter(conn As MySqlConnection) As MySqlDataAdapter

      Dim da As MySqlDataAdapter = New MySqlDataAdapter()
      Dim cmd As MySqlCommand
      Dim parm As MySqlParameter
      ' Create the SelectCommand.
      cmd = New MySqlCommand("SELECT * FROM mytable WHERE id=?id AND name=?name", conn)
      cmd.Parameters.Add("?id", MySqlDbType.VarChar, 15)
      cmd.Parameters.Add("?name", MySqlDbType.VarChar, 15)
      da.SelectCommand = cmd
      ' Create the UpdateCommand.
      cmd = New MySqlCommand("UPDATE mytable SET id=?id, name=?name WHERE id=?oldId", conn)
      cmd.Parameters.Add( "?id", MySqlDbType.VarChar, 15, "id" )
      cmd.Parameters.Add( "?name", MySqlDbType.VarChar, 15, "name" )

      parm = cmd.Parameters.Add("?oldId", MySqlDbType.VarChar, 15, "id")
      parm.SourceVersion = DataRowVersion.Original

      da.UpdateCommand = cmd

      Return da
    End Function

C# example:

    public static MySqlDataAdapter CreateCustomerAdapter(MySqlConnection conn)
    {
      MySqlDataAdapter da = new MySqlDataAdapter();
      MySqlCommand cmd;
      MySqlParameter parm;
      // Create the SelectCommand.
      cmd = new MySqlCommand("SELECT * FROM mytable WHERE id=?id AND name=?name", conn);
      cmd.Parameters.Add("?id", MySqlDbType.VarChar, 15);
      cmd.Parameters.Add("?name", MySqlDbType.VarChar, 15);
      da.SelectCommand = cmd;
      // Create the UpdateCommand.
      cmd = new MySqlCommand("UPDATE mytable SET id=?id, name=?name WHERE id=?oldId", conn);
      cmd.Parameters.Add("?id", MySqlDbType.VarChar, 15, "id" );
      cmd.Parameters.Add("?name", MySqlDbType.VarChar, 15, "name" );

      parm = cmd.Parameters.Add( "?oldId", MySqlDbType.VarChar, 15, "id" );
      parm.SourceVersion = DataRowVersion.Original;

      da.UpdateCommand = cmd;
      return da;
    }

##### 18.2.3.4.8. SelectCommand

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

Value: A `MySqlCommand` used during `System.Data.Common.DbDataAdapter.Fill` to select records from the database for placement in the `DataSet`.

When `SelectCommand` is assigned to a previously created `MySqlCommand`, the `MySqlCommand` is not cloned. The `SelectCommand` maintains a reference to the previously created `MySqlCommand` object.

If the `SelectCommand` does not return any rows, no tables are added to the `DataSet`, and no exception is raised.

Examples

The following example creates a `MySqlDataAdapter` and sets the `SelectCommand` and `InsertCommand` properties. It assumes you have already created a `MySqlConnection` object.

Visual Basic example:

    Public Shared Function CreateCustomerAdapter(conn As MySqlConnection) As MySqlDataAdapter

      Dim da As MySqlDataAdapter = New MySqlDataAdapter()
      Dim cmd As MySqlCommand
      Dim parm As MySqlParameter
      ' Create the SelectCommand.
      cmd = New MySqlCommand("SELECT * FROM mytable WHERE id=?id AND name=?name", conn)
      cmd.Parameters.Add("?id", MySqlDbType.VarChar, 15)
      cmd.Parameters.Add("?name", MySqlDbType.VarChar, 15)
      da.SelectCommand = cmd
      ' Create the InsertCommand.
      cmd = New MySqlCommand("INSERT INTO mytable (id,name) VALUES (?id, ?name)", conn)
      cmd.Parameters.Add( "?id", MySqlDbType.VarChar, 15, "id" )
      cmd.Parameters.Add( "?name", MySqlDbType.VarChar, 15, "name" )
      da.InsertCommand = cmd

      Return da
    End Function

C# example:

    public static MySqlDataAdapter CreateCustomerAdapter(MySqlConnection conn)
    {
      MySqlDataAdapter da = new MySqlDataAdapter();
      MySqlCommand cmd;
      MySqlParameter parm;
      // Create the SelectCommand.
      cmd = new MySqlCommand("SELECT * FROM mytable WHERE id=?id AND name=?name", conn);
      cmd.Parameters.Add("?id", MySqlDbType.VarChar, 15);
      cmd.Parameters.Add("?name", MySqlDbType.VarChar, 15);
      da.SelectCommand = cmd;
      // Create the InsertCommand.
      cmd = new MySqlCommand("INSERT INTO mytable (id,name) VALUES (?id,?name)", conn);
      cmd.Parameters.Add("?id", MySqlDbType.VarChar, 15, "id" );
      cmd.Parameters.Add("?name", MySqlDbType.VarChar, 15, "name" );

      da.InsertCommand = cmd;
      return da;
    }

#### 18.2.3.5. MySqlDataReader

To create a `MySQLDataReader`, you must call the `MySqlCommand.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 `MySqlDataReader.Close` method of the `MySqlDataReader` is called.

`MySqlDataReader.IsClosed` and `MySqlDataReader.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 `MySqlDataReader.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`.

Examples

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`.

Visual Basic example:

    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

C# example:

    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();
     }

##### 18.2.3.5.1. GetBytes

`GetBytes` returns the number of available bytes in the field. In most cases this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetBytes` has already been used to obtain bytes from the field. This may be the case, for example, if the `MySqlDataReader` is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for `MySqlCommand.CommandBehavior`.

If you pass a buffer that is a null reference (`Nothing` in Visual Basic), `GetBytes` returns the length of the field in bytes.

No conversions are performed; therefore the data retrieved must already be a byte array.

##### 18.2.3.5.2. GetTimeSpan

Gets the value of the specified column as a `TimeSpan` object.

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

##### 18.2.3.5.3. GetDateTime

Gets the value of the specified column as a `System.DateTime` object.

Note. MySql allows date columns to contain the value '0000-00-00' and datetime columns to contain the value '0000-00-00 00:00:00'. The DateTime structure cannot contain or represent these values. To read a datetime value from a column that might contain zero values, use `GetMySqlDateTime`. The behavior of reading a zero datetime column using this method is defined by the `ZeroDateTimeBehavior` connection string option. For more information on this option, please refer to `MySqlConnection.ConnectionString`.

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

##### 18.2.3.5.4. GetMySqlDateTime

Gets the value of the specified column as a `MySql.Data.Types.MySqlDateTime` object.

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

##### 18.2.3.5.5. GetString

Gets the value of the specified column as a `String` object.

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

##### 18.2.3.5.6. GetDecimal

Gets the value of the specified column as a `Decimal` object.

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

##### 18.2.3.5.7. GetDouble

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

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

##### 18.2.3.5.8. GetFloat

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

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

##### 18.2.3.5.9. GetGiud

Gets the value of the specified column as a globally-unique identifier (GUID).

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

##### 18.2.3.5.10. GetInt16

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

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

##### 18.2.3.5.11. GetInt32

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

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

##### 18.2.3.5.12. GetInt64

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

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

##### 18.2.3.5.13. GetUInt16

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

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

##### 18.2.3.5.14. GetUInt32

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

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

##### 18.2.3.5.15. GetUInt64

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

Parameters: The zero-based column ordinal.

Returns: The value of the specified column.

#### 18.2.3.6. MySqlException

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.

Examples

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

Visual Basic example:

    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

C# example:

    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 );
       }
    }

#### 18.2.3.7. MySqlParameter

Parameter names are not case sensitive.

Examples

The following example creates multiple instances of `MySqlParameter` through the `MySqlParameterCollection` collection within the `MySqlDataAdapter`. These parameters are used to select data from the data source and place the data in the `DataSet`. This example assumes that a `DataSet` and a `MySqlDataAdapter` have already been created with the appropriate schema, commands, and connection.

Visual Basic example:

    Public Sub AddSqlParameters()
        ' ...
        ' create myDataSet and myDataAdapter
        ' ...
        myDataAdapter.SelectCommand.Parameters.Add("@CategoryName", MySqlDbType.VarChar, 80).Value = "toasters"
        myDataAdapter.SelectCommand.Parameters.Add("@SerialNum", MySqlDbType.Long).Value = 239

        myDataAdapter.Fill(myDataSet)
    End Sub 'AddSqlParameters

C# example:

    public void AddSqlParameters()
    {
    // ...
    // create myDataSet and myDataAdapter
    // ...
      myDataAdapter.SelectCommand.Parameters.Add("@CategoryName", MySqlDbType.VarChar, 80).Value = "toasters";
      myDataAdapter.SelectCommand.Parameters.Add("@SerialNum", MySqlDbType.Long).Value = 239;
      myDataAdapter.Fill(myDataSet);
    }

#### 18.2.3.8. MySqlParameterCollection

The number of the parameters in the collection must be equal to the number of parameter placeholders within the command text, or an exception will be generated.

Examples

The following example creates multiple instances of `MySqlParameter` through the `MySqlParameterCollection` collection within the `MySqlDataAdapter`. These parameters are used to select data within the data source and place the data in the `DataSet`. This code assumes that a `DataSet` and a `MySqlDataAdapter` have already been created with the appropriate schema, commands, and connection.

Visual Basic example:

    Public Sub AddParameters()
        ' ...
        ' create myDataSet and myDataAdapter
        ' ...
        myDataAdapter.SelectCommand.Parameters.Add("@CategoryName", MySqlDbType.VarChar, 80).Value = "toasters"
        myDataAdapter.SelectCommand.Parameters.Add("@SerialNum", MySqlDbType.Long).Value = 239

        myDataAdapter.Fill(myDataSet)
    End Sub 'AddSqlParameters

C# example:

    public void AddSqlParameters()
    {
    // ...
    // create myDataSet and myDataAdapter
    // ...
      myDataAdapter.SelectCommand.Parameters.Add("@CategoryName", MySqlDbType.VarChar, 80).Value = "toasters";
      myDataAdapter.SelectCommand.Parameters.Add("@SerialNum", MySqlDbType.Long).Value = 239;
      myDataAdapter.Fill(myDataSet);
    }

#### 18.2.3.9. MySqlTransaction

Represents a SQL transaction to be made in a MySQL database. This class cannot be inherited.

The application creates a `MySqlTransaction` object by calling `MySqlConnection.BeginTransaction` on the `MySqlConnection` object. All subsequent operations associated with the transaction (for example, committing or aborting the transaction), are performed on the `MySqlTransaction` object.

Examples

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

Visual Basic example:

    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

C# example:

    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();
        }
    }

##### 18.2.3.9.1. Rollback

Rolls back a transaction from a pending state.

The Rollback method is equivalent to the MySQL statement ROLLBACK. The transaction can only be rolled back from a pending state (after BeginTransaction has been called, but before Commit is called).

Examples

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

Visual Basic example:

    Public Sub RunSqlTransaction(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 mytable (id, desc) VALUES (100, 'Description')"
          myCommand.ExecuteNonQuery()
          myCommand.CommandText = "Insert into mytable (id, desc) VALUES (101, 'Description')"
          myCommand.ExecuteNonQuery()
          myTrans.Commit()
          Console.WriteLine("Success.")
        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

C# example:

    public void RunSqlTransaction(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 mytable (id, desc) VALUES (100, 'Description')";
          myCommand.ExecuteNonQuery();
          myCommand.CommandText = "Insert into mytable (id, desc) 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();
        }
    }

##### 18.2.3.9.2. Commit

Commits the database transaction.

The `Commit` method is equivalent to the MySQL SQL statement COMMIT.

Examples

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

Visual Basic example:

    Public Sub RunSqlTransaction(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 mytable (id, desc) VALUES (100, 'Description')"
          myCommand.ExecuteNonQuery()
          myCommand.CommandText = "Insert into mytable (id, desc) VALUES (101, 'Description')"
          myCommand.ExecuteNonQuery()
          myTrans.Commit()
          Console.WriteLine("Success.")
        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

C# example:

    public void RunSqlTransaction(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 mytable (id, desc) VALUES (100, 'Description')";
          myCommand.ExecuteNonQuery();
          myCommand.CommandText = "Insert into mytable (id, desc) 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();
        }
    }

### 18.2.4. Connector/NET Reference

This section of the manual contains a complete reference to the Connector/NET ADO.NET component, automatically generated from the embedded documentation.

#### 18.2.4.1. MySql.Data.MySqlClient

Namespace hierarchy

Classes

Class | Description
MySqlCommand |
MySqlCommandBuilder |
MySqlConnection |
MySqlDataAdapter |
MySqlDataReader | Provides a means of reading a forward-only stream of rows from a MySQL database. This class cannot be inherited.
MySqlError | Collection of error codes that can be returned by the server
MySqlException | The exception that is thrown when MySQL returns an error. This class cannot be inherited.
MySqlHelper | Helper class that makes it easier to work with the provider.
MySqlInfoMessageEventArgs | Provides data for the InfoMessage event. This class cannot be inherited.
MySqlParameter | Represents a parameter to a MySqlCommand , and optionally, its mapping to DataSetcolumns. This class cannot be inherited.
MySqlParameterCollection | Represents a collection of parameters relevant to a MySqlCommand as well as their respective mappings to columns in a DataSet. This class cannot be inherited.
MySqlRowUpdatedEventArgs | Provides data for the RowUpdated event. This class cannot be inherited.
MySqlRowUpdatingEventArgs | Provides data for the RowUpdating event. This class cannot be inherited.
MySqlTransaction |

Delegates

Delegate | Description
MySqlInfoMessageEventHandler | Represents the method that will handle the InfoMessage event of a MySqlConnection.
MySqlRowUpdatedEventHandler | Represents the method that will handle the RowUpdatedevent of a MySqlDataAdapter .
MySqlRowUpdatingEventHandler | Represents the method that will handle the RowUpdatingevent of a MySqlDataAdapter .

Enumerations

Enumeration | Description
MySqlDbType | Specifies MySQL specific data type of a field, property, for use in a MySqlParameter .
MySqlErrorCode |

##### 18.2.4.1.1. MySql.Data.MySqlClientHierarchy

See Also

MySql.Data.MySqlClient Namespace

##### 18.2.4.1.2. MySqlCommand Class

For a list of all members of this type, see MySqlCommand Members .

Syntax: Visual Basic

    NotInheritable Public Class MySqlCommand_
      Inherits Component_
      Implements IDbCommand, ICloneable

Syntax: C#

    public sealed class MySqlCommand : Component, IDbCommand, ICloneable

Thread Safety

Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlCommand Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1. MySqlCommand Members

MySqlCommand overview

Public Instance Constructors

MySqlCommand | Overloaded. Initializes a new instance of the MySqlCommand class.

Public Instance Properties

CommandText |
CommandTimeout |
CommandType |
Connection |
Container(inherited from Component) | Gets the IContainerthat contains the Component.
IsPrepared |
Parameters |
Site(inherited from Component) | Gets or sets the ISiteof the Component.
Transaction |
UpdatedRowSource |

Public Instance Methods

Cancel | Attempts to cancel the execution of a MySqlCommand. This operation is not supported.
CreateObjRef(inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.
CreateParameter | Creates a new instance of a MySqlParameter object.
Dispose(inherited from Component) | Releases all resources used by the Component.
Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
ExecuteNonQuery |
ExecuteReader | Overloaded.
ExecuteScalar |
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetLifetimeService(inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance.
GetType(inherited from Object) | Gets the Typeof the current instance.
InitializeLifetimeService(inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance.
Prepare |
ToString(inherited from Component) | Returns a Stringcontaining the name of the Component, if any. This method should not be overridden.

Public Instance Events

Disposed(inherited from Component) | Adds an event handler to listen to the Disposedevent on the component.

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1. MySqlCommand Constructor

Initializes a new instance of the MySqlCommand class.

Overload List

Initializes a new instance of the MySqlCommand class.

- public MySqlCommand();

- public MySqlCommand(string);

- public MySqlCommand(string,MySqlConnection);

- public MySqlCommand(string,MySqlConnection,MySqlTransaction);

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.1. MySqlCommand Constructor ()

Initializes a new instance of the MySqlCommand class.

Syntax: Visual Basic

    Overloads Public Sub New()

Syntax: C#

    public MySqlCommand();

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace , MySqlCommand Constructor Overload List

###### 18.2.4.1.2.1.1.2. MySqlCommand Constructor (String)

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal cmdText As String _
    )

Syntax: C#

    public MySqlCommand(
    stringcmdText
    );

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace , MySqlCommand Constructor Overload List

###### 18.2.4.1.2.1.1.3. MySqlCommand Constructor (String, MySqlConnection)

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal cmdText As String, _
       ByVal connection As MySqlConnection _
    )

Syntax: C#

    public MySqlCommand(
    stringcmdText,
    MySqlConnectionconnection
    );

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace , MySqlCommand Constructor Overload List

###### 18.2.4.1.2.1.1.3.1. MySqlConnection Class

For a list of all members of this type, see MySqlConnection Members .

Syntax: Visual Basic

    NotInheritable Public Class MySqlConnection_
      Inherits Component_
      Implements IDbConnection, ICloneable

Syntax: C#

    public sealed class MySqlConnection : Component, IDbConnection, ICloneable

Thread Safety

Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlConnection Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1. MySqlConnection Members

MySqlConnection overview

Public Instance Constructors

MySqlConnection | Overloaded. Initializes a new instance of the MySqlConnection class.

Public Instance Properties

ConnectionString |
ConnectionTimeout |
Container(inherited from Component) | Gets the IContainerthat contains the Component.
Database |
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 |
Site(inherited from Component) | Gets or sets the ISiteof the Component.
State |
UseCompression | Indicates if this connection should use compression when communicating with the server.

Public Instance Methods

BeginTransaction | Overloaded.
ChangeDatabase |
Close |
CreateCommand |
CreateObjRef(inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.
Dispose(inherited from Component) | Releases all resources used by the Component.
Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetLifetimeService(inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance.
GetType(inherited from Object) | Gets the Typeof the current instance.
InitializeLifetimeService(inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance.
Open |
Ping | Ping
ToString(inherited from Component) | Returns a Stringcontaining the name of the Component, if any. This method should not be overridden.

Public Instance Events

Disposed(inherited from Component) | Adds an event handler to listen to the Disposedevent on the component.
InfoMessage |
StateChange |

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.1. MySqlConnection Constructor

Initializes a new instance of the MySqlConnection class.

Overload List

Initializes a new instance of the MySqlConnection class.

- public MySqlConnection();

- public MySqlConnection(string);

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.1.1. MySqlConnection Constructor ()

Initializes a new instance of the MySqlConnection class.

Syntax: Visual Basic

    Overloads Public Sub New()

Syntax: C#

    public MySqlConnection();

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace , MySqlConnection Constructor Overload List

###### 18.2.4.1.2.1.1.3.1.1.1.2. MySqlConnection Constructor (String)

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal connectionString As String _
    )

Syntax: C#

    public MySqlConnection(
    stringconnectionString
    );

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace , MySqlConnection Constructor Overload List

###### 18.2.4.1.2.1.1.3.1.1.2. ConnectionString Property

Syntax: Visual Basic

    NotOverridable Public Property ConnectionString As String _
    _
      Implements IDbConnection.ConnectionString

Syntax: C#

    public string ConnectionString {get; set;}

Implements

IDbConnection.ConnectionString

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.3. ConnectionTimeout Property

Syntax: Visual Basic

    NotOverridable Public ReadOnly Property ConnectionTimeout As Integer _
    _
      Implements IDbConnection.ConnectionTimeout

Syntax: C#

    public int ConnectionTimeout {get;}

Implements

IDbConnection.ConnectionTimeout

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.4. Database Property

Syntax: Visual Basic

    NotOverridable Public ReadOnly Property Database As String _
    _
      Implements IDbConnection.Database

Syntax: C#

    public string Database {get;}

Implements

IDbConnection.Database

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.5. DataSource Property

Gets the name of the MySQL server to which to connect.

Syntax: Visual Basic

    Public ReadOnly Property DataSource As String

Syntax: C#

    public string DataSource {get;}

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.6. ServerThread Property

Returns the id of the server thread this connection is executing on

Syntax: Visual Basic

    Public ReadOnly Property ServerThread As Integer

Syntax: C#

    public int ServerThread {get;}

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.7. ServerVersion Property

Syntax: Visual Basic

    Public ReadOnly Property ServerVersion As String

Syntax: C#

    public string ServerVersion {get;}

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.8. State Property

Syntax: Visual Basic

    NotOverridable Public ReadOnly Property State As ConnectionState _
    _
      Implements IDbConnection.State

Syntax: C#

    public System.Data.ConnectionState State {get;}

Implements

IDbConnection.State

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.9. UseCompression Property

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

Syntax: Visual Basic

    Public ReadOnly Property UseCompression As Boolean

Syntax: C#

    public bool UseCompression {get;}

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.10. BeginTransaction Method

Overload List

- public MySqlTransaction BeginTransaction();

- public MySqlTransaction BeginTransaction(IsolationLevel);

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.10.1. MySqlConnection.BeginTransaction Method ()

Syntax: Visual Basic

    Overloads Public Function BeginTransaction() As MySqlTransaction

Syntax: C#

    public MySqlTransaction BeginTransaction();

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace , MySqlConnection.BeginTransaction Overload List

###### 18.2.4.1.2.1.1.3.1.1.10.1.1. MySqlTransaction Class

For a list of all members of this type, see MySqlTransaction Members .

Syntax: Visual Basic

    NotInheritable Public Class MySqlTransaction_
      Implements IDbTransaction, IDisposable

Syntax: C#

    public sealed class MySqlTransaction : IDbTransaction, IDisposable

Thread Safety

Public static (Sharedin Visual Basic) members of this type are safe for multithreaded operations. Instance members are notguaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlTransaction Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.10.1.1.1. MySqlTransaction Members

MySqlTransaction overview

Public Instance Properties

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 IsolationLevelfor this transaction.

Public Instance Methods

Commit |
Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetType(inherited from Object) | Gets the Typeof the current instance.
Rollback |
ToString(inherited from Object) | Returns a Stringthat represents the current Object.

See Also

MySqlTransaction Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.10.1.1.1.1. Connection Property

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

Syntax: Visual Basic

    Public ReadOnly Property Connection As MySqlConnection

Syntax: C#

    public MySqlConnection Connection {get;}

Property Value

The MySqlConnection object associated with this transaction.

Remarks

A single application may have multiple database connections, each with zero or more transactions. This property enables you to determine the connection object associated with a particular transaction created by BeginTransaction .

See Also

MySqlTransaction Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.10.1.1.1.2. IsolationLevel Property

Specifies the IsolationLevelfor this transaction.

Syntax: Visual Basic

    NotOverridable Public ReadOnly Property IsolationLevel As IsolationLevel _
    _
      Implements IDbTransaction.IsolationLevel

Syntax: C#

    public System.Data.IsolationLevel IsolationLevel {get;}

Property Value

The IsolationLevel for this transaction. The default is ReadCommitted.

Implements

IDbTransaction.IsolationLevel

Remarks

Parallel transactions are not supported. Therefore, the IsolationLevel applies to the entire transaction.

See Also

MySqlTransaction Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.10.1.1.1.3. MySqlTransaction.Commit Method

Syntax: Visual Basic

    NotOverridable Public Sub Commit() _
    _
      Implements IDbTransaction.Commit

Syntax: C#

    public void Commit();

Implements

IDbTransaction.Commit

See Also

MySqlTransaction Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.10.1.1.1.4. MySqlTransaction.Rollback Method

Syntax: Visual Basic

    NotOverridable Public Sub Rollback() _
    _
      Implements IDbTransaction.Rollback

Syntax: C#

    public void Rollback();

Implements

IDbTransaction.Rollback

See Also

MySqlTransaction Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.10.2. MySqlConnection.BeginTransaction Method (IsolationLevel)

Syntax: Visual Basic

    Overloads Public Function BeginTransaction( _
       ByVal iso As IsolationLevel _
    ) As MySqlTransaction

Syntax: C#

    public MySqlTransaction BeginTransaction(
    IsolationLeveliso
    );

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace , MySqlConnection.BeginTransaction Overload List

###### 18.2.4.1.2.1.1.3.1.1.11. MySqlConnection.ChangeDatabase Method

Syntax: Visual Basic

    NotOverridable Public Sub ChangeDatabase( _
       ByVal databaseName As String _
    ) _
    _
      Implements IDbConnection.ChangeDatabase

Syntax: C#

    public void ChangeDatabase(
    stringdatabaseName
    );

Implements

IDbConnection.ChangeDatabase

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.12. MySqlConnection.Close Method

Syntax: Visual Basic

    NotOverridable Public Sub Close() _
    _
      Implements IDbConnection.Close

Syntax: C#

    public void Close();

Implements

IDbConnection.Close

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.13. MySqlConnection.CreateCommand Method

Syntax: Visual Basic

    Public Function CreateCommand() As MySqlCommand

Syntax: C#

    public MySqlCommand CreateCommand();

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.14. MySqlConnection.Open Method

Syntax: Visual Basic

    NotOverridable Public Sub Open() _
    _
      Implements IDbConnection.Open

Syntax: C#

    public void Open();

Implements

IDbConnection.Open

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.15. MySqlConnection.Ping Method

Ping

Syntax: Visual Basic

    Public Function Ping() As Boolean

Syntax: C#

    public bool Ping();

Return Value

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.16. MySqlConnection.InfoMessage Event

Syntax: Visual Basic

    Public Event InfoMessage As MySqlInfoMessageEventHandler

Syntax: C#

    public event MySqlInfoMessageEventHandler InfoMessage;

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.16.1. MySqlInfoMessageEventHandler Delegate

Represents the method that will handle the InfoMessage event of a MySqlConnection .

Syntax: Visual Basic

    Public Delegate Sub MySqlInfoMessageEventHandler( _
       ByVal sender As Object, _
       ByVal args As MySqlInfoMessageEventArgs _
    )

Syntax: C#

    public delegate void MySqlInfoMessageEventHandler(
    objectsender,
    MySqlInfoMessageEventArgsargs
    );

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.16.1.1. MySqlInfoMessageEventArgs Class

Provides data for the InfoMessage event. This class cannot be inherited.

For a list of all members of this type, see MySqlInfoMessageEventArgs Members .

Syntax: Visual Basic

    Public Class MySqlInfoMessageEventArgs_
      Inherits EventArgs

Syntax: C#

    public class MySqlInfoMessageEventArgs : EventArgs

Thread Safety

Public static (Sharedin Visual Basic) members of this type are safe for multithreaded operations. Instance members are notguaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlInfoMessageEventArgs Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.16.1.1.1. MySqlInfoMessageEventArgs Members

MySqlInfoMessageEventArgs overview

Public Instance Constructors

MySqlInfoMessageEventArgs Constructor | Initializes a new instance of the MySqlInfoMessageEventArgs class.

Public Instance Fields

errors |

Public Instance Methods

Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetType(inherited from Object) | Gets the Typeof the current instance.
ToString(inherited from Object) | Returns a Stringthat represents the current Object.

Protected Instance Methods

Finalize(inherited from Object) | Allows an Objectto attempt to free resources and perform other cleanup operations before the Objectis reclaimed by garbage collection.
MemberwiseClone(inherited from Object) | Creates a shallow copy of the current Object.

See Also

MySqlInfoMessageEventArgs Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.16.1.1.1.1. MySqlInfoMessageEventArgs Constructor

Initializes a new instance of the MySqlInfoMessageEventArgs class.

Syntax: Visual Basic

    Public Sub New()

Syntax: C#

    public MySqlInfoMessageEventArgs();

See Also

MySqlInfoMessageEventArgs Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.16.1.1.1.2. MySqlInfoMessageEventArgs.errors Field

Syntax: Visual Basic

    Public errors As MySqlError()

Syntax: C#

    public MySqlError[] errors;

See Also

MySqlInfoMessageEventArgs Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.16.1.1.1.2.1. MySqlError Class

Collection of error codes that can be returned by the server

For a list of all members of this type, see MySqlError Members .

Syntax: Visual Basic

    Public Class MySqlError

Syntax: C#

    public class MySqlError

Thread Safety

Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlError Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.16.1.1.1.2.1.1. MySqlError Members

MySqlError overview

Public Instance Constructors

MySqlError Constructor |

Public Instance Properties

Code | Error code
Level | Error level
Message | Error message

Public Instance Methods

Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetType(inherited from Object) | Gets the Typeof the current instance.
ToString(inherited from Object) | Returns a Stringthat represents the current Object.

Protected Instance Methods

Finalize(inherited from Object) | Allows an Objectto attempt to free resources and perform other cleanup operations before the Objectis reclaimed by garbage collection.
MemberwiseClone(inherited from Object) | Creates a shallow copy of the current Object.

See Also

MySqlError Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.16.1.1.1.2.1.1.1. MySqlError Constructor

Syntax: Visual Basic

    Public Sub New( _
       ByVal level As String, _
       ByVal code As Integer, _
       ByVal message As String _
    )

Syntax: C#

    public MySqlError(
    stringlevel,
    intcode,
    stringmessage
    );

Parameters

- `level`:

- `code`:

- `message`:

See Also

MySqlError Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.16.1.1.1.2.1.1.2. Code Property

Error code

Syntax: Visual Basic

    Public ReadOnly Property Code As Integer

Syntax: C#

    public int Code {get;}

See Also

MySqlError Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.16.1.1.1.2.1.1.3. Level Property

Error level

Syntax: Visual Basic

    Public ReadOnly Property Level As String

Syntax: C#

    public string Level {get;}

See Also

MySqlError Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.16.1.1.1.2.1.1.4. Message Property

Error message

Syntax: Visual Basic

    Public ReadOnly Property Message As String

Syntax: C#

    public string Message {get;}

See Also

MySqlError Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.3.1.1.17. MySqlConnection.StateChange Event

Syntax: Visual Basic

    Public Event StateChange As StateChangeEventHandler

Syntax: C#

    public event StateChangeEventHandler StateChange;

See Also

MySqlConnection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.1.4. MySqlCommand Constructor (String, MySqlConnection, MySqlTransaction)

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal cmdText As String, _
       ByVal connection As MySqlConnection, _
       ByVal transaction As MySqlTransaction _
    )

Syntax: C#

    public MySqlCommand(
    stringcmdText,
    MySqlConnectionconnection,
    MySqlTransactiontransaction
    );

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace , MySqlCommand Constructor Overload List

###### 18.2.4.1.2.1.2. CommandText Property

Syntax: Visual Basic

    NotOverridable Public Property CommandText As String _
    _
      Implements IDbCommand.CommandText

Syntax: C#

    public string CommandText {get; set;}

Implements

IDbCommand.CommandText

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.3. CommandTimeout Property

Syntax: Visual Basic

    NotOverridable Public Property CommandTimeout As Integer _
    _
      Implements IDbCommand.CommandTimeout

Syntax: C#

    public int CommandTimeout {get; set;}

Implements

IDbCommand.CommandTimeout

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.4. CommandType Property

Syntax: Visual Basic

    NotOverridable Public Property CommandType As CommandType _
    _
      Implements IDbCommand.CommandType

Syntax: C#

    public System.Data.CommandType CommandType {get; set;}

Implements

IDbCommand.CommandType

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.5. Connection Property

Syntax: Visual Basic

    Public Property Connection As MySqlConnection

Syntax: C#

    public MySqlConnection Connection {get; set;}

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.6. IsPrepared Property

Syntax: Visual Basic

    Public ReadOnly Property IsPrepared As Boolean

Syntax: C#

    public bool IsPrepared {get;}

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7. Parameters Property

Syntax: Visual Basic

    Public ReadOnly Property Parameters As MySqlParameterCollection

Syntax: C#

    public MySqlParameterCollection Parameters {get;}

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1. MySqlParameterCollection Class

Represents a collection of parameters relevant to a MySqlCommand as well as their respective mappings to columns in a DataSet. This class cannot be inherited.

For a list of all members of this type, see MySqlParameterCollection Members .

Syntax: Visual Basic

    NotInheritable Public Class MySqlParameterCollection_
      Inherits MarshalByRefObject_
      Implements IDataParameterCollection, IList, ICollection, IEnumerable

Syntax: C#

    public sealed class MySqlParameterCollection : MarshalByRefObject, IDataParameterCollection, IList, ICollection, IEnumerable

Thread Safety

Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlParameterCollection Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1. MySqlParameterCollection Members

MySqlParameterCollection overview

Public Instance Constructors

MySqlParameterCollection Constructor | Initializes a new instance of the MySqlParameterCollection class.

Public Instance Properties

Count | Gets the number of MySqlParameter objects in the collection.
Item | Overloaded. Gets the MySqlParameter with a specified attribute. In C#, this property is the indexer for the MySqlParameterCollection class.

Public Instance Methods

Add | Overloaded. Adds the specified MySqlParameter object to the MySqlParameterCollection .
Clear | Removes all items from the collection.
Contains | Overloaded. Gets a value indicating whether a MySqlParameter exists in the collection.
CopyTo | Copies MySqlParameter objects from the MySqlParameterCollection to the specified array.
CreateObjRef(inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.
Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetLifetimeService(inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance.
GetType(inherited from Object) | Gets the Typeof the current instance.
IndexOf | Overloaded. Gets the location of a MySqlParameter in the collection.
InitializeLifetimeService(inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance.
Insert | Inserts a MySqlParameter into the collection at the specified index.
Remove | Removes the specified MySqlParameter from the collection.
RemoveAt | Overloaded. Removes the specified MySqlParameter from the collection.
ToString(inherited from Object) | Returns a Stringthat represents the current Object.

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.1. MySqlParameterCollection Constructor

Initializes a new instance of the MySqlParameterCollection class.

Syntax: Visual Basic

    Public Sub New()

Syntax: C#

    public MySqlParameterCollection();

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.2. Count Property

Gets the number of MySqlParameter objects in the collection.

Syntax: Visual Basic

    NotOverridable Public ReadOnly Property Count As Integer _
    _
      Implements ICollection.Count

Syntax: C#

    public int Count {get;}

Implements

ICollection.Count

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3. Item Property

Gets the MySqlParameter with a specified attribute. In C#, this property is the indexer for the MySqlParameterCollection class.

Overload List

Gets the MySqlParameter at the specified index.

- public MySqlParameter this[int] {get; set;}

Gets the MySqlParameter with the specified name.

- public MySqlParameter this[string] {get; set;}

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1. MySqlParameter Class

Represents a parameter to a MySqlCommand , and optionally, its mapping to DataSetcolumns. This class cannot be inherited.

For a list of all members of this type, see MySqlParameter Members .

Syntax: Visual Basic

    NotInheritable Public Class MySqlParameter_
      Inherits MarshalByRefObject_
      Implements IDataParameter, IDbDataParameter, ICloneable

Syntax: C#

    public sealed class MySqlParameter : MarshalByRefObject, IDataParameter, IDbDataParameter, ICloneable

Thread Safety

Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlParameter Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1. MySqlParameter Members

MySqlParameter overview

Public Instance Constructors

MySqlParameter | Overloaded. Initializes a new instance of the MySqlParameter class.

Public Instance Properties

DbType | Gets or sets the DbTypeof the parameter.
Direction | Gets or sets a value indicating whether the parameter is input-only, output-only, bidirectional, or a stored procedure return value parameter. As of MySql version 4.1 and earlier, input-only is the only valid choice.
IsNullable | Gets or sets a value indicating whether the parameter accepts null values.
IsUnsigned |
MySqlDbType | Gets or sets the MySqlDbType of the parameter.
ParameterName | Gets or sets the name of the MySqlParameter.
Precision | Gets or sets the maximum number of digits used to represent the Value property.
Scale | Gets or sets the number of decimal places to which Value is resolved.
Size | Gets or sets the maximum size, in bytes, of the data within the column.
SourceColumn | Gets or sets the name of the source column that is mapped to the DataSetand used for loading or returning the Value .
SourceVersion | Gets or sets the DataRowVersionto use when loading Value .
Value | Gets or sets the value of the parameter.

Public Instance Methods

CreateObjRef(inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.
Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetLifetimeService(inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance.
GetType(inherited from Object) | Gets the Typeof the current instance.
InitializeLifetimeService(inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance.
ToString | Overridden. Gets a string containing the ParameterName .

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.1. MySqlParameter Constructor

Initializes a new instance of the MySqlParameter class.

Overload List

Initializes a new instance of the MySqlParameter class.

- public MySqlParameter();

Initializes a new instance of the MySqlParameter class with the parameter name and the data type.

- public MySqlParameter(string,MySqlDbType);

Initializes a new instance of the MySqlParameter class with the parameter name, the MySqlDbType , and the size.

- public MySqlParameter(string,MySqlDbType,int);

Initializes a new instance of the MySqlParameter class with the parameter name, the type of the parameter, the size of the parameter, a ParameterDirection, the precision of the parameter, the scale of the parameter, the source column, a DataRowVersionto use, and the value of the parameter.

- public MySqlParameter(string,MySqlDbType,int,ParameterDirection,bool,byte,byte,string,DataRowVersion,object);

Initializes a new instance of the MySqlParameter class with the parameter name, the MySqlDbType , the size, and the source column name.

- public MySqlParameter(string,MySqlDbType,int,string);

Initializes a new instance of the MySqlParameter class with the parameter name and a value of the new MySqlParameter.

- public MySqlParameter(string,object);

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.1.1. MySqlParameter Constructor ()

Initializes a new instance of the MySqlParameter class.

Syntax: Visual Basic

    Overloads Public Sub New()

Syntax: C#

    public MySqlParameter();

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace , MySqlParameter Constructor Overload List

###### 18.2.4.1.2.1.7.1.1.3.1.1.1.2. MySqlParameter Constructor (String, MySqlDbType)

Initializes a new instance of the MySqlParameter class with the parameter name and the data type.

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal parameterName As String, _
       ByVal dbType As MySqlDbType _
    )

Syntax: C#

    public MySqlParameter(
    stringparameterName,
    MySqlDbTypedbType
    );

Parameters

- `parameterName`: The name of the parameter to map.

- `dbType`: One of the MySqlDbType values.

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace , MySqlParameter Constructor Overload List

###### 18.2.4.1.2.1.7.1.1.3.1.1.1.2.1. MySqlDbType Enumeration

Specifies MySQL specific data type of a field, property, for use in a MySqlParameter .

Syntax: Visual Basic

    Public Enum MySqlDbType

Syntax: C#

    public enum MySqlDbType

Members

Member Name | Description
VarString | A variable-length string containing 0 to 65535 characters
Timestamp | A timestamp. The range is '1970-01-01 00:00:01' to sometime in the year 2037
LongBlob | A BLOB or TEXT column with a maximum length of 4294967295 or 4G (2^32 - 1) characters
Time | The range is '-838:59:59' to '838:59:59'.
TinyBlob | A BLOB or TEXT column with a maximum length of 255 (2^8 - 1) characters
Datetime | The supported range is '1000-01-01 00:00:00' to '9999-12-31 23:59:59'.
Decimal | A fixed precision and scale numeric value between -1038 -1 and 10 38 -1.
UByte |
Blob | A BLOB or TEXT column with a maximum length of 65535 (2^16 - 1) characters
Double | A normal-size (double-precision) floating-point number. Allowable values are -1.7976931348623157E+308 to -2.2250738585072014E-308, 0, and 2.2250738585072014E-308 to 1.7976931348623157E+308.
Newdate | Obsolete Use Datetime or Date type
Byte | The signed range is -128 to 127. The unsigned range is 0 to 255.
Date | Date The supported range is '1000-01-01' to '9999-12-31'.
VarChar | A variable-length string containing 0 to 255 characters
UInt16 |
UInt24 |
Int16 | A 16-bit signed integer. The signed range is -32768 to 32767. The unsigned range is 0 to 65535
NewDecimal | New Decimal
Set | A set. A string object that can have zero or more values, each of which must be chosen from the list of values 'value1', 'value2', ... A SET can have a maximum of 64 members.
String | Obsolete Use VarChar type
Enum | An enumeration. A string object that can have only one value, chosen from the list of values 'value1', 'value2', ..., NULL or the special "" error value. An ENUM can have a maximum of 65535 distinct values
Geometry |
UInt64 |
Int64 | A 64-bit signed integer.
UInt32 |
Int24 | Specifies a 24 (3 byte) signed or unsigned value.
Bit | Bit-field data type
Float | A small (single-precision) floating-point number. Allowable values are -3.402823466E+38 to -1.175494351E-38, 0, and 1.175494351E-38 to 3.402823466E+38.
Year | A year in 2- or 4-digit format (default is 4-digit). The allowable values are 1901 to 2155, 0000 in the 4-digit year format, and 1970-2069 if you use the 2-digit format (70-69)
Int32 | A 32-bit signed integer
MediumBlob | A BLOB or TEXT column with a maximum length of 16777215 (2^24 - 1) characters

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.1.3. MySqlParameter Constructor (String, MySqlDbType, Int32)

Initializes a new instance of the MySqlParameter class with the parameter name, the MySqlDbType , and the size.

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal parameterName As String, _
       ByVal dbType As MySqlDbType, _
       ByVal size As Integer _
    )

Syntax: C#

    public MySqlParameter(
    stringparameterName,
    MySqlDbTypedbType,
    intsize
    );

Parameters

- `parameterName`: The name of the parameter to map.

- `dbType`: One of the MySqlDbType values.

- `size`: The length of the parameter.

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace , MySqlParameter Constructor Overload List

###### 18.2.4.1.2.1.7.1.1.3.1.1.1.4. MySqlParameter Constructor (String, MySqlDbType, Int32, ParameterDirection, Boolean, Byte, Byte, String, DataRowVersion, Object)

Initializes a new instance of the MySqlParameter class with the parameter name, the type of the parameter, the size of the parameter, a ParameterDirection, the precision of the parameter, the scale of the parameter, the source column, a DataRowVersionto use, and the value of the parameter.

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal parameterName As String, _
       ByVal dbType As MySqlDbType, _
       ByVal size As Integer, _
       ByVal direction As ParameterDirection, _
       ByVal isNullable As Boolean, _
       ByVal precision As Byte, _
       ByVal scale As Byte, _
       ByVal sourceColumn As String, _
       ByVal sourceVersion As DataRowVersion, _
       ByVal value As Object _
    )

Syntax: C#

    public MySqlParameter(
    stringparameterName,
    MySqlDbTypedbType,
    intsize,
    ParameterDirectiondirection,
    boolisNullable,
    byteprecision,
    bytescale,
    stringsourceColumn,
    DataRowVersionsourceVersion,
    objectvalue
    );

Parameters

- `parameterName`: The name of the parameter to map.

- `dbType`: One of the MySqlDbType values.

- `size`: The length of the parameter.

- `direction`: One of the ParameterDirectionvalues.

- `isNullable`: true if the value of the field can be null, otherwise false.

- `precision`: The total number of digits to the left and right of the decimal point to which Value is resolved.

- `scale`: The total number of decimal places to which Value is resolved.

- `sourceColumn`: The name of the source column.

- `sourceVersion`: One of the DataRowVersionvalues.

- `value`: An Objectthat is the value of the MySqlParameter .

Exceptions

Exception Type | Condition
ArgumentException |

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace , MySqlParameter Constructor Overload List

###### 18.2.4.1.2.1.7.1.1.3.1.1.1.4.1. Value Property

Gets or sets the value of the parameter.

Syntax: Visual Basic

    NotOverridable Public Property Value As Object _
    _
      Implements IDataParameter.Value

Syntax: C#

    public object Value {get; set;}

Implements

IDataParameter.Value

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.1.5. MySqlParameter Constructor (String, MySqlDbType, Int32, String)

Initializes a new instance of the MySqlParameter class with the parameter name, the MySqlDbType , the size, and the source column name.

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal parameterName As String, _
       ByVal dbType As MySqlDbType, _
       ByVal size As Integer, _
       ByVal sourceColumn As String _
    )

Syntax: C#

    public MySqlParameter(
    stringparameterName,
    MySqlDbTypedbType,
    intsize,
    stringsourceColumn
    );

Parameters

- `parameterName`: The name of the parameter to map.

- `dbType`: One of the MySqlDbType values.

- `size`: The length of the parameter.

- `sourceColumn`: The name of the source column.

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace , MySqlParameter Constructor Overload List

###### 18.2.4.1.2.1.7.1.1.3.1.1.1.6. MySqlParameter Constructor (String, Object)

Initializes a new instance of the MySqlParameter class with the parameter name and a value of the new MySqlParameter.

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal parameterName As String, _
       ByVal value As Object _
    )

Syntax: C#

    public MySqlParameter(
    stringparameterName,
    objectvalue
    );

Parameters

- `parameterName`: The name of the parameter to map.

- `value`: An Objectthat is the value of the MySqlParameter .

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace , MySqlParameter Constructor Overload List

###### 18.2.4.1.2.1.7.1.1.3.1.1.2. DbType Property

Gets or sets the DbTypeof the parameter.

Syntax: Visual Basic

    NotOverridable Public Property DbType As DbType _
    _
      Implements IDataParameter.DbType

Syntax: C#

    public System.Data.DbType DbType {get; set;}

Implements

IDataParameter.DbType

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.3. Direction Property

Gets or sets a value indicating whether the parameter is input-only, output-only, bidirectional, or a stored procedure return value parameter. As of MySql version 4.1 and earlier, input-only is the only valid choice.

Syntax: Visual Basic

    NotOverridable Public Property Direction As ParameterDirection _
    _
      Implements IDataParameter.Direction

Syntax: C#

    public System.Data.ParameterDirection Direction {get; set;}

Implements

IDataParameter.Direction

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.4. IsNullable Property

Gets or sets a value indicating whether the parameter accepts null values.

Syntax: Visual Basic

    NotOverridable Public Property IsNullable As Boolean _
    _
      Implements IDataParameter.IsNullable

Syntax: C#

    public bool IsNullable {get; set;}

Implements

IDataParameter.IsNullable

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.5. IsUnsigned Property

Syntax: Visual Basic

    Public Property IsUnsigned As Boolean

Syntax: C#

    public bool IsUnsigned {get; set;}

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.6. MySqlDbType Property

Gets or sets the MySqlDbType of the parameter.

Syntax: Visual Basic

    Public Property MySqlDbType As MySqlDbType

Syntax: C#

    public MySqlDbType MySqlDbType {get; set;}

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.7. ParameterName Property

Gets or sets the name of the MySqlParameter.

Syntax: Visual Basic

    NotOverridable Public Property ParameterName As String _
    _
      Implements IDataParameter.ParameterName

Syntax: C#

    public string ParameterName {get; set;}

Implements

IDataParameter.ParameterName

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.8. Precision Property

Gets or sets the maximum number of digits used to represent the Value property.

Syntax: Visual Basic

    NotOverridable Public Property Precision As Byte _
    _
      Implements IDbDataParameter.Precision

Syntax: C#

    public byte Precision {get; set;}

Implements

IDbDataParameter.Precision

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.9. Scale Property

Gets or sets the number of decimal places to which Value is resolved.

Syntax: Visual Basic

    NotOverridable Public Property Scale As Byte _
    _
      Implements IDbDataParameter.Scale

Syntax: C#

    public byte Scale {get; set;}

Implements

IDbDataParameter.Scale

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.10. Size Property

Gets or sets the maximum size, in bytes, of the data within the column.

Syntax: Visual Basic

    NotOverridable Public Property Size As Integer _
    _
      Implements IDbDataParameter.Size

Syntax: C#

    public int Size {get; set;}

Implements

IDbDataParameter.Size

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.11. SourceColumn Property

Gets or sets the name of the source column that is mapped to the DataSetand used for loading or returning the Value .

Syntax: Visual Basic

    NotOverridable Public Property SourceColumn As String _
    _
      Implements IDataParameter.SourceColumn

Syntax: C#

    public string SourceColumn {get; set;}

Implements

IDataParameter.SourceColumn

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.12. SourceVersion Property

Gets or sets the DataRowVersionto use when loading Value .

Syntax: Visual Basic

    NotOverridable Public Property SourceVersion As DataRowVersion _
    _
      Implements IDataParameter.SourceVersion

Syntax: C#

    public System.Data.DataRowVersion SourceVersion {get; set;}

Implements

IDataParameter.SourceVersion

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.1.1.13. MySqlParameter.ToString Method

Overridden. Gets a string containing the ParameterName .

Syntax: Visual Basic

    Overrides Public Function ToString() As String

Syntax: C#

    public override string ToString();

Return Value

See Also

MySqlParameter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.3.2. Item Property (Int32)

Gets the MySqlParameter at the specified index.

Syntax: Visual Basic

    Overloads Public Default Property Item( _
       ByVal index As Integer _
    ) As MySqlParameter

Syntax: C#

    public MySqlParameter this[
    intindex
    ] {get; set;}

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.Item Overload List

###### 18.2.4.1.2.1.7.1.1.3.3. Item Property (String)

Gets the MySqlParameter with the specified name.

Syntax: Visual Basic

    Overloads Public Default Property Item( _
       ByVal name As String _
    ) As MySqlParameter

Syntax: C#

    public MySqlParameter this[
    stringname
    ] {get; set;}

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.Item Overload List

###### 18.2.4.1.2.1.7.1.1.4. Add Method

Adds the specified MySqlParameter object to the MySqlParameterCollection .

Overload List

Adds the specified MySqlParameter object to the MySqlParameterCollection .

- public MySqlParameter Add(MySqlParameter);

Adds the specified MySqlParameter object to the MySqlParameterCollection .

- public int Add(object);

Adds a MySqlParameter to the MySqlParameterCollection given the parameter name and the data type.

- public MySqlParameter Add(string,MySqlDbType);

Adds a MySqlParameter to the MySqlParameterCollection with the parameter name, the data type, and the column length.

- public MySqlParameter Add(string,MySqlDbType,int);

Adds a MySqlParameter to the MySqlParameterCollection with the parameter name, the data type, the column length, and the source column name.

- public MySqlParameter Add(string,MySqlDbType,int,string);

Adds a MySqlParameter to the MySqlParameterCollection given the specified parameter name and value.

- public MySqlParameter Add(string,object);

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.4.1. MySqlParameterCollection.Add Method (MySqlParameter)

Adds the specified MySqlParameter object to the MySqlParameterCollection .

Syntax: Visual Basic

    Overloads Public Function Add( _
       ByVal value As MySqlParameter _
    ) As MySqlParameter

Syntax: C#

    public MySqlParameter Add(
    MySqlParametervalue
    );

Parameters

- `value`: The MySqlParameter to add to the collection.

Return Value

The newly added MySqlParameter object.

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.Add Overload List

###### 18.2.4.1.2.1.7.1.1.4.2. MySqlParameterCollection.Add Method (Object)

Adds the specified MySqlParameter object to the MySqlParameterCollection .

Syntax: Visual Basic

    NotOverridable Overloads Public Function Add( _
       ByVal value As Object _
    ) As Integer _
    _
      Implements IList.Add

Syntax: C#

    public int Add(
    objectvalue
    );

Parameters

- `value`: The MySqlParameter to add to the collection.

Return Value

The index of the new MySqlParameter object.

Implements

IList.Add

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.Add Overload List

###### 18.2.4.1.2.1.7.1.1.4.3. MySqlParameterCollection.Add Method (String, MySqlDbType)

Adds a MySqlParameter to the MySqlParameterCollection given the parameter name and the data type.

Syntax: Visual Basic

    Overloads Public Function Add( _
       ByVal parameterName As String, _
       ByVal dbType As MySqlDbType _
    ) As MySqlParameter

Syntax: C#

    public MySqlParameter Add(
    stringparameterName,
    MySqlDbTypedbType
    );

Parameters

- `parameterName`: The name of the parameter.

- `dbType`: One of the MySqlDbType values.

Return Value

The newly added MySqlParameter object.

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.Add Overload List

###### 18.2.4.1.2.1.7.1.1.4.4. MySqlParameterCollection.Add Method (String, MySqlDbType, Int32)

Adds a MySqlParameter to the MySqlParameterCollection with the parameter name, the data type, and the column length.

Syntax: Visual Basic

    Overloads Public Function Add( _
       ByVal parameterName As String, _
       ByVal dbType As MySqlDbType, _
       ByVal size As Integer _
    ) As MySqlParameter

Syntax: C#

    public MySqlParameter Add(
    stringparameterName,
    MySqlDbTypedbType,
    intsize
    );

Parameters

- `parameterName`: The name of the parameter.

- `dbType`: One of the MySqlDbType values.

- `size`: The length of the column.

Return Value

The newly added MySqlParameter object.

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.Add Overload List

###### 18.2.4.1.2.1.7.1.1.4.5. MySqlParameterCollection.Add Method (String, MySqlDbType, Int32, String)

Adds a MySqlParameter to the MySqlParameterCollection with the parameter name, the data type, the column length, and the source column name.

Syntax: Visual Basic

    Overloads Public Function Add( _
       ByVal parameterName As String, _
       ByVal dbType As MySqlDbType, _
       ByVal size As Integer, _
       ByVal sourceColumn As String _
    ) As MySqlParameter

Syntax: C#

    public MySqlParameter Add(
    stringparameterName,
    MySqlDbTypedbType,
    intsize,
    stringsourceColumn
    );

Parameters

- `parameterName`: The name of the parameter.

- `dbType`: One of the MySqlDbType values.

- `size`: The length of the column.

- `sourceColumn`: The name of the source column.

Return Value

The newly added MySqlParameter object.

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.Add Overload List

###### 18.2.4.1.2.1.7.1.1.4.6. MySqlParameterCollection.Add Method (String, Object)

Adds a MySqlParameter to the MySqlParameterCollection given the specified parameter name and value.

Syntax: Visual Basic

    Overloads Public Function Add( _
       ByVal parameterName As String, _
       ByVal value As Object _
    ) As MySqlParameter

Syntax: C#

    public MySqlParameter Add(
    stringparameterName,
    objectvalue
    );

Parameters

- `parameterName`: The name of the parameter.

- `value`: The Value of the MySqlParameter to add to the collection.

Return Value

The newly added MySqlParameter object.

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.Add Overload List

###### 18.2.4.1.2.1.7.1.1.5. MySqlParameterCollection.Clear Method

Removes all items from the collection.

Syntax: Visual Basic

    NotOverridable Public Sub Clear() _
    _
      Implements IList.Clear

Syntax: C#

    public void Clear();

Implements

IList.Clear

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.6. Contains Method

Gets a value indicating whether a MySqlParameter exists in the collection.

Overload List

Gets a value indicating whether a MySqlParameter exists in the collection.

- public bool Contains(object);

Gets a value indicating whether a MySqlParameter with the specified parameter name exists in the collection.

- public bool Contains(string);

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.6.1. MySqlParameterCollection.Contains Method (Object)

Gets a value indicating whether a MySqlParameter exists in the collection.

Syntax: Visual Basic

    NotOverridable Overloads Public Function Contains( _
       ByVal value As Object _
    ) As Boolean _
    _
      Implements IList.Contains

Syntax: C#

    public bool Contains(
    objectvalue
    );

Parameters

- `value`: The value of the MySqlParameter object to find.

Return Value

true if the collection contains the MySqlParameter object; otherwise, false.

Implements

IList.Contains

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.Contains Overload List

###### 18.2.4.1.2.1.7.1.1.6.2. MySqlParameterCollection.Contains Method (String)

Gets a value indicating whether a MySqlParameter with the specified parameter name exists in the collection.

Syntax: Visual Basic

    NotOverridable Overloads Public Function Contains( _
       ByVal name As String _
    ) As Boolean _
    _
      Implements IDataParameterCollection.Contains

Syntax: C#

    public bool Contains(
    stringname
    );

Parameters

- `name`: The name of the MySqlParameter object to find.

Return Value

true if the collection contains the parameter; otherwise, false.

Implements

IDataParameterCollection.Contains

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.Contains Overload List

###### 18.2.4.1.2.1.7.1.1.7. MySqlParameterCollection.CopyTo Method

Copies MySqlParameter objects from the MySqlParameterCollection to the specified array.

Syntax: Visual Basic

    NotOverridable Public Sub CopyTo( _
       ByVal array As Array, _
       ByVal index As Integer _
    ) _
    _
      Implements ICollection.CopyTo

Syntax: C#

    public void CopyTo(
    Arrayarray,
    intindex
    );

Parameters

- `array`:

- `index`:

Implements

ICollection.CopyTo

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.8. IndexOf Method

Gets the location of a MySqlParameter in the collection.

Overload List

Gets the location of a MySqlParameter in the collection.

- public int IndexOf(object);

Gets the location of the MySqlParameter in the collection with a specific parameter name.

- public int IndexOf(string);

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.8.1. MySqlParameterCollection.IndexOf Method (Object)

Gets the location of a MySqlParameter in the collection.

Syntax: Visual Basic

    NotOverridable Overloads Public Function IndexOf( _
       ByVal value As Object _
    ) As Integer _
    _
      Implements IList.IndexOf

Syntax: C#

    public int IndexOf(
    objectvalue
    );

Parameters

- `value`: The MySqlParameter object to locate.

Return Value

The zero-based location of the MySqlParameter in the collection.

Implements

IList.IndexOf

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.IndexOf Overload List

###### 18.2.4.1.2.1.7.1.1.8.2. MySqlParameterCollection.IndexOf Method (String)

Gets the location of the MySqlParameter in the collection with a specific parameter name.

Syntax: Visual Basic

    NotOverridable Overloads Public Function IndexOf( _
       ByVal parameterName As String _
    ) As Integer _
    _
      Implements IDataParameterCollection.IndexOf

Syntax: C#

    public int IndexOf(
    stringparameterName
    );

Parameters

- `parameterName`: The name of the MySqlParameter object to retrieve.

Return Value

The zero-based location of the MySqlParameter in the collection.

Implements

IDataParameterCollection.IndexOf

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.IndexOf Overload List

###### 18.2.4.1.2.1.7.1.1.9. MySqlParameterCollection.Insert Method

Inserts a MySqlParameter into the collection at the specified index.

Syntax: Visual Basic

    NotOverridable Public Sub Insert( _
       ByVal index As Integer, _
       ByVal value As Object _
    ) _
    _
      Implements IList.Insert

Syntax: C#

    public void Insert(
    intindex,
    objectvalue
    );

Parameters

- `index`:

- `value`:

Implements

IList.Insert

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.10. MySqlParameterCollection.Remove Method

Removes the specified MySqlParameter from the collection.

Syntax: Visual Basic

    NotOverridable Public Sub Remove( _
       ByVal value As Object _
    ) _
    _
      Implements IList.Remove

Syntax: C#

    public void Remove(
    objectvalue
    );

Parameters

- `value`:

Implements

IList.Remove

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.11. RemoveAt Method

Removes the specified MySqlParameter from the collection.

Overload List

Removes the specified MySqlParameter from the collection using a specific index.

- public void RemoveAt(int);

Removes the specified MySqlParameter from the collection using the parameter name.

- public void RemoveAt(string);

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.7.1.1.11.1. MySqlParameterCollection.RemoveAt Method (Int32)

Removes the specified MySqlParameter from the collection using a specific index.

Syntax: Visual Basic

    NotOverridable Overloads Public Sub RemoveAt( _
       ByVal index As Integer _
    ) _
    _
      Implements IList.RemoveAt

Syntax: C#

    public void RemoveAt(
    intindex
    );

Parameters

- `index`: The zero-based index of the parameter.

Implements

IList.RemoveAt

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.RemoveAt Overload List

###### 18.2.4.1.2.1.7.1.1.11.2. MySqlParameterCollection.RemoveAt Method (String)

Removes the specified MySqlParameter from the collection using the parameter name.

Syntax: Visual Basic

    NotOverridable Overloads Public Sub RemoveAt( _
       ByVal name As String _
    ) _
    _
      Implements IDataParameterCollection.RemoveAt

Syntax: C#

    public void RemoveAt(
    stringname
    );

Parameters

- `name`: The name of the MySqlParameter object to retrieve.

Implements

IDataParameterCollection.RemoveAt

See Also

MySqlParameterCollection Class , MySql.Data.MySqlClient Namespace , MySqlParameterCollection.RemoveAt Overload List

###### 18.2.4.1.2.1.8. Transaction Property

Syntax: Visual Basic

    Public Property Transaction As MySqlTransaction

Syntax: C#

    public MySqlTransaction Transaction {get; set;}

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.9. UpdatedRowSource Property

Syntax: Visual Basic

    NotOverridable Public Property UpdatedRowSource As UpdateRowSource _
    _
      Implements IDbCommand.UpdatedRowSource

Syntax: C#

    public System.Data.UpdateRowSource UpdatedRowSource {get; set;}

Implements

IDbCommand.UpdatedRowSource

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.10. MySqlCommand.Cancel Method

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

Syntax: Visual Basic

    NotOverridable Public Sub Cancel() _
    _
      Implements IDbCommand.Cancel

Syntax: C#

    public void Cancel();

Implements

IDbCommand.Cancel

Remarks

Cancelling an executing command is currently not supported on any version of MySQL.

Exceptions

Exception Type | Condition
NotSupportedException | This operation is not supported.

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.11. MySqlCommand.CreateParameter Method

Creates a new instance of a MySqlParameter object.

Syntax: Visual Basic

    Public Function CreateParameter() As MySqlParameter

Syntax: C#

    public MySqlParameter CreateParameter();

Return Value

A MySqlParameter object.

Remarks

This method is a strongly-typed version of CreateParameter.

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.12. MySqlCommand.ExecuteNonQuery Method

Syntax: Visual Basic

    NotOverridable Public Function ExecuteNonQuery() As Integer _
    _
      Implements IDbCommand.ExecuteNonQuery

Syntax: C#

    public int ExecuteNonQuery();

Implements

IDbCommand.ExecuteNonQuery

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13. ExecuteReader Method

Overload List

- public MySqlDataReader ExecuteReader();

- public MySqlDataReader ExecuteReader(CommandBehavior);

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1. MySqlCommand.ExecuteReader Method ()

Syntax: Visual Basic

    Overloads Public Function ExecuteReader() As MySqlDataReader

Syntax: C#

    public MySqlDataReader ExecuteReader();

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace , MySqlCommand.ExecuteReader Overload List

###### 18.2.4.1.2.1.13.1.1. MySqlDataReader Class

Provides a means of reading a forward-only stream of rows from a MySQL database. This class cannot be inherited.

For a list of all members of this type, see MySqlDataReader Members .

Syntax: Visual Basic

    NotInheritable Public Class MySqlDataReader_
      Inherits MarshalByRefObject_
      Implements IEnumerable, IDataReader, IDisposable, IDataRecord

Syntax: C#

    public sealed class MySqlDataReader : MarshalByRefObject, IEnumerable, IDataReader, IDisposable, IDataRecord

Thread Safety

Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlDataReader Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1. MySqlDataReader Members

MySqlDataReader overview

Public Instance Properties

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 | Overloaded. Overloaded. 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.

Public Instance Methods

Close | Closes the MySqlDataReader object.
CreateObjRef(inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.
Equals(inherited from Object) | Determines whether the specified Objectis equal to the current 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 |
GetDecimal |
GetDouble |
GetFieldType | Gets the Type that is the data type of the object.
GetFloat |
GetGuid |
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetInt16 |
GetInt32 |
GetInt64 |
GetLifetimeService(inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance.
GetMySqlDateTime |
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 |
GetTimeSpan |
GetType(inherited from Object) | Gets the Typeof the current instance.
GetUInt16 |
GetUInt32 |
GetUInt64 |
GetValue | Gets the value of the specified column in its native format.
GetValues | Gets all attribute columns in the collection for the current row.
InitializeLifetimeService(inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance.
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.
ToString(inherited from Object) | Returns a Stringthat represents the current Object.

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.1. Depth Property

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

Syntax: Visual Basic

    NotOverridable Public ReadOnly Property Depth As Integer _
    _
      Implements IDataReader.Depth

Syntax: C#

    public int Depth {get;}

Implements

IDataReader.Depth

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.2. FieldCount Property

Gets the number of columns in the current row.

Syntax: Visual Basic

    NotOverridable Public ReadOnly Property FieldCount As Integer _
    _
      Implements IDataRecord.FieldCount

Syntax: C#

    public int FieldCount {get;}

Implements

IDataRecord.FieldCount

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.3. HasRows Property

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

Syntax: Visual Basic

    Public ReadOnly Property HasRows As Boolean

Syntax: C#

    public bool HasRows {get;}

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.4. IsClosed Property

Gets a value indicating whether the data reader is closed.

Syntax: Visual Basic

    NotOverridable Public ReadOnly Property IsClosed As Boolean _
    _
      Implements IDataReader.IsClosed

Syntax: C#

    public bool IsClosed {get;}

Implements

IDataReader.IsClosed

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.5. Item Property

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

Overload List

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

- public object this[int] {get;}

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

- public object this[string] {get;}

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.5.1. Item Property (Int32)

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

Syntax: Visual Basic

    NotOverridable Overloads Public Default ReadOnly Property Item( _
       ByVal i As Integer _
    ) _
    _
      Implements IDataRecord.Item As Object _
    _
      Implements IDataRecord.Item

Syntax: C#

    public object this[
    inti
    ] {get;}

Implements

IDataRecord.Item

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace , MySqlDataReader.Item Overload List

###### 18.2.4.1.2.1.13.1.1.1.5.2. Item Property (String)

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

Syntax: Visual Basic

    NotOverridable Overloads Public Default ReadOnly Property Item( _
       ByVal name As String _
    ) _
    _
      Implements IDataRecord.Item As Object _
    _
      Implements IDataRecord.Item

Syntax: C#

    public object this[
    stringname
    ] {get;}

Implements

IDataRecord.Item

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace , MySqlDataReader.Item Overload List

###### 18.2.4.1.2.1.13.1.1.1.6. RecordsAffected Property

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

Syntax: Visual Basic

    NotOverridable Public ReadOnly Property RecordsAffected As Integer _
    _
      Implements IDataReader.RecordsAffected

Syntax: C#

    public int RecordsAffected {get;}

Implements

IDataReader.RecordsAffected

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.7. MySqlDataReader.Close Method

Closes the MySqlDataReader object.

Syntax: Visual Basic

    NotOverridable Public Sub Close() _
    _
      Implements IDataReader.Close

Syntax: C#

    public void Close();

Implements

IDataReader.Close

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.8. MySqlDataReader.GetBoolean Method

Gets the value of the specified column as a Boolean.

Syntax: Visual Basic

    NotOverridable Public Function GetBoolean( _
       ByVal i As Integer _
    ) As Boolean _
    _
      Implements IDataRecord.GetBoolean

Syntax: C#

    public bool GetBoolean(
    inti
    );

Parameters

- `i`:

Return Value

Implements

IDataRecord.GetBoolean

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.9. MySqlDataReader.GetByte Method

Gets the value of the specified column as a byte.

Syntax: Visual Basic

    NotOverridable Public Function GetByte( _
       ByVal i As Integer _
    ) As Byte _
    _
      Implements IDataRecord.GetByte

Syntax: C#

    public byte GetByte(
    inti
    );

Parameters

- `i`:

Return Value

Implements

IDataRecord.GetByte

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.10. MySqlDataReader.GetBytes Method

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

Syntax: Visual Basic

    NotOverridable Public Function GetBytes( _
       ByVal i As Integer, _
       ByVal dataIndex As Long, _
       ByVal buffer As Byte(), _
       ByVal bufferIndex As Integer, _
       ByVal length As Integer _
    ) As Long _
    _
      Implements IDataRecord.GetBytes

Syntax: C#

    public long GetBytes(
    inti,
    longdataIndex,
    byte[]buffer,
    intbufferIndex,
    intlength
    );

Parameters

- `i`: The zero-based column ordinal.

- `dataIndex`: The index within the field from which to begin the read operation.

- `buffer`: The buffer into which to read the stream of bytes.

- `bufferIndex`: The index for buffer to begin the read operation.

- `length`: The maximum length to copy into the buffer.

Return Value

The actual number of bytes read.

Implements

IDataRecord.GetBytes

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.11. MySqlDataReader.GetChar Method

Gets the value of the specified column as a single character.

Syntax: Visual Basic

    NotOverridable Public Function GetChar( _
       ByVal i As Integer _
    ) As Char _
    _
      Implements IDataRecord.GetChar

Syntax: C#

    public char GetChar(
    inti
    );

Parameters

- `i`:

Return Value

Implements

IDataRecord.GetChar

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.12. MySqlDataReader.GetChars Method

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

Syntax: Visual Basic

    NotOverridable Public Function GetChars( _
       ByVal i As Integer, _
       ByVal fieldOffset As Long, _
       ByVal buffer As Char(), _
       ByVal bufferoffset As Integer, _
       ByVal length As Integer _
    ) As Long _
    _
      Implements IDataRecord.GetChars

Syntax: C#

    public long GetChars(
    inti,
    longfieldOffset,
    char[]buffer,
    intbufferoffset,
    intlength
    );

Parameters

- `i`:

- `fieldOffset`:

- `buffer`:

- `bufferoffset`:

- `length`:

Return Value

Implements

IDataRecord.GetChars

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.13. MySqlDataReader.GetDataTypeName Method

Gets the name of the source data type.

Syntax: Visual Basic

    NotOverridable Public Function GetDataTypeName( _
       ByVal i As Integer _
    ) As String _
    _
      Implements IDataRecord.GetDataTypeName

Syntax: C#

    public string GetDataTypeName(
    inti
    );

Parameters

- `i`:

Return Value

Implements

IDataRecord.GetDataTypeName

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.14. MySqlDataReader.GetDateTime Method

Syntax: Visual Basic

    NotOverridable Public Function GetDateTime( _
       ByVal index As Integer _
    ) As Date _
    _
      Implements IDataRecord.GetDateTime

Syntax: C#

    public DateTime GetDateTime(
    intindex
    );

Implements

IDataRecord.GetDateTime

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.15. MySqlDataReader.GetDecimal Method

Syntax: Visual Basic

    NotOverridable Public Function GetDecimal( _
       ByVal index As Integer _
    ) As Decimal _
    _
      Implements IDataRecord.GetDecimal

Syntax: C#

    public decimal GetDecimal(
    intindex
    );

Implements

IDataRecord.GetDecimal

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.16. MySqlDataReader.GetDouble Method

Syntax: Visual Basic

    NotOverridable Public Function GetDouble( _
       ByVal index As Integer _
    ) As Double _
    _
      Implements IDataRecord.GetDouble

Syntax: C#

    public double GetDouble(
    intindex
    );

Implements

IDataRecord.GetDouble

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.17. MySqlDataReader.GetFieldType Method

Gets the Type that is the data type of the object.

Syntax: Visual Basic

    NotOverridable Public Function GetFieldType( _
       ByVal i As Integer _
    ) As Type _
    _
      Implements IDataRecord.GetFieldType

Syntax: C#

    public Type GetFieldType(
    inti
    );

Parameters

- `i`:

Return Value

Implements

IDataRecord.GetFieldType

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.18. MySqlDataReader.GetFloat Method

Syntax: Visual Basic

    NotOverridable Public Function GetFloat( _
       ByVal index As Integer _
    ) As Single _
    _
      Implements IDataRecord.GetFloat

Syntax: C#

    public float GetFloat(
    intindex
    );

Implements

IDataRecord.GetFloat

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.19. MySqlDataReader.GetGuid Method

Syntax: Visual Basic

    NotOverridable Public Function GetGuid( _
       ByVal index As Integer _
    ) As Guid _
    _
      Implements IDataRecord.GetGuid

Syntax: C#

    public Guid GetGuid(
    intindex
    );

Implements

IDataRecord.GetGuid

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.20. MySqlDataReader.GetInt16 Method

Syntax: Visual Basic

    NotOverridable Public Function GetInt16( _
       ByVal index As Integer _
    ) As Short _
    _
      Implements IDataRecord.GetInt16

Syntax: C#

    public short GetInt16(
    intindex
    );

Implements

IDataRecord.GetInt16

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.21. MySqlDataReader.GetInt32 Method

Syntax: Visual Basic

    NotOverridable Public Function GetInt32( _
       ByVal index As Integer _
    ) As Integer _
    _
      Implements IDataRecord.GetInt32

Syntax: C#

    public int GetInt32(
    intindex
    );

Implements

IDataRecord.GetInt32

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.22. MySqlDataReader.GetInt64 Method

Syntax: Visual Basic

    NotOverridable Public Function GetInt64( _
       ByVal index As Integer _
    ) As Long _
    _
      Implements IDataRecord.GetInt64

Syntax: C#

    public long GetInt64(
    intindex
    );

Implements

IDataRecord.GetInt64

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.23. MySqlDataReader.GetMySqlDateTime Method

Syntax: Visual Basic

    Public Function GetMySqlDateTime( _
       ByVal index As Integer _
    ) As MySqlDateTime

Syntax: C#

    public MySqlDateTime GetMySqlDateTime(
    intindex
    );

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.24. MySqlDataReader.GetName Method

Gets the name of the specified column.

Syntax: Visual Basic

    NotOverridable Public Function GetName( _
       ByVal i As Integer _
    ) As String _
    _
      Implements IDataRecord.GetName

Syntax: C#

    public string GetName(
    inti
    );

Parameters

- `i`:

Return Value

Implements

IDataRecord.GetName

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.25. MySqlDataReader.GetOrdinal Method

Gets the column ordinal, given the name of the column.

Syntax: Visual Basic

    NotOverridable Public Function GetOrdinal( _
       ByVal name As String _
    ) As Integer _
    _
      Implements IDataRecord.GetOrdinal

Syntax: C#

    public int GetOrdinal(
    stringname
    );

Parameters

- `name`:

Return Value

Implements

IDataRecord.GetOrdinal

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.26. MySqlDataReader.GetSchemaTable Method

Returns a DataTable that describes the column metadata of the MySqlDataReader.

Syntax: Visual Basic

    NotOverridable Public Function GetSchemaTable() As DataTable _
    _
      Implements IDataReader.GetSchemaTable

Syntax: C#

    public DataTable GetSchemaTable();

Return Value

Implements

IDataReader.GetSchemaTable

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.27. MySqlDataReader.GetString Method

Syntax: Visual Basic

    NotOverridable Public Function GetString( _
       ByVal index As Integer _
    ) As String _
    _
      Implements IDataRecord.GetString

Syntax: C#

    public string GetString(
    intindex
    );

Implements

IDataRecord.GetString

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.28. MySqlDataReader.GetTimeSpan Method

Syntax: Visual Basic

    Public Function GetTimeSpan( _
       ByVal index As Integer _
    ) As TimeSpan

Syntax: C#

    public TimeSpan GetTimeSpan(
    intindex
    );

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.29. MySqlDataReader.GetUInt16 Method

Syntax: Visual Basic

    Public Function GetUInt16( _
       ByVal index As Integer _
    ) As UInt16

Syntax: C#

    public ushort GetUInt16(
    intindex
    );

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.30. MySqlDataReader.GetUInt32 Method

Syntax: Visual Basic

    Public Function GetUInt32( _
       ByVal index As Integer _
    ) As UInt32

Syntax: C#

    public uint GetUInt32(
    intindex
    );

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.31. MySqlDataReader.GetUInt64 Method

Syntax: Visual Basic

    Public Function GetUInt64( _
       ByVal index As Integer _
    ) As UInt64

Syntax: C#

    public ulong GetUInt64(
    intindex
    );

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.32. MySqlDataReader.GetValue Method

Gets the value of the specified column in its native format.

Syntax: Visual Basic

    NotOverridable Public Function GetValue( _
       ByVal i As Integer _
    ) As Object _
    _
      Implements IDataRecord.GetValue

Syntax: C#

    public object GetValue(
    inti
    );

Parameters

- `i`:

Return Value

Implements

IDataRecord.GetValue

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.33. MySqlDataReader.GetValues Method

Gets all attribute columns in the collection for the current row.

Syntax: Visual Basic

    NotOverridable Public Function GetValues( _
       ByVal values As Object() _
    ) As Integer _
    _
      Implements IDataRecord.GetValues

Syntax: C#

    public int GetValues(
    object[]values
    );

Parameters

- `values`:

Return Value

Implements

IDataRecord.GetValues

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.34. MySqlDataReader.IsDBNull Method

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

Syntax: Visual Basic

    NotOverridable Public Function IsDBNull( _
       ByVal i As Integer _
    ) As Boolean _
    _
      Implements IDataRecord.IsDBNull

Syntax: C#

    public bool IsDBNull(
    inti
    );

Parameters

- `i`:

Return Value

Implements

IDataRecord.IsDBNull

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.35. MySqlDataReader.NextResult Method

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

Syntax: Visual Basic

    NotOverridable Public Function NextResult() As Boolean _
    _
      Implements IDataReader.NextResult

Syntax: C#

    public bool NextResult();

Return Value

Implements

IDataReader.NextResult

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.1.1.1.36. MySqlDataReader.Read Method

Advances the MySqlDataReader to the next record.

Syntax: Visual Basic

    NotOverridable Public Function Read() As Boolean _
    _
      Implements IDataReader.Read

Syntax: C#

    public bool Read();

Return Value

Implements

IDataReader.Read

See Also

MySqlDataReader Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.13.2. MySqlCommand.ExecuteReader Method (CommandBehavior)

Syntax: Visual Basic

    Overloads Public Function ExecuteReader( _
       ByVal behavior As CommandBehavior _
    ) As MySqlDataReader

Syntax: C#

    public MySqlDataReader ExecuteReader(
    CommandBehaviorbehavior
    );

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace , MySqlCommand.ExecuteReader Overload List

###### 18.2.4.1.2.1.14. MySqlCommand.ExecuteScalar Method

Syntax: Visual Basic

    NotOverridable Public Function ExecuteScalar() As Object _
    _
      Implements IDbCommand.ExecuteScalar

Syntax: C#

    public object ExecuteScalar();

Implements

IDbCommand.ExecuteScalar

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.2.1.15. MySqlCommand.Prepare Method

Syntax: Visual Basic

    NotOverridable Public Sub Prepare() _
    _
      Implements IDbCommand.Prepare

Syntax: C#

    public void Prepare();

Implements

IDbCommand.Prepare

See Also

MySqlCommand Class , MySql.Data.MySqlClient Namespace

##### 18.2.4.1.3. MySqlCommandBuilder Class

For a list of all members of this type, see MySqlCommandBuilder Members .

Syntax: Visual Basic

    NotInheritable Public Class MySqlCommandBuilder_
      Inherits Component

Syntax: C#

    public sealed class MySqlCommandBuilder : Component

Thread Safety

Public static (Sharedin Visual Basic) members of this type are safe for multithreaded operations. Instance members are notguaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlCommandBuilder Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1. MySqlCommandBuilder Members

MySqlCommandBuilder overview

Public Static (Shared) Methods

DeriveParameters | Overloaded. 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.

Public Instance Constructors

MySqlCommandBuilder | Overloaded. Initializes a new instance of the MySqlCommandBuilder class.

Public Instance Properties

Container(inherited from Component) | Gets the IContainerthat contains the Component.
DataAdapter |
QuotePrefix |
QuoteSuffix |
Site(inherited from Component) | Gets or sets the ISiteof the Component.

Public Instance Methods

CreateObjRef(inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.
Dispose(inherited from Component) | Releases all resources used by the Component.
Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetDeleteCommand |
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetInsertCommand |
GetLifetimeService(inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance.
GetType(inherited from Object) | Gets the Typeof the current instance.
GetUpdateCommand |
InitializeLifetimeService(inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance.
RefreshSchema |
ToString(inherited from Component) | Returns a Stringcontaining the name of the Component, if any. This method should not be overridden.

Public Instance Events

Disposed(inherited from Component) | Adds an event handler to listen to the Disposedevent on the component.

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.1. DeriveParameters Method

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.

Overload List

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.

- public static void DeriveParameters(MySqlCommand);

- public static void DeriveParameters(MySqlCommand,bool);

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.1.1. MySqlCommandBuilder.DeriveParameters Method (MySqlCommand)

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.

Syntax: Visual Basic

    Overloads Public Shared Sub DeriveParameters( _
       ByVal command As MySqlCommand _
    )

Syntax: C#

    public static void DeriveParameters(
    MySqlCommandcommand
    );

Parameters

- `command`: The MySqlCommand referencing the stored procedure from which the parameter information is to be derived. The derived parameters are added to the Parameters collection of the MySqlCommand.

Exceptions

Exception Type | Condition
InvalidOperationException | The command text is not a valid stored procedure name.

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace , MySqlCommandBuilder.DeriveParameters Overload List

###### 18.2.4.1.3.1.1.2. MySqlCommandBuilder.DeriveParameters Method (MySqlCommand, Boolean)

Syntax: Visual Basic

    Overloads Public Shared Sub DeriveParameters( _
       ByVal command As MySqlCommand, _
       ByVal useProc As Boolean _
    )

Syntax: C#

    public static void DeriveParameters(
    MySqlCommandcommand,
    booluseProc
    );

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace , MySqlCommandBuilder.DeriveParameters Overload List

###### 18.2.4.1.3.1.2. MySqlCommandBuilder Constructor

Initializes a new instance of the MySqlCommandBuilder class.

Overload List

Initializes a new instance of the MySqlCommandBuilder class.

- public MySqlCommandBuilder();

- public MySqlCommandBuilder(MySqlDataAdapter);

- public MySqlCommandBuilder(MySqlDataAdapter,bool);

- public MySqlCommandBuilder(bool);

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.1. MySqlCommandBuilder Constructor ()

Initializes a new instance of the MySqlCommandBuilder class.

Syntax: Visual Basic

    Overloads Public Sub New()

Syntax: C#

    public MySqlCommandBuilder();

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace , MySqlCommandBuilder Constructor Overload List

###### 18.2.4.1.3.1.2.2. MySqlCommandBuilder Constructor (MySqlDataAdapter)

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal adapter As MySqlDataAdapter _
    )

Syntax: C#

    public MySqlCommandBuilder(
    MySqlDataAdapteradapter
    );

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace , MySqlCommandBuilder Constructor Overload List

###### 18.2.4.1.3.1.2.2.1. MySqlDataAdapter Class

For a list of all members of this type, see MySqlDataAdapter Members .

Syntax: Visual Basic

    NotInheritable Public Class MySqlDataAdapter_
      Inherits DbDataAdapter

Syntax: C#

    public sealed class MySqlDataAdapter : DbDataAdapter

Thread Safety

Public static (Sharedin Visual Basic) members of this type are safe for multithreaded operations. Instance members are notguaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlDataAdapter Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1. MySqlDataAdapter Members

MySqlDataAdapter overview

Public Instance Constructors

MySqlDataAdapter | Overloaded. Initializes a new instance of the MySqlDataAdapter class.

Public Instance Properties

AcceptChangesDuringFill(inherited from DataAdapter) | Gets or sets a value indicating whether AcceptChangesis called on a DataRowafter it is added to the DataTableduring any of the Fill operations.
AcceptChangesDuringUpdate(inherited from DataAdapter) | Gets or sets whether AcceptChangesis called during a Update.
Container(inherited from Component) | Gets the IContainerthat contains the Component.
ContinueUpdateOnError(inherited from DataAdapter) | Gets or sets a value that specifies whether to generate an exception when an error is encountered during a row update.
DeleteCommand | Overloaded.
FillLoadOption(inherited from DataAdapter) | Gets or sets the LoadOptionthat determines how the adapter fills the DataTablefrom the DbDataReader.
InsertCommand | Overloaded.
MissingMappingAction(inherited from DataAdapter) | Determines the action to take when incoming data does not have a matching table or column.
MissingSchemaAction(inherited from DataAdapter) | Determines the action to take when existing DataSetschema does not match incoming data.
ReturnProviderSpecificTypes(inherited from DataAdapter) | Gets or sets whether the Fillmethod should return provider-specific values or common CLS-compliant values.
SelectCommand | Overloaded.
Site(inherited from Component) | Gets or sets the ISiteof the Component.
TableMappings(inherited from DataAdapter) | Gets a collection that provides the master mapping between a source table and a DataTable.
UpdateBatchSize(inherited from DbDataAdapter) | Gets or sets a value that enables or disables batch processing support, and specifies the number of commands that can be executed in a batch.
UpdateCommand | Overloaded.

Public Instance Methods

CreateObjRef(inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.
Dispose(inherited from Component) | Releases all resources used by the Component.
Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
Fill(inherited from DbDataAdapter) | Overloaded. Adds or refreshes rows in the DataSetto match those in the data source using the DataSetname, and creates a DataTablenamed "Table."
FillSchema(inherited from DbDataAdapter) | Overloaded. Configures the schema of the specified DataTablebased on the specified SchemaType.
GetFillParameters(inherited from DbDataAdapter) | Gets the parameters set by the user when executing an SQL `SELECT` statement.
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetLifetimeService(inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance.
GetType(inherited from Object) | Gets the Typeof the current instance.
InitializeLifetimeService(inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance.
ResetFillLoadOption(inherited from DataAdapter) | Resets FillLoadOptionto its default state and causes Fillto honor AcceptChangesDuringFill.
ShouldSerializeAcceptChangesDuringFill(inherited from DataAdapter) | Determines whether the AcceptChangesDuringFillproperty should be persisted.
ShouldSerializeFillLoadOption(inherited from DataAdapter) | Determines whether the FillLoadOptionproperty should be persisted.
ToString(inherited from Component) | Returns a Stringcontaining the name of the Component, if any. This method should not be overridden.
Update(inherited from DbDataAdapter) | Overloaded. Calls the respective INSERT, UPDATE, or DELETE statements for each inserted, updated, or deleted row in the specified DataSet.

Public Instance Events

Disposed(inherited from Component) | Adds an event handler to listen to the Disposedevent on the component.
FillError(inherited from DataAdapter) | Returned when an error occurs during a fill operation.
RowUpdated | Occurs during Update after a command is executed against the data source. The attempt to update is made, so the event fires.
RowUpdating | Occurs during Update before a command is executed against the data source. The attempt to update is made, so the event fires.

Protected Internal Instance Properties

FillCommandBehavior(inherited from DbDataAdapter) | Gets or sets the behavior of the command used to fill the data adapter.

See Also

MySqlDataAdapter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.1. MySqlDataAdapter Constructor

Initializes a new instance of the MySqlDataAdapter class.

Overload List

Initializes a new instance of the MySqlDataAdapter class.

- public MySqlDataAdapter();

- public MySqlDataAdapter(MySqlCommand);

- public MySqlDataAdapter(string,MySqlConnection);

- public MySqlDataAdapter(string,string);

See Also

MySqlDataAdapter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.1.1. MySqlDataAdapter Constructor ()

Initializes a new instance of the MySqlDataAdapter class.

Syntax: Visual Basic

    Overloads Public Sub New()

Syntax: C#

    public MySqlDataAdapter();

See Also

MySqlDataAdapter Class , MySql.Data.MySqlClient Namespace , MySqlDataAdapter Constructor Overload List

###### 18.2.4.1.3.1.2.2.1.1.1.2. MySqlDataAdapter Constructor (MySqlCommand)

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal selectCommand As MySqlCommand _
    )

Syntax: C#

    public MySqlDataAdapter(
    MySqlCommandselectCommand
    );

See Also

MySqlDataAdapter Class , MySql.Data.MySqlClient Namespace , MySqlDataAdapter Constructor Overload List

###### 18.2.4.1.3.1.2.2.1.1.1.3. MySqlDataAdapter Constructor (String, MySqlConnection)

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal selectCommandText As String, _
       ByVal connection As MySqlConnection _
    )

Syntax: C#

    public MySqlDataAdapter(
    stringselectCommandText,
    MySqlConnectionconnection
    );

See Also

MySqlDataAdapter Class , MySql.Data.MySqlClient Namespace , MySqlDataAdapter Constructor Overload List

###### 18.2.4.1.3.1.2.2.1.1.1.4. MySqlDataAdapter Constructor (String, String)

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal selectCommandText As String, _
       ByVal selectConnString As String _
    )

Syntax: C#

    public MySqlDataAdapter(
    stringselectCommandText,
    stringselectConnString
    );

See Also

MySqlDataAdapter Class , MySql.Data.MySqlClient Namespace , MySqlDataAdapter Constructor Overload List

###### 18.2.4.1.3.1.2.2.1.1.2. DeleteCommand Property

Syntax: Visual Basic

    Overloads Public Property DeleteCommand As MySqlCommand

Syntax: C#

    new public MySqlCommand DeleteCommand {get; set;}

See Also

MySqlDataAdapter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.3. InsertCommand Property

Syntax: Visual Basic

    Overloads Public Property InsertCommand As MySqlCommand

Syntax: C#

    new public MySqlCommand InsertCommand {get; set;}

See Also

MySqlDataAdapter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.4. SelectCommand Property

Syntax: Visual Basic

    Overloads Public Property SelectCommand As MySqlCommand

Syntax: C#

    new public MySqlCommand SelectCommand {get; set;}

See Also

MySqlDataAdapter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.5. UpdateCommand Property

Syntax: Visual Basic

    Overloads Public Property UpdateCommand As MySqlCommand

Syntax: C#

    new public MySqlCommand UpdateCommand {get; set;}

See Also

MySqlDataAdapter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.6. MySqlDataAdapter.RowUpdated Event

Occurs during Update after a command is executed against the data source. The attempt to update is made, so the event fires.

Syntax: Visual Basic

    Public Event RowUpdated As MySqlRowUpdatedEventHandler

Syntax: C#

    public event MySqlRowUpdatedEventHandler RowUpdated;

Event Data

The event handler receives an argument of type MySqlRowUpdatedEventArgs containing data related to this event. The following MySqlRowUpdatedEventArgsproperties provide information specific to this event.

Property | Description
Command | Gets or sets the MySqlCommand executed when Update is called.
Errors | Gets any errors generated by the .NET Framework data provider when the Commandwas executed.
RecordsAffected | Gets the number of rows changed, inserted, or deleted by execution of the SQL statement.
Row | Gets the DataRowsent through an Update.
RowCount | Gets the number of rows processed in a batch of updated records.
StatementType | Gets the type of SQL statement executed.
Status | Gets the UpdateStatusof the Commandproperty.
TableMapping | Gets the DataTableMappingsent through an Update.

See Also

MySqlDataAdapter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.6.1. MySqlRowUpdatedEventHandler Delegate

Represents the method that will handle the RowUpdatedevent of a MySqlDataAdapter .

Syntax: Visual Basic

    Public Delegate Sub MySqlRowUpdatedEventHandler( _
       ByVal sender As Object, _
       ByVal e As MySqlRowUpdatedEventArgs _
    )

Syntax: C#

    public delegate void MySqlRowUpdatedEventHandler(
    objectsender,
    MySqlRowUpdatedEventArgse
    );

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.6.1.1. MySqlRowUpdatedEventArgs Class

Provides data for the RowUpdated event. This class cannot be inherited.

For a list of all members of this type, see MySqlRowUpdatedEventArgs Members .

Syntax: Visual Basic

    NotInheritable Public Class MySqlRowUpdatedEventArgs_
      Inherits RowUpdatedEventArgs

Syntax: C#

    public sealed class MySqlRowUpdatedEventArgs : RowUpdatedEventArgs

Thread Safety

Public static (Sharedin Visual Basic) members of this type are safe for multithreaded operations. Instance members are notguaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlRowUpdatedEventArgs Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.6.1.1.1. MySqlRowUpdatedEventArgs Members

MySqlRowUpdatedEventArgs overview

Public Instance Constructors

MySqlRowUpdatedEventArgs Constructor | Initializes a new instance of the MySqlRowUpdatedEventArgs class.

Public Instance Properties

Command | Overloaded. Gets or sets the MySqlCommand executed when Update is called.
Errors(inherited from RowUpdatedEventArgs) | Gets any errors generated by the .NET Framework data provider when the Commandwas executed.
RecordsAffected(inherited from RowUpdatedEventArgs) | Gets the number of rows changed, inserted, or deleted by execution of the SQL statement.
Row(inherited from RowUpdatedEventArgs) | Gets the DataRowsent through an Update.
RowCount(inherited from RowUpdatedEventArgs) | Gets the number of rows processed in a batch of updated records.
StatementType(inherited from RowUpdatedEventArgs) | Gets the type of SQL statement executed.
Status(inherited from RowUpdatedEventArgs) | Gets the UpdateStatusof the Commandproperty.
TableMapping(inherited from RowUpdatedEventArgs) | Gets the DataTableMappingsent through an Update.

Public Instance Methods

CopyToRows(inherited from RowUpdatedEventArgs) | Overloaded. Copies references to the modified rows into the provided array.
Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetType(inherited from Object) | Gets the Typeof the current instance.
ToString(inherited from Object) | Returns a Stringthat represents the current Object.

See Also

MySqlRowUpdatedEventArgs Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.6.1.1.1.1. MySqlRowUpdatedEventArgs Constructor

Initializes a new instance of the MySqlRowUpdatedEventArgs class.

Syntax: Visual Basic

    Public Sub New( _
       ByVal row As DataRow, _
       ByVal command As IDbCommand, _
       ByVal statementType As StatementType, _
       ByVal tableMapping As DataTableMapping _
    )

Syntax: C#

    public MySqlRowUpdatedEventArgs(
    DataRowrow,
    IDbCommandcommand,
    StatementTypestatementType,
    DataTableMappingtableMapping
    );

Parameters

- `row`: The DataRowsent through an Update.

- `command`: The IDbCommandexecuted when Updateis called.

- `statementType`: One of the StatementTypevalues that specifies the type of query executed.

- `tableMapping`: The DataTableMappingsent through an Update.

See Also

MySqlRowUpdatedEventArgs Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.6.1.1.1.2. Command Property

Gets or sets the MySqlCommand executed when Update is called.

Syntax: Visual Basic

    Overloads Public ReadOnly Property Command As MySqlCommand

Syntax: C#

    new public MySqlCommand Command {get;}

See Also

MySqlRowUpdatedEventArgs Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.7. MySqlDataAdapter.RowUpdating Event

Occurs during Update before a command is executed against the data source. The attempt to update is made, so the event fires.

Syntax: Visual Basic

    Public Event RowUpdating As MySqlRowUpdatingEventHandler

Syntax: C#

    public event MySqlRowUpdatingEventHandler RowUpdating;

Event Data

The event handler receives an argument of type MySqlRowUpdatingEventArgs containing data related to this event. The following MySqlRowUpdatingEventArgsproperties provide information specific to this event.

Property | Description
Command | Gets or sets the MySqlCommand to execute when performing the Update.
Errors | Gets any errors generated by the .NET Framework data provider when the Commandexecutes.
Row | Gets the DataRowthat will be sent to the server as part of an insert, update, or delete operation.
StatementType | Gets the type of SQL statement to execute.
Status | Gets or sets the UpdateStatusof the Commandproperty.
TableMapping | Gets the DataTableMappingto send through the Update.

See Also

MySqlDataAdapter Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.7.1. MySqlRowUpdatingEventHandler Delegate

Represents the method that will handle the RowUpdatingevent of a MySqlDataAdapter .

Syntax: Visual Basic

    Public Delegate Sub MySqlRowUpdatingEventHandler( _
       ByVal sender As Object, _
       ByVal e As MySqlRowUpdatingEventArgs _
    )

Syntax: C#

    public delegate void MySqlRowUpdatingEventHandler(
    objectsender,
    MySqlRowUpdatingEventArgse
    );

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.7.1.1. MySqlRowUpdatingEventArgs Class

Provides data for the RowUpdating event. This class cannot be inherited.

For a list of all members of this type, see MySqlRowUpdatingEventArgs Members .

Syntax: Visual Basic

    NotInheritable Public Class MySqlRowUpdatingEventArgs_
      Inherits RowUpdatingEventArgs

Syntax: C#

    public sealed class MySqlRowUpdatingEventArgs : RowUpdatingEventArgs

Thread Safety

Public static (Sharedin Visual Basic) members of this type are safe for multithreaded operations. Instance members are notguaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlRowUpdatingEventArgs Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.7.1.1.1. MySqlRowUpdatingEventArgs Members

MySqlRowUpdatingEventArgs overview

Public Instance Constructors

MySqlRowUpdatingEventArgs Constructor | Initializes a new instance of the MySqlRowUpdatingEventArgs class.

Public Instance Properties

Command | Overloaded. Gets or sets the MySqlCommand to execute when performing the Update.
Errors(inherited from RowUpdatingEventArgs) | Gets any errors generated by the .NET Framework data provider when the Commandexecutes.
Row(inherited from RowUpdatingEventArgs) | Gets the DataRowthat will be sent to the server as part of an insert, update, or delete operation.
StatementType(inherited from RowUpdatingEventArgs) | Gets the type of SQL statement to execute.
Status(inherited from RowUpdatingEventArgs) | Gets or sets the UpdateStatusof the Commandproperty.
TableMapping(inherited from RowUpdatingEventArgs) | Gets the DataTableMappingto send through the Update.

Public Instance Methods

Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetType(inherited from Object) | Gets the Typeof the current instance.
ToString(inherited from Object) | Returns a Stringthat represents the current Object.

See Also

MySqlRowUpdatingEventArgs Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.7.1.1.1.1. MySqlRowUpdatingEventArgs Constructor

Initializes a new instance of the MySqlRowUpdatingEventArgs class.

Syntax: Visual Basic

    Public Sub New( _
       ByVal row As DataRow, _
       ByVal command As IDbCommand, _
       ByVal statementType As StatementType, _
       ByVal tableMapping As DataTableMapping _
    )

Syntax: C#

    public MySqlRowUpdatingEventArgs(
    DataRowrow,
    IDbCommandcommand,
    StatementTypestatementType,
    DataTableMappingtableMapping
    );

Parameters

- `row`: The DataRowto Update.

- `command`: The IDbCommandto execute during Update.

- `statementType`: One of the StatementTypevalues that specifies the type of query executed.

- `tableMapping`: The DataTableMappingsent through an Update.

See Also

MySqlRowUpdatingEventArgs Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.2.1.1.7.1.1.1.2. Command Property

Gets or sets the MySqlCommand to execute when performing the Update.

Syntax: Visual Basic

    Overloads Public Property Command As MySqlCommand

Syntax: C#

    new public MySqlCommand Command {get; set;}

See Also

MySqlRowUpdatingEventArgs Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.2.3. MySqlCommandBuilder Constructor (MySqlDataAdapter, Boolean)

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal adapter As MySqlDataAdapter, _
       ByVal lastOneWins As Boolean _
    )

Syntax: C#

    public MySqlCommandBuilder(
    MySqlDataAdapteradapter,
    boollastOneWins
    );

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace , MySqlCommandBuilder Constructor Overload List

###### 18.2.4.1.3.1.2.4. MySqlCommandBuilder Constructor (Boolean)

Syntax: Visual Basic

    Overloads Public Sub New( _
       ByVal lastOneWins As Boolean _
    )

Syntax: C#

    public MySqlCommandBuilder(
    boollastOneWins
    );

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace , MySqlCommandBuilder Constructor Overload List

###### 18.2.4.1.3.1.3. DataAdapter Property

Syntax: Visual Basic

    Public Property DataAdapter As MySqlDataAdapter

Syntax: C#

    public MySqlDataAdapter DataAdapter {get; set;}

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.4. QuotePrefix Property

Syntax: Visual Basic

    Public Property QuotePrefix As String

Syntax: C#

    public string QuotePrefix {get; set;}

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.5. QuoteSuffix Property

Syntax: Visual Basic

    Public Property QuoteSuffix As String

Syntax: C#

    public string QuoteSuffix {get; set;}

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.6. MySqlCommandBuilder.GetDeleteCommand Method

Syntax: Visual Basic

    Public Function GetDeleteCommand() As MySqlCommand

Syntax: C#

    public MySqlCommand GetDeleteCommand();

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.7. MySqlCommandBuilder.GetInsertCommand Method

Syntax: Visual Basic

    Public Function GetInsertCommand() As MySqlCommand

Syntax: C#

    public MySqlCommand GetInsertCommand();

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.8. MySqlCommandBuilder.GetUpdateCommand Method

Syntax: Visual Basic

    Public Function GetUpdateCommand() As MySqlCommand

Syntax: C#

    public MySqlCommand GetUpdateCommand();

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.3.1.9. MySqlCommandBuilder.RefreshSchema Method

Syntax: Visual Basic

    Public Sub RefreshSchema()

Syntax: C#

    public void RefreshSchema();

See Also

MySqlCommandBuilder Class , MySql.Data.MySqlClient Namespace

##### 18.2.4.1.4. MySqlException Class

The exception that is thrown when MySQL returns an error. This class cannot be inherited.

For a list of all members of this type, see MySqlException Members .

Syntax: Visual Basic

    NotInheritable Public Class MySqlException_
      Inherits SystemException

Syntax: C#

    public sealed class MySqlException : SystemException

Thread Safety

Public static (Sharedin Visual Basic) members of this type are safe for multithreaded operations. Instance members are notguaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlException Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.4.1. MySqlException Members

MySqlException overview

Public Instance Properties

Data(inherited from Exception) | Gets a collection of key/value pairs that provide additional, user-defined information about the exception.
HelpLink(inherited from Exception) | Gets or sets a link to the help file associated with this exception.
InnerException(inherited from Exception) | Gets the Exceptioninstance that caused the current exception.
Message(inherited from Exception) | Gets a message that describes the current exception.
Number | Gets a number that identifies the type of error.
Source(inherited from Exception) | Gets or sets the name of the application or the object that causes the error.
StackTrace(inherited from Exception) | Gets a string representation of the frames on the call stack at the time the current exception was thrown.
TargetSite(inherited from Exception) | Gets the method that throws the current exception.

Public Instance Methods

Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetBaseException(inherited from Exception) | When overridden in a derived class, returns the Exceptionthat is the root cause of one or more subsequent exceptions.
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetObjectData(inherited from Exception) | When overridden in a derived class, sets the SerializationInfowith information about the exception.
GetType(inherited from Exception) | Gets the runtime type of the current instance.
ToString(inherited from Exception) | Creates and returns a string representation of the current exception.

See Also

MySqlException Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.4.1.1. Number Property

Gets a number that identifies the type of error.

Syntax: Visual Basic

    Public ReadOnly Property Number As Integer

Syntax: C#

    public int Number {get;}

See Also

MySqlException Class , MySql.Data.MySqlClient Namespace

##### 18.2.4.1.5. MySqlHelper Class

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

For a list of all members of this type, see MySqlHelper Members .

Syntax: Visual Basic

    NotInheritable Public Class MySqlHelper

Syntax: C#

    public sealed class MySqlHelper

Thread Safety

Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlHelper Members , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.5.1. MySqlHelper Members

MySqlHelper overview

Public Static (Shared) Methods

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 | Overloaded. 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 | Overloaded. 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 | Overloaded. Execute a single command against a MySQL database.
UpdateDataSet | Updates the given table with data from the given DataSet

Public Instance Methods

Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetType(inherited from Object) | Gets the Typeof the current instance.
ToString(inherited from Object) | Returns a Stringthat represents the current Object.

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.5.1.1. MySqlHelper.ExecuteDataRow Method

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.

Syntax: Visual Basic

    Public Shared Function ExecuteDataRow( _
       ByVal connectionString As String, _
       ByVal commandText As String, _
       ParamArray parms As MySqlParameter() _
    ) As DataRow

Syntax: C#

    public static DataRow ExecuteDataRow(
    stringconnectionString,
    stringcommandText,
       params MySqlParameter[]parms
    );

Parameters

- `connectionString`: Settings to be used for the connection

- `commandText`: Command to execute

- `parms`: Parameters to use for the command

Return Value

DataRow containing the first row of the resultset

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.5.1.2. ExecuteDataset Method

Executes a single SQL command and returns the resultset in a DataSet. The state of the MySqlConnection object remains unchanged after execution of this method.

Overload List

Executes a single SQL command and returns the resultset in a DataSet. The state of the MySqlConnection object remains unchanged after execution of this method.

- public static DataSet ExecuteDataset(MySqlConnection,string);

Executes a single SQL command and returns the resultset in a DataSet. The state of the MySqlConnection object remains unchanged after execution of this method.

- public static DataSet ExecuteDataset(MySqlConnection,string,params MySqlParameter[]);

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

- public static DataSet ExecuteDataset(string,string);

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

- public static DataSet ExecuteDataset(string,string,params MySqlParameter[]);

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.5.1.2.1. MySqlHelper.ExecuteDataset Method (MySqlConnection, String)

Executes a single SQL command and returns the resultset in a DataSet. The state of the MySqlConnection object remains unchanged after execution of this method.

Syntax: Visual Basic

    Overloads Public Shared Function ExecuteDataset( _
       ByVal connection As MySqlConnection, _
       ByVal commandText As String _
    ) As DataSet

Syntax: C#

    public static DataSet ExecuteDataset(
    MySqlConnectionconnection,
    stringcommandText
    );

Parameters

- `connection`: MySqlConnection object to use

- `commandText`: Command to execute

Return Value

DataSetcontaining the resultset

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace , MySqlHelper.ExecuteDataset Overload List

###### 18.2.4.1.5.1.2.2. MySqlHelper.ExecuteDataset Method (MySqlConnection, String, MySqlParameter[])

Executes a single SQL command and returns the resultset in a DataSet. The state of the MySqlConnection object remains unchanged after execution of this method.

Syntax: Visual Basic

    Overloads Public Shared Function ExecuteDataset( _
       ByVal connection As MySqlConnection, _
       ByVal commandText As String, _
       ParamArray commandParameters As MySqlParameter() _
    ) As DataSet

Syntax: C#

    public static DataSet ExecuteDataset(
    MySqlConnectionconnection,
    stringcommandText,
       params MySqlParameter[]commandParameters
    );

Parameters

- `connection`: MySqlConnection object to use

- `commandText`: Command to execute

- `commandParameters`: Parameters to use for the command

Return Value

DataSetcontaining the resultset

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace , MySqlHelper.ExecuteDataset Overload List

###### 18.2.4.1.5.1.2.3. MySqlHelper.ExecuteDataset Method (String, String)

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

Syntax: Visual Basic

    Overloads Public Shared Function ExecuteDataset( _
       ByVal connectionString As String, _
       ByVal commandText As String _
    ) As DataSet

Syntax: C#

    public static DataSet ExecuteDataset(
    stringconnectionString,
    stringcommandText
    );

Parameters

- `connectionString`: Settings to be used for the connection

- `commandText`: Command to execute

Return Value

DataSetcontaining the resultset

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace , MySqlHelper.ExecuteDataset Overload List

###### 18.2.4.1.5.1.2.4. MySqlHelper.ExecuteDataset Method (String, String, MySqlParameter[])

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

Syntax: Visual Basic

    Overloads Public Shared Function ExecuteDataset( _
       ByVal connectionString As String, _
       ByVal commandText As String, _
       ParamArray commandParameters As MySqlParameter() _
    ) As DataSet

Syntax: C#

    public static DataSet ExecuteDataset(
    stringconnectionString,
    stringcommandText,
       params MySqlParameter[]commandParameters
    );

Parameters

- `connectionString`: Settings to be used for the connection

- `commandText`: Command to execute

- `commandParameters`: Parameters to use for the command

Return Value

DataSetcontaining the resultset

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace , MySqlHelper.ExecuteDataset Overload List

###### 18.2.4.1.5.1.3. ExecuteNonQuery Method

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.

Overload List

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.

- public static int ExecuteNonQuery(MySqlConnection,string,params MySqlParameter[]);

Executes a single command against a MySQL database. A new MySqlConnection is created using the ConnectionString given.

- public static int ExecuteNonQuery(string,string,params MySqlParameter[]);

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.5.1.3.1. MySqlHelper.ExecuteNonQuery Method (MySqlConnection, String, MySqlParameter[])

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.

Syntax: Visual Basic

    Overloads Public Shared Function ExecuteNonQuery( _
       ByVal connection As MySqlConnection, _
       ByVal commandText As String, _
       ParamArray commandParameters As MySqlParameter() _
    ) As Integer

Syntax: C#

    public static int ExecuteNonQuery(
    MySqlConnectionconnection,
    stringcommandText,
       params MySqlParameter[]commandParameters
    );

Parameters

- `connection`: MySqlConnection object to use

- `commandText`: SQL command to be executed

- `commandParameters`: Array of MySqlParameter objects to use with the command.

Return Value

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace , MySqlHelper.ExecuteNonQuery Overload List

###### 18.2.4.1.5.1.3.2. MySqlHelper.ExecuteNonQuery Method (String, String, MySqlParameter[])

Executes a single command against a MySQL database. A new MySqlConnection is created using the ConnectionString given.

Syntax: Visual Basic

    Overloads Public Shared Function ExecuteNonQuery( _
       ByVal connectionString As String, _
       ByVal commandText As String, _
       ParamArray parms As MySqlParameter() _
    ) As Integer

Syntax: C#

    public static int ExecuteNonQuery(
    stringconnectionString,
    stringcommandText,
       params MySqlParameter[]parms
    );

Parameters

- `connectionString`: ConnectionString to use

- `commandText`: SQL command to be executed

- `parms`: Array of MySqlParameter objects to use with the command.

Return Value

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace , MySqlHelper.ExecuteNonQuery Overload List

###### 18.2.4.1.5.1.4. ExecuteReader Method

Executes a single command against a MySQL database.

Overload List

Executes a single command against a MySQL database.

- public static MySqlDataReader ExecuteReader(string,string);

Executes a single command against a MySQL database.

- public static MySqlDataReader ExecuteReader(string,string,params MySqlParameter[]);

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.5.1.4.1. MySqlHelper.ExecuteReader Method (String, String)

Executes a single command against a MySQL database.

Syntax: Visual Basic

    Overloads Public Shared Function ExecuteReader( _
       ByVal connectionString As String, _
       ByVal commandText As String _
    ) As MySqlDataReader

Syntax: C#

    public static MySqlDataReader ExecuteReader(
    stringconnectionString,
    stringcommandText
    );

Parameters

- `connectionString`: Settings to use for this command

- `commandText`: Command text to use

Return Value

MySqlDataReader object ready to read the results of the command

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace , MySqlHelper.ExecuteReader Overload List

###### 18.2.4.1.5.1.4.2. MySqlHelper.ExecuteReader Method (String, String, MySqlParameter[])

Executes a single command against a MySQL database.

Syntax: Visual Basic

    Overloads Public Shared Function ExecuteReader( _
       ByVal connectionString As String, _
       ByVal commandText As String, _
       ParamArray commandParameters As MySqlParameter() _
    ) As MySqlDataReader

Syntax: C#

    public static MySqlDataReader ExecuteReader(
    stringconnectionString,
    stringcommandText,
       params MySqlParameter[]commandParameters
    );

Parameters

- `connectionString`: Settings to use for this command

- `commandText`: Command text to use

- `commandParameters`: Array of MySqlParameter objects to use with the command

Return Value

MySqlDataReader object ready to read the results of the command

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace , MySqlHelper.ExecuteReader Overload List

###### 18.2.4.1.5.1.5. ExecuteScalar Method

Execute a single command against a MySQL database.

Overload List

Execute a single command against a MySQL database.

- public static object ExecuteScalar(MySqlConnection,string);

Execute a single command against a MySQL database.

- public static object ExecuteScalar(MySqlConnection,string,params MySqlParameter[]);

Execute a single command against a MySQL database.

- public static object ExecuteScalar(string,string);

Execute a single command against a MySQL database.

- public static object ExecuteScalar(string,string,params MySqlParameter[]);

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace

###### 18.2.4.1.5.1.5.1. MySqlHelper.ExecuteScalar Method (MySqlConnection, String)

Execute a single command against a MySQL database.

Syntax: Visual Basic

    Overloads Public Shared Function ExecuteScalar( _
       ByVal connection As MySqlConnection, _
       ByVal commandText As String _
    ) As Object

Syntax: C#

    public static object ExecuteScalar(
    MySqlConnectionconnection,
    stringcommandText
    );

Parameters

- `connection`: MySqlConnection object to use

- `commandText`: Command text to use for the command

Return Value

The first column of the first row in the result set, or a null reference if the result set is empty.

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace , MySqlHelper.ExecuteScalar Overload List

###### 18.2.4.1.5.1.5.2. MySqlHelper.ExecuteScalar Method (MySqlConnection, String, MySqlParameter[])

Execute a single command against a MySQL database.

Syntax: Visual Basic

    Overloads Public Shared Function ExecuteScalar( _
       ByVal connection As MySqlConnection, _
       ByVal commandText As String, _
       ParamArray commandParameters As MySqlParameter() _
    ) As Object

Syntax: C#

    public static object ExecuteScalar(
    MySqlConnectionconnection,
    stringcommandText,
       params MySqlParameter[]commandParameters
    );

Parameters

- `connection`: MySqlConnection object to use

- `commandText`: Command text to use for the command

- `commandParameters`: Parameters to use for the command

Return Value

The first column of the first row in the result set, or a null reference if the result set is empty.

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace , MySqlHelper.ExecuteScalar Overload List

###### 18.2.4.1.5.1.5.3. MySqlHelper.ExecuteScalar Method (String, String)

Execute a single command against a MySQL database.

Syntax: Visual Basic

    Overloads Public Shared Function ExecuteScalar( _
       ByVal connectionString As String, _
       ByVal commandText As String _
    ) As Object

Syntax: C#

    public static object ExecuteScalar(
    stringconnectionString,
    stringcommandText
    );

Parameters

- `connectionString`: Settings to use for the update

- `commandText`: Command text to use for the update

Return Value

The first column of the first row in the result set, or a null reference if the result set is empty.

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace , MySqlHelper.ExecuteScalar Overload List

###### 18.2.4.1.5.1.5.4. MySqlHelper.ExecuteScalar Method (String, String, MySqlParameter[])

Execute a single command against a MySQL database.

Syntax: Visual Basic

    Overloads Public Shared Function ExecuteScalar( _
       ByVal connectionString As String, _
       ByVal commandText As String, _
       ParamArray commandParameters As MySqlParameter() _
    ) As Object

Syntax: C#

    public static object ExecuteScalar(
    stringconnectionString,
    stringcommandText,
       params MySqlParameter[]commandParameters
    );

Parameters

- `connectionString`: Settings to use for the command

- `commandText`: Command text to use for the command

- `commandParameters`: Parameters to use for the command

Return Value

The first column of the first row in the result set, or a null reference if the result set is empty.

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace , MySqlHelper.ExecuteScalar Overload List

###### 18.2.4.1.5.1.6. MySqlHelper.UpdateDataSet Method

Updates the given table with data from the given DataSet

Syntax: Visual Basic

    Public Shared Sub UpdateDataSet( _
       ByVal connectionString As String, _
       ByVal commandText As String, _
       ByVal ds As DataSet, _
       ByVal tablename As String _
    )

Syntax: C#

    public static void UpdateDataSet(
    stringconnectionString,
    stringcommandText,
    DataSetds,
    stringtablename
    );

Parameters

- `connectionString`: Settings to use for the update

- `commandText`: Command text to use for the update

- `ds`: DataSetcontaining the new data to use in the update

- `tablename`: Tablename in the dataset to update

See Also

MySqlHelper Class , MySql.Data.MySqlClient Namespace

##### 18.2.4.1.6. MySqlErrorCode Enumeration

Syntax: Visual Basic

    Public Enum MySqlErrorCode

Syntax: C#

    public enum MySqlErrorCode

Members

Member Name | Description
PacketTooLarge |
PasswordNotAllowed |
DuplicateKeyEntry |
HostNotPrivileged |
PasswordNoMatch |
AnonymousUser |
DuplicateKey |
KeyNotFound |
DuplicateKeyName |

Requirements

Namespace: MySql.Data.MySqlClient

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySql.Data.MySqlClient Namespace

#### 18.2.4.2. MySql.Data.Types

Namespace hierarchy

Classes

Class | Description
MySqlConversionException | Summary description for MySqlConversionException.
MySqlDateTime | Summary description for MySqlDateTime.
MySqlValue |

##### 18.2.4.2.1. MySql.Data.TypesHierarchy

See Also

MySql.Data.Types Namespace

##### 18.2.4.2.2. MySqlConversionException Class

Summary description for MySqlConversionException.

For a list of all members of this type, see MySqlConversionException Members .

Syntax: Visual Basic

    Public Class MySqlConversionException_
      Inherits ApplicationException

Syntax: C#

    public class MySqlConversionException : ApplicationException

Thread Safety

Public static (Sharedin Visual Basic) members of this type are safe for multithreaded operations. Instance members are notguaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.Types

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlConversionException Members , MySql.Data.Types Namespace

###### 18.2.4.2.2.1. MySqlConversionException Members

MySqlConversionException overview

Public Instance Constructors

MySqlConversionException Constructor | Ctor

Public Instance Properties

Data(inherited from Exception) | Gets a collection of key/value pairs that provide additional, user-defined information about the exception.
HelpLink(inherited from Exception) | Gets or sets a link to the help file associated with this exception.
InnerException(inherited from Exception) | Gets the Exceptioninstance that caused the current exception.
Message(inherited from Exception) | Gets a message that describes the current exception.
Source(inherited from Exception) | Gets or sets the name of the application or the object that causes the error.
StackTrace(inherited from Exception) | Gets a string representation of the frames on the call stack at the time the current exception was thrown.
TargetSite(inherited from Exception) | Gets the method that throws the current exception.

Public Instance Methods

Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetBaseException(inherited from Exception) | When overridden in a derived class, returns the Exceptionthat is the root cause of one or more subsequent exceptions.
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetObjectData(inherited from Exception) | When overridden in a derived class, sets the SerializationInfowith information about the exception.
GetType(inherited from Exception) | Gets the runtime type of the current instance.
ToString(inherited from Exception) | Creates and returns a string representation of the current exception.

Protected Instance Properties

HResult(inherited from Exception) | Gets or sets HRESULT, a coded numerical value that is assigned to a specific exception.

Protected Instance Methods

Finalize(inherited from Object) | Allows an Objectto attempt to free resources and perform other cleanup operations before the Objectis reclaimed by garbage collection.
MemberwiseClone(inherited from Object) | Creates a shallow copy of the current Object.

See Also

MySqlConversionException Class , MySql.Data.Types Namespace

###### 18.2.4.2.2.1.1. MySqlConversionException Constructor

Syntax: Visual Basic

    Public Sub New( _
       ByVal msg As String _
    )

Syntax: C#

    public MySqlConversionException(
    stringmsg
    );

See Also

MySqlConversionException Class , MySql.Data.Types Namespace

##### 18.2.4.2.3. MySqlDateTime Class

Summary description for MySqlDateTime.

For a list of all members of this type, see MySqlDateTime Members .

Syntax: Visual Basic

    Public Class MySqlDateTime_
      Inherits MySqlValue_
      Implements IConvertible, IComparable

Syntax: C#

    public class MySqlDateTime : MySqlValue, IConvertible, IComparable

Thread Safety

Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.Types

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlDateTime Members , MySql.Data.Types Namespace

###### 18.2.4.2.3.1. MySqlDateTime Members

MySqlDateTime overview

Public Static (Shared) Type Conversions

Explicit MySqlDateTime to DateTime Conversion |

Public Instance Properties

Day | Returns the day portion of this datetime
Hour | Returns the hour portion of this datetime
IsNull (inherited from MySqlValue) |
IsValidDateTime | Indicates if this object contains a value that can be represented as a DateTime
Minute | Returns the minute portion of this datetime
Month | Returns the month portion of this datetime
Second | Returns the second portion of this datetime
ValueAsObject (inherited from MySqlValue) | Returns the value of this field as an object
Year | Returns the year portion of this datetime

Public Instance Methods

Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetDateTime | Returns this value as a DateTime
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetType(inherited from Object) | Gets the Typeof the current instance.
ToString | Returns a MySQL specific string representation of this value

Protected Instance Fields

classType (inherited from MySqlValue) | The system type represented by this value
dbType (inherited from MySqlValue) | The generic dbtype of this value
isNull (inherited from MySqlValue) | Is this value null
mySqlDbType (inherited from MySqlValue) | The specific MySQL db type
mySqlTypeName (inherited from MySqlValue) | The MySQL specific typename of this value
objectValue (inherited from MySqlValue) |

Protected Instance Methods

Finalize(inherited from Object) | Allows an Objectto attempt to free resources and perform other cleanup operations before the Objectis reclaimed by garbage collection.
MemberwiseClone(inherited from Object) | Creates a shallow copy of the current Object.

See Also

MySqlDateTime Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.1. MySqlDateTime Explicit MySqlDateTime to DateTime Conversion

Syntax: Visual Basic

    MySqlDateTime.op_Explicit(val)

Syntax: C#

    public static explicit operator DateTime(
    MySqlDateTimeval
    );

Parameters

- `val`:

Return Value

See Also

MySqlDateTime Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.2. Day Property

Returns the day portion of this datetime

Syntax: Visual Basic

    Public Property Day As Integer

Syntax: C#

    public int Day {get; set;}

See Also

MySqlDateTime Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.3. Hour Property

Returns the hour portion of this datetime

Syntax: Visual Basic

    Public Property Hour As Integer

Syntax: C#

    public int Hour {get; set;}

See Also

MySqlDateTime Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.4. IsNull Property

Syntax: Visual Basic

    Public Property IsNull As Boolean

Syntax: C#

    public bool IsNull {get; set;}

See Also

MySqlValue Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.4.1. MySqlValue Class

For a list of all members of this type, see MySqlValue Members .

Syntax: Visual Basic

    MustInherit Public Class MySqlValue

Syntax: C#

    public abstract class MySqlValue

Thread Safety

Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

Requirements

Namespace: MySql.Data.Types

Assembly: MySql.Data (in MySql.Data.dll)

See Also

MySqlValue Members , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.4.1.1. MySqlValue Members

MySqlValue overview

Protected Static (Shared) Fields

numberFormat |

Public Instance Constructors

MySqlValue Constructor | Initializes a new instance of the MySqlValue class.

Public Instance Properties

IsNull |
ValueAsObject | Returns the value of this field as an object

Public Instance Methods

Equals(inherited from Object) | Determines whether the specified Objectis equal to the current Object.
GetHashCode(inherited from Object) | Serves as a hash function for a particular type. GetHashCodeis suitable for use in hashing algorithms and data structures like a hash table.
GetType(inherited from Object) | Gets the Typeof the current instance.
ToString | Returns a string representation of this value

Protected Instance Fields

classType | The system type represented by this value
dbType | The generic dbtype of this value
isNull | Is this value null
mySqlDbType | The specific MySQL db type
mySqlTypeName | The MySQL specific typename of this value
objectValue |

Protected Instance Methods

Finalize(inherited from Object) | Allows an Objectto attempt to free resources and perform other cleanup operations before the Objectis reclaimed by garbage collection.
MemberwiseClone(inherited from Object) | Creates a shallow copy of the current Object.

See Also

MySqlValue Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.4.1.1.1. MySqlValue.numberFormat Field

Syntax: Visual Basic

    Protected Shared numberFormat As NumberFormatInfo

Syntax: C#

    protected static NumberFormatInfo numberFormat;

See Also

MySqlValue Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.4.1.1.2. MySqlValue Constructor

Initializes a new instance of the MySqlValue class.

Syntax: Visual Basic

    Public Sub New()

Syntax: C#

    public MySqlValue();

See Also

MySqlValue Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.4.1.1.3. ValueAsObject Property

Returns the value of this field as an object

Syntax: Visual Basic

    Public ReadOnly Property ValueAsObject As Object

Syntax: C#

    public object ValueAsObject {get;}

See Also

MySqlValue Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.4.1.1.4. MySqlValue.ToString Method

Returns a string representation of this value

Syntax: Visual Basic

    Overrides Public Function ToString() As String

Syntax: C#

    public override string ToString();

See Also

MySqlValue Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.4.1.1.5. MySqlValue.classType Field

The system type represented by this value

Syntax: Visual Basic

    Protected classType As Type

Syntax: C#

    protected Type classType;

See Also

MySqlValue Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.4.1.1.6. MySqlValue.dbType Field

The generic dbtype of this value

Syntax: Visual Basic

    Protected dbType As DbType

Syntax: C#

    protected DbType dbType;

See Also

MySqlValue Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.4.1.1.7. MySqlValue.mySqlDbType Field

The specific MySQL db type

Syntax: Visual Basic

    Protected mySqlDbType As MySqlDbType

Syntax: C#

    protected MySqlDbType mySqlDbType;

See Also

MySqlValue Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.4.1.1.8. MySqlValue.mySqlTypeName Field

The MySQL specific typename of this value

Syntax: Visual Basic

    Protected mySqlTypeName As String

Syntax: C#

    protected string mySqlTypeName;

See Also

MySqlValue Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.4.1.1.9. MySqlValue.objectValue Field

Syntax: Visual Basic

    Protected objectValue As Object

Syntax: C#

    protected object objectValue;

See Also

MySqlValue Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.5. IsValidDateTime Property

Indicates if this object contains a value that can be represented as a DateTime

Syntax: Visual Basic

    Public ReadOnly Property IsValidDateTime As Boolean

Syntax: C#

    public bool IsValidDateTime {get;}

See Also

MySqlDateTime Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.6. Minute Property

Returns the minute portion of this datetime

Syntax: Visual Basic

    Public Property Minute As Integer

Syntax: C#

    public int Minute {get; set;}

See Also

MySqlDateTime Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.7. Month Property

Returns the month portion of this datetime

Syntax: Visual Basic

    Public Property Month As Integer

Syntax: C#

    public int Month {get; set;}

See Also

MySqlDateTime Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.8. Second Property

Returns the second portion of this datetime

Syntax: Visual Basic

    Public Property Second As Integer

Syntax: C#

    public int Second {get; set;}

See Also

MySqlDateTime Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.9. Year Property

Returns the year portion of this datetime

Syntax: Visual Basic

    Public Property Year As Integer

Syntax: C#

    public int Year {get; set;}

See Also

MySqlDateTime Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.10. MySqlDateTime.GetDateTime Method

Returns this value as a DateTime

Syntax: Visual Basic

    Public Function GetDateTime() As Date

Syntax: C#

    public DateTime GetDateTime();

See Also

MySqlDateTime Class , MySql.Data.Types Namespace

###### 18.2.4.2.3.1.11. MySqlDateTime.ToString Method

Returns a MySQL specific string representation of this value

Syntax: Visual Basic

    Overrides Public Function ToString() As String

Syntax: C#

    public override string ToString();

See Also

MySqlDateTime Class , MySql.Data.Types Namespace

### 18.2.5. Connector/NET Notes and Tips

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.

#### 18.2.5.1. Connecting to MySQL Using Connector/NET

##### 18.2.5.1.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.

##### 18.2.5.1.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 for Section 18.2.3.3.15, “ConnectionString”):

- `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.

##### 18.2.5.1.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.

Visual Basic Example

    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# Example

    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:

Visual Basic Example

    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# Example

    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 Connector/NET classes to communicate with the MySQL server.

##### 18.2.5.1.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:

Visual Basic Example

    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# Example

    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");
        }
    }

Important: Note that if you are using multilanguage databases you must specify the character set in the connection string. If you do not specify the character set, the connection defaults to the `latin1` charset. You can specify the character set as part of the connection string, for example:

    MySqlConnection myConnection = new MySqlConnection("server=127.0.0.1;uid=root;" +
        "pwd=12345;database=test;Charset=latin1;");

#### 18.2.5.2. Using the Connector/NET with Prepared Statements

##### 18.2.5.2.1. Introduction

As of MySQL 4.1, it is possible to use prepared statements with 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.

##### 18.2.5.2.2. Preparing Statements in 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.

Visual Basic Example

    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# Example

    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);
    }

#### 18.2.5.3. Accessing Stored Procedures with Connector/NET

##### 18.2.5.3.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.

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.

Note: When you call a stored procedure, the command object makes an additional `SELECT` call to determine the parameters of the stored procedure. You must ensure that the user calling the procedure has the `SELECT` privilege on the `mysql.proc` table to enable them to verify the parameters. Failure to do this will result in an error when calling the procedure.

This section will not provide in-depth information on creating Stored Procedures. For such information, please refer to http://dev.mysql.com/doc/mysql/en/stored-procedures.html.

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

##### 18.2.5.3.2. Creating Stored Procedures from 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:

Visual Basic Example

    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# Example

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

##### 18.2.5.3.3. Calling a Stored Procedure from Connector/NET

To call a stored procedure using 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:

Visual Basic Example

    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# Example

    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.

#### 18.2.5.4. Handling BLOB Data With Connector/NET

##### 18.2.5.4.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 Connector/NET installation.

##### 18.2.5.4.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.

##### 18.2.5.4.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:

Visual Basic Example

    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# Example

    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.

##### 18.2.5.4.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:

Visual Basic Example

    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# Example

    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.

#### 18.2.5.5. Using Connector/NET with Crystal Reports

##### 18.2.5.5.1. Introduction

Crystal Reports is a common tool used by Windows application developers to perform reporting and document generation. In this section we will show how to use Crystal Reports XI with MySQL and Connector/NET.

##### 18.2.5.5.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:

Visual Basic Example

    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# Example

    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.

##### 18.2.5.5.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.

##### 18.2.5.5.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 Section 18.2.5.5.2, “Creating a Data Source”, and have a crViewer control on your form named `myViewer`.

Visual Basic Example

    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# Example

    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:

Visual Basic Example

    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# Example

    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.

#### 18.2.5.6. Handling Date and Time Information in Connector/NET

##### 18.2.5.6.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 Connector/NET.

##### 18.2.5.6.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.

##### 18.2.5.6.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 Section 5.2.5, “SQL Modes”.

##### 18.2.5.6.4. Handling Invalid Dates

Although 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 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 Connector/NET to return `MySqlDateTime` objects for invalid dates.

To instruct 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.

##### 18.2.5.6.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:

Visual Basic Example

    If Not myReader.IsDBNull(myReader.GetOrdinal("mytime")) Then
        myTime = myReader.GetDateTime(myReader.GetOrdinal("mytime"))
    Else
        myTime = DateTime.MinValue
    End If

C# Example

    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.

### 18.2.6. Connector/NET Support

The developers of Connector/NET greatly value the input of our users in the software development process. If you find Connector/NET lacking some feature important to you, or if you discover a bug and need to file a bug report, please use the instructions in Section 1.8, “How to Report Bugs or Problems”.

#### 18.2.6.1. Connector/NET Community Support

- Community support for Connector/NET can be found through the forums at http://forums.mysql.com.

- Community support for Connector/NET can also be found through the mailing lists at http://lists.mysql.com.

- Paid support is available from MySQL AB. Additional information is available at http://www.mysql.com/support/.

#### 18.2.6.2. How to report Connector/NET Problems or Bugs

If you encounter difficulties or problems with Connector/NET, contact the Connector/NET community Section 18.2.6.1, “Connector/NET Community Support”.

You should first try to execute the same SQL statements and commands from the mysql client program or from `admndemo`. This helps you determine whether the error is in Connector/NET or MySQL.

If reporting a problem, you should ideally include the following information with the email:

- Operating system and version

- Connector/NET version

- MySQL server version

- Copies of error messages or other unexpected output

- Simple reproducible sample

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

If you believe the problem to be a bug, then you must report the bug through http://bugs.mysql.com/.

#### 18.2.6.3. Connector/NET Change History

The Connector/NET Change History (Changelog) is located with the main Changelog for MySQL. See Section D.7, “Connector/NET Change History”.

## 18.3. MySQL Visual Studio Plugin

The MySQL Visual Studio Plugin is a DDEX provider; a plug-in for Visual Studio 2005 that allows developers to maintain database structures, and supports built-in data-driven application development tools.

The current version of the MySQL Visual Studio Pluginincludes only database maintenance tools. Data-driven application development tools are not supported.

The MySQL DDEX Provider operates as a standard extension to the Visual Studio Data Designer functionality available through the Server Explorer menu of Visual Studio 2005, and enables developers to create database objects and data within a MySQL database.

The MySQL Visual Studio Plugin is designed to work with MySQL version 5.0, but is also compatible with MySQL 4.1.1 and provides limited compatibility with MySQL 5.1.

### 18.3.1. Installing the MySQL Visual Studio Plugin

The MySQL Visual Studio Plugin requires Visual Studio 2005 Professional Edition to be installed, and therefore it has the same hardware and system requirements.

Here is the list of components that should already be installed before starting the installation of the MySQL Visual Studio Plugin:

- Visual Studio 2005 Standard, Professional or Team Developer Edition.

- MySQL Server 4.1.1 or later (either installed on the same machine, or a separate server).

- MySQL Connector.NET 5.0.

The user used to connect to the MySQL server must have the following privileges to use the functionality provided by the MySQL Visual Studio Plugin:

- The `SELECT` privilege for the `INFORMATION_SCHEMA` database.

- The `EXECUTE` privilege for the `SHOW CREATE TABLE` statement.

- The `SELECT` privilege for the `mysql.proc` table (required for operations with stored procedures and functions).

- The `SELECT` privilege for the `mysql.func` table (required for operations with User Defined Functions (UDF)).

- The `EXECUTE` privilege for the `SHOW ENGINE STATUS` statement (required for retrieving extended error information).

- Appropriate privileges for performed operations (e.g. the `SELECT` privilege is required to browse data from a table etc.).

The MySQL Visual Studio Plugin is delivered as a MSI package that can be used to install, uninstall or reinstall the Provider. If you are not using Windows XP or Windows Server 2003 you upgrade the Windows Installer system to the latest version (see http://support.microsoft.com/default.aspx?scid=kb;EN-US;292539 for details).

The MSI-package is named `MySQL.VisualStudio.msi`. To install the MySQL Visual Studio Plugin, right click on the MSI file and select Install. The installation process is as follow:

1. The standard Welcome dialog is opened. Click Next to continue installation.

2. The License agreement (GNU GPL) window is opened. Accept the agreement and click Next to continue.

3. The destination folder choice dialog is opened. Here you can point out the folder where the MySQL Visual Studio Plugin will be installed. The default destination folder is `%ProgramFilesDir%\MySQL\MySQL DDEX Data Provider`, where `%ProgramFilesDir%` is the Program Files folder of the installation machine. After choosing the destination folder, click Next to continue.

4. The installer will ask to confirm that installation. Click Install to start installation process.

5. The installation will now take place. At the end of this step the Visual Studio command table is rebuilt (this process may take several minutes).

6. Once installation is complete, click Finish to end the installation process.

To uninstall the MySQL Visual Studio Plugin, you can use either Add/Remove Programs component of the Control Panel or the same MSI-package. Choose the Remove option, and the Provider will be uninstalled automatically.

To repair the Provider, right click the MSI-package and choose the Repair option. The MySQL Visual Studio Plugin will be repaired automatically.

The installation package includes the following files:

- `MySQL.VisualStudio.dll` — the MySQL DDEX Provider assembly.

- `MySQL.Data.dll` — the assembly containing the MySQL Connector .NET which is used by the Provider.

- `MySql.VisualStudio.dll.config` — the configuration file for the MySQL Visual Studio Plugin. This file contains default values for the provider GUI layout.

  ### Note

  Do not remove this file before the first use of the Provider.

- `Register.reg` — the file with registry entries that can be used to register the MySQL DDEX Provider in the case of the manual installation.

- `Install.js` — the script used to register the Connector .NET as an ADO.NET data provider in the machine.config file.

- `Release notes.doc` — the document with release notes.

To install the Provider manually, copy all files of the installation package in a desired folder, then set the full path to the Provider assembly as a value of the CodeBase entry. For example:

    [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\Packages\{79A115C9-B133-4891-9E7B-242509DAD272}]@="MySql.Data.VisualStudio.MySqlDataProviderPackage"
    "InprocServer32"="C:\\WINNT\\system32\\mscoree.dll"
    "Class"="MySql.Data.VisualStudio.MySqlDataProviderPackage"
    "CodeBase"="C:\\MySqlDdexProvider\\MySql.VisualStudio.dll"

Then import information from the Register.reg file to the registry by clicking of the file. At the confirmation dialog choose Yes. Next you must run the command devenv.exe /setup within a Command Prompt to rebuild the Visual Studio command table.

### 18.3.2. Creating a connection to the MySQL server

Once the MySQL Visual Studio Plugin is installed, you can use it to create, modify and delete connections to MySQL databases. To create a connection with a MySQL database, perform the following steps:

1. Start Visual Studio 2005 and open Server Explorer window by choosing the Server Explorer option from the View menu.

2. Right click on the Data Connections node and choose the Add Connection button.

3. The Add Connection dialog is opened. Press the Change button to choose MySQL Database as a data source.

4. Change Data Source dialog is opened. Choose MySQL Database in the list of data sources (or the `other` option, if MySQL Database is absent), and then choose .NET Framework Data Provider for MySQL in the combo box of data providers.

   Press OK to confirm your choice.

5. Enter the connection settings: the server host name (for example, localhost if the MySQL server is installed on the local machine), the user name, the password, and the default database schema. Note that you must specify the default schema name to open the connection.

6. You can also set the port to connect with the MySQL server by pressing the Advanced button. To test a connection with the MySQL server, ser the server host name, the user name, and the password, and press the Test Connection button. If the test fails, check the connection values that you have supplied are correct and that the corresponding user and privileges have been configured on the MySQL server.

7. After you set all settings and test the connection, press OK. The newly created connection is displayed in Server Explorer. Now you can work with the MySQL server through standard Server Explorer interface.

After a connection is successfully established, all the connection settings are saved. When you next open Visual Studio, the connection to the MySQL server will appear within Server Explorer so that you can re-establish a connection to the MySQL server.

To modify and delete a connection, use the Server Explorer context menu for the corresponding node. You can modify any of the settings just by overwriting the existing values with new ones. Note that a connection should be modified or deleted only if no active editor for it's objects is opened. Otherwise your data could be lost.

### 18.3.3. Using the MySQL Visual Studio Plugin

To work with a MySQL server using the MySQL Visual Studio Plugin, open the Visual Studio 2005, open the Server Explorer, and select the required connection. The working area of the MySQL Visual Studio Plugin consists of three parts.

- Database objects (tables, views, stored routines, triggers, and user defined functions) are displayed in the Server Explorer tree. Here you can choose an object and edit its properties and definition.

- Properties of a selected database object are displayed in the Properties panel. Certain properties can be edited directly within this window.

- The editor panel provides direct access to the SQL statement and definition of specific objects. Fore example, the SQL statements within a stored procedure definition are shown and edited within this panel.

#### 18.3.3.1. Editing Tables

The Table Editor can be accessed through a mouse action on table-type node of Server Explorer. To create a new table, right click on the Tables node (under the connection node) and choose the Create Table command from a context menu. To modify an existing table, double click on a node of the table you wish to modify, or right click on this node and choose the Alter Table command from a context menu. Either of the commands opens the Table Editor.

The MySQL Visual Studio Plugin Table Editor is implemented in a similar fashion to the standard Query Browser Table Editor, but with minor differences.

The Table Editor consists of the following parts:

- Columns Editor — for column creation, modification and deletion.

- Indexes tab — for table/column index management.

- Foreign Keys tab — for configuration of foreign keys.

- Column Details tab — used to set advanced column options.

- Properties window — used to set table properties.

To save changes you have made in the Table Editor, use either Save or Save All buttons of the Visual Studio main toolbar, or just press Ctrl+S. Before changes are saved, a confirmation dialog will be displayed to confirm that you want to update the corresponding object within the MySQL database.

##### 18.3.3.1.1. Column Editor

You can use the Column Editor to set or change the name, data type, default value and other properties of a table column. To set the properties of an individual column, select the column using the mouse. Alternatively, you can move through the grid using Tab and Shift+Tab keys.

- To set or change the name, data type, default value and comment of a column, select the appropriate cell and edit the desired value.

- To set or unset flag-type column properties (i.e., primary key, `NOT NULL`, auto incremented, flags), check or uncheck the corresponding checkboxes. Note that the available column flags will depend on the columns data type.

- To reorder columns, index columns or foreign key columns in the Column Editor, select the whole column you wish to reorder by clicking on the selector column at the left of the column grid. Then move the column by using Ctrl+Up (to move the column up) and Ctrl+Down (to move the column down) keys.

- To delete a column, select it by clicking on the selector column at the left of the column grid, then press the Delete button on a keyboard.

##### 18.3.3.1.2. Indexes tab

Index management is performed via the Indexes tab.

- To add an index, press the + button and set the properties in the Index Settings groupbox at the right. You can set the index name, index kind, index type and a set of index columns.

- To remove an index, select the index from the list and press the - button.

- To change index settings, select the index from the list; detailed information about the index is displayed in the Index Settings panel.

You cannot change a table column to an index column using drag and drop. Instead, you can add new index columns to a table and set their table columns by using the embedded editor within the Indexes tab

##### 18.3.3.1.3. Foreign Keys tab

Foreign Key management is performed via the Foreign Keys tab.

- To add a foreign key, press the + button and set properties in the Foreign Keys Settings panel. You can set the foreign key name, referenced table name, foreign key columns and actions on update and delete.

- To remove a foreign key, select the foreign key and press the - button.

- To change foreign key settings, select the foreign key and use the Foreign Keys Settings panel to edit the properties.

- When a foreign key is changed, the MySQL Visual Studio Plugin generates two queries: the first query drops the changed keys and the second one recreates the new values. The reason for such a behavior is to avoid the Bug#8377 and Bug#8919.

### Note

If changed values are for some reason inconsistent and cause the second query to fail, all affected foreign keys will be dropped. If this is the case, the MySQL Visual Studio Plugin will mark them as new in the Table Editor, and you will have to recreate them later. But if you close the Table Editor without saving, these foreign keys will be lost.

##### 18.3.3.1.4. Column Details tab

The Column Details tab can be used to set column options. Besides the main column properties that are presented in the Column Editor, in the Column Details tab you can set two additional properties options: the character set and the collation sequence.

##### 18.3.3.1.5. Table Properties window

There is no separate tab for table options and advanced options. All table options can be browsed and changed using the Properties window of Visual Studio 2005.

The following table properties can be set:

- Auto Increment

- Average Row Length

- Character Set

- Checksum for Rows

- Collation

- Comment

- Connection

- Data Directory

- Delay Key Updates

- Engine

- Index Directory

- Insert Method

- Maximum Rows

- Minimum Rows

- Name

- Pack Keys

- Password

- Row Format

- Union

Some of these properties can have arbitrary text values, others accept values from a predefined set.

The properties Schema and Server are read only.

#### 18.3.3.2. Editing Table Data

The Table Data Editor, allows a user to browse, create and edit data of tables. The Table Data Editor is implemented as a simple data grid with auto generated columns.

To access the Table Data Editor, right click on a node representing the table or view in Server Explorer. From the nodes context menu, choose the Browse or Edit Data command. For tables and updatable views, this command opens the Table Data Editor in edit mode. For non-updatable views, this command opens the Table Data Editor in read-only mode.

When in the edit mode, you can modify table data by modifying the displayed table contents directly. To add a row, set desired values in the last row of the grid. To modify values, set new values in appropriate cells. To delete a row, select it by clicking on the selector column at the left of the grid, then press the Delete button.

To save changes you have made in the Table Data Editor, use either Save or Save All buttons of the Visual Studio main toolbar, or just press Ctrl+S. A confirmation dialog will confirm whether you want the changes saved to the database.

#### 18.3.3.3. Editing Views

To create a new view, right click the Views node under the connection node in Server Explorer. From the nodes context menu, choose the Create View command. This command opens the SQL Editor.

To modify an existing view, double click on a node of the view you wish to modify, or right click on this node and choose the Alter View command from a context menu. Either of the commands opens the SQL Editor.

To create or alter the view definition using SQL Editor, type the appropriate SQL statement in the SQL Editor.

### Note

You should enter only the defining statement itself, without the `CREATE VIEW AS` preface.

All other view properties can be set in the Properties window. These properties are:

- Algorithm

- Check Option

- Definer

- Name

- Security Type

Some of these properties can have arbitrary text values, others accept values from a predefined set.

The properties Is Updatable, Schema and Server are readonly.

To save changes you have made, use either Save or Save All buttons of the Visual Studio main toolbar, or just press Ctrl+S. A confirmation dialog will confirm whether you want the changes saved to the database.

#### 18.3.3.4. Editing Stored Procedures and Functions

To create a new stored procedure, right click the Stored Procedures node under the connection node in Server Explorer. From the nodes context menu, choose the Create Routine command. This command opens the SQL Editor.

To create a new stored function, right click the Functions node under the connection node in Server Explorer. From the node's context menu, choose the Create Routine command.

To modify an existing stored routine (procedure or function), double click on a node of the routine you wish to modify, or right click on this node and choose the Alter Routine command from a context menu. Either of the commands opens the SQL Editor.

To create or alter the routine definition using SQL Editor, type this definition in the SQL Editor using standard SQL.

All other routine properties can be set in the Properties window. These properties are:

- Comment

- Data Access

- Definer

- Is Deterministic

- Security Type

Some of these properties can have arbitrary text values, others accept values only from a predefined set.

Also you can set all the options directly in the SQL Editor, using the standard `CREATE PROCEDURE` or `CREATE FUNCTION` statement. However, it is recommended to use the Properties window instead.

### Note

You should never add the `CREATE` preface to the routine definition.

The properties Name, Schema and Server in the Properties window are read-only. Set or change the procedure name in the SQL editor.

To save changes you have made, use either Save or Save All buttons of the Visual Studio main toolbar, or just press Ctrl+S. A confirmation dialog will confirm whether you want the changes saved to the database..

#### 18.3.3.5. Editing Triggers

To create a new trigger, right click on a node of a table for which you wish to add a trigger. From the node's context menu, choose the Create Trigger command. This command opens the SQL Editor.

To modify an existing trigger, double click on a node of the trigger you wish to modify, or right click on this node and choose the Alter Trigger command from a context menu. Either of the commands opens the SQL Editor.

To create or alter the trigger definition using SQL Editor, type the trigger statement in the SQL Editor using standard SQL.

### Note

You should enter only the trigger statement, that is the part of the `CREATE TRIGGER` query that is placed after the `FOR EACH ROW` clause.

All other trigger properties are set in the Properties window. These properties are:

- Definer

- Event Manipulation

- Name

- Timing

Some of these properties can have arbitrary text values, others accept values only from a predefined set.

The properties Event Table, Schema and Server in the Properties window are read-only.

To save changes you have made, use either Save or Save All buttons of the Visual Studio main toolbar, or just press Ctrl+S. A confirmation dialog will confirm whether you want the changes saved to the database.

#### 18.3.3.6. Editing User Defined Functions (UDF)

To create a new User Defined Function (UDF), right click the UDFs node under the connection node in Server Explorer. From the node's context menu, choose the Create UDF command. This command opens the UDF Editor.

To modify an existing UDF, double click on a node of the UDF you wish to modify, or right click on this node and choose the Alter UDF command from a context menu. Either of the commands opens the UDF Editor.

The UDF editor allows you to set the following properties through the properties panel:

- Name

- So-name (DLL name)

- Return type

- Is Aggregate

The property Server in the Properties window is read-only.

To save changes you have made, use either Save or Save All buttons of the Visual Studio main toolbar, or just press Ctrl+S. A confirmation dialog will confirm whether you want the changes saved to the database.

#### 18.3.3.7. Dropping database objects

Tables, views, stored routines, triggers, an UDFs can be dropped with the appropriate Drop command from its context menu: Drop Table, Drop View, Drop Routine, Drop Trigger, Drop UDF.

You will be asked to confirm the execution of the corresponding drop query in a confirmation dialog.

Dropping of multiple objects is not supported.

#### 18.3.3.8. Cloning database objects

Tables, views, stored procedures and functions can be cloned with the appropriate Clone command from its context menu: Clone Table, Clone View, Clone Routine. The clone commands open the corresponding editor for a new object: the Table Editor for cloning a table and the SQL Editor for cloning a view or a routine.

To save the cloned object, use either Save or Save All buttons of the Visual Studio main toolbar, or just press Ctrl+S. A confirmation dialog will confirm whether you want the changes saved to the database.

### 18.3.4. Visual Studio Plugin Support

If you have a comment, or if you discover a bug, please, use our MySQL bug tracking system (http://bugs.mysql.com) to report problem or add your suggestion.

#### 18.3.4.1. Visual Studio Plugin FAQ

Questions

- 19.3.4.1.1: When creating a connection, typing the connection details causes the connection window to immediately close.

Questions and Answers

19.3.4.1.1: When creating a connection, typing the connection details causes the connection window to immediately close.

There are known issues with versions of Connector/NET earlier than 5.0.2. Connector/NET 1.0.x is known not to work. If you have any of these versions installed, or have previously upgraded from an earlier version, uninstall Connector/NET completely and then install Connector/NET 5.0.2.

## 18.4. 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 pure Java, implements version 3.0 of the JDBC specification, and communicates directly with the MySQL server using the MySQL protocol.

Although JDBC is useful by itself, we would hope that if you are not familiar with JDBC that after reading the first few sections of this manual, that you would avoid using naked JDBC for all but the most trivial problems and consider using one of the popular persistence frameworks such as Hibernate, 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:

- JDBC Basics — A tutorial from Sun covering beginner topics in JDBC

- JDBC Short Course — A more in-depth tutorial from Sun and JGuru

### 18.4.1. Connector/J Versions

There are currently three versions of MySQL Connector/J available:

- Connector/J 3.0 provides core functionality and was designed with connectivity to MySQL 3.x or MySQL 4.1 servers, although it will provide basic compatibility with later versions of MySQL. Connector/J 3.0 does not support server-side prepared statements, and does not support any of the features in versions of MySQL later than 4.1.

- Connector/J 3.1 was designed for connectivity to MySQL 4.1 and MySQL 5.0 servers and provides support for all the functionality in MySQL 5.0 except distributed transaction (XA) support.

- Connector/J 5.0 provides support for all the functionality offered by Connector/J 3.1 and includes distributed transaction (XA) support.

The current recommended version for Connector/J is 5.0. This guide covers all three connector versions, with specific notes given where a setting applies to a specific option.

#### 18.4.1.1. Java Versions Supported

MySQL Connector/J supports Java-2 JVMs, including:

- JDK 1.2.x (only for Connector/J 3.1.x or earlier)

- JDK 1.3.x

- JDK 1.4.x

- JDK 1.5.x

If you are building Connector/J from source using the source distribution (see Section 18.4.2.4, “Installing from the Development Source Tree”) then you must use JDK 1.4.x or newer to compiler the Connector package.

MySQL Connector/J does not support JDK-1.1.x or JDK-1.0.x.

Because of the implementation of `java.sql.Savepoint`, Connector/J 3.1.0 and newer will not run on JDKs older than 1.4 unless the class verifier is turned off (by setting the `-Xverify:none` option to the Java runtime). This is because the class verifier will try to load the class definition for `java.sql.Savepoint` even though it is not accessed by the driver unless you actually use savepoint functionality.

Caching functionality provided by Connector/J 3.1.0 or newer is also not available on JVMs older than 1.4.x, as it relies on `java.util.LinkedHashMap` which was first available in JDK-1.4.0.

### 18.4.2. Connector/J Installation

You can install the Connector/J package using two methods, using either the binary or source distribution. The binary distribution provides the easiest methods for installation; the source distribution enables you to customize your installation further. With either solution, you must manually add the Connector/J location to your Java `CLASSPATH`.

#### 18.4.2.1. Installing Connector/J from a Binary Distribution

The easiest method of installation is to use the binary distribution of the Connector/J package. The binary distribution is available either as a Tar/Gzip or Zip file which you must extract to a suitable location and then optionally make the information about the package available by changing your `CLASSPATH` (see Section 18.4.2.2, “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, and the 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, the `.class` files that constitute the JAR files are only included as part of the driver JAR file.

You should not use the debug build of the driver unless instructed to do so when reporting a problem ors 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 graphical 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.

#### 18.4.2.2. Installing the Driver and Configuring the `CLASSPATH`

Once you have extracted the distribution archive, you can install the driver by placing `mysql-connector-java-[version]-bin.jar` in your classpath, either by adding the full path to it to your `CLASSPATH` environment variable, or by directly specifying it with the command line switch -cp when starting your JVM.

If you are going to use the driver with the JDBC DriverManager, you would use `com.mysql.jdbc.Driver` as the class that implements java.sql.Driver.

You can set the `CLASSPATH` environment variableunder UNIX, Linux or Mac OS X either locally for a user within their `.profile`, `.login` or other login file. You can also set it globally by editing the global `/etc/profile` file.

For example, under a C shell (csh, tcsh) you would add the Connector/J driver to your `CLASSPATH` using the following:

    shell> setenv CLASSPATH /path/mysql-connector-java-[ver]-bin.jar:$CLASSPATH

Or with a Bourne-compatible shell (sh, ksh, bash):

    export set CLASSPATH=/path/mysql-connector-java-[ver]-bin.jar:$CLASSPATH

Within Windows 2000, Windows XP and Windows Server 2003, you must set the environment variable through the System control panel.

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. For configuration examples for some J2EE application servers, see Section 18.4.5.2, “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 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. Starting with Connector/J 5.0.0, the `javax.sql.XADataSource` interface is implemented via the `com.mysql.jdbc.jdbc2.optional.MysqlXADataSource` class, which supports XA distributed transactions when used in combination with MySQL server version 5.0.

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

#### 18.4.2.3. 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.

##### 18.4.2.3.1. Upgrading from MySQL Connector/J 3.0 to 3.1

Connector/J 3.1 is designed to be backward-compatible with Connector/J 3.0 as much as possible. Major changes are isolated to new functionality exposed in MySQL-4.1 and newer, which includes Unicode character sets, server-side prepared statements, SQLState codes returned in error messages by the server and various performance enhancements that can be enabled or disabled via configuration properties.

- Unicode Character Sets — See the next section, as well as Chapter 10, Character Set Support, 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 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 an SQLException with an SQLState of `S1009`.

  - `convertToNull`, which returns `NULL` instead of the date.

  - `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 time zone 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 from 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 configuration property useSqlStateCodes=false.

- `ResultSet.getString()` — 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.

- Debug builds — 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 to do so when reporting a problem or bug to MySQL AB, as it is not designed to be run in production environments, and will have adverse performance impact when used. The debug binary also depends on the Aspect/J runtime library, which is located in the `src/lib/aspectjrt.jar` file that comes with the Connector/J distribution.

##### 18.4.2.3.2. JDBC-Specific Issues When Upgrading to MySQL Server 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`

#### 18.4.2.4. Installing from the Development Source Tree

Caution. You should read this section only if you are interested in helping us test our new code. If you just want to get MySQL Connector/J up and running on your system, you should use a standard release distribution.

To install MySQL Connector/J from the development source tree, make sure that you have the following prerequisites:

- Subversion, to check out the sources from our repository (available from http://subversion.tigris.org/).

- Apache Ant version 1.6 or newer (available from http://ant.apache.org/).

- JDK-1.4.2 or later. Although MySQL Connector/J can be installed on older JDKs, to compile it from source you must have at least JDK-1.4.2.

The Subversion source code repository for MySQL Connector/J is located at http://svn.mysql.com/svnpublic/connector-j. In general, you should not check out the entire repository because it contains every branch and tag for MySQL Connector/J and is quite large.

To check out and compile a specific branch of MySQL Connector/J, follow these steps:

1. At the time of this writing, there are three active branches of Connector/J: `branch_3_0`, `branch_3_1` and `branch_5_0`. Check out the latest code from the branch that you want with the following command (replacing `[major]` and `[minor]` with appropriate version numbers):

       shell> svn co »
       http://svn.mysql.com/svnpublic/connector-j/branches/branch_[major]_[minor]/connector-j

   This creates a `connector-j` subdirectory in the current directory that contains the latest sources for the requested branch.

2. Change location to the `connector-j` directory to make it your current working directory:

       shell> cd connector-j

3. Issue the following command to compile the driver and create a `.jar` file suitable for installation:

       shell> ant dist

   This creates a `build` directory in the current directory, where all build output will go. A directory is created in the `build` directory that includes the version number of the sources you are building from. This directory contains the sources, compiled `.class` files, and a `.jar` file suitable for deployment. For other possible targets, including ones that will create a fully packaged distribution, issue the following command:

       shell> ant --projecthelp

4. A newly created `.jar` file containing the JDBC driver will be placed in the directory `build/mysql-connector-java-`[version]``.

   Install the newly created JDBC driver as you would a binary `.jar` file that you download from MySQL by following the instructions in Section 18.4.2.2, “Installing the Driver and Configuring the `CLASSPATH`”.

### 18.4.3. Connector/J Examples

Examples of using Connector/J are located throughout this document, this section provides a summary and links to these examples.

- Example 18.1, “Obtaining a connection from the `DriverManager`”

- Example 18.2, “Using java.sql.Statement to execute a `SELECT` query”

- Example 18.3, “Stored Procedures”

- Example 18.4, “Using `Connection.prepareCall()`”

- Example 18.5, “Registering output parameters”

- Example 18.6, “Setting `CallableStatement` input parameters”

- Example 18.7, “Retrieving results and output parameter values”

- Example 18.8, “Retrieving `AUTO_INCREMENT` column values using `Statement.getGeneratedKeys()`”

- Example 18.9, “Retrieving `AUTO_INCREMENT` column values using `SELECT LAST_INSERT_ID()`”

- Example 18.10, “Retrieving `AUTO_INCREMENT` column values in `Updatable ResultSets`”

- Example 18.11, “Using a connection pool with a J2EE application server”

- Example 18.12, “Example of transaction with retry logic”

### 18.4.4. Connector/J (JDBC) Reference

This section of the manual contains reference material for MySQL Connector/J, some of which is automatically generated during the Connector/J build process.

#### 18.4.4.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 backward-compatible with MM.MySQL. You should use this class name when registering the driver, or when otherwise configuring software to use MySQL Connector/J.

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 default 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 the `javax.sql.DataSource` `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 tables.

Connection/Authentication.

Property Name | Definition | Default Value | Since Version
user | The user to connect as |  | all
password | The password to use when connecting |  | all
socketFactory | The name of the class that the driver should use for creating socket connections to the server. This class must implement the interface 'com.mysql.jdbc.SocketFactory' and have public no-args constructor. | com.mysql.jdbc.StandardSocketFactory | 3.0.3
connectTimeout | Timeout for socket connect (in milliseconds), with 0 being no timeout. Only works on JDK-1.4 or newer. Defaults to '0'. | 0 | 3.0.1
socketTimeout | Timeout on network socket operations (0, the default means no timeout). | 0 | 3.0.1
useConfigs | Load the comma-delimited list of configuration properties before parsing the URL or applying user-specified properties. These configurations are explained in the 'Configurations' of the documentation. |  | 3.1.5
interactiveClient | Set the CLIENT_INTERACTIVE flag, which tells MySQL to timeout connections based on INTERACTIVE_TIMEOUT instead of WAIT_TIMEOUT | false | 3.1.0
propertiesTransform | An implementation of com.mysql.jdbc.ConnectionPropertiesTransform that the driver will use to modify URL properties passed to the driver before attempting a connection |  | 3.1.4
useCompression | Use zlib compression when communicating with the server (true/false)? Defaults to 'false'. | false | 3.0.17

High Availability and Clustering.

Property Name | Definition | Default Value | Since Version

autoReconnect

Should 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 andstale connections properly. Alternatively, investigate setting the MySQL server variable "wait_timeout"to some high value rather than the default of 8 hours.

false

1.1

autoReconnectForPools | Use a reconnection strategy appropriate for connection pools (defaults to 'false') | false | 3.1.3
failOverReadOnly | When failing over in autoReconnect mode, should the connection be set to 'read-only'? | true | 3.0.12
reconnectAtTxEnd | If autoReconnect is set to true, should the driver attempt reconnectionsat the end of every transaction? | false | 3.0.10
roundRobinLoadBalance | When autoReconnect is enabled, and failoverReadonly is false, should we pick hosts to connect to on a round-robin basis? | false | 3.1.2
queriesBeforeRetryMaster | Number of queries to issue before falling back to master when failed over (when using multi-host failover). Whichever condition is met first, 'queriesBeforeRetryMaster' or 'secondsBeforeRetryMaster' will cause an attempt to be made to reconnect to the master. Defaults to 50. | 50 | 3.0.2
secondsBeforeRetryMaster | How long should the driver wait, when failed over, before attempting to reconnect to the master server? Whichever condition is met first, 'queriesBeforeRetryMaster' or 'secondsBeforeRetryMaster' will cause an attempt to be made to reconnect to the master. Time in seconds, defaults to 30 | 30 | 3.0.2
enableDeprecatedAutoreconnect | Auto-reconnect functionality is deprecated starting with version 3.2, and will be removed in version 3.3. Set this property to 'true' to disable the check for the feature being configured. | false | 3.2.1
resourceId | A globally unique name that identifies the resource that this datasource or connection is connected to, used for XAResource.isSameRM() when the driver can't determine this value based on hostnames used in the URL |  | 5.0.1

Security.

Property Name | Definition | Default Value | Since Version
allowMultiQueries | Allow the use of ';' to delimit multiple queries during one statement (true/false, defaults to 'false' | false | 3.1.1
useSSL | Use SSL when communicating with the server (true/false), defaults to 'false' | false | 3.0.2
requireSSL | Require SSL connection if useSSL=true? (defaults to 'false'). | false | 3.1.0
allowUrlInLocalInfile | Should the driver allow URLs in 'LOAD DATA LOCAL INFILE' statements? | false | 3.1.4
paranoid | Take measures to prevent exposure sensitive information in error messages and clear data structures holding sensitive data when possible? (defaults to 'false') | false | 3.0.1

Performance Extensions.

Property Name | Definition | Default Value | Since Version
metadataCacheSize | The number of queries to cacheResultSetMetadata for if cacheResultSetMetaData is set to 'true' (default 50) | 50 | 3.1.1
prepStmtCacheSize | If prepared statement caching is enabled, how many prepared statements should be cached? | 25 | 3.0.10
prepStmtCacheSqlLimit | If prepared statement caching is enabled, what's the largest SQL the driver will cache the parsing for? | 256 | 3.0.10
useCursorFetch | If connected to MySQL > 5.0.2, and setFetchSize() > 0 on a statement, should that statement use cursor-based fetching to retrieve rows? | false | 5.0.0
blobSendChunkSize | Chunk to use when sending BLOB/CLOBs via ServerPreparedStatements | 1048576 | 3.1.9
cacheCallableStmts | Should the driver cache the parsing stage of CallableStatements | false | 3.1.2
cachePrepStmts | Should 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? | false | 3.0.10
cacheResultSetMetadata | Should the driver cache ResultSetMetaData for Statements and PreparedStatements? (Req. JDK-1.4+, true/false, default 'false') | false | 3.1.1
cacheServerConfiguration | Should the driver cache the results of 'SHOW VARIABLES' and 'SHOW COLLATION' on a per-URL basis? | false | 3.1.5
defaultFetchSize | The driver will call setFetchSize(n) with this value on all newly-created Statements | 0 | 3.1.9
dontTrackOpenResources | The JDBC specification requires the driver to automatically track and close resources, however if your application doesn't do a good job of explicitly calling close() on statements or result sets, this can cause memory leakage. Setting this property to true relaxes this constraint, and can be more memory efficient for some applications. | false | 3.1.7
dynamicCalendars | Should the driver retrieve the default calendar when required, or cache it per connection/session? | false | 3.1.5
elideSetAutoCommits | If using MySQL-4.1 or newer, should the driver only issue 'set autocommit=n' queries when the server's state doesn't match the requested state by Connection.setAutoCommit(boolean)? | false | 3.1.3
holdResultsOpenOverStatementClose | Should the driver close result sets on Statement.close() as required by the JDBC specification? | false | 3.1.7
locatorFetchBufferSize | If 'emulateLocators' is configured to 'true', what size buffer should be used when fetching BLOB data for getBinaryInputStream? | 1048576 | 3.2.1

rewriteBatchedStatements

Should the driver use multiqueries (irregardless of the setting of "allowMultiQueries") as well as rewriting of prepared statements for INSERT into multi-value inserts when executeBatch() is called? Notice that this has the potential for SQL injection if using plain java.sql.Statements and your code doesn't sanitize input correctly. Notice that for prepared statements, server-side prepared statements can not currently take advantage of this rewrite option, and that if you don't specify stream lengths when using PreparedStatement.set*Stream(),the driver won't be able to determine the optimium number of parameters per batch and you might receive an error from the driver that the resultant packet is too large. Statement.getGeneratedKeys() for these rewritten statements only works when the entire batch includes INSERT statements.

false

3.1.13

useFastIntParsing | Use internal String->Integer conversion routines to avoid excessive object creation? | true | 3.1.4
useJvmCharsetConverters | Always use the character encoding routines built into the JVM, rather than using lookup tables for single-byte character sets? (The default of "true" for this is appropriate for newer JVMs | true | 5.0.1
useLocalSessionState | Should the driver refer to the internal values of autocommit and transaction isolation that are set by Connection.setAutoCommit() and Connection.setTransactionIsolation(), rather than querying the database? | false | 3.1.7
useReadAheadInput | Use newer, optimized non-blocking, buffered input stream when reading from the server? | true | 3.1.5

Debuging/Profiling.

Property Name | Definition | Default Value | Since Version
logger | The name of a class that implements 'com.mysql.jdbc.log.Log' that will be used to log messages to.(default is 'com.mysql.jdbc.log.StandardLogger', which logs to STDERR) | com.mysql.jdbc.log.StandardLogger | 3.1.1
profileSQL | Trace queries and their execution/fetch times to the configured logger (true/false) defaults to 'false' | false | 3.1.0
reportMetricsIntervalMillis | If 'gatherPerfMetrics' is enabled, how often should they be logged (in ms)? | 30000 | 3.1.2
maxQuerySizeToLog | Controls the maximum length/size of a query that will get logged when profiling or tracing | 2048 | 3.1.3
packetDebugBufferSize | The maximum number of packets to retain when 'enablePacketDebug' is true | 20 | 3.1.3
slowQueryThresholdMillis | If 'logSlowQueries' is enabled, how long should a query (in ms) before it is logged as 'slow'? | 2000 | 3.1.2
useUsageAdvisor | Should the driver issue 'usage' warnings advising proper and efficient usage of JDBC and MySQL Connector/J to the log (true/false, defaults to 'false')? | false | 3.1.1
autoGenerateTestcaseScript | Should the driver dump the SQL it is executing, including server-side prepared statements to STDERR? | false | 3.1.9
dumpMetadataOnColumnNotFound | Should the driver dump the field-level metadata of a result set into the exception message when ResultSet.findColumn() fails? | false | 3.1.13
dumpQueriesOnException | Should the driver dump the contents of the query sent to the server in the message for SQLExceptions? | false | 3.1.3
enablePacketDebug | When enabled, a ring-buffer of 'packetDebugBufferSize' packets will be kept, and dumped when exceptions are thrown in key areas in the driver's code | false | 3.1.3
explainSlowQueries | If 'logSlowQueries' is enabled, should the driver automatically issue an 'EXPLAIN' on the server and send the results to the configured log at a WARN level? | false | 3.1.2
logSlowQueries | Should queries that take longer than 'slowQueryThresholdMillis' be logged? | false | 3.1.2
traceProtocol | Should trace-level network protocol be logged? | false | 3.1.2

Miscellaneous.

Property Name | Definition | Default Value | Since Version
useUnicode | Should the driver use Unicode character encodings when handling strings? Should only be used when the driver can't determine the character set mapping, or you are trying to 'force' the driver to use a character set that MySQL either doesn't natively support (such as UTF-8), true/false, defaults to 'true' | true | 1.1g
characterEncoding | If 'useUnicode' is set to true, what character encoding should the driver use when dealing with strings? (defaults is to 'autodetect') |  | 1.1g
characterSetResults | Character set to tell the server to return results as. |  | 3.0.13
connectionCollation | If set, tells the server to use this collation via 'set collation_connection' |  | 3.0.13
sessionVariables | A comma-separated list of name/value pairs to be sent as SET SESSION ... to the server when the driver connects. |  | 3.1.8
allowNanAndInf | Should the driver allow NaN or +/- INF values in PreparedStatement.setDouble()? | false | 3.1.5
autoClosePStmtStreams | Should the driver automatically call .close() on streams/readers passed as arguments via set*() methods? | false | 3.1.12
autoDeserialize | Should the driver automatically detect and de-serialize objects stored in BLOB fields? | false | 3.1.5
capitalizeTypeNames | Capitalize type names in DatabaseMetaData? (usually only useful when using WebObjects, true/false, defaults to 'false') | false | 2.0.7
clobCharacterEncoding | The character encoding to use for sending and retrieving TEXT, MEDIUMTEXT and LONGTEXT values instead of the configured connection characterEncoding |  | 5.0.0
clobberStreamingResults | This will cause a 'streaming' ResultSet to be automatically closed, and any outstanding data still streaming from the server to be discarded if another query is executed before all the data has been read from the server. | false | 3.0.9
continueBatchOnError | Should the driver continue processing batch commands if one statement fails. The JDBC spec allows either way (defaults to 'true'). | true | 3.0.3
createDatabaseIfNotExist | Creates the database given in the URL if it doesn't yet exist. Assumes the configured user has permissions to create databases. | false | 3.1.9
emptyStringsConvertToZero | Should the driver allow conversions from empty string fields to numeric values of '0'? | true | 3.1.8
emulateLocators | N/A | false | 3.1.0
emulateUnsupportedPstmts | Should the driver detect prepared statements that are not supported by the server, and replace them with client-side emulated versions? | true | 3.1.7
ignoreNonTxTables | Ignore non-transactional table warning for rollback? (defaults to 'false'). | false | 3.0.9
jdbcCompliantTruncation | Should the driver throw java.sql.DataTruncation exceptions when data is truncated as is required by the JDBC specification when connected to a server that supports warnings(MySQL 4.1.0 and newer)? | true | 3.1.2
maxRows | The maximum number of rows to return (0, the default means return all rows). | -1 | all versions
noAccessToProcedureBodies | When determining procedure parameter types for CallableStatements, and the connected user can't access procedure bodies through "SHOW CREATE PROCEDURE" or select on mysql.proc should the driver instead create basic metadata (all parameters reported as INOUT VARCHARs) instead of throwing an exception? | false | 5.0.3
noDatetimeStringSync | Don't ensure that ResultSet.getDatetimeType().toString().equals(ResultSet.getString()) | false | 3.1.7
noTimezoneConversionForTimeType | Don't convert TIME values using the server timezone if 'useTimezone'='true' | false | 5.0.0
nullCatalogMeansCurrent | When DatabaseMetadataMethods ask for a 'catalog' parameter, does the value null mean use the current catalog? (this is not JDBC-compliant, but follows legacy behavior from earlier versions of the driver) | true | 3.1.8
nullNamePatternMatchesAll | Should DatabaseMetaData methods that accept *pattern parameters treat null the same as '%' (this is not JDBC-compliant, however older versions of the driver accepted this departure from the specification) | true | 3.1.8

overrideSupportsIntegrityEnhancementFacility

Should the driver return "true" for DatabaseMetaData.supportsIntegrityEnhancementFacility() even if the database doesn't support it to workaround applications that require this method to return "true" to signal support of foreign keys, even though the SQL specification states that this facility contains much more than just foreign key support (one such application being OpenOffice)?

false

3.1.12

pedantic | Follow the JDBC spec to the letter. | false | 3.0.0
pinGlobalTxToPhysicalConnection | When using XAConnections, should the driver ensure that operations on a given XID are always routed to the same physical connection? This allows the XAConnection to support "XA START ... JOIN" after "XA END" has been called | false | 5.0.1
processEscapeCodesForPrepStmts | Should the driver process escape codes in queries that are prepared? | true | 3.1.12
relaxAutoCommit | If the version of MySQL the driver connects to does not support transactions, still allow calls to commit(), rollback() and setAutoCommit() (true/false, defaults to 'false')? | false | 2.0.13
retainStatementAfterResultSetClose | Should the driver retain the Statement reference in a ResultSet after ResultSet.close() has been called. This is not JDBC-compliant after JDBC-4.0. | false | 3.1.11
rollbackOnPooledClose | Should the driver issue a rollback() when the logical connection in a pool is closed? | true | 3.0.15
runningCTS13 | Enables workarounds for bugs in Sun's JDBC compliance testsuite version 1.3 | false | 3.1.7
serverTimezone | Override detection/mapping of timezone. Used when timezone from server doesn't map to Java timezone |  | 3.0.2
strictFloatingPoint | Used only in older versions of compliance test | false | 3.0.0
strictUpdates | Should the driver do strict checking (all primary keys selected) of updatable result sets (true, false, defaults to 'true')? | true | 3.0.4
tinyInt1isBit | Should the driver treat the datatype TINYINT(1) as the BIT type (because the server silently converts BIT -> TINYINT(1) when creating tables)? | true | 3.0.16
transformedBitIsBoolean | If the driver converts TINYINT(1) to a different type, should it use BOOLEAN instead of BIT for future compatibility with MySQL-5.0, as MySQL-5.0 has a BIT type? | false | 3.1.9
ultraDevHack | Create PreparedStatements for prepareCall() when required, because UltraDev is broken and issues a prepareCall() for _all_ statements? (true/false, defaults to 'false') | false | 2.0.3
useGmtMillisForDatetimes | Convert between session timezone and GMT before creating Date and Timestamp instances (value of "false" is legacy behavior, "true" leads to more JDBC-compliant behavior. | false | 3.1.12
useHostsInPrivileges | Add '@hostname' to users in DatabaseMetaData.getColumn/TablePrivileges() (true/false), defaults to 'true'. | true | 3.0.2
useInformationSchema | When connected to MySQL-5.0.7 or newer, should the driver use the INFORMATION_SCHEMA to derive information used by DatabaseMetaData? | false | 5.0.0
useJDBCCompliantTimezoneShift | Should the driver use JDBC-compliant rules when converting TIME/TIMESTAMP/DATETIME values' timezone information for those JDBC arguments which take a java.util.Calendar argument? (Notice that this option is exclusive of the "useTimezone=true" configuration option.) | false | 5.0.0
useOldAliasMetadataBehavior | Should the driver use the legacy behavior for "AS" clauses on columns and tables, and only return aliases (if any) for ResultSetMetaData.getColumnName() or ResultSetMetaData.getTableName() rather than the original column/table name? | true | 5.0.4
useOldUTF8Behavior | Use the UTF-8 behavior the driver did when communicating with 4.0 and older servers | false | 3.1.6
useOnlyServerErrorMessages | Don't prepend 'standard' SQLState error messages to error messages returned by the server. | true | 3.0.15
useServerPrepStmts | Use server-side prepared statements if the server supports them? (defaults to 'true'). | true | 3.1.0
useSqlStateCodes | Use SQL Standard state codes instead of 'legacy' X/Open/SQL state codes (true/false), default is 'true' | true | 3.1.3
useStreamLengthsInPrepStmts | Honor stream length parameter in PreparedStatement/ResultSet.setXXXStream() method calls (true/false, defaults to 'true')? | true | 3.0.2
useTimezone | Convert time/date types between client and server timezones (true/false, defaults to 'false')? | false | 3.0.2
useUnbufferedInput | Don't use BufferedInputStream for reading data from the server | true | 3.0.11
yearIsDateType | Should the JDBC driver treat the MySQL type "YEAR" as a java.sql.Date, or as a SHORT? | true | 3.1.9
zeroDateTimeBehavior | What should happen when the driver encounters DATETIME values that are composed entirely of zeroes (used by MySQL to represent invalid dates)? Valid values are 'exception', 'round' and 'convertToNull'. | exception | 3.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. You can enable this feature using:

    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`.

#### 18.4.4.2. JDBC API Implementation Notes

MySQL Connector/J passes all of the tests in the publicly-available version of Sun's JDBC compliance test suite. However, in many places the JDBC specification is vague about how certain functionality should be implemented, or the specification allows leeway in implementation.

This section gives details on a interface-by-interface level about how certain implementation decisions may affect how you use MySQL Connector/J.

- Blob

  Starting with Connector/J version 3.1.0, you can emulate Blobs with locators by adding the property 'emulateLocators=true' to your JDBC URL. Using this method, the driver will delay loading the actual Blob data until you retrieve the other data and then use retrieval methods (`getInputStream()`, `getBytes()`, and so forth) on the blob data stream.

  For this to work, you must use a column alias with the value of the column to the actual name of the Blob, for example:

      SELECT id, data as 'data' from blobtable

  For this to work, you must also follow follow these rules:

  - The `SELECT` must also reference only one table, the table must have a primary key.

  - The `SELECT` must cover all columns that make up the primary key.

  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.

- 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 (`getImportedKeys()`/`getExportedKeys()` and `getCrossReference()`) is only available from InnoDB tables. However, the driver uses `SHOW CREATE TABLE` to retrieve this information, so when other storage engines support foreign keys, the driver will transparently support them as well.

- 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:

  - During both server-side prepared statements and client-side emulation, large data is exchanged only when `PreparedStatement.execute()` is called.

  - 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.

  Connector/J 5.0.0 and later include support for both `Statement.cancel()` and `Statement.setQueryTimeout()`. Both require MySQL 5.0.0 or newer server, and require a separate connection to issue the `KILL QUERY` statement. In the case of `setQueryTimeout()`, the implementation creates an additional thread to handle the timeout functionality.

  ### Note

  Failures to cancel the statement for `setQueryTimeout()` may manifest themselves as `RuntimeException` rather than failing silently, as there is currently no way to unblock the thread that is executing the query being cancelled due to timeout expiration and have it throw the exception instead.

  MySQL does not support SQL cursors, and the JDBC driver doesn't emulate them, so "setCursorName()" has no effect.

#### 18.4.4.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:

Connection Properties - Miscellaneous.

These MySQL Data Types | Can always be converted to these Java types
`CHAR, VARCHAR, BLOB, TEXT, ENUM, and SET` | `java.lang.String, java.io.InputStream, java.io.Reader, java.sql.Blob, java.sql.Clob`
`FLOAT, REAL, DOUBLE PRECISION, NUMERIC, DECIMAL, TINYINT, SMALLINT, MEDIUMINT, INTEGER, BIGINT` | `java.lang.String, java.lang.Short, java.lang.Integer, java.lang.Long, java.lang.Double, java.math.BigDecimal`
`DATE, TIME, DATETIME, TIMESTAMP` | `java.lang.String, java.sql.Date, java.sql.Timestamp`

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.

The `ResultSet.getObject()` method uses the type conversions between MySQL and Java types, following the JDBC specification where appropriate. The value returned by `ResultSetMetaData.GetColumnClassName()` is also shown below. For more information on the `java.sql.Types` classes see Java 2 Platform Types.

MySQL Types to Java Types for ResultSet.getObject().

MySQL Type Name | Return value of `GetColumnClassName` | Returned as Java Class
BIT(1) (new in MySQL-5.0) | BIT | `java.lang.Boolean`
BIT( > 1) (new in MySQL-5.0) | BIT | `byte[]`
TINYINT | TINYINT | `java.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, BOOLEAN | TINYINT | See TINYINT, above as these are aliases for TINYINT(1), currently.
SMALLINT[(M)] [UNSIGNED] | SMALLINT [UNSIGNED] | `java.lang.Integer` (regardless if UNSIGNED or not)
MEDIUMINT[(M)] [UNSIGNED] | MEDIUMINT [UNSIGNED] | `java.lang.Integer,` if UNSIGNED `java.lang.Long`
INT,INTEGER[(M)] [UNSIGNED] | INTEGER [UNSIGNED] | `java.lang.Integer`, if UNSIGNED `java.lang.Long`
BIGINT[(M)] [UNSIGNED] | BIGINT [UNSIGNED] | `java.lang.Long`, if UNSIGNED `java.math.BigInteger`
FLOAT[(M,D)] | FLOAT | `java.lang.Float`
DOUBLE[(M,B)] | DOUBLE | `java.lang.Double`
DECIMAL[(M[,D])] | DECIMAL | `java.math.BigDecimal`
DATE | DATE | `java.sql.Date`
DATETIME | DATETIME | `java.sql.Timestamp`
TIMESTAMP[(M)] | TIMESTAMP | `java.sql.Timestamp`
TIME | TIME | `java.sql.Time`
YEAR[(2|4)] | YEAR | If `yearIsDateType` configuration property is set to false, then the returned object type is `java.sql.Short`. If set to true (the default) then an object of type `java.sql.Date` (with the date set to January 1st, at midnight).
CHAR(M) | CHAR | `java.lang.String` (unless the character set for the column is BINARY, then `byte[]` is returned.
VARCHAR(M) [BINARY] | VARCHAR | `java.lang.String` (unless the character set for the column is BINARY, then `byte[]` is returned.
BINARY(M) | BINARY | `byte[]`
VARBINARY(M) | VARBINARY | `byte[]`
TINYBLOB | TINYBLOB | `byte[]`
TINYTEXT | VARCHAR | `java.lang.String`
BLOB | BLOB | `byte[]`
TEXT | VARCHAR | `java.lang.String`
MEDIUMBLOB | MEDIUMBLOB | `byte[]`
MEDIUMTEXT | VARCHAR | `java.lang.String`
LONGBLOB | LONGBLOB | `byte[]`
LONGTEXT | VARCHAR | `java.lang.String`
ENUM('value1','value2',...) | CHAR | `java.lang.String`
SET('value1','value2',...) | CHAR | `java.lang.String`

#### 18.4.4.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()`, `setAsciiStream()`, `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 `character_set` system variable for server versions older than 4.1.0 and `character_set_server` for server versions 4.1.0 and newer. For more information, see Section 10.3.1, “Server Character Set and Collation”.

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:

MySQL to Java Encoding Name Translations.

MySQL Character Set Name | Java-Style Character Encoding Name
ascii | US-ASCII
big5 | Big5
gbk | GBK
sjis | SJIS (or Cp932 or MS932 for MySQL Server < 4.1.11)
cp932 | Cp932 or MS932 (MySQL Server > 4.1.11)
gb2312 | EUC_CN
ujis | EUC_JP
euckr | EUC_KR
latin1 | ISO8859_1
latin2 | ISO8859_2
greek | ISO8859_7
hebrew | ISO8859_8
cp866 | Cp866
tis620 | TIS620
cp1250 | Cp1250
cp1251 | Cp1251
cp1257 | Cp1257
macroman | MacRoman
macce | MacCentralEurope
utf8 | UTF-8
ucs2 | UnicodeBig

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.

#### 18.4.4.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:

- A JDK that includes JSSE (Java Secure Sockets Extension), like JDK-1.4.1 or newer. SSL does not currently work with a JDK that you can add JSSE to, like JDK-1.2.x or JDK-1.3.x due to the following JSSE bug: http://developer.java.sun.com/developer/bugParade/bugs/4273544.html

- A MySQL server that supports SSL and has been compiled and configured to do so, which is MySQL-4.0.4 or later, see Section 5.8.7, “Using Secure Connections”, for more information.

- A client certificate (covered later in this section)

You will first need to import the MySQL server CA Certificate into a Java truststore. A sample MySQL server CA Certificate is located in the `SSL` subdirectory of the MySQL source distribution. This is what SSL will use to determine if you are communicating with a secure MySQL server.

To use Java's keytool to create a truststore in the current directory , and import the server's CA certificate (`cacert.pem`), you can do the following (assuming that keytool is in your path. The keytool should be 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=Some-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.

#### 18.4.4.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 FROM alt_table");

         .......
      }
    }

### 18.4.5. Connector/J Notes and Tips

#### 18.4.5.1. Basic JDBC Concepts

This section provides some general JDBC background.

##### 18.4.5.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 18.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 `Statement` and `PreparedStatement` objects, as well as retrieve metadata about the database. This is explained in the following sections.

##### 18.4.5.1.2. Using Statements to Execute SQL

`Statement` objects 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 it was an `UPDATE`, `INSERT`, or `DELETE` statement. If the statement was a `SELECT` query, you can retrieve the results by calling the `getResultSet()` method. If the statement was an `UPDATE`, `INSERT`, or `DELETE` statement, you can retrieve the affected rows count by calling `getUpdateCount()` on the `Statement` instance.

Example 18.2. Using java.sql.Statement to execute a `SELECT` query

    // assume that 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;
        }
    }

##### 18.4.5.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.

See Stored Procedures and Functions, for more information on MySQL stored procedures.

Connector/J exposes stored procedure functionality through JDBC's `CallableStatement` interface.

Note. Current versions of MySQL server do not return enough information for the JDBC driver to provide result set metadata for callable statements. This means that when using `CallableStatement`, `ResultSetMetaData` may return `NULL`.

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 18.3. Stored Procedures

    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 18.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 18.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, and
       // uses the type 'INTEGER' for values returned from
       // getObject()
       //

       cStmt.registerOutParameter(2, Types.INTEGER);

       //
       // 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 18.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.

   Although `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 18.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 = rs.getMoreResults();
           }

           //
           // Retrieve output parameters
           //
           // Connector/J supports both index-based and
           // name-based retrieval
           //

           int outputValue = cStmt.getInt(2); // index-based

           outputValue = cStmt.getInt("inOutParam"); // name-based

       ...

##### 18.4.5.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 `insertRow()` method.

Example 18.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 18.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 18.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 preceding example code, 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.

#### 18.4.5.2. Using Connector/J with J2EE and Other Java Frameworks

This section describes how to use Connector/J in several contexts.

##### 18.4.5.2.1. General J2EE Concepts

This section provides general background on J2EE concepts that pertain to use of Connector/J.

###### 18.4.5.2.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

  Although this is not usually an issue with the quick connection setup that MySQL offers compared to other databases, creating new JDBC connections still incurs networking and JDBC driver overhead that will be avoided if connections are recycled.

- 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, and so forth) on both the client and server side. Every connection limits how many resources there are available to your application as well as the MySQL server. Many of these resources will be used whether or not the connection is actually doing any useful work!

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 18.11. 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, and so forth), connections, and anything created by them (such as statements or result sets) are closed, so that they may be re-used, otherwise they will be stranded, which in the best case means that the MySQL server resources they represent (such as buffers, locks, or sockets) may be tied up for some time, or worst case, may be tied up forever.

What's the Best Size for my Connection Pool?

As with all other configuration rules-of-thumb, the answer is: it depends. Although the optimal size depends on anticipated load and average database transaction time, the optimum connection pool size is smaller than you might expect. If you take Sun's Java Petstore blueprint application for example, a connection pool of 15-20 connections can serve a relatively moderate load (600 concurrent users) using MySQL and Tomcat with response times that are acceptable.

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 backward from there to determine what values of minimum and maximum pooled connections give the best performance for your particular application.

##### 18.4.5.2.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 whether 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

##### 18.4.5.2.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>

#### 18.4.5.3. 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.

Questions

- 19.4.5.3.1: 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.

- 19.4.5.3.2: My application throws an SQLException 'No Suitable Driver'. Why is this happening?

- 19.4.5.3.3: 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

- 19.4.5.3.4: I have a servlet/application that works fine for a day, and then stops working overnight

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

- 19.4.5.3.6: I cannot connect to the MySQL server using Connector/J, and I'm sure the connection paramters are correct.

Questions and Answers

19.4.5.3.1: 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.

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 the connection should be allowed.

You must add the necessary security credentials to the MySQL server for this to happen, using the `GRANT` statement to your MySQL Server. See Section 13.5.1.2, “`GRANT` Syntax”, for more information.

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. Changing privileges and permissions improperly in MySQL can potentially cause your server installation to not have optimal security properties.

19.4.5.3.2: My application throws an SQLException 'No Suitable Driver'. Why is this happening?

There are three possible causes for this error:

- The Connector/J driver is not in your `CLASSPATH`, see Section 18.4.2, “Connector/J Installation”.

- The format of your connection URL is incorrect, or you are referencing the wrong JDBC driver.

- When using DriverManager, the `jdbc.drivers` system property has not been populated with the location of the Connector/J driver.

19.4.5.3.3: 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

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

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

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 Section 18.4.4.1, “Driver/Datasource Class Names, URL Syntax and Configuration Properties for 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 18.12. 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 40001 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) || "40001".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));
    }

Note. Use of the `autoReconnect` option is not recommended because there is no safe method of reconnecting to the MySQL server without risking some corruption of the connection state or database state information. Instead, you should use a connection pool which will enable your application to connect to the MySQL server using an available connection from the pool. The `autoReconnect` facility is deprecated, and may be removed in a future release.

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

Because MySQL does not have row identifiers, MySQL Connector/J can only update result sets that have come from queries on tables that have at least one primary key, the query must select every primary key and the query can only span one table (that is, no joins). This is outlined in the JDBC specification.

Note that this issue only occurs when using updatable result sets, and is caused because Connector/J is unable to guarantee that it can identify the correct rows within the result set to be updated without having a unique reference to each row. There is no requirement to have a unique field on a table if you are using `UPDATE` or `DELETE` statements on a table where you can individually specify the criteria to be matched using a `WHERE` clause.

19.4.5.3.6: I cannot connect to the MySQL server using Connector/J, and I'm sure the connection paramters are correct.

Make sure that the `skip-networking` option has not been enabled on your server. Connector/J must be able to communicate with your server over TCP/IP, named sockets are not supported. Also ensure that you are not filtering connections through a Firewall or other network security system. For more informaiton, see Section A.2.2, “`Can't connect to [local] MySQL server`”.

### 18.4.6. Connector/J Support

#### 18.4.6.1. Connector/J Community Support

MySQL AB provides assistance to the user community by means of its mailing lists. For Connector/J related issues, you can get help from experienced users by using the MySQL and Java mailing list. Archives and subscription information is available online at http://lists.mysql.com/java.

For information about subscribing to MySQL mailing lists or to browse list archives, visit http://lists.mysql.com/. See Section 1.7.1, “MySQL Mailing Lists”.

Community support from experienced users is also available through the JDBC Forum. You may also find help from other users in the other MySQL Forums, located at http://forums.mysql.com. See Section 1.7.2, “MySQL Community Support at the MySQL Forums”.

#### 18.4.6.2. How to Report Connector/J 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_at_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 from 'jdbc:mysql:///test', 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/.

#### 18.4.6.3. Connector/J Change History

The Connector/J Change History (Changelog) is located with the main Changelog for MySQL. See Section D.8, “MySQL Connector/J Change History”.

## 18.5. MySQL Connector/MXJ

MySQL Connector/MXJ is a solution for deploying the MySQL database engine (`mysqld`) intelligently from within a Java package.

### 18.5.1. Introduction to Connector/MXJ

MySQL Connector/MXJ is a Java Utility package for deploying and managing a MySQL database. 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.

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 a beta release and feedback is welcome and encouraged.

Please send questions or comments to the MySQL and Java mailing list.

#### 18.5.1.1. Connector/MXJ Versions

Connector/MX

- Connector/MXJ 5.x, currently in beta status, includes `mysqld` version 5.x and includes binaries for Linux x86, Mac OS X PPC, Windows XP/NT/2000 x86 and Solaris SPARC. Connector/MXJ 5.x requires the Connector/J 5.x package.

  The exact version of `mysqld` included depends on the version of Connector/MXJ

  1. Connector/MXJ v5.0.3 included MySQL v5.0.22

  2. Connector/MXJ v5.0.4 includes MySQL v5.0.27 (Community) or MySQL v5.0.32 (Enterprise)

- Connector/MXJ 1.x includes `mysqld` version 4.1.13 and includes binaries for Linux x86, Windows XP/NT/2000 x86 and Solaris SPARC. Connector/MXJ 1.x requires the Connector/J 3.x package.

This guide provides information on the Connector/MXJ 5.x release. For information on using the older releases, please see the documentation included with the appropriate distribution.

#### 18.5.1.2. Connector/MXJ Overview

Connector/MXJ consists of a Java class, a copy of the `mysqld` binary for a specific list of platforms, and associated files and support utilities. The Java class controls the initialization of an instance of the embedded `mysqld` binary, and the ongoing management of the `mysqld` process. The entire sequence and management can be controlled entirely from within Java using the Connector/MXJ Java classes. You can see an overview of the contents of the Connector/MXJ package in the figure below.

It is important to note that Connector/MXJ is not an embedded version of MySQL, or a version of MySQL written as part of a Java class. Connector/MXJ works through the use of an embedded, compiled binary of `mysqld` as would normally be used when deploying a standard MySQL installation.

It is the Connector/MXJ wrapper, support classes and tools, that enable Connector/MXJ to appear as a MySQL instance.

When Connector/MXJ is initialized, the corresponding `mysqld` binary for the current platform is extracted, along with a pre-configured data directed. Both are contained within the Connector/MXJ JAR file. The `mysqld` instance is then started, with any additional options as specified during the initialization, and the MySQL database becomes accessible.

Because Connector/MXJ works in combination with Connector/J, you can access and integrate with the MySQL instance through a JDBC connection. When you have finished with the server, the instance is terminated, and, by default, any data created during the session is retained within the temporary directory created when the instance was started.

Connector/MXJ and the embedded `mysqld` instance can be deployed in a number of environments where relying on an existing database, or installing a MySQL instance would be impossible, including CD-ROM embedded database applications and temporary database requirements within a Java-based application environment.

### 18.5.2. Connector/MXJ Installation

Connector/MXJ does not have a installation application or process, but there are some steps you can follow to make the installation and deployment of Connector/MXJ easier.

Before you start, there are some baseline requirements for

- Java Runtime Environment (v1.4.0 or newer) if you are only going to deploy the package.

- Java Development Kit (v1.4.0 or newer) if you want to build Connector/MXJ from source.

- Connector/J 5.0 or newer.

Depending on your target installation/deployment environment you may also require:

- JBoss - 4.0rc1 or newer

- Apache Tomcat - 5.0 or newer

- Sun's JMX reference implementation version 1.2.1 (from http://java.sun.com/products/JavaManagement/)

#### 18.5.2.1. Supported Platforms

Connector/MXJ is compatible with any platform supporting Java and MySQL. By default, Connector/MXJ incorporates the `mysqld` binary for a select number of platforms, as outlined below.

- Linux, i386

- Windows NT, Windows 2000, Windows XP, x86

- Solaris 8, SPARC 32 (compatible with Solaris 8, Solaris 9 and Solaris 10 on SPARC 32-bit and 64-bit platforms)

- Mac OS X, PowerPC

For more information on packaging your own Connector/MXJ with the platforms you require, see Section 18.5.5.1, “Creating your own Connector/MXJ Package”

#### 18.5.2.2. Connector/MXJ Base Installation

Because there is no formal installation process, the method, installation directory, and access methods you use for Connector/MXJ are entirely up to your individual requirements.

To perform a basic installation, choose a target directory for the files included in the Connector/MXJ package. On Unix/Linux systems you may opt to use a directory such as `/usr/local/connector-mxj`; On Windows, you may want to install the files in the base directory, `C:\Connector-MXJ`, or within the `Program Files` directory.

To install the files, for a Connector/MXJ 5.0.4 installation:

1. Download the Connector/MXJ package, either in Tar/Gzip format (ideal for Unix/Linux systems) or Zip format (Windows).

2. Extract the files from the package. This will create a directory `connector-mxj`. Copy and optionally rename this directory to your desired location.

3. For best results, you should update your global `CLASSPATH` variable with the location of the required `jar` files.

   Within Unix/Linux you can do this globally by editing the global shell profile, or on a user by user basis by editing their individual shell profile.

   On Windows 2000, Windows NT and Windows XP, you can edit the global `CLASSPATH` by editing the `Environment Variables` configured through the `System` control panel.

For Connector/MXJ 5.0.4 and later you need the following JAR files in your `CLASSPATH`

1. `connector-mxj.jar` — contains the main Connector/MXJ classes.

2. `connector-mxj-db-files.jar` — contains the embedded `mysqld` and database files.

3. `aspectjrt.jar` — the AspectJ runtime library, located in `lib/aspectjrt.jar` in the Connector/MXJ package.

4. `connector-j.jar` — Connector/J, see Section 18.4, “MySQL Connector/J”.

For Connector/MXJ 5.0.3 and earlier, you need the following JAR files:

1. `connector-mxj.jar`

2. `aspectjrt.jar` — the AspectJ runtime library, located in `lib/aspectjrt.jar` in the Connector/MXJ package.

3. `connector-j.jar` — Connector/J, see Section 18.4, “MySQL Connector/J”.

#### 18.5.2.3. Connector/MXJ Quick Start Guide

Once you have extracted the Connector/MXJ and Connector/J components you can run one of the sample applications that initiates a MySQL instance. You can test the installation by running the `ConnectorMXJUrlTestExample`:

    java ConnectorMXJUrlTestExample
    jdbc:mysql:mxj://localhost:3336/test?server.basedir=/var/tmp/test-mxj
    [MysqldResource] launching mysqld (getOptions)
    [/var/tmp/test-mxj/bin/mysqld][--no-defaults] »
    [--pid-file=/var/tmp/test-mxj/data/MysqldResource.pid] »
    [--socket=mysql.sock][--datadir=/var/tmp/test-mxj/data] »
    [--port=3336][--basedir=/var/tmp/test-mxj]
    [MysqldResource] launching mysqld (driver_launched_mysqld_1)
    InnoDB: The first specified data file ./ibdata1 did not exist:
    InnoDB: a new database to be created!
    060726 15:40:42  InnoDB: Setting file ./ibdata1 size to 10 MB
    InnoDB: Database physically writes the file full: wait...
    060726 15:40:43  InnoDB: Log file ./ib_logfile0 did not exist: new to be created
    InnoDB: Setting log file ./ib_logfile0 size to 5 MB
    InnoDB: Database physically writes the file full: wait...
    060726 15:40:43  InnoDB: Log file ./ib_logfile1 did not exist: new to be created
    InnoDB: Setting log file ./ib_logfile1 size to 5 MB
    InnoDB: Database physically writes the file full: wait...
    InnoDB: Doublewrite buffer not found: creating new
    InnoDB: Doublewrite buffer created
    InnoDB: Creating foreign key constraint system tables
    InnoDB: Foreign key constraint system tables created
    060726 15:40:44  InnoDB: Started; log sequence number 0 0
    060726 15:40:44 [Note] /var/tmp/test-mxj/bin/mysqld: ready for connections.
    Version: '5.0.22-max'  socket: 'mysql.sock'  port: 3336  MySQL Community Edition - Experimental (GPL)
    [MysqldResource] mysqld running as process: 1210
    ------------------------

    5.0.22-max

    ------------------------
    [MysqldResource] stopping mysqld (process: 1210)
    060726 15:40:44 [Note] /var/tmp/test-mxj/bin/mysqld: Normal shutdown

    060726 15:40:45  InnoDB: Starting shutdown...
    060726 15:40:48  InnoDB: Shutdown completed; log sequence number 0 43655
    060726 15:40:48 [Note] /var/tmp/test-mxj/bin/mysqld: Shutdown complete

    [MysqldResource] clearing options
    [MysqldResource] shutdown complete

The above output shows an instance of MySQL starting, the necessary files being created (log files, InnoDB data files) and the MySQL database entering the running state. The instance is then shutdown by Connector/MXJ before the example terminates.

#### 18.5.2.4. Deploying Connector/MXJ using Driver Launch

Connector/MXJ and Connector/J work together to enable you to launch an instance of the `mysqld` server through the use of a keyword in the JDBC connection string. Deploying Connector/MXJ within a Java application can be automated through this method, making the deployment of Connector/MXJ a simple process:

1. Download and unzip Connector/MXJ, add `connector-mxj.jar` to the `CLASSPATH`.

   If you are using Connector/MXJ v5.0.4 or later you will also need to add the `connector-mxj-db-files.jar` file to your `CLASSPATH`.

2. To the JDBC connection string, embed the `mxj` keyword, for example: `jdbc:mysql:mxj://localhost:`PORT`/`DBNAME``.

For more details, see Section 18.5.3, “Connector/MXJ Configuration”.

#### 18.5.2.5. Deploying Connector/MXJ within JBoss

For deployment within a JBoss environment, you must configure the JBoss environment to use the Connector/MXJ component within the JDBC parameters:

1. Download Connector/MXJ and copy the `connector-mxj.jar` file to the `$JBOSS_HOME/server/default/lib` directory.

   If you are using Connector/MXJ v5.0.4 or later you will also need to copy the `connector-mxj-db-files.jar` file to `$JBOSS_HOME/server/default/lib`.

2. Download Connector/J and copy the `mysql-connector-java-`5.0.4`-bin.jar` file to the `$JBOSS_HOME/server/default/lib` directory.

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`.

#### 18.5.2.6. Verifying Installation using JUnit

The best way to ensure that your platform is supported is to run the JUnit tests. These will test the Connector/MXJ classes and the associated components.

##### 18.5.2.6.1. JUnit Test Requirements

The first thing to do is make sure that the components will work on the platform. The `MysqldResource` class is really a wrapper for a native version of MySQL, so 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 5.0 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:

   - JBoss - 4.0rc1 or newer.

   - Apache Tomcat - 5.0 or newer.

   - Sun's JMX reference implementation version 1.2.1 (from http://java.sun.com/products/JavaManagement/).

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/).

##### 18.5.2.6.2. 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 because the default 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 suppress output to the console by default. For verbose output, you may set the "c-mxj_test_silent" Java property to "false".

2. 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.

### 18.5.3. Connector/MXJ Configuration

#### 18.5.3.1. Running as part of the JDBC Driver

A feature of the MySQL Connector/J JDBC driver is the ability to specify a connection to an embedded Connector/MXJ instance through the use of the mxj keyword in the JDBC connection string.

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.

You can find this file in the Connector/MXJ package as `src/ConnectorMXJUrlTestExample.java`.

    import java.io.File;
    import java.sql.Connection;
    import java.sql.DriverManager;
    import java.sql.ResultSet;
    import java.sql.Statement;

    import com.mysql.management.driverlaunched.ServerLauncherSocketFactory;

    public class ConnectorMXJUrlTestExample {
        public static String DRIVER = "com.mysql.jdbc.Driver";

        public static String JAVA_IO_TMPDIR = "java.io.tmpdir";

        public static void main(String[] args) throws Exception {
            File ourAppDir = new File(System.getProperty(JAVA_IO_TMPDIR));
            File databaseDir = new File(ourAppDir, "test-mxj");
            int port = 3336;

            String url = "jdbc:mysql:mxj://localhost:" + port + "/test" + "?"
                    + "server.basedir=" + databaseDir;

            System.out.println(url);

            String userName = "root";
            String password = "";

            Class.forName(DRIVER);
            Connection conn = null;
            try {
                conn = DriverManager.getConnection(url, userName, password);
                printQueryResults(conn, "SELECT VERSION()");
            } finally {
                try {
                    if (conn != null)
                        conn.close();
                } catch (Exception e) {
                    e.printStackTrace();
                }

                ServerLauncherSocketFactory.shutdown(databaseDir, null);
            }
        }

        public static void printQueryResults(Connection conn, String SQLquery)
                throws Exception {
            Statement stmt = conn.createStatement();
            ResultSet rs = stmt.executeQuery(SQLquery);
            int columns = rs.getMetaData().getColumnCount();
            System.out.println("------------------------");
            System.out.println();
            while (rs.next()) {
                for (int i = 1; i <= columns; i++) {
                    System.out.println(rs.getString(i));
                }
                System.out.println();
            }
            rs.close();
            stmt.close();
            System.out.println("------------------------");
            System.out.flush();
            Thread.sleep(100); // wait for System.out to finish flush
        }
    }

To run the above program, be sure to have connector-mxj.jar and Connector/J in the CLASSPATH. Then type:

    java ConnectorMXJTestExample

#### 18.5.3.2. Running within a Java Object

If you 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 enables 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 application using plain java objects.

You can find this file in the Connector/MXJ package as `src/ConnectorMXJObjectTestExample.java`.

    import java.io.File;
    import java.sql.Connection;
    import java.sql.DriverManager;
    import java.sql.ResultSet;
    import java.sql.Statement;
    import java.util.HashMap;
    import java.util.Map;

    import com.mysql.management.MysqldResource;

    public class ConnectorMXJObjectTestExample {
        public static String DRIVER = "com.mysql.jdbc.Driver";

        public static String JAVA_IO_TMPDIR = "java.io.tmpdir";

        public static void main(String[] args) throws Exception {
            File ourAppDir = new File(System.getProperty(JAVA_IO_TMPDIR));
            File databaseDir = new File(ourAppDir, "mysql-mxj");
            int port = 3336;

            MysqldResource mysqldResource = startDatabase(databaseDir, port);

            String userName = "root";
            String password = "";

            Class.forName(DRIVER);
            Connection conn = null;
            try {
                String url = "jdbc:mysql://localhost:" + port + "/test";
                conn = DriverManager.getConnection(url, userName, password);
                printQueryResults(conn, "SELECT VERSION()");
            } finally {
                try {
                    if (conn != null) {
                        conn.close();
                    }
                } catch (Exception e) {
                    e.printStackTrace();
                }
                try {
                    mysqldResource.shutdown();
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }
        }

        public static MysqldResource startDatabase(File databaseDir, int port) {
            MysqldResource mysqldResource = new MysqldResource(databaseDir);

            Map database_options = new HashMap();
            database_options.put("port", Integer.toString(port));
            mysqldResource.start("test-mysqld-thread", database_options);

            if (!mysqldResource.isRunning()) {
                throw new RuntimeException("MySQL did not start.");
            }

            System.out.println("MySQL is running.");

            return mysqldResource;
        }

        public static void printQueryResults(Connection conn, String SQLquery)
                throws Exception {
            Statement stmt = conn.createStatement();
            ResultSet rs = stmt.executeQuery(SQLquery);
            int columns = rs.getMetaData().getColumnCount();
            System.out.println("------------------------");
            System.out.println();
            while (rs.next()) {
                for (int i = 1; i <= columns; i++) {
                    System.out.println(rs.getString(i));
                }
                System.out.println();
            }
            rs.close();
            stmt.close();
            System.out.println("------------------------");
            System.out.flush();
            Thread.sleep(100); // wait for System.out to finish flush
        }
    }

#### 18.5.3.3. Setting server options

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 two driver parameters and two server parameters:

            String url = "jdbc:mysql://" + hostColonPort + "/"
                    + "?"
                    + "cacheServerConfiguration=true"
                    + "&"
                    + "useLocalSessionState=true"
                    + "&"
                    + "server.basedir=/opt/myapp/db"
                    + "&"
                    + "server.datadir=/mnt/bigdisk/myapp/data";

### 18.5.4. Connector/MXJ Reference

#### 18.5.4.1. MysqldResource API

##### 18.5.4.1.1. MysqldResource Constructors

The `MysqldResource` class supports three different constructor forms:

- `public MysqldResource(File baseDir, File dataDir, String mysqlVersionString, PrintStream out, PrintStream err, Utils util)`

  The most detailed constructor, enables you to set the base directory, data directory, select a server by its version string, standard out and standard error and MySQL utilities class.

- `public MysqldResource(File baseDir, File dataDir, String mysqlVersionString, PrintStream out, PrintStream err)`

  Enables you to set the base directory, data directory, select a server by its version string, standard out and standard error.

- `public MysqldResource(File baseDir, File dataDir, String mysqlVersionString)`

  Enables you to set the base directory, data directory and select a server by its version string. Output for standard out and standard err are directed to System.out and System.err.

- `public MysqldResource(File baseDir, File dataDir)`

  Enables you to set the base directory and data directory. The default MySQL version is selected, and output for standard out and standard err are directed to System.out and System.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;

##### 18.5.4.1.2. MysqldResource Methods

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 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.

### 18.5.5. Connector/MXJ Notes and Tips

This section contains notes and tips on using the Connector/MXJ component within your applications.

#### 18.5.5.1. Creating your own Connector/MXJ Package

If you want to create a custom Connector/MXJ package that includes a specific `mysqld` version or platform then you must extract and rebuild the `connector-mxj.jar` (Connector/MXJ v5.0.3 or earlier) or `connector-mxj-db-files.jar` (Connector/MXJ v5.0.4 or later) file.

First, you should create a new directory into which you can extract the current `connector-mxj.jar`:

    shell> mkdir custom-mxj
    shell> cd custom-mxj
    shell> jar -xf connector-mxj.jar
    shell> ls
    5-0-22/
    ConnectorMXJObjectTestExample.class
    ConnectorMXJUrlTestExample.class
    META-INF/
    TestDb.class
    com/
    kill.exe

If you are using Connector/MXJ v5.0.4 or later, you should unpack the `connector-mxj-db-files.jar`:

    shell> mkdir custom-mxj
    shell> cd custom-mxj
    shell> jar -xf connector-mxj-db-files.jar
    shell> ls
    5-0-27/
    META-INF/
    connector-mxj.properties

The MySQL version directory, `5-0-22` or `5-0-27` in the above examples, contains all of the files used to create an instance of MySQL when Connector/MXJ is executed. All of the files in this directory are required for each version of MySQL that you want to embed. Note as well the format of the version number, which uses hyphens instead of periods to separate the version number components.

Within the version specific directory are the platform specific directories, and archives of the `data` and `share` directory required by MySQL for the various platforms. For example, here is the listing for the default Connector/MXJ package:

    shell>> ls
    Linux-i386/
    META-INF/
    Mac_OS_X-ppc/
    SunOS-sparc/
    Win-x86/
    com/
    data_dir.jar
    share_dir.jar
    win_share_dir.jar

Platform specific directories are listed by their OS and platform - for example the `mysqld` for Mac OS X PowerPC is located within the `Mac_OS_X-ppc` directory. You can delete directories from this location that you do not require, and add new directories for additional platforms that you want to support.

To add a platform specific `mysqld`, create a new directory with the corresponding name for your operating system/platform. For example, you could add a directory for Mac OS X/Intel using the directory `Mac_OS_X-i386`.

On Unix systems, you can determine the platform using `uname`:

    shell> uname -p
    i386

Now you need to download or compile `mysqld` for the MySQL version and platform you want to include in your custom `connector-mxj.jar` package into the new directory.

Create a file called `version.txt` in the OS/platform directory you have just created that contains the version string/path of the mysqld binary. For example:

    mysql-5.0.22-osx10.3-i386/bin/mysqld

You can now recreate the `connector-mxj.jar` file with the added `mysqld`:

    shell> cd custom-mxj
    shell> jar -cf ../connector-mxj.jar *

For Connector/MXJ v5.0.4 and later, you should repackage to the `connector-mxj-db-files.jar`:

    shell> cd custom-mxj
    shell> jar -cf ../connector-mxj-db-files.jar *

You should test this package using the steps outlined in Section 18.5.2.3, “Connector/MXJ Quick Start Guide”.

### Note

Because the `connector-mxj-db-files.jar` file is separate from the main Connector/MXJ classes you can distribute different `connector-mxj-db-files.jar` files to different hotsts or for different projects without having to create a completely new main `connector-mxj.jar` file for each one.

#### 18.5.5.2. Deploying Connector/MXJ with a pre-configured database

To include a pre-configured/populated database within your Connector/MXJ JAR file you must create a custom `data_dir.jar` file, as included within the main `connector-mxj.jar` (Connector/MXJ 5.0.3 or earlier) or `connector-mxj-db-files.jar` (Connector/MXJ 5.0.4 or later) file:

1. First extract the `connector-mxj.jar` file, as outlined in the previous section (see Section 18.5.5.1, “Creating your own Connector/MXJ Package”).

2. First, create your database and populate the database with the information you require in an existing instance of MySQL - including Connector/MXJ instances. Data file formats are compatible across platforms.

3. Shutdown the instance of MySQL.

4. Create a JAR file of the data directory and databases that you want to include your Connector/MXJ package. You should include the `mysql` database, which includes user authentication information, in addition to the specific databases you want to include. For example, to create a JAR of the `mysql` and `mxjtest` databases:

       shell> jar -cf ../data_dir.jar mysql mxjtest

5. For Connector/MXJ 5.0.3 or earlier, copy the `data_dir.jar` file into the extracted `connector-mxj.jar` directory, and then create an archive for `connector-mxj.jar`.

   For Connector/MXJ 5.0.4 or later, copy the `data_dir.jar` file into the extracted `connector-mxj-db-files.jar` directory, and then create an archive for `connector-mxj-db-files.jar`.

Note that if you are create databases using the InnoDB engine, you must include the `ibdata.*` and `ib_logfile*` files within the `data_dir.jar` archive.

#### 18.5.5.3. Running within a JMX Agent (custom)

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.

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)

#### 18.5.5.4. 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 experiment 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.

### 18.5.6. Connector/MXJ Support

There are a wide variety of options available for obtaining support for using Connector/MXJ. You should contact the Connector/MXJ community for help before reporting a potential bug or problem. See Section 18.5.6.1, “Connector/MXJ Community Support”.

#### 18.5.6.1. Connector/MXJ Community Support

MySQL AB provides assistance to the user community by means of a number of mailing lists and web based forums.

You can find help and support through the MySQL and Java mailing list.

For information about subscribing to MySQL mailing lists or to browse list archives, visit http://lists.mysql.com/. See Section 1.7.1, “MySQL Mailing Lists”.

Community support from experienced users is also available through the MyODBC Forum. You may also find help from other users in the other MySQL Forums, located at http://forums.mysql.com. See Section 1.7.2, “MySQL Community Support at the MySQL Forums”.

#### 18.5.6.2. How to Report Connector/MXJ Problems

If you encounter difficulties or problems with Connector/MXJ, contact the Connector/MXJ community Section 18.5.6.1, “Connector/MXJ Community Support”.

If reporting a problem, you should ideally include the following information with the email:

- Operating system and version

- Connector/MXJ version

- MySQL server version

- Copies of error messages or other unexpected output

- Simple reproducible sample

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

If you believe the problem to be a bug, then you must report the bug through http://bugs.mysql.com/.

## 18.6. Connector/PHP

The PHP distribution and documentation are available from the PHP Web site. MySQL provides the `mysql` and `mysqli` extensions for the Windows operating system on http://dev.mysql.com/downloads/connector/php/ for MySQL version 4.1.16 and higher, MySQL 5.0.18, and MySQL 5.1. You can find information why you should preferably use the extensions provided by MySQL on that page. For platforms other than Windows, you should use the `mysql` or `mysqli` extensions shipped with the PHP sources. See Section 17.3, “MySQL PHP API”.

Prev |  | Next
Chapter 17. APIs and Libraries | Home | Chapter 19. Extending MySQL