All pages
Powered by GitBook
1 of 5

Connector/ODBC

Learn about MariaDB Connector/ODBC, enabling applications to connect to MariaDB and MySQL databases using the Open Database Connectivity API. This guide covers setup and usage.

About MariaDB Connector/ODBC

Download MariaDB Connector/ODBC

MariaDB Connector/ODBC is a database driver that uses the industry standard Open Database Connectivity (ODBC) API. Some of the key features of the driver are:

  • It is LGPL-licensed.

  • It is compliant with the ODBC 3.5 standard.

  • It can be used as a drop-in replacement for MySQL Connector/ODBC.

  • It supports both Unicode and ANSI modes.

  • It primarily uses the MariaDB/MySQL binary protocol (i.e. server-side prepared statements).

The current release series are:

  • MariaDB Connector/ODBC 3.1 is the current stable release series.

  • MariaDB Connector/ODBC 3.0 and 2.0 are both previous stable release series.

Recent Releases

The most recent Stable (GA) release of MariaDB Connector/ODBC is:MariaDB Connector/ODBC 3.2.5

Date
Release
Status
Release Notes
Changelog

24 Feb 2025

MariaDB Connector/ODBC 3.2.5

Stable (GA)

Release Notes

Changelog

14 Nov 2024

MariaDB Connector/ODBC 3.2.4

Stable (GA)

Release Notes

Changelog

26 Aug 2024

MariaDB Connector/ODBC 3.2.3

Stable (GA)

Release Notes

Changelog

24 Feb 2025

MariaDB Connector/ODBC 3.1.21

Stable (GA)

Release Notes

Changelog

4 Dec 2023

MariaDB Connector/ODBC 3.1.20

Stable (GA)

Release Notes

Changelog

7 Jul 2023

MariaDB Connector/ODBC 3.1.19

Stable (GA)

Release Notes

Changelog

see all releases

Installing MariaDB Connector/ODBC

MariaDB Connector/ODBC packages can also be downloaded by selecting ODBC connector as the Product on the following page:

See the instructions below for information on how to install the MariaDB Connector/ODBC package for your operating system.

Installing MariaDB Connector/ODBC on Windows

To install MariaDB Connector/ODBC on Windows, we distribute MSI packages. The MSI installation process is fairly straightforward.

MariaDB Connector/ODBC supports the built-in ODBC Driver Manager on Windows, so nothing else needs to be installed. The MSI installation process will even take care of registering MariaDB Connector/ODBC with the ODBC Driver Manager, so that it is ready to use immediately.

It is generally a good idea to download and install both the 32-bit and 64-bit MSI packages. Otherwise, the ODBC Driver Manager may sometimes load the wrong version of the driver for your application, which can cause errors like the following:

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

Installing MariaDB Connector/ODBC on Linux

To install MariaDB Connector/ODBC on Linux, we currently only distribute binary tarball packages.

The installation process is fairly easy. First, you need to extract the files from the binary tarball. Then, you need to install the driver's shared library to the appropriate place in your system. The driver's shared library is called libmaodbc.so and it is located in either the lib directory or the lib64 directory, depending on whether you downloaded a 32-bit or 64-bit package. The driver's shared library can be installed anywhere, but for simplicity, the instructions below will assume that you are installing it to /usr/lib64, which is a common directory for 64-bit shared libraries on many Linux distributions.

Installation steps for some common Linux distributions are shown below. The commands would be similar for other Linux distributions. However, the URL of the package and the installation path may be different.

Installing MariaDB Connector/ODBC on RHEL/CentOS

The following commands would download and install MariaDB Connector/ODBC 3.1.7 on RHEL or CentOS 7:

mkdir odbc_package
cd odbc_package
wget https://downloads.mariadb.com/Connectors/odbc/connector-odbc-3.1.7/mariadb-connector-odbc-3.1.7-ga-rhel7-x86_64.tar.gz
tar -xvzf mariadb-connector-odbc-3.1.7-ga-rhel7-x86_64.tar.gz
sudo install lib64/libmaodbc.so /usr/lib64/
sudo install -d /usr/lib64/mariadb/
sudo install -d /usr/lib64/mariadb/plugin/
sudo install lib64/mariadb/plugin/auth_gssapi_client.so /usr/lib64/mariadb/plugin/
sudo install lib64/mariadb/plugin/caching_sha2_password.so /usr/lib64/mariadb/plugin/
sudo install lib64/mariadb/plugin/client_ed25519.so /usr/lib64/mariadb/plugin/
sudo install lib64/mariadb/plugin/dialog.so /usr/lib64/mariadb/plugin/
sudo install lib64/mariadb/plugin/mysql_clear_password.so /usr/lib64/mariadb/plugin/
sudo install lib64/mariadb/plugin/sha256_password.so /usr/lib64/mariadb/plugin/

Installing MariaDB Connector/ODBC on Debian/Ubuntu

The following commands would download and install MariaDB Connector/ODBC 3.1.7 on Debian or Ubuntu:

mkdir odbc_package
cd odbc_package
wget https://downloads.mariadb.com/Connectors/odbc/connector-odbc-3.1.7/mariadb-connector-odbc-3.1.7-ga-debian-x86_64.tar.gz
tar -xvzf mariadb-connector-odbc-3.1.7-ga-debian-x86_64.tar.gz
sudo install lib64/libmaodbc.so /usr/lib/
sudo install -d /usr/lib/mariadb/
sudo install -d /usr/lib/mariadb/plugin/
sudo install lib/mariadb/plugin/auth_gssapi_client.so /usr/lib/mariadb/plugin/
sudo install lib/mariadb/plugin/caching_sha2_password.so /usr/lib/mariadb/plugin/
sudo install lib/mariadb/plugin/client_ed25519.so /usr/lib/mariadb/plugin/
sudo install lib/mariadb/plugin/dialog.so /usr/lib/mariadb/plugin/
sudo install lib/mariadb/plugin/mysql_clear_password.so /usr/lib/mariadb/plugin/
sudo install lib/mariadb/plugin/sha256_password.so /usr/lib/mariadb/plugin/

These steps may not work on the following operating system versions due to the packaging bug ODBC-278:

  • Debian 9 (Stretch)

  • Debian 10 (Buster)

  • Ubuntu 19.10 (Eoan Ermine)

  • Ubuntu 20.04 LTS (Focal Fossa)

Installing MariaDB Connector/ODBC on Mac OS X

To install MariaDB Connector/ODBC on Mac OS X, we distribute PKG packages for releases starting with MariaDB Connector/ODBC 3.1.

MariaDB Connector/ODBC supports the built-in iODBC Driver Manager on Mac OS X, so nothing else needs to be installed.

Installing MariaDB Connector/ODBC from Source

See Building MariaDB Connector/ODBC from Source for information on how to build MariaDB Connector/ODBC from source.

Installing UnixODBC on Linux

In order to use MariaDB Connector/ODBC on Linux, you will also need to install a supported Driver Manager. The only Driver Manager that we currently support on Linux is UnixODBC. In most Linux distributions, you can install UnixODBC by using your Linux distribution's package manager.

For example, the following command would install the unixODBC package on RHEL, CentOS, and similar Linux distributions:

sudo yum install unixODBC

And the following command would install the unixodbc and odbcinst packages on Debian, Ubuntu, and similar Linux distributions:

sudo apt-get update
sudo apt-get install unixodbc odbcinst

If you plan to compile an application from source against MariaDB Connector/ODBC and UnixODBC, then you also need the development header files that define the ODBC API function prototypes, ODBC data types, etc. In most Linux distributions, you can install these UnixODBC development files by using your Linux distribution's package manager.

For example, the following command would install the unixODBC-devel package on RHEL, CentOS, and similar Linux distributions:

sudo yum install unixODBC-devel

And the following command would install the unixodbc-dev package on Debian, Ubuntu, and similar Linux distributions:

sudo apt-get update
sudo apt-get install unixodbc-dev

If you can't find the UnixODBC packages with your Linux distribution's package manager, then you may want to look at the download page at UnixODBC.org for other installation options.

Creating a Data Source with MariaDB Connector/ODBC

See Creating a Data Source with MariaDB Connector/ODBC for information on how to create a data source.

Installing Client Authentication Plugins

Authentication plugins are all compiled in statically on Windows since 3.1.18

In MariaDB Connector/ODBC 3.1 and later, MariaDB Connector/ODBC bundles client authentication plugins with the connector.

In MariaDB Connector/ODBC 3.0 and before, MariaDB Connector/ODBC does not bundle client authentication plugins with the connector.

The connector will need to use client authentication plugins in the following scenarios:

  • The server uses the pam authentication plugin.

  • The server uses the gssapi authentication plugin.

  • The server uses the ed25519 authentication plugin.

  • You are connecting to a MySQL server that uses one of the SHA-256 authentication plugins--i.e. either the sha256_password or the caching_sha2_password authentication plugins. However, MariaDB Connector/ODBC is more compatible with MariaDB than with MySQL, and it may not yet fully support these MySQL-only authentication plugins. See ODBC-241 for more information.

If you need client authentication plugins in a version which does not bundle them with the connector, then you will also need to install MariaDB Connector/C, which installs the client authentication plugins as shared libraries, which can be used by MariaDB Connector/ODBC.

MariaDB Connector/ODBC can be configured to use MariaDB Connector/C's client authentication plugins by setting the PLUGINDIR parameter to the MariaDB Connector/C's plugin directory. The plugin directory can also be specified with the MARIADB_PLUGIN_DIR environment variable.

On Windows, MariaDB Connector/C often installs plugins to one of the following directories:

  • C:\Program Files\MariaDB\MariaDB Connector C\lib\plugin

  • C:\Program Files (x86)\MariaDB\MariaDB Connector C\lib\plugin

On Linux, MariaDB Connector/C often installs client authentication plugins to one of the following directories:

  • /usr/lib64/mysql/plugin

  • /usr/lib/mysql/plugin

When you install the client authentication plugins, ensure that they are for the same architecture as your MariaDB Connector/ODBC installation. If your MariaDB Connector/ODBC installation is 64-bit, then you should install 64-bit client authentication plugins. Likewise, if your MariaDB Connector/ODBC installation is 32-bit, then you should install 32-bit client authentication plugins.

Parameters

DSN-Related Parameters

  • DSN: Name of the DSN

  • Driver: The name of the MariaDB ODBC Driver. On Windows, this must be {MariaDB ODBC 3.1 Driver} for 3.1 drivers, or for versions from other release series, you must use the corresponding version number for that release series. On Linux, either this must be a path to the driver's shared library or it must match the Driver name that you provided when you configured the Driver with UnixODBC.

  • Description: Description of the data source.

  • SaveFile: Save a string representation of the DSN to this file.

  • FileDSN: The file where the string representation of the DSN can be read.

Logging-Related Parameters

  • Trace: Whether to enable the ODBC trace log.

  • TraceFile: If the ODBC trace log is enabled, then this is the path to the output file.

General Connection Parameters

  • 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

    • 7(128) Allows [load-data-infile|LOAD DATA INFILE LOCAL]

    • 11(2048) - Tells connector to use compression protocol

    • 13(8192) - See NAMEDPIPE

    • 16(65536) - See USE_MYCNF

    • 21(2097152) - See FORWARDONLY

    • 22(4194304) - See AUTO_RECONNECT

    • 26(67108864) - Allows to send multiple statements in one query

  • NAMEDPIPE: This parameter accepts a boolean value, where all non-zero values are treated as true. When this parameter is enabled, the value of the SOCKET parameter is treated as a named pipe name, rather than a path to a Unix domain socket. Alternatively, setting the 13th bit in the OPTIONS bitmask is equivalent to setting this parameter. This parameter only has an effect on Windows.

  • TCPIP: This parameter has the opposite meaning of the NAMEDPIPE parameter. When TCPIP=0 is set, NAMEDPIPE=1 is effectively set. This parameter only has an effect on Windows.

  • SOCKET: By default, this parameter accepts a path to a Unix domain socket. If NAMEDPIPE=1 is set on Windows, this parameter accepts the name of a named pipe instead. When this parameter is specified, the value of the SERVER parameter and its aliases are ignored.

  • 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: Specify the location of client plugins. Starting from the version 3.1.12, all authentication plugins are compiled in for Windows releases, thus with option becomes Linux/MacOS-specific

  • USE_MYCNF: whether to read options from the [odbc] option group in the system's default my.cnf option file.

  • SERVERKEY: Specifies the name of the file which contains the RSA public key of the database server. The format of this file must be in PEM format. This option is used by the caching_sha2_password client authentication plugin.

    • This parameter is available starting with MariaDB Connector/ODBC version 3.1.4.

  • INTERACTIVE: tells server, that the client is interactive, and it should use interactive_timeout for this connection

    • This parameter is available starting with MariaDB Connector/ODBC version 3.1.10.

  • FORWARDONLY: forces all cursors to be forward only.

    • This parameter is available starting with MariaDB Connector/ODBC version 3.1.10

  • PREPONCLIENT: forces SQLPrepare to use client side prepare if possible.

    • This parameter is available starting with MariaDB Connector/ODBC version 3.2.0

  • ATTR: option to set connection attributes. Using it makes sense only if performance schema is enabled on server. Format: ATTR={<attrname1>=<attrvalue1>[,<attrname2=attrvalue2,...]}

    • This parameter is available starting with MariaDB Connector/ODBC version 3.2.0

  • EDSERVER: forces SQLExecDirect to use server side prepare if possible. It is useful if binary protocol is preferable to use for the queries.

    • This parameter is available starting with MariaDB Connector/ODBC version 3.2.5

General Connection Parameters Example

For example, to set these parameters in a connection string via C/C++ code, you could do something like the following:

SQLWCHAR *ConnStr= L"Driver={MariaDB ODBC 3.2 Driver};SERVER=mydatabase.mydomain.com;USER=odbc_user;PASSWORD=odbc_pw;DATABASE=odbc_test;PORT=3306";

To set these same parameters in a UnixODBC or iODBC configuration file, you could do something like the following:

[MariaDB-server]
Description = MariaDB server
Driver = MariaDB ODBC 3.2 Driver
Trace = Yes
TraceFile = /tmp/trace.log
SERVER = mydatabase.mydomain.com
USER = odbc_user
PASSWORD = odbc_pw
DATABASE = odbc_test
PORT = 3306

TLS-Related Connection Parameters

The following TLS-related connection parameters are available in MariaDB Connector/ODBC 3.0 and later:

  • SSLCERT: Defines a path to the X509 certificate file to use for TLS. This parameter requires that you use the absolute path, not a relative path.

  • SSLKEY: Defines a path to a private key file to use for TLS. The key file must be unencrypted. This parameter requires that you use the absolute path, not a relative path.

  • SSLCA: Defines a path to a PEM file that should contain one or more X509 certificates for trusted Certificate Authorities (CAs) to use for TLS. This parameter requires that you use the absolute path, not a relative path.

  • SSLCAPATH: Defines a path to a directory that contains one or more PEM files that should each contain one X509 certificate for a trusted Certificate Authority (CA) to use for TLS. This parameter requires that you use the absolute path, not a relative path. The directory specified by this parameter needs to be run through the openssl rehash command.

  • SSLCIPHER: Defines a list of permitted ciphers or cipher suites to use for TLS..

  • SSLVERIFY: Enables (or disables) server certificate verification.

  • SSLCRL: Defines a path to a PEM file that should contain one or more revoked X509 certificates to use for TLS. This parameter requires that you use the absolute path, not a relative path.

  • SSLCRLPATH: Defines a path to a directory that contains one or more PEM files that should each contain one revoked X509 certificate to use for TLS. This parameter requires that you use the absolute path, not a relative path. The directory specified by this parameter needs to be run through the openssl rehash command.

  • TLSVERSION: Specify which TLS versions are allowed. The value can be a comma-separated list of string names consisting of TLSv1.1, TLSv1.2, and TLSv1.3, or it can be an integer value that represents a bitmap, where TLSv1.1 corresponds to bit 1, TLSv1.2 corresponds to bit 2, and TLSv1.3 corresponds to bit 3.

    • This parameter is available starting with MariaDB Connector/ODBC versions 3.0.9 and 3.1.1.

  • FORCETLS: Whether to force TLS.

    • This parameter is available starting with MariaDB Connector/ODBC versions 3.0.9 and 3.1.1.

  • TLSPEERFP: Specify the SHA1 fingerprint of a server certificate for validation during the TLS handshake. Aliases: SSLFP

    • This parameter is available starting with MariaDB Connector/ODBC version 3.1.4.

  • TLSPEERFPLIST: Specify a file which contains one or more SHA1 fingerprints of server certificates for validation during the TLS handshake. Aliases: SSLFPLIST

    • This parameter is available starting with MariaDB Connector/ODBC version 3.1.4.

  • TLSKEYPWD: Specify a passphrase for a passphrase-protected private key, as configured by the SSLKEY option. This option is only supported if the connector was built with OpenSSL or GnuTLS. If the connector was built with Schannel, then this option is not supported.

    • This parameter is available starting with MariaDB Connector/ODBC version 3.1.8.

TLS-Related Connection Parameters Examples

Two-Way TLS Example

Two-way TLS means that both the client and server provide TLS certificates and keys.

For example, to set these parameters in a connection string via C/C++ code, you could do something like the following:

SQLWCHAR *ConnStr= L"Driver={MariaDB ODBC 3.2 Driver};SERVER=mydatabase.mydomain.com;USER=odbc_user;PASSWORD=odbc_pw;DATABASE=odbc_test;PORT=3306;SSLCERT=/etc/my.cnf.d/certificates/client-cert.pem;SSLKEY=/etc/my.cnf.d/certificates/client-key.pem;SSLCA=/etc/my.cnf.d/certificates/ca.pem;SSLVERIFY=1";

To set these same parameters in a UnixODBC or iODBC configuration file, you could do something like the following:

[MariaDB-server]
Description = MariaDB server
Driver = MariaDB ODBC 3.2 Driver
Trace = Yes
TraceFile = /tmp/trace.log
SERVER = mydatabase.mydomain.com
USER = odbc_user
PASSWORD = odbc_pw
DATABASE = odbc_test
PORT = 3306
SSLCERT = /etc/my.cnf.d/certificates/client-cert.pem
SSLKEY = /etc/my.cnf.d/certificates/client-key.pem
SSLCA = /etc/my.cnf.d/certificates/ca.pem
SSLVERIFY = 1

One-Way TLS Examples

One-Way TLS with Server Certificate Verification Example

One-way TLS means that only the server provides TLS certificates and keys. Server certificate verification means that the client verifies that the certificate belongs to the server.

For example, to set these parameters in a connection string via C/C++ code, you could do something like the following:

SQLWCHAR *ConnStr= L"Driver={MariaDB ODBC 3.2 Driver};SERVER=mydatabase.mydomain.com;USER=odbc_user;PASSWORD=odbc_pw;DATABASE=odbc_test;PORT=3306;SSLCA=/etc/my.cnf.d/certificates/ca.pem;SSLVERIFY=1";

To set these same parameters in a UnixODBC or iODBC configuration file, you could do something like the following:

[MariaDB-server]
Description = MariaDB server
Driver = MariaDB ODBC 3.2 Driver
Trace = Yes
TraceFile = /tmp/trace.log
SERVER = mydatabase.mydomain.com
USER = odbc_user
PASSWORD = odbc_pw
DATABASE = odbc_test
PORT = 3306
SSLCA = /etc/my.cnf.d/certificates/ca.pem
SSLVERIFY = 1

One-Way TLS without Server Certificate Verification Example

One-way TLS means that only the server provides TLS certificates and keys.

For example, to set these parameters in a connection string via C/C++ code, you could do something like the following:

SQLWCHAR *ConnStr= L"Driver={MariaDB ODBC 3.2 Driver};SERVER=mydatabase.mydomain.com;USER=odbc_user;PASSWORD=odbc_pw;DATABASE=odbc_test;PORT=3306;SSLCIPHER=DHE-RSA-AES256-GCM-SHA384";

To set these same parameters in a UnixODBC or iODBC configuration file, you could do something like the following:

[MariaDB-server]
Description = MariaDB server
Driver = MariaDB ODBC 3.2 Driver
Trace = Yes
TraceFile = /tmp/trace.log
SERVER = mydatabase.mydomain.com
USER = odbc_user
PASSWORD = odbc_pw
DATABASE = odbc_test
PORT = 3306
SSLCIPHER = DHE-RSA-AES256-GCM-SHA384

Data Source Specific Attributes

ODBC 3.8 allows drivers to define and use their own connection and statement attributes. MariaDB Connector/ODBC conforms ODBC 3.8 starting from 3.2 release series. In the version 3.2.5 we introduce our first MariaDB specific statement and connection attribute types.

Independence from the data source is one of the greatest values that using of the ODBC gives to application developers, and use of such attributes won't cause the vendor lock, i.e. dependency on concrete ODBC driver. If application sets these attributes with other 3.8 conforming driver, it will simply get the HYC00 error "Optional feature not implemented". If the driver manager or the driver does not support ODBC 3.8, it will return error about unknown attribute HY024. In any case the application should simply ignore the error(or process it in some way but not to stop normal execution) and using of these attributes with other data sources will not have any bad outcomes, while improving performance if used with the data source they have been designed for MariaDB Connector/ODBC in this case.

The values of these attribute types are defined in the sqlmariadb.h that will be included in our distribution packages and installed under include/mariadb. However application developers might consider to use attribute type literal values and not their defined names in order to avoid extra build dependency.

Here is the list of currently supported attributes

  • SQL_ATTR_EXECDIRECT_ON_SERVER=25100 Can be set at statement or connection level. It controls if SQLExecDirect should use server(if set to SQL_TRUE) or client side(if set to SQL_FALSE, the default) prepared statements. At the connection level it will define default attribute value for all statements created for the connection and is equivalent of use of the EDSERVER connection string option. The type of the attribute value is SQLLEN.

To set the attribute value:

// If sqlmariadb.h included
// This makes Stmt to use server side prepared statement in SQLExecDirect
SQLSetStmtAttr(Stmt, SQL_ATTR_EXECDIRECT_ON_SERVER, (SQLPOINTER)SQL_TRUE, 0);
// This makes all statements created on Connection after this, to use client side prepared statement in
// SQLExecDirect, unless attribute is set to different value for that statement handle
SQLSetConnectAttr(Conn, SQL_ATTR_EXECDIRECT_ON_SERVER, (SQLPOINTER)SQL_FALSE, 0);

// If sqlmariadb.h is *not* included
// This makes Stmt to use client side prepared statement in SQLExecDirect
SQLSetStmtAttr(Stmt, SQL_ATTR_EXECDIRECT_ON_SERVER, (SQLPOINTER)SQL_FALSE, 0);
// This makes all statements created on Connection after this, to use server side prepared statement in
// SQLExecDirect, unless attribute is set to different value for that statement handle
SQLSetConnectAttr(Conn, SQL_ATTR_EXECDIRECT_ON_SERVER, (SQLPOINTER)SQL_TRUE, 0);

To read the attribute value

SQLLEN attributeValue= -1;
// If sqlmariadb.h included
SQLGetStmtAttr(Stmt, SQL_ATTR_EXECDIRECT_ON_SERVER, &attributeValue, 0, NULL);
if (attributeValue == SQL_TRUE) {
// SQLExecDirect will prepare a query on the server and use binary protocol
}
SQLGetConnectAttr(Conn, SQL_ATTR_EXECDIRECT_ON_SERVER, &attributeValue, 0, NULL);

// If sqlmariadb.h is *not* included
SQLGetStmtAttr(Stmt, 25100,  &attributeValue, 0, NULL);
if (attributeValue == SQL_FALSE) {
// SQLExecDirect will prepare a query on the client and use text protocol
}
SQLGetConnectAttr(Conn, 25100, &attributeValue, 0, NULL);

This attribute is available starting with MariaDB Connector/ODBC version 3.2.5.

  • SQL_ATTR_PREPARE_ON_CLIENT=25101 Can be set at statement or connection level. It controls if SQLPrepare should use server(if set to SQL_FALSE, the default) or client side(if set to SQL_TRUE) prepared statements. At the connection level it will define default attribute value for all statements created for the connection and is equivalent of use of the PREPONCLIENT connection string option. The type of the attribute value is SQLLEN.

To set the attribute value:

// If sqlmariadb.h included
// This makes Stmt to use client side prepared statement in SQLPrepare
SQLSetStmtAttr(Stmt, SQL_ATTR_PREPARE_ON_CLIENT, (SQLPOINTER)SQL_TRUE, 0);
// This makes all statements created on Conn after this, to use server side prepared statement in
// SQLPrepare, unless attribute is set to different value for that statement handle
SQLSetConnectAttr(Conn, SQL_ATTR_PREPARE_ON_CLIENT, (SQLPOINTER)SQL_FALSE, 0);

// If sqlmariadb.h is *not* included
// This makes Stmt to use server side prepared statement in SQLPrepare
SQLSetStmtAttr(Stmt, 25101, (SQLPOINTER)SQL_FALSE, 0);
// This makes all statements created on Conn after this, to use client side prepared statement in
// SQLPrepare, unless attribute is set to different value for that statement handle
SQLSetConnectAttr(Conn, 25101, (SQLPOINTER)SQL_TRUE, 0);

To read the attribute value

SQLLEN attributeValue= -1;
// If sqlmariadb.h included
SQLGetStmtAttr(Stmt, SQL_ATTR_PREPARE_ON_CLIENT, &attributeValue, 0, NULL);
if (attributeValue == SQL_TRUE) {
// SQLPrepare will prepare a query on the client side and use text protocol
}
SQLGetConnectAttr(Conn, SQL_ATTR_PREPARE_ON_CLIENT, &attributeValue, 0, NULL);

// If sqlmariadb.h is *not* included
SQLGetStmtAttr(Stmt, 25101,  &attributeValue, 0, NULL);
if (attributeValue == SQL_FALSE) {
// SQLPrepare will prepare a query on the server side and use binary protocol
}
SQLGetConnectAttr(Conn, 25101, &attributeValue, 0, NULL);

This attribute is available starting with MariaDB Connector/ODBC version 3.2.5.

Known Issues

Multiple Statement Execution

Multiple statement execution is not fully supported. This means that if you try to prepare a multi-statement query where one of statements depends on the execution result of one of the previous statements, then it may fail. For example, the following may return an error in some versions:

SQLPrepare(hstmt, "CREATE VIEW some_table_view AS SELECT * FROM some_table;SELECT * FROM some_table_view ", SQL_NTS);

Some bugs related to this have been fixed, such as ODBC-159. If you find similar cases, please report a bug.

3.2 eliminates this issue, but option allowing to send multiple statements in one query(bit 26 = 67108864) has to be selected.

Authenticating with PAM

If you try to authenticate with a user account that is configured to use the pam authentication plugin, then you might see one of the following errors.

You might see this error:

Authentication plugin 'dialog' cannot be loaded: The specified module could not be found.

Or if the server has the pam_use_cleartext_plugin system variable set, then you might see this error instead:

Authentication plugin 'mysql_clear_password' cannot be loaded: The specified module could not be found.

These errors occur because the pam authentication plugin requires specific client authentication plugins in order to work, and MariaDB Connector/ODBC does not install these plugins. To fix the problem, please install the client authentication plugins.

See ODBC-23 for more information.

Authentication plugins are all compiled in statically on Windows since 3.1.18

Reporting Bugs

If you find a bug, please report it via the ODBC project on MariaDB's Jira bug tracker.

Source Code

The source code is available at the mariadb-connector-odbc repository on GitHub.

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.

Building MariaDB Connector/ODBC from Source

Installing MariaDB Connector/ODBC Build Dependencies

Before you can build MariaDB Connector/ODBC, you need to have the following tools installed:

  • cmake

  • git

  • a C compiler - (i.e. Visual Studio on Windows or gcc on Unix-like platforms)

There are no other build dependencies on Windows.

On Unix-like platforms, you also need to have the following tools installed:

  • make

  • UnixODBC - libraries and development headers

If you want your build to support TLS on Unix-like platforms, then you also need to have the following tools installed:

  • OpenSSL - libraries and development headers

Installing Build Dependencies on Linux

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

For example, the following command would install the necessary packages on RHEL, CentOS, and similar Linux distributions:

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

And the following command would install the necessary packages on Debian, Ubuntu, and similar Linux distributions:

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

Building MariaDB Connector/ODBC from the Git Repository

Cloning the MariaDB Connector/ODBC Git Repository

We recommend that you build from the git repository rather than from a source package.

If you are building from the git repository, then your next step would be to clone a local copy of the MariaDB Connector/ODBC source code from the git repository.

The git repository is available on GitHub: mariadb-connector-odbc

You can clone it by executing the git clone command like the following:

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

If you want to build a specific revision or version of MariaDB Connector/ODBC, then you will need to checkout the specific branch or tag by executing the git checkout command like the following:

git checkout 3.0.8

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

Building MariaDB Connector/ODBC

You can build MariaDB Connector/ODBC by executing the cmake command like the following:

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

Installing MariaDB Connector/ODBC

To install a freshly built MariaDB Connector/ODBC on Windows, execute the following:

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

Or to install it on Unix-like platforms, execute the following:

sudo make install

Building MariaDB Connector/ODBC from a Source Package

Building MariaDB Connector/ODBC from a source package is a bit different than building it from the git repoisitory. The source package comes without MariaDB Connector/C source code. And in order to build MariaDB Connector/ODBC, you need to download MariaDB Connector/C source separately, and then copy it into the 'libmariadb' subdirectory in the root of the MariaDB 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 MariaDB Connector/C headers and library installed on your system. You need to ensure that the appropriate MariaDB Connector/C version is installed. Most probably you will need to point your compiler and/or linker to the location of the MariaDB 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" .

Creating a Data Source with MariaDB Connector/ODBC

MariaDB Connector/ODBC is a database driver that uses the industry standard Open Database Connectivity (ODBC) API. Some of the key features of the driver are:

  • It is LGPL-licensed.

  • It is compliant with the ODBC 3.5 standard.

  • It can be used as a drop-in replacement for MySQL Connector/ODBC.

  • It supports both Unicode and ANSI modes.

  • It primarily uses the MariaDB/MySQL binary protocol (i.e. server-side prepared statements).

The current release series are:

  • MariaDB Connector/ODBC 3.1 is the current stable release series.

  • MariaDB Connector/ODBC 2.0 is the previous stable release series, which is currently still supported.

This page discusses how to create a data source with MariaDB Connector/ODBC.

Creating a Data Source with MariaDB Connector/ODBC on Windows

To create a data source on Windows, you would use the ODBC Data Source Administrator.

If you are using the 64-bit version of MariaDB Connector/ODBC, then make sure you use the 64-bit version of ODBC Data Source Administrator. Similarly, if you are using the 32-bit version of MariaDB Connector/ODBC, then make sure you use the 32-bit version of ODBC Data Source Administrator.

To open the ODBC Data Source Administrator in Windows 10:

  • On the Start page, type ODBC Data Sources. The ODBC Data Sources Desktop App should appear as a choice.

To open the ODBC Data Source Administrator in Windows 7:

  • On the Start menu, click Control Panel.

  • In Control Panel, click Administrative Tools.

  • In Administrative Tools, click Data Sources (ODBC).

To open the ODBC Data Source Administrator in Windows Server 2008:

  • On the Start menu, point to Administrative Tools, and then click Data Sources (ODBC).

Creating a Data Source with MariaDB Connector/ODBC on Linux

Linux uses UnixODBC as a Driver Manager. To create a data source on Linux, there are two steps:

  • First, configure UnixODBC to recognize MariaDB Connector/ODBC as a Driver.

  • Second, configure UnixODBC with a Data Source Name (DSN) for your MariaDB Server.

You will need to ensure that UnixODBC has been installed before you can perform these steps.

Configuring MariaDB Connector/ODBC as a UnixODBC Driver on Linux

The first step is to configure UnixODBC to recognize MariaDB Connector/ODBC as a Driver. To configure the Driver, you can use the odbcinst tool, which can add a configuration entry for MariaDB Connector/ODBC to the system's global /etc/odbcinst.ini file.

For example, create a template file similar to the following, with a name like MariaDB_odbc_driver_template.ini:

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

And then install it to the system's global /etc/odbcinst.ini file with the following command:

sudo odbcinst -i -d -f MariaDB_odbc_driver_template.ini

At this point, you should be able to connect to MariaDB by using the Driver with the SQLDriverConnect function. To connect with SQLDriverConnect, you would need to specify Driver={MariaDB ODBC 3.0 Driver} in your connection string along with your other connection parameters.

See Parameters for connection string options.

Configuring a DSN with UnixODBC on Linux

The second step is to configure UnixODBC with a Data Source Name (DSN) for your MariaDB Server. A DSN allows you to centrally configure all of your server's connection parameters, so that you can easily configure how to connect to your server in your environment. To configure the DSN, you can use the odbcinst tool, which can add a configuration entry for the given data source to the system's global /etc/odbc.ini file or your user's local ~/.odbc.ini file.

For example, create a template file similar to the following, with a name like MariaDB_odbc_data_source_template.ini:

[MariaDB-server]
Description=MariaDB server
Driver=MariaDB ODBC 3.0 Driver
SERVER=<your server>
USER=<your user>
PASSWORD=<your password>
DATABASE=<your database>
PORT=<your port>

And then you can install it to the system's global /etc/odbc.ini file with the following command:

sudo odbcinst -i -s -l -f MariaDB_odbc_data_source_template.ini

Or you can install it to your user's local ~/.odbc.ini file with the following command:

odbcinst -i -s -h -f MariaDB_odbc_data_source_template.ini

At this point, you should be able to connect to MariaDB by using the DSN with either SQLConnect or the SQLDriverConnect functions. To connect with SQLConnect, you would have to provide MariaDB-server as the ServerName parameter. To connect with SQLDriverConnect, you would have to provide DSN={MariaDB-server} in the connection string along with your other connection parameters.

See Parameters for connection string options.

UnixODBC also provides a GUI to add DSNs. However, MariaDB Connector/ODBC doesn't yet support this GUI interface for adding DSNs.

Verifying a DSN Configuration with UnixODBC on Linux

You can verify that a DSN is properly configured with UnixODBC on Linux by using the isql utility.

For example, if the DSN is called MariaDB-server, then we can verify that it works properly by executing the following:

$ isql MariaDB-server
+---------------------------------------+
| Connected!                            |
|                                       |
| sql-statement                         |
| help [tablename]                      |
| quit                                  |
|                                       |
+---------------------------------------+
SQL> SELECT @@global.hostname;
+-------------------------------------------+
| @@global.hostname                         |
+-------------------------------------------+
| ip-172-30-0-249.us-west-2.compute.internal|
+-------------------------------------------+
SQLRowCount returns 1
1 rows fetched
SQL> quit

Changing UnixODBC's Configuration File Paths

You can also change the paths that unixODBC uses for its configuration files by changing some environment variables. For example:

  • ODBCSYSINI - Overloads path to unixODBC configuration files. By default equals to /etc.

  • ODBCINSTINI - Overloads the name of the drivers configuration file. It is relative to ODBCSYSINI and by default set to odbcinst.ini.

  • ODBCINI - Overloads the path to user configuration file. By default it is set to ~/.odbc.ini.

Creating a Data Source with MariaDB Connector/ODBC on Mac OS X

Mac OS X uses iODBC as a Driver Manager. To create a data source on Mac OS X, there are two primary ways to do it:

Creating a Data Source with iODBC Administrator on Mac OS X

iODBC Administrator is not installed by default. In order to use it, you need to dowload it from iODBC's download page and then install it.

Creating a Data Source with iODBC on Mac OS X

The steps to create a data source with iODBC on Mac OS X can be found here. There are essentially two steps:

  • First, configure iODBC to recognize MariaDB Connector/ODBC as a Driver.

  • Second, configure iODBC with a Data Source Name (DSN) for your MariaDB Server.

Configuring MariaDB Connector/ODBC as a iODBC Driver on Mac OS X

The first step is to configure iODBC to recognize MariaDB Connector/ODBC as a Driver.

The iODBC Driver configuration file might be at one of these paths:

  • The path specified by the $ODBCINSTINI environment variable.

  • ~/.odbcinst.ini

  • ~/Library/ODBC/odbcinst.ini

  • /etc/odbcinst.ini

  • /Library/ODBC/odbcinst.ini

MariaDB Connector/ODBC's PKG package automatically configures itself as a Driver in /Library/ODBC/odbcinst.ini, so you can most likely skip this step.

To add MariaDB Connector/ODBC as a Driver, the configuration file would look something like the following:

[ODBC Drivers]
MariaDB ODBC 3.1 Driver = installed

[MariaDB ODBC 3.1 Driver]
Description=MariaDB Connector/ODBC v.3.1
Driver=/Library/MariaDB/MariaDB-Connector-ODBC/libmaodbc.dylib
Threading=0

Configuring a DSN with iODBC on Mac OS X

The second step is to configure iODBC with a Data Source Name (DSN) for your MariaDB Server. A DSN allows you to centrally configure all of your server's connection parameters, so that you can easily configure how to connect to your server in your environment.

The iODBC DSN configuration file might be at one of these paths:

  • The path specified by the $ODBCINI environment variable.

  • ~/.odbc.ini

  • ~/Library/ODBC/odbc.ini

  • /etc/odbc.ini

  • /Library/ODBC/odbc.ini

To add a DSN that uses MariaDB Connector/ODBC, the configuration file would look something like the following:

[ODBC]
Debug = 1
DebugFile = /tmp/odbc-debugfile.log
Trace = 0
TraceFile = /tmp/odbc-tracefile.log
TraceAutoStop = 1

[ODBC Data Sources]
MariaDB-server = MariaDB ODBC 3.1 Driver

[MariaDB-server]
Description = MariaDB server
Driver = /Library/MariaDB/MariaDB-Connector-ODBC/libmaodbc.dylib
SERVER=<your server>
USER=<your user>
PASSWORD=<your password>
DATABASE=<your database>
PORT=<your port>

Verifying a DSN Configuration with iODBC on Mac OS X

You can verify that a DSN is properly configured with iODBC on Mac OS X by using the iodbctest utility.

For example, if the DSN is called MariaDB-server, then we can verify that it works properly by executing the following:

$ iodbctest "DSN=MariaDB-server"

List of MariaDB Connector/ODBC Releases

Download MariaDB Connector/ODBC

<< back to About MariaDB Connector/ODBC

Date
Release
Status
Release Notes
Changelog

24 Feb 2025

MariaDB Connector/ODBC 3.2.5

Stable (GA)

Release Notes

Changelog

14 Nov 2024

MariaDB Connector/ODBC 3.2.4

Stable (GA)

Release Notes

Changelog

26 Aug 2024

MariaDB Connector/ODBC 3.2.3

Stable (GA)

Release Notes

Changelog

18 Jun 2024

MariaDB Connector/ODBC 3.2.2

Stable (GA)

Release Notes

Changelog

1 Dec 2023

MariaDB Connector/ODBC 3.2.1

RC

Release Notes

Changelog

21 Apr 2023

MariaDB Connector/ODBC 3.2.0

Alpha

Release Notes

Changelog

24 Feb 2025

MariaDB Connector/ODBC 3.1.21

Stable (GA)

Release Notes

Changelog

4 Dec 2023

MariaDB Connector/ODBC 3.1.20

Stable (GA)

Release Notes

Changelog

7 Jul 2023

MariaDB Connector/ODBC 3.1.19

Stable (GA)

Release Notes

Changelog

13 Apr 2023

MariaDB Connector/ODBC 3.1.18

Stable (GA)

Release Notes

Changelog

30 Aug 2022

MariaDB Connector/ODBC 3.1.17

Stable (GA)

Release Notes

Changelog

22 Jun 2022

MariaDB Connector/ODBC 3.1.16

Stable (GA)

Release Notes

Changelog

18 Nov 2021

MariaDB Connector/ODBC 3.1.15

Stable (GA)

Release Notes

Changelog

25 Oct 2021

MariaDB Connector/ODBC 3.1.14

Stable (GA)

Release Notes

Changelog

7 Jun 2021

MariaDB Connector/ODBC 3.1.13

Stable (GA)

Release Notes

Changelog

21 Apr 2021

MariaDB Connector/ODBC 3.1.12

Stable (GA)

Release Notes

Changelog

11 Dec 2020

MariaDB Connector/ODBC 3.1.11

Stable (GA)

Release Notes

Changelog

20 Oct 2020

MariaDB Connector/ODBC 3.1.10

Stable (GA)

Release Notes

Changelog

30 Jun 2020

MariaDB Connector/ODBC 3.1.9

Stable (GA)

Release Notes

Changelog

8 Apr 2020

MariaDB Connector/ODBC 3.1.7

Stable (GA)

Release Notes

Changelog

21 Jan 2020

MariaDB Connector/ODBC 3.1.6

Stable (GA)

Release Notes

Changelog

12 Nov 2019

MariaDB Connector/ODBC 3.1.5

Stable (GA)

Release Notes

Changelog

20 Sep 2019

MariaDB Connector/ODBC 3.1.4

Stable (GA)

Release Notes

Changelog

8 Aug 2019

MariaDB Connector/ODBC 3.1.3

Stable (GA)

Release Notes

Changelog

23 Jul 2019

MariaDB Connector/ODBC 3.1.2

Stable (GA)

Release Notes

Changelog

9 May 2019

MariaDB Connector/ODBC 3.1.1

Stable (GA)

Release Notes

Changelog

29 Jan 2019

MariaDB Connector/ODBC 3.1.0

RC

Release Notes

Changelog

3 May 2019

MariaDB Connector/ODBC 3.0.9

Stable (GA)

Release Notes

Changelog

4 Jan 2019

MariaDB Connector/ODBC 3.0.8

Stable (GA)

Release Notes

Changelog

14 Nov 2018

MariaDB Connector/ODBC 3.0.7

Stable (GA)

Release Notes

Changelog

2 Aug 2018

MariaDB Connector/ODBC 3.0.6

Stable (GA)

Release Notes

Changelog

12 Jun 2018

MariaDB Connector/ODBC 3.0.5

Stable (GA)

Release Notes

Changelog

8 Feb 2018

MariaDB Connector/ODBC 3.0.3

Stable (GA)

Release Notes

Changelog

12 Oct 2017

MariaDB Connector/ODBC 3.0.2

Stable (GA)

Release Notes

Changelog

01 Aug 2017

MariaDB Connector/ODBC 3.0.1

Beta

Release Notes

Changelog

19 Jan 2017

MariaDB Connector/ODBC 3.0.0

Alpha

Release Notes

Changelog

5 Jun 2019

MariaDB Connector/ODBC 2.0.19

Stable (GA)

Release Notes

Changelog

8 Sep 2018

MariaDB Connector/ODBC 2.0.18

Stable (GA)

Release Notes

Changelog

12 Jun 2018

MariaDB Connector/ODBC 2.0.17

Stable (GA)

Release Notes

Changelog

8 Feb 2018

MariaDB Connector/ODBC 2.0.16

Stable (GA)

Release Notes

Changelog

23 May 2017

MariaDB Connector/ODBC 2.0.15

Stable (GA)

Release Notes

Changelog

7 Apr 2017

MariaDB Connector/ODBC 2.0.14

Stable (GA)

Release Notes

Changelog

31 Oct 2016

MariaDB Connector/ODBC 2.0.13

Stable (GA)

Release Notes

Changelog

15 Sep 2016

MariaDB Connector/ODBC 2.0.12

Stable (GA)

Release Notes

Changelog

9 Jun 2016

MariaDB Connector/ODBC 2.0.11

Stable (GA)

Release Notes

Changelog

11 Apr 2016

MariaDB Connector/ODBC 2.0.10

Stable (GA)

Release Notes

Changelog

16 Nov 2015

MariaDB Connector/ODBC 2.0.9

Beta

Release Notes

Changelog

11 Apr 2016

MariaDB Connector/ODBC 1.0.6

Stable (GA)

Release Notes

Changelog

10 Sep 2015

MariaDB Connector/ODBC 1.0.5

Stable (GA)

Release Notes

Changelog

29 Jan 2015

MariaDB Connector/ODBC 1.0.0

Stable (GA)

Release Notes

Changelog

2 Apr 2014

MariaDB ODBC Driver 0.9.1

Beta

Release Notes

Changelog

<< back to About MariaDB Connector/ODBC