Skip to content

libmysql_libmariadb

Jump to bottom
Georg Richter edited this page Feb 20, 2019 · 9 revisions

Differences between MariaDB and MySQL Connector/C

History and License

Even if MariaDB Connector/C and MySQL Connector/C have common roots (namely the version 3.23.51 from the year 2003 which was published under the LGPL), both have some differences.

While MySQL Connector/C (or libmysql) was further developed under the GPL, MariaDB Connector/C was newly developed based on MySQL 3.23.51. Major enhancements, such as the prepared statement API and numerous protocol extensions have been integrated from mysqlnd extension of the PHP project. The first version of MariaDB Connector/C was released in 2012.

In contrast to MySQL Connector/C, MariaDB Connector/C is licensed under the LGPL license and thus can be integrated and used free of charge in almost all (including commercial/closed source) projects.

API

API functions which are supported by both MySQL and MariaDB Connector/C are prefixed with "mysql", MariaDB specific features are prefixed with "mariadb".

Example:

  • mysql_real_connect
  • mariadb_stmt_execute_direct

No rule without exception: For example, the mysql_optionsv function only exists in MariaDB Connector / C. It was added as an extension of the existing mysql_options function to allow a function call with a variable number of parameters.

Unsupported API functions

Unsupported functions in MariaDB Connector/C

  • mysql_reset_server_public_key
  • mysql_result_metadata (scheduled for MariaDB C/C 3.1)
  • mysql_binlog_* (The binlog replication API in MariaDB C/C 3.1 has a different interface)

Unsupported functions in MySQL Connector/C

  • mariadb_connection
  • mysql_optionsv
  • mysql_get_info
  • mariadb_reconnect
  • mariadb_cancel
  • mariadb_stmt_execute_direct
  • mysql_stmt_warning_count
  • mysql_get_timeout_value/ms
  • mariadb_dyncol-* (dynamic column api)
  • mysql_async_* (asynchronous/non-blocking API)
  • mariadb_rpl_* (replication/binlog API)

Protocol

Especially in the last versions (MySQL C/C> = 5.7 and MariaDB C/C> = 3.0) some protocol extensions were added which are not or only partially supported:

Protocol MySQL C/C MariaDB C/C
X-Protocol X -
Extended OK packet X - (scheduled for 3.1)
Prepared statement bulk insert - X
Prepared statemnt direct execution - X

Client authentication plugins

Both MySQL and MariaDB Connector/C support different kind of plugable client authentication plugins:

Authentication plugin MySQL C/C MariaDB C/C
Native password X X
Old password X (removed in newer versions) X
Cleartext X X
Dialog X X
SHA256 X X¹
Caching SHA2 X X¹
Kerberos/GSSAPI - X
ed25519 - X

¹= requires OpenSSL, LibreSSL or GnuTLS

Security/TLS (Transport layer security protocol)

Both MySQL and MariaDB Connector/C support secure connection using the TLS protocol, however with some differences:

Supported TLS libraries

TLS library MySQL C/C MariaDB C/C
OpenSSL X X
LibreSSL X X
GnuTLS - X
Windows Schannel - X
WolfSSL X -²
Yassl X -²

²= license incompatible

Supported TLS protocols

Protocol version MySQL C/C MariaDB C/C
SSLv3 x (yassl only) -
TLSv1.0 X X
TLSv1.1 X X
TLSv1.2 X (not yassl) X
TLSv1.3 X (not yassl) X

Supported TLS features

Feature MySQL C/C MariaDB C/C
ssl mode X -
server certificate verification X X
passphrase protected keys - X
force use of tls version - X
certificate finger print verification - X

Coding hints

General advice

  • Consider structures to be opaque
    • don't access internal members, e.g. like mysql->reconnect
    • instead use mysql_optionsv/mysql_get_optionsv for setting or retrieving information
  • If there is no api function or option available for retrieving internal information, file a task in Jira system
  • Don't include other files than mysql.h (unless you need some special API like dynamic columns or you're writing a client plugin using the client plugin interface)

Detecting server and client library type

Often, an application will be able to build with both MariaDB or MySQL Connector/C and to connect either to a MySQL or a MariaDB server. In this case often it is necessary to determine the type of the server and/or the client library in use.

MariaDB or MySQL server?

Using MariaDB Connector/C it's quite simple to detect if the application is connected to MariaDB or MySQL server by using the API function mariadb_connection():

  if (mysql && mariadb_connection(mysql))
    printf("We're connected to a MariaDB database server");

When using MySQL Connector/C or you application supports both Connectors, the server version needs to be retrieved by mysql_get_server_info() and the returned string must be checked if it contains the string "mariadb":

char *server_version= mysql_get_server_info(mysql);
if (strstr(mysql->server_version, "MariaDB") ||
    strstr(mysql->server_version, "-maria-"))
  printf("Connected to a MariaDB server\n");

MySQL or MariaDB Connector/C ?

Due to some differences an application often needs to check which connector is in use.

Detecting Connector at compile time

The simplest solution to detect the type of connector at compile time is to check if the preprocessor definition MARIADB_BASE_VERSION is defined:

#ifdef MARIADB_BASE_VERSION
  const char *client_library= "MariaDB Connector/C";
#else
  const char *client_library= "MySQL Connector/C";
#endif
Detecting Connector type at run time

Since neither MySQL nor MariaDB Connector/C offer an API function to detect the type of the connector, detection is a little bit more tricky: The option MYSQL_PROGRESS_CALLBACK is available in MariaDB C/C only - passing it to mysql_options will result in an error, in case MySQL C/C is used:

#ifndef MARIADB_BASE_VERSION
  #define MYSQL_PROGRESS_CALLBACK 5999
#endif

if (mysql_options(mysql, MYSQL_PROGRESS_CALLBACK, NULL))
  /* MYSQL_PROGRESS_CALLBACK is not defined in MySQL Connector/C, 
     therefore mysql_options() will return an error */
  printf("using MySQL Connector/C\n");
else
  printf("using MariaDB Connector/C\n");

Building an application with MariaDB Connector/C

Include files

How to find MariaDB include files

Windows

For Microsoft Windows Platforms MariaDB Connector/C doesn't provide configuration tools, in the default installation the files will always installed at the same location.

The windows default installation (using MariaDB Connector/C MSI package) installs the include files in folder \ProgramFiles\MariaDB\MariaDB Connector/C 64-bit\include (or for 32-bit installation in \ProgramFiles\MariaDB\MariaDB Connector/C 32-bit\include.

Posix

On Posix platforms you can either use the mariadb_config utility which is located in the binary folder of your MariaDB Connector/C installation, or you can use the pkg-config command of your distribution, e.g.

$> mariadb_config --include
-I/usr/local/include/mariadb

$> pkg-config  libmariadb --cflags
-I/usr/local/include/mariadb

If you're using a different compiler than gcc or clang, you might need to adjust the include option for the compiler.

General includes

For using MariaDB Connector/C from your application, only the include file mysql.h is required.

Error handling

If you don't want to deal with numbers but also with the error code definitions, you need to include errmsg.h for client errors and mysqld_error.h for server errors. Latter one might not contain the latest server error codes, e.g. if you're using MySQL Connector/C from 10.2 server package it will not contain 10.3 or 10.4 error codes. It will also not contain all error codes from MySQL Server.

MariaDB extensions

Some special and not widely used extensions like the asynchronous API have their own include files which are not automatically included by mysql.h.

Extension required include files
Dynamic column API mariadb_dyncol.h
Asynchronous/non blocking API mariadb_async.h

Client plugins

If you want to develop a client plugin (e.g. for authentication or connection handling) the plugin code must include mysql/client_plugin.h.

Linking your application against MariaDB Connector/C

Windows

For static linking the library libmariadb.lib is required, for dynamic linking use libmariadb.dll. Using the MSI installer these libraries can be found in the lib directory of your MariaDB Connector/C installation.

Unless you use the experimental plugin remote_io (which requires the curl library) there are no dependencies to other libraries than the Windows system libraries.

Posix

To detect library path and the required libraries use mariadb_config or pkg_config command:

$ mariadb_config --libs
-L/usr/local/lib/mariadb/ -lmariadb -ldl -lm -lpthread -lssl -lcrypto
$ pkg-config libmariadb --libs
-L/usr/local/lib/mariadb/ -lmariadb -ldl -lm -lpthread -lssl -lcrypto

Both programs will return the location of the MariaDB Connector/C library (-L), the library name (-lmariadb) and the depending libraries.

To use the static library extract the library path from mariadb_config output or specify the option --libs-only-L when running the pkg-config command and append libmariadbclient.a to the path.

Example using gcc: gcc -o my_test my_test.o -L/usr/local/lib/mariadb/libmariadbclient.a

Depending on the configuration you might need to also link against the libraries returned by --libs option.

MariaDB Connector/C Reference

Clone this wiki locally