Chapter 23. Connectors

Table of Contents

23.1. MySQL Connector/ODBC
23.1.1. Introduction to MyODBC
23.1.2. How to Install MyODBC
23.1.3. MyODBC Configuration
23.1.4. MyODBC Examples
23.1.5. MyODBC Reference
23.1.6. MyODBC Notes and Tips
23.1.7. MyODBC Support
23.2. Connector/NET
23.2.1. Connector/NET Versions
23.2.2. How to install Connector/NET
23.2.3. Connector/NET Examples
23.2.4. Connector/NET Reference
23.2.5. Connector/NET Notes and Tips
23.2.6. Connector/NET Support
23.3. MySQL Connector/J
23.3.1. Basic JDBC concepts
23.3.2. Installing Connector/J
23.3.3. JDBC Reference
23.3.4. Using Connector/J with J2EE and Other Java Frameworks
23.3.5. Diagnosing Connector/J Problems
23.3.6. MySQL Connector/J Change History
23.4. MySQL Connector/MXJ
23.4.1. Introduction
23.4.2. Supported Platforms
23.4.3. JUnit Test Requirements
23.4.4. Running the JUnit Tests
23.4.5. Running as part of the JDBC Driver
23.4.6. Running within a Java Object
23.4.7. The MysqldResource API
23.4.8. Running within a JMX Agent (custom)
23.4.9. Deployment in a standard JMX Agent environment (JBoss)
23.4.10. Installation
23.5. Connector/PHP

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

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 22, APIs and Libraries chapter.

23.1. MySQL Connector/ODBC

The MySQL Connector/ODBC is the name for the family of MySQL ODBC drivers (also 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 MyODBC 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 MyODBC 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 MyODBC for Unix or Mac OS X if you have an application that requires an ODBC interface to communicate with database.. Applications that require ODBC to communicate with MySQL include ColdFusion, Microsoft Office, and Filemaker Pro.

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

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

23.1.1. Introduction to MyODBC

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

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

23.1.1.1. MyODBC Versions

There are currently two version of MyODBC available:

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

  • MyODBC 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 MyODBC 2.50 driver. It has support for ODBC 3.5x specification level 1 (complete core API + level 2 features) in order to continue to provide all functionality of ODBC for accessing MySQL.

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

23.1.1.2. General Information About ODBC and MyODBC

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

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

23.1.1.2.1. MyODBC Architecture

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

MyODBC Architecture
  • 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 MyODBC driver to enable the ODBC API to communicate with the MySQL host.

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

  • MyODBC Driver:

    The MyODBC 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 23.1.3, “MyODBC 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).

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

23.1.2. How to Install MyODBC

You can install the MyODBC 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 MyODBC drivers before installation.

23.1.2.1. Where to Get MyODBC

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

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

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

23.1.2.2. Supported Platforms

MyODBC 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 23.1.2.4, “Installing MyODBC 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 , so that it becomes available for other users.

23.1.2.3. Installing MyODBC from a binary distribution

Using a binary distribution offers the most straightforward method for installing MyODBC. 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 23.1.2.4, “Installing MyODBC from a source distribution”.

23.1.2.3.1. Installing MyODBC from a Binary Distribution on Windows

Before installing the MyODBC 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 website.

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.

23.1.2.3.1.1. Installing the Windows MyODBC Driver using an installer

The installer packages offer a very simple method for installing the MyODBC 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.

    MyODBC Windows Installer -
                  Welcome
  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.

    MyODBC Windows Installer - Choosing
                  a Setup type welcome
  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.

    MyODBC Windows Installer - Custom
                  Installation welcome
  5. Once the files have copied to your machine, the installation is complete. Click Finish to exit the installer.

    MyODBC Windows Installer -
                  Completion welcome

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

23.1.2.3.1.2. Installing the Windows MyODBC Driver using the Zipped DLL package

If you have downloaded the Zipped DLL package then you must install the individual files required for MyODBC 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 MyODBC Zipped DLL package.

  2. Open a Command Prompt.

  3. Change to the directory created when you unzipped the MyODBC Zipped DLL package.

  4. Run Install.bat:

    C:\> Install.bat

    This will copy the necessary files into the default location, and then register the MyODBC 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 MyODBC 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 MyODBC Zipped DLL package.

  2. Open a Command Prompt.

  3. Change to the directory created when you unzipped the MyODBC 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 MyODBC 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 MyODBC 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.

23.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 MyODBC files and the final installation should still work. If it doesn't, the solution is to re-boot your computer in “safe mode.” Choose safe mode by pressing F8 just before your machine starts Windows during re-booting, install the MyODBC drivers, and re-boot to normal mode.

23.1.2.3.2. Installing MyODBC from a Binary Distribution on Unix

There are two methods available for installing MyODBC 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.

23.1.2.3.2.1. Installing MyODBC from a Binary Tarball Distribution

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

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

23.1.2.3.2.2. Installing MyODBC from an RPM Distribution

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

If you are installing for the first time:

shell> su root
 shell> rpm -ivh MyODBC-3.51.12.i386.rpm

If the driver exists, upgrade it like this:

shell> su root
shell> rpm -Uvh MyODBC-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 23.1.3.4, “Configuring a MyODBC DSN on Unix”.

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

shell> su root
shell> rpm -e MyODBC
23.1.2.3.3. Installing MyODBC 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 MyODBC driver enables you to connect to MySQL databases on any platform through the ODBC interface. You should only need to install the MyODBC driver when your application requires an ODBC interface. Applications that require or can use ODBC (and therefore the MyODBC 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.

23.1.2.3.3.1. Installing the MyODBC Driver

You can install MyODBC 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 MyODBC 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.

    MyODBC Mac OS X Installer -
                  Installer welcome
  4. Please take the time to read the Important Information as it contains guidance on how to complete the installation process. Note that if you want to test a connection to a MySQL database, you will need location of your MySQL server, and a user and password to use to create a suitable DSN to test your installation. Testing the connection is not required to complete the installation. Once you have read the notice and collected the necessary information, click Continue.

    MyODBC Mac OS X Installer -
                  Important Information
  5. MyODBC 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.

    MyODBC Mac OS X Installer -
                  License
  6. Choose a location to install the MyODBC 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.

    MyODBC Mac OS X Installer - Choosing
                  a destination
  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.

    MyODBC Mac OS X Installer -
                  Installation type
  8. When installation has been completed you will get a window like the one shown below. Click Close to close and quit the installer.

    MyODBC Mac OS X Installer -
                  Installation complete

23.1.2.4. Installing MyODBC from a source distribution

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

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

23.1.2.4.1. Installing MyODBC from a Source Distribution on Windows

You should only need to install MyODBC 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 23.1.2.3.1, “Installing MyODBC from a Binary Distribution on Windows”.

Installing MyODBC 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 MyODBC uses new calls and structures that exist only starting from this version of the library. To get the client libraries and include files, visit http://dev.mysql.com/downloads/.

23.1.2.4.1.1. Building MyODBC 3.51

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

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

23.1.2.4.2. Installing MyODBC 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 MyODBC uses new calls and structures that exist only starting from this version of the library. To get the client libraries and include files, visit http://dev.mysql.com/downloads/.

    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. MyODBC is known to work with the iODBC and unixODBC managers. See Section 23.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.

23.1.2.4.2.1. Typical configure Options

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

shell> ./configure --help

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

  1. To compile MyODBC, you need to supply the MySQL client include and library files path using the --with-mysql-path=DIR option, where DIR is the directory where 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 MyODBC drivers in /usr/local/odbc/lib, use the --prefix=/usr/local/odbc option.

The final configuration command looks something like this:

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

There are a number of other options that you need, or want, to set when configuring the MyODBC 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 MyODBC 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
    
23.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 for further assistance.

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

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

This builds and places the libmyodbc3-3.51.01.so file in the .libs directory. Copy this file to the MyODBC 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
23.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 MyODBC 3.51:

  • libmyodbc3.so

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

  • libmyodbc3.a

For thread-safe MyODBC 3.51:

  • libmyodbc3_r.so

  • libmyodbc3-3_r.51.01.so

  • libmyodbc3_r.a

For MyODBC 2.5.0:

  • libmyodbc.so

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

  • libmyodbc.a

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

23.1.2.4.2.6. Testing MyODBC 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.

23.1.2.4.2.7. Building MyODBC 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
23.1.2.4.2.8. Building MyODBC 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.

23.1.2.4.2.9. Building MyODBC 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'.

23.1.2.4.3. Installing MyODBC 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 MyODBC 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 MyODBC 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 MyODBC 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;