Connect with MariaDB Connector/ODBC

Application developers can use MariaDB Connector/ODBC to establish a data source for client connections with MariaDB Enterprise.

Component

Description

MariaDB Enterprise Server

100% Open Source modern SQL database with enterprise-grade enhancements

MariaDB MaxScale

Advanced database proxy, firewall, and query router

MariaDB Connector/ODBC can also be used to connect to MariaDB SkySQL and MariaDB Community Server.

The method for configuring the data source varies operating system.

Configuring a Data Source on Linux

  1. Configure unixODBC to recognize the driver by creating a file called MariaDB_odbc_driver_template.ini with the relevant driver definition.

    For example, on CentOS/RHEL:

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

    On Debian/Ubuntu:

    [MariaDB ODBC 3.1 Driver]
    Description = MariaDB Connector/ODBC v.3.1
    Driver      = /usr/lib/libmaodbc.so
    
  2. Install the driver using the odbcinst command.

    For example:

    $ sudo odbcinst -i -d -f MariaDB_odbc_driver_template.ini
    odbcinst: Driver installed. Usage count increased to 1.
    Target directory is /etc
    
  3. Determine the connection parameters for your MariaDB server:

    Connection Parameter

    Description

    Default Value

    Driver

    The driver configured in the unixODBC driver template file MariaDB_odbc_driver_template.ini.

    SERVER

    Host name, IPv4 address, or IPv6 address of the MariaDB Enterprise Server or other MariaDB Enterprise component.

    localhost

    SOCKET

    Socket file for socket connections. MariaDB Enterprise Server uses different default socket files on different Linux distributions:
    On Debian/Ubuntu, the default socket file is /var/run/mysqld/mysqld.sock or /run/mysqld/mysqld.sock.
    On CentOS/RHEL, the default socket file is /var/lib/mysql/mysql.sock.

    /tmp/mysql.sock

    DATABASE

    Database name to select upon successful connection. The database must already exist, and the user account must have privileges to select it.

    PORT

    TCP port of the MariaDB Enterprise Server or other MariaDB Enterprise component.

    3306

    USER

    The username to connect as.

    PASSWORD

    User password.

  4. Configure unixODBC to connect to the data source by creating a file called MariaDB_odbc_data_source_template.ini with the relevant data source parameters.

    For example:

    # Data Source for unixODBC
    [MariaDB-Server]
    Description = Database service for MariaDB Enterprise Server
    Driver      = MariaDB ODBC 3.1 Driver
    Trace       = Yes
    TraceFile   = /tmp/trace.log
    SERVER      = localhost
    SOCKET      = /var/run/mysqld/mysqld.sock
    DATABASE    = test
    USER        = db_user
    PASSWORD    = db_user_passwd
    
    • Substitute the values of the SERVER, SOCKET, DATABASE, PORT, USER, and PASSWORD parameters with the relevant value for your environment.

  5. Install the unixODBC data source template file:

    $ sudo odbcinst -i -s -h -f MariaDB_odbc_data_source_template.ini
    
  6. Test the data source MariaDB-Server configured in the MariaDB_odbc_data_source_template.ini file using the isql command:

    $ isql MariaDB-Server
    +-------------------------+
    | Connected!              |
    | sql-statement           |
    | help[tablename]         |
    | quit                    |
    +-------------------------+
    SQL>
    
  7. To select your new data source in your application, select the data source with the name that you configured, which is MariaDB-Server in the above example.

Configuring a Data Source on macOS

  1. Confirm that MariaDB Connector/ODBC has been registered with iODBC by confirming that the following options are set in the iODBC configuration file at /Library/ODBC/odbcinst.ini:

    [ODBC]
    Trace     = no
    TraceFile = /tmp/iodbc_trace.log
    
    [ODBC Drivers]
    MariaDB ODBC 3.1 Unicode Driver = Installed
    
    [MariaDB ODBC 3.1 Unicode Driver]
    Driver      = /Library/MariaDB/MariaDB-Connector-ODBC/libmaodbc.dylib
    Description = MariaDB Connector/ODBC(Unicode) 3.1 64bit
    Threading   = 0
    
  2. Determine the connection parameters for your MariaDB server:

    Connection Parameter

    Description

    Default Value

    Driver

    The path to the driver's shared library, which is installed at /Library/MariaDB/MariaDB-Connector-ODBC/libmaodbc.dylib by default.

    SERVER

    Host name, IPv4 address, or IPv6 address of the MariaDB Enterprise Server or other MariaDB Enterprise component.

    localhost

    SOCKET

    Socket file for socket connections.

    /tmp/mysql.sock

    DATABASE

    Database name to select upon successful connection. The database must already exist, and the user account must have privileges to select it.

    PORT

    TCP port of the MariaDB Enterprise Server or other MariaDB Enterprise component.

    3306

    USER

    The username to connect as.

    PASSWORD

    User password.

  3. Add a data source for MariaDB Enterprise to iODBC by adding the following options to the iODBC configuration file at /Library/ODBC/odbc.ini:

    [ODBC Data Sources]
    MariaDB-Server = MariaDB ODBC 3.1 Unicode Driver
    
    [MariaDB-Server]
    Driver   = /Library/MariaDB/MariaDB-Connector-ODBC/libmaodbc.dylib
    SERVER   = 192.0.2.1
    DATABASE = test
    USER     = db_user
    PASSWORD = db_user_passwd
    
    • Substitute the values of the SERVER, SOCKET, DATABASE, PORT, USER, and PASSWORD parameters with the relevant value for your environment.

  4. Test the data source using the iodbctest command:

    $ iodbctest "DSN=MariaDB-Server"
    
  5. To select your new data source in your application, select the data source with the name that you configured, which is MariaDB-Server in the above example.

Configuring a Data Source on Windows

MariaDB Connector/ODBC requires at least Windows 8.

Windows 10 was used to prepare these instructions. When using other versions of Windows, these instructions may require adjustment.

  1. In the start menu, search for "ODBC Data Sources".

  2. In the search results, open the application called "ODBC Data Sources (32-bit)" or "ODBC Data Sources (64-bit)", depending on whether you need a data source for a 32-bit or 64-bit application.

  3. In the ODBC Data Source Administrator, click the "Add" button on the right side.

  4. In the "Create New Data Source" window:

    • Click on "MariaDB ODBC 3.1 Driver" in the list.

    • Click the "Finish" button.

  5. In the "Create a new Data Source to MariaDB" window:

    • In the "Name" text box, enter a name for the data source.

    • In the "Description" test box, enter a description for the data source.

    • Click the "Next" button.

  6. In the next window, provide the connection credentials:

    • In the "Server Name" field, provide the IP address or domain name for the Server.

    • In the "User name" field, provide the username for the database user account.

    • In the "Password" field, provide the password for that user.

    • In the "Database" field, provide the the default database to use.

    • Then, click the "Next" button.

  7. Continue configuring the data source using the wizard:

    • The wizard provides a series of windows for configuring various aspects of the connection, such as enabling TLS encryption. Enable settings you want to use.

    • Click the "Next" button to move onto the next window in the wizard.

    • Click the "Finish" on the last window to exit the wizard and save your data source.

  8. To select your new data source in your application, select the data source with the name that you configured for the "Name" field.