MariaDB Connector/ODBC is a standardized, LGPL licensed database driver using the industry standard Open Database Connectivity (ODBC) API. It supports ODBC Standard 3.5, can be used as a drop-in replacement for MySQL Connector/ODBC, and it supports both Unicode and ANSI modes. It uses primarily MySQL binary protocol, i.e. prepared statements.

Connector/ODBC 3.0 is the current stable release series, and Connector/ODBC 2.0 the previous, still supported, release series.

The most recent stable (GA) release of MariaDB Connector/ODBC is:
MariaDB Connector/ODBC 3.0.6

DateReleaseStatusRelease NotesChangelog
2 Aug 2018MariaDB Connector/ODBC 3.0.6Stable (GA)Release NotesChangelog
12 Jun 2018MariaDB Connector/ODBC 3.0.5Stable (GA)Release NotesChangelog
8 Feb 2018MariaDB Connector/ODBC 3.0.3Stable (GA)Release NotesChangelog
8 Sep 2018MariaDB Connector/ODBC 2.0.18Stable (GA)Release NotesChangelog
12 Jun 2018MariaDB Connector/ODBC 2.0.17Stable (GA)Release NotesChangelog
8 Feb 2018MariaDB Connector/ODBC 2.0.16Stable (GA)Release NotesChangelog

see all releases

Obtaining MariaDB Connector/ODBC

The driver is available for download from https://downloads.mariadb.org/connector-odbc/

You should install both the 32-bit and 64-bit drivers. Otherwise you may get this error message:

[Microsoft][ODBC Driver Manager] The specified DSN contains an
 architecture mismatch between the Driver and Application.

Source Code

The source code is available on GitHub: https://github.com/MariaDB/mariadb-connector-odbc

Building from Source

We recommend that you build from the git checkout.

First, to be able to build Connector/ODBC, you need to have the following tools - cmake, git, and a compiler - Visual Studio on Windows or gcc on other OSs. You don't need to install anything additional on Windows. On other systems you also need 'make' and UnixODBC Driver Manager. It's possible to build Connector/ODBC without encrypted connection support. Otherwise you will need to have OpenSSL headers and libraries installed.

On Linux, you may need to run one of following commands to install these dependencies:

sudo yum -y install git cmake make gcc openssl-devel unixODBC unixODBC-devel

or

sudo apt-get update
sudo sh apt-get install -y git cmake make gcc libssl-dev unixodbc-dev

The next step will be to obtain the connector source code:

git clone https://github.com/MariaDB/mariadb-connector-odbc.git
cd mariadb-connector-odbc

If you want to build a specific revision or version, you will need to run something like:

git checkout 3.0.6

This example will put your source tree into the 3.0.6 version state.

Now all is set to start the build itself:

cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCONC_WITH_UNIT_TESTS=Off -DCONC_WITH_MSI=OFF -DCMAKE_INSTALL_PREFIX=/usr/local .
cmake --build . --config RelWithDebInfo

To install a freshly built Connector/ODBC on Windows, run

msiexec.exe /i wininstall\mariadb-connector-odbc-3.0.6-win32.msi

or, on other systems, run

sudo make install

It is slightly different to building from the Connector/ODBC source package. It comes without Connector/C source code. And in order to build Connector/ODBC, you need to download Connector/C source separately, and then copy it into the 'libmariadb' subdirectory in the root of the Connector/ODBC source tree. Other steps are all the same as for building from git checkout.

Also, it should be possible to build from source package using the Connector/C headers and library installed on your system. You need to ensure that the appropriate Connector/C version is installed. Most probably you will need to point your compiler and/or linker to the location of the Connector/C headers and/or library. e.g.

cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCONC_WITH_UNIT_TESTS=Off -DCMAKE_C_FLAGS_RELWITHDEBINFO="-I/usr/local/incude/mariadb -L/usr/local/lib" .

Installation

For Windows, we distribute the MSI installer and the process is fairly straightforward. The installer will take care of registering the connector with the ODBC Driver Manager.

For Linux we currently distribute binaries in tarball only. We don't yet have a library providing a GUI interface for DSN setup for Linux.

First, expand the archive and copy the library file libmaodbc.so to the appropriate place in your system. It can be placed anywhere, but for simplicity let's assume you've copied it to /usr/local/lib.

Then you might need to install the Driver Manager. On Linux we support UnixODBC only. You can install it from the package from the repositories of your Linux distribution, or you may look at the UnixODBC Download page for other options.

Even if you plan to link your application directly against MariaDB Connector/ODBC, you still need header files with ODBC API function prototypes, ODBC data type definitions, etc. For that reason you would still probably need to install UnixODBC. But otherwise, there's nothing more to do to start using MariaDB Connector/ODBC.

If your application uses Driver Manager, i.e. is linked against libodbc from UnixODBC, then you still need to register the connector with Driver Manager.

To do that, first check the ODBCINI and ODBCSYSINI variables of your application environment. ODBCINI should contain the path (absolute or relative) and filename of the odbc.ini file, and ODBCSYSINI the path to the directory containing your ini files. For example:

ODBCINI=~/odbc/odbc.ini
ODBCSYSINI=~/odbc/

If they are not set, you might want to either set them, or to use odbc.ini and odbcinst.ini in the /etc/ directory.

After you have decided on the location of your ini files, add the following section in your odbcinst.ini file.

[MariaDB ODBC 3.0 Driver]
Description = MariaDB Connector/ODBC v.3.0
Driver = /usr/local/lib/libmaodbc.so

This is the minimum you need to be able to connect with SQLDriverConnect function call using MariaDB Connector/ODBC. For that you should specify DRIVER={MariaDB ODBC 3.0 Driver} in your connection string along with other connection parameters. See Connection Parameters below for connection string options.

You might also want to add DSN definition to the odbc.ini file. It may look something like the following:

[mariadb_test]
Driver=MariaDB ODBC 3.0 Driver
DATABASE=test
DESCRIPTION=MariaDB via ODBC
SERVER=localhost
UID=<your_uid>
PASSWORD=<your_pwd>
PORT=3306

Then you can use mariadb_test as the ServerName parameter of SQLConnect, or DSN={mariadb_test} in the connection string of SQLDriverConnect

Connection Parameters

When configuring a DSN you can use the following keywords:

  • DSN: Name of the DSN
  • Driver: The name of the MariaDB ODBC Driver. Must be {MariaDB ODBC 3.0 Driver} for 3.0 drivers. For older versions please use the corresponding version name.
  • Server: name or IP of the MariaDB database server. Aliases: Servername
  • User: user name for database authentication. Aliases: UID,
  • Password: password for database authentication. Aliases: PWD
  • Database: default database. Aliases: DB
  • Port: TCP/IP Port of the database server
  • Option: For MySQL Connector/ODBC compatibility. Aliases: Options. Here are used bits meaning:
    • 0(1) - Currently is not used
    • 1(2) - Tells connector to return the number of matched rows instead of number of changed rows
    • 4(16) - See NO_PROMPT
    • 5(32) - Forces use of dynamic cursor
    • 6(64) - Forbids the use of database.tablename.column syntax
    • 11(2048) - Tells connector to use compression protocol
    • 13(8192) - See NAMEDPIPE
    • 22(4194304) - See AUTO_RECONNECT
    • 26(67108864) - Allows to send multiple statements in one query
  • NAMEDPIPE: boolean value(non-zero value is treated as TRUE) determining whether Server is treated as a named pipe name, or as domain name/IP address. Using of NAMEDPIPE is equivalent of setting/resetting of 13th bit(counting from 0, 8192) OPTIONS bit. It has effect on Windows only.
  • TCPIP: has reverse meaning with NAMEDPIPE. i.e. setting TCPIP=0 effectively means NamedPipe=1. This keyword is also Windows specific.
  • SOCKET: full socket name, if it is specified, server name is disregarded. It has effect on Linux only.
  • INITSTMT: SQL command(s) to be run at connection time
  • CONN_TIMEOUT : connect timeout in seconds
  • AUTO_RECONNECT: enabling/disabling automatic reconnect, the same as setting/resetting 22th(4194304) OPTIONS bit
  • NO_PROMPT: suppresses prompt dialog display at the connection time. This has the same meaning as setting/resetting bit #4(16) of the OPTIONS
  • CHARSET: connection character set. Connector assumes that all incoming string data is encoded in this character set, and uses it if recoding to/from Unicode(utf16) encoding is required.
  • PLUGIN_DIR: directory where to look for (Connector/C) plugins.

The following options are available in 3.0 connectors only

  • SSLKEY: the name of a TLS key for a secure connection
  • SSLCERT: the name of a TLS certificate for a secure connection
  • SSLCA: the name of a file which contains one or more trusted TLS CAs
  • SSLCAPATH: the path which contains trusted CAs
  • SSLCIPHER: a list of cipher suites for TLS encryption
  • SSLVERIFY: Enable (or disable) the verification of the hostname against common name (CN) of the servers host certificate
  • SSLCRL: a file with certificate revocation list
  • SSLCRLPATH: a directory with contains files with certificate revocation lists

Example

SQLWCHAR *ConnStr= L"Driver={MariaDB ODBC 3.0 Driver};Server=localhost;UID=odbc_user;PWD=odbc_pw;DB=odbc_test;Port=3306";

Known Bugs and Limitations

  • multiple statement execution is not fully supported. For example, if you try to prepare a multistatement query where one of statements depends on the execution result of one of the previous statements, it may fail. e.g.
SQLPrepare(hstmt, "CREATE VIEW some_table_view AS SELECT * FROM some_table;SELECT * FROM some_table_view ", SQL_NTS);

will return an error.

Bug Reporting

If you find a bug, please report it via the Jira bug system for MariaDB products.

License

GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

For licensing questions, see the Licensing FAQ.

Comments

Comments loading...