About MariaDB Connector/ODBC

You are viewing an old version of this article. View the current version here.

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.

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

DateReleaseStatusRelease NotesChangelog
12 Jun 2018MariaDB Connector/ODBC 3.0.5Stable (GA)Release NotesChangelog
8 Feb 2018MariaDB Connector/ODBC 3.0.3Stable (GA)Release NotesChangelog
12 Oct 2017MariaDB Connector/ODBC 3.0.2Stable (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
23 May 2017MariaDB Connector/ODBC 2.0.15Stable (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

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

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...
Content reproduced on this site is the property of its respective owners, and this content is not reviewed in advance by MariaDB. The views, information and opinions expressed by this content do not necessarily represent those of MariaDB or any other party.