1 of 100

Connector/C

The MariaDB Connector/C is used to connect applications developed in C/C++ to MariaDB and MySQL databases. MariaDB Connector/C is LGPLv2.1 licensed.

MariaDB Connector/C Overview

Quickstart Guide for Connector/C

MariaDB Connector/C is used to connect applications developed in C/C++ to MariaDB and MySQL databases.The client library is LGPL licensed.

Integration with MariaDB Server

MariaDB Connector/C is distributed with MariaDB Server packages. Eventually, it will completely replace the functionality that has traditionally been performed by libmysqlclient in those packages. Currently, MariaDB Connector/C has replaced libmysqlclient as the client library for client utilities that are distributed with MariaDB Server. See MDEV-9055 for more information.

Installing MariaDB Connector/C

MariaDB Connector/C packages can be downloaded by selecting your desired version from the following page:

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

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

Installing MariaDB Connector/C on Windows

To install MariaDB Connector/C on Windows, we distribute . The MSI installation process is fairly straightforward. Both 32-bit and 64-bit MSI packages are available.

Installing MariaDB Connector/C on Linux

MariaDB Connector/C is distributed in on Linux.

Installing with a Package Manager

Since MariaDB Connector/C is now integrated with MariaDB Server, it can also be installed via a package manager on Linux. In order to do so, your system needs to be configured to install from one of the MariaDB repositories. The repository needs to be configured for or later.

You can configure your package manager to install it from MariaDB Corporation's MariaDB Package Repository by using the .

You can also configure your package manager to install it from MariaDB Foundation's MariaDB Repository by using the .

Installing with yum/dnf

On RHEL, CentOS, Fedora, and other similar Linux distributions, it is highly recommended to install the relevant from MariaDB's repository using or . Starting with RHEL 8 and Fedora 22, yum has been replaced by dnf, which is the next major version of yum. However, yum commands still work on many systems that use dnf. For example:

If you want to build applications with MariaDB Connector/C, then you will also need to install the development package. For example:

Installing with apt-get

On Debian, Ubuntu, and other similar Linux distributions, it is highly recommended to install the relevant from MariaDB's repository using . For example:

If you want to build applications with MariaDB Connector/C, then you will also need to install the development package. For example:

Installing with zypper

On SLES, OpenSUSE, and other similar Linux distributions, it is highly recommended to install the relevant from MariaDB's repository using .

For example:

If you want to build applications with MariaDB Connector/C, then you will also need to install the development package. For example:

Installing MariaDB Connector/C from Source

See for information on how to build MariaDB Connector/C from source.

API - Function Reference

MariaDB Connector/C has exactly the same API as the MySQL Connector/C for MySQL 5.5

The function reference is available at:

It is also downloadable in html format from

Configuring MariaDB Connector/C with Option Files

Just like MariaDB Server and libmysqlclient, MariaDB Connector/C can also read configuration options from client in .

See for more information.

Known Bugs and Limitations

double to string conversion for prepared statements doesn't work correctly
Connector 3.0.7 and below doesn't support the MySQL 8.0 default authentication protocol, . This protocol should be supported in Connector/C 3.0.8 and above.

Reporting Bugs

If you find a bug, please report it via the on .

Source Code

The source code is available at the 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 .

Install MariaDB Connector/C

MariaDB Connector/C supports several Linux distributions and Microsoft Windows.

Configure Package Repository (Linux)

To install MariaDB Connector/C on Linux using APT, YUM, or ZYpp, you must configure your system to use either the ES Package Repository or the CS Package Repository.

If your system is already configured to use one of these package repositories, you can skip to install MariaDB Connector/C.

Choose a package repository to configure:

ES Package Repository

MariaDB Connector/C is available from the same package repository as MariaDB Enterprise Server.

To configure the ES package repository:

Install curl.
Install via APT on Debian, Ubuntu:
Install via YUM on CentOS, RHEL, Rocky Linux:
Install via ZYpp on SLES:
Download the utility, validate its checksum, and ensure that its permissions allow it to be executed:

CS Package Repository

MariaDB Connector/C is available from the same package repository as MariaDB Community Server.

To configure the CS package repository:

Install curl.
Install via APT on Debian, Ubuntu:
Install via YUM on CentOS, RHEL, Rocky Linux:
Install via ZYpp on SLES:
Download the utility, validate its checksum, and ensure that its permissions allow it to be executed:

Installation

Installation via Package Repository (Linux)

On supported Linux distributions, MariaDB Connector/C can be installed using APT, YUM, or ZYpp if the system is configured to use the or the .

Install on CentOS, RHEL, Rocky Linux

To install MariaDB Connector/C on CentOS, RHEL, and Rocky Linux, you can use YUM if you have the or configured.

Install MariaDB Connector/C and package dependencies:

Install on Debian, Ubuntu

To install MariaDB Connector/C on Debian and Ubuntu, you can use APT if you have the or configured.

Install MariaDB Connector/C and package dependencies:

Install on SLES

To install MariaDB Connector/C on SLES, you can use ZYpp if you have the or configured.

Install MariaDB Connector/C and package dependencies:

Install via Binary Tarball (Linux)

MariaDB Connector/C can be installed on supported Linux distributions via a binary tarball package:

Go to the
Ensure the "Product" dropdown reads "C connector."
In the "Version" dropdown, select the version you want to download.
In the "OS" dropdown, select your Linux distribution.

Install via MSI (Windows)

MariaDB Connector/C can be installed on Microsoft Windows via an MSI package:

Go to the
Ensure the "Product" dropdown reads "C connector."
In the "Version" dropdown, select the version you want to download.
In the "OS" dropdown, select either "MS Windows (64-bit)" or "MS Windows (32-bit)", depending on whether you need a 64-bit or 32-bit connector.

MariaDB Binlog/Replication API reference

These are currently documented on the .

MariaDB Connector/C Plugins

MariaDB Connector/C functionality can be extended via loadable (or statically compiled in) plugins. As of the version 3.1.11 Connector/C comes with the following plugins

connection plugins

aurora

replication

pvio plugins

These plugins are used by the Connector/C to communicate with the MariaDB server.

socket

npipe

shmem

io plugins

These are plugins that are used whenever Connector/C needs to read a file. For example, for LOAD DATA LOCAL INFILE statement, when a server requests the Connector/C to send a specific file.

remote_io

This plugin uses libcurl to access remote files, it allows the client to execute statements like

LOAD DATA LOCAL INFILE 'http://mariadb.com/example.csv' INTO t1

Note that here, like with any LOAD DATA LOCAL, it'll be the client that fetches the file, not the server.

This plugin supports the following url schemes: http://, https://, ftp://, sftp://, ldap://, smb://.

auth plugins

These are authentication plugins. They are loaded automatically by the Connector/C when the server requests a specific authentication method.

mysql_native_password

dialog

This is a generic dialog plugin that asks the user a question (as instructed by the server) and sends the answer to the server. Everything is sent in plain text, one should enable SSL if secrets are sent via this plugin. Graphical clients can customize the plugin to provide graphical dialog form. See

client_ed25519

caching_sha2_password

sha256_password

auth_gssapi_client

mysql_old_password

mysql_clear_password

Building Connector/C From Source

Build MariaDB Connector/C from source. Download the package from MariaDB downloads or get the latest development version from the Connector/C GitHub repository.

Compiling Connector/C

After successful configuration, Connector/C can now be compiled.

Compiling on Windows

If no CMake generator was specified, CMake creates by default build files for Visual Studio. You can now either build Connector/C inside Visual Studio

or via command line

Prerequisites For Building Connector/C From Source

Windows

Visual Studio 2013 or newer (older versions of Visual Studio may also work but have not been tested).
cmake 2.8.12 or newer, available from the CMake website.
for Connector/C 2.x: OpenSSL libraries and include files.
for Connector/C 3.0 remote-io plugin: libraries and include files

Linux / Mac OS X

The following is a list of tools that are required for building MariaDB Connector/C on Linux and Mac OS X. Most, if not all, of these will exist as packages in your distribution's package repositories, so check there first.

gcc 3.4.6 or newer C compiler
TLS/SSL libraries and include files
- OpenSSL 1.0.1 or newer or
- GnuTLS 3.4 or newer

On Linux you can get those programs with your package manager. On Mac OS X you will need Xcode and to install the remaining programs with or .

MariaDB Connector/C API Functions

Explore API functions for MariaDB Connector/C. This section provides detailed documentation on functions for connecting, querying, and managing data, enabling robust C applications for MariaDB.

mariadb_cancel

Syntax

int mariadb_cancel(MYSQL * mysql);

mysql - mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Immediately aborts a connection by making all subsequent read/write operations fail.mariadb_cancel() does not invalidate memory used for mysql structure, nor close any communication channels. To free the memory, must be called.mariadb_cancel() is useful to break long queries in situations where sending KILL is not possible.

mariadb_cancel() was added in Connector/C 3.0

mysql_affected_rows

Syntax

mysql is a connection identifier, which was previously allocated by or .

Description

mysql_autocommit

Syntax

mysql - a mysql handle, identifier, which was previously allocated by or .
auto_mode

mysql_character_set_name

Syntax

mysql - a mysql handle, which was previously allocated by or .

Description

mysql_close

Syntax

void mysql_close(MYSQL * mysql);

mysql - mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Closes a previously opened connection.

mysql_commit

Syntax

my_bool mysql_commit(MYSQL * mysql);

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Commits the current transaction for the specified database connection. Returns zero on success, nonzero if an error occurred.

Executing mysql_commit() will not affected the behaviour of . This means, any update or insert statements following mysql_commit() will be rolled back when the connection gets closed.

mysql_data_seek

Syntax

void mysql_data_seek(MYSQL_RES * result,
                     my_ulonglong offset);

result - a result set identifier returned by mysql_store_result().
offset - the field offset. Must be between zero and the total number of rows minus one (0..mysql_num_rows - 1).

Description

The mysql_data_seek() function seeks to an arbitrary function result pointer specified by the offset in the result set. Returns zero on success, nonzero if an error occurred.

This function can only be used with buffered result sets obtained from the use of the function.

mysql_errno

Syntax

mysql - a mysql handle, which was previously allocated by or .

mysql_error

Syntax

const char * mysql_error(MYSQL * mysql);

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns the last error message for the most recent function call that can succeed or fail. If no error occurred an empty string is returned.

mysql_escape_string

Syntax

unsigned long mysql_escape_string(char * to,
                                  const char * from,
                                  unsigned long);

Description

Escapes a string using the default character set.

This function is deprecated and will be discontinued. Please use instead.

mysql_fetch_field

Syntax

result - a result set identifier returned by mysql_store_result() or mysql_use_result().

Description

Returns the definition of one column of a result set as a pointer to a MYSQL_FIELD structure. Call this function repeatedly to retrieve information about all columns in the result set.

The field order will be reset if you execute a new SELECT query.

In case only information for a specific field is required the field can be selected by using the function or obtained by function.

mysql_fetch_field_direct

Syntax

res - a result set identifier returned by or .
fieldnr

mysql_fetch_lengths

Syntax

unsigned long * mysql_fetch_lengths(MYSQL_RES * result);

result - a result set identifier returned by mysql_store_result() or mysql_use_result().

Description

The mysql_fetch_lengths() function returns an array containing the lengths of every column of the current row within the result set (not including terminating zero character) or NULL if an error occurred.

mysql_fetch_lengths() is valid only for the current row of the result set. It returns NULL if you call it before calling or after retrieving all rows in the result.

mysql_fetch_row

Syntax

result - a result set identifier returned by or .

mysql_field_count

Syntax

mysql - a mysql handle, which was previously allocated by or .

mysql_field_seek

Syntax

result - a result set identifier returned by mysql_store_result() or mysql_use_result().
offset - the field number. This number must be in the range from 0..number of fields - 1.

Description

Sets the field cursor to the given offset. The next call to will retrieve the field definition of the column associated with that offset.

Returns the previous value of the field cursor.

The number of fields can be obtained from .

To move the field cursor to the first field offset parameter should be null.

mysql_free_result

Syntax

result - a result set identifier returned by or .

mysql_get_character_set_info

Syntax

void mysql_get_character_set_info(MYSQL * mysql,
                                  MY_CHARSET_INFO * charset);

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
charset - a pointer to a MY_CHARSET_INFO structure, in which the information will be copied.

Description

Returns information about the current default for the specified connection.

A complete list of supported character sets in the client library is listed in the function description for .

mysql_get_client_info

Syntax

Description

Returns a string representing the client library version

mysql_get_client_version

Syntax

unsigned long mysql_get_client_version(void);

Description

Returns a number representing the client library version.

To obtain a string containing the client library version use the function.

mysql_get_host_info

Syntax

mysql - a mysql handle, which was previously allocated by or .

mysql_get_proto_info

Syntax

unsigned int mysql_get_proto_info(MYSQL * mysql);

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns the protocol version number for the specified connection

The client library doesn't support protocol version 9 and prior.

mysql_get_server_version

Syntax

unsigned long mysql_get_server_version(MYSQL * mysql);

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns an integer representing the version of connected server.

The form of the version number is VERSION_MAJOR * 10000 + VERSION_MINOR * 100 + VERSION_PATCH

mysql_get_ssl_cipher

Syntax

const char *mysql_get_ssl_cipher(MYSQL *mysql)

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns the name of the currently used cipher of the , or NULL for non TLS connections.

mysql_hex_string

Syntax

unsigned long mysql_hex_string(char * to,
                               const char * from,
                               unsigned long len);

to - result buffer
from - the string which will be encoded
len - length of the string (from)

Description

This function is used to create a hexadecimal string which can be used in SQL statements. e.g. INSERT INTO my_blob VALUES(X'A0E1CD').

Returns the length of the encoded string without the trailing null character.

The size of the buffer for the encoded string must be 2 * length + 1.

The encoded string does not contain a leading X'.

mysql_insert_id

Syntax

mysql - a mysql handle, which was previously allocated by or .

mysql_kill

Syntax

mysql - a mysql handle, which was previously allocated by or .
long

mysql_library_end

Syntax

void mysql_library_end(void)

Description

Call when finished using the library, such as after disconnecting from the server. In an embedded server application, the embedded server is shut down and cleaned up. For a client program, only cleans up by performing memory management tasks.

mysql_server_end() is an alias.

mysql_library_init

Syntax

Description

Call to initialize the library before calling other functions, both for embedded servers and regular clients. If used on an embedded server, the server is started and subsystems initialized. Returns zero for success, or nonzero if an error occurred.

mysql_more_results

Syntax

mysql - a mysql handle, which was previously allocated by or .

mysql_num_fields

Syntax

MYSQL RES * - A result set identifier returned by or .

mysql_num_rows

Syntax

MYSQL_RES - a result set identifier returned by or .

mysql_ping

Syntax

mysql - a mysql handle, which was previously allocated by or .

mysql_query

Syntax

mysql - a mysql handle, which was previously allocated by or .
query

mysql_read_query_result

Syntax

int mysql_read_query_result(MYSQL * mysql);

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Returns zero on success, otherwise non-zero.

Description

mysql_read_query_result() reads the result of a SQL statement executed with . If the SQL statement returned a resultset, it must be freed before the next call to mysql_read_query_result() is made. This is similar to how results from must be processed before another call can be made.

mysql_reset_connection

Syntax

mysql - a MySQL handle, which was previously allocated by or .

mysql_rollback

Syntax

mysql - a mysql handle, which was previously allocated by or .

mysql_row_seek

Syntax

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES * result,
    MYSQL_ROW_OFFSET offset);

result - a result set identifier returned by mysql_store_result().
offset - row offset. This value can be obtained either by mysql_row_seek() or

Description

Positions the row cursor to an aribtrary row in a result set which was obtained by . Returns the previous row offset.

This function will not work if the result set was obtained by .

mysql_row_tell

Syntax

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES * res);

res - a result set identifier returned by mysql_store_result().

Description

Returns the row offset of a result cursor. The returned offset value can be used to reposition the result cursor by calling .

This function will not work if the result set was obtained by .

mysql_select_db

Syntax

mysql - a mysql handle, which was previously allocated by or .
db

mysql_send_query

Syntax

mysql - a mysql handle, which was previously allocated by or .
query

mysql_server_end

Syntax

void mysql_server_end(void );

Description

mysql_server_end() is an alias for mysql_library_end().

mysql_server_init

Syntax

Description

mysql_server_init() is an alias for .

mysql_session_track_get_first

Syntax

mysql - mysql handle, which was previously allocated by or .
type

mysql_session_track_get_next

Syntax

mysql - mysql handle, which was previously allocated by or .
type

mysql_set_server_option

Syntax

mysql - a mysql handle, which was previously allocated by or .
enum_mysql_set_option

mysql_set_local_infile_default

Name

mysql_set_local_infile_default - Sets local infile callback functions to default

Synopsis

#include <mysql.h>

void mysql_set_local_infile_default(MYSQL *conn);

Description

Sets local infile callback functions to MariaDB Connector/C internal default callback functions.

Parameter

mysql - mysql handle, which was previously allocated by

mysql_shutdown

Syntax

mysql - a mysql handle, which was previously allocated by or .
mysql_enum_shutdown_level

mysql_sqlstate

Syntax

mysql - a mysql handle, which was previously allocated by or .

mysql_ssl_set

Syntax

mysql - a mysql handle, which was previously allocated by or .
key

mysql_stat

Syntax

mysql - a mysql handle, which was previously allocated by or .

mysql_store_result

Syntax

mysql - a mysql handle, which was previously allocated by or .

mysql_thread_end

Syntax

Description

The mysql_thread_end() function needs to be called before a client thread ends. It will release thread-specific memory, which was allocated by a previous

mysql_thread_id

Syntax

mysql - a mysql handle, which was previously allocated by or .

mysql_thread_init

Syntax

Description

Thread initialization for multi-threaded clients. Multi-threaded clients should call mysql_thread_init() at the beginning of the thread initialization to initialize thread specific client library variables. If

mysql_thread_safe

Syntax

Description

Indicates whether or not the client library is compiled as thread safe. Returns 1 if the client library was compiled as thread safe otherwise zero.

MariaDB Connector/C API Prepared Statement Functions

Explore API functions for prepared statements in Connector/C. This section provides detailed documentation on using prepared statements for efficient and secure query execution in C applications.

mysql_stmt_close

Syntax

stmt - a statement handle, which was previously allocated by .

MARIADB_CONNECTION_ASYNC_TIMEOUT: Retrieves the timeout for non-blocking calls in seconds.Parameter type: unsigned int.
MARIADB_CONNECTION_ASYNC_TIMEOUT_MS: Retrieves the timeout for non-blocking calls in milliseconds.Parameter type: unsigned int.
MARIADB_CONNECTION_MARIADB_CHARSET_INFO: Retrieves character set information for given connection. Parameter type: const MY_CHARSET_INFO *.
MARIADB_CONNECTION_CLIENT_CAPABILITIES: Returns the capability flags of the client.Parameter type: unsigned long.
MARIADB_CONNECTION_ERROR: Retrieves error message for last used command. Parameter type: const char *.
MARIADB_CONNECTION_ERROR_ID: Retrieves error number for last used command. Parameter type: unsigned int.
MARIADB_CONNECTION_EXTENDED_SERVER_CAPABILITIES: Returns the extended of the connected MariaDB server.Parameter type: unsigned long.
MARIADB_CONNECTION_HOST: Retrieves connection's host name. Parameter type: const char *.
MARIADB_CONNECTION_INFO: Retrieves generic info for last used command.Parameter type: const char *.
MARIADB_CONNECTION_PORT: Retrieves the port number of server host.Parameter type: unsigned int.
MARIADB_CONNECTION_PROTOCOL_VERSION_ID: Retrieves the protocol version number.Parameter type: unsigned int.
MARIADB_CONNECTION_PVIO_TYPE: Retrives the pvio plugin used for specified connection.Parameter type: unsigned int.
MARIADB_CONNECTION_SCHEMA: Retrieves the current schema.Parameter type: const char*.
MARIADB_CONNECTION_SERVER_CAPABILITIES: Returns the of the connected server.Parameter type: unsigned long.
MARIADB_CONNECTION_SERVER_STATUS: Returns server status after last operation. A list of possible flags can be found in the description OK packet.Parameter type: unsigned int.
MARIADB_CONNECTION_SERVER_TYPE: Retrieves the type of the server.Parameter type: const char*.
MARIADB_CONNECTION_SERVER_VERSION: Retrieves the server version in literal format.Parameter type: const char *.
MARIADB_CONNECTION_SERVER_VERSION_ID: Retrieves the server version in numeric format.Parameter type: unsigned int.
MARIADB_CONNECTION_SOCKET: Retrieves the handle (socket) for given connection.Parameter type: my_socket.
MARIADB_CONNECTION_SQLSTATE: Retrieves current sqlstate information for last used command. Parameter type: const char *.
MARIADB_CONNECTION_SSL_CIPHER: Retrieves the TLS cipher in use.Parameter type: const char *.
MARIADB_CONNECTION_TLS_VERSION: Retrieves the TLS protocol version used in literal format.Parameter type: char *.
MARIADB_CONNECTION_TLS_VERSION_ID: Retrieves the TLS protocol version used in numeric format.Parameter type: unsigned int.
MARIADB_CONNECTION_UNIX_SOCKET: Retrieves the file name of the unix socketParameter type: const char *.
MARIADB_CONNECTION_USER: Retrieves connection's user name.Parameter type: const char *.

Configuring MariaDB Connector/C with Option Files

Just like MariaDB Server and libmysqlclient, MariaDB Connector/C can also read configuration options from client in .

Default Option File Locations

MariaDB Connector/C reads option files from many different directories by default. See the sections below to find out which directories are checked for which system.

MariaDB Connector/C allows application developers to read options from the default option files by calling the mysql_optionsv function and providing the MYSQL_READ_DEFAULT_FILE option name and a NULL pointer as arguments. For example:

Default Option File Locations on Linux, Unix, Mac

On Linux, Unix, or Mac OS X, the default option file is called my.cnf. MariaDB Connector/C looks for the MariaDB option file in the locations and orders listed below.

The locations are dependent on whether the DEFAULT_SYSCONFDIR option was defined when MariaDB Connector/C was built. This option is usually defined as /etc when building , but it is usually not defined when building or .

When the DEFAULT_SYSCONFDIR option was not defined, MariaDB Connector/C looks for the MariaDB option file in the following locations in the following order:

Location

When the DEFAULT_SYSCONFDIR option was defined, MariaDB Connector/C looks for the MariaDB option file in the following locations in the following order:

Location

Default Option File Locations on Windows

On Windows, the default option file can be called either my.ini or my.cnf. MariaDB Connector/C looks for the MariaDB option file in the following locations in the following order:

Location

The System Windows Directory is the directory returned by the function. The value is usually C:\Windows. To find its specific value on your system, open and execute:

The Windows Directory is the directory returned by the function. The value may be a private Windows Directory for the application, or it may be the same as the System Windows Directory returned by the function.
EXEDIR is the parent directory of the executable program that MariaDB Connector/C is linked with.
MYSQL_HOME

Default Option File Hierarchy

MariaDB Connector/C will look in all of the above locations, in order, even if has already found an option file, and it's possible for more than one option file to exist. For example, you could have an option file in /etc/my.cnf with global settings for all servers, and then you could another option file in ~/.my.cnf (i.e.your user account's home directory) which will specify additional settings (or override previously specified setting) that are specific only to that user.

Custom Option File Locations

MariaDB Connector/C allows application developers to read option files from a custom option file by calling the function and providing the option name and an option file path as arguments. For example:

Many MariaDB clients can be configured to read options from custom options files with the following command-line arguments. They must be given as the first argument on the command-line. Application developers who use MariaDB Connector/C in their application and rely on option files may also want to consider implementing these command-line arguments:

Option

Description

The command-line option is roughly equivalent to setting the option with a non-NULL argument.

The command-line option does not yet have an equivalent option in MariaDB Connector/C. See for more information.

Option File Syntax

The syntax of the MariaDB option files are:

Lines starting with

are comments.

Empty lines are ignored.
Option groups use the syntax [group-name]. See the section below for more information on available option groups.
The same option group can appear multiple times.
The !include

Option Groups

MariaDB Connector/C reads client options from the following in :

Group

Description

MariaDB Connector/C allows application developers to read options from these option groups by calling the function and providing the option name and a NULL pointer as arguments.

For example:

Custom Option Groups

MariaDB Connector/C allows application developers to read options from a custom option group by calling the function and providing the option name and the name of the custom option group as arguments.

For example:

The custom option group will be read in addition to the default option groups listed above.

Many MariaDB clients can be configured to read options from option groups with a custom suffix by providing the following command-line argument. It must be given as the first argument on the command-line. Application developers who use MariaDB Connector/C in their application and rely on option files may also want to consider implementing this command-line argument:

Option

Description

The command-line option does not yet have an equivalent option in MariaDB Connector/C. See for more information.

Including Option Files

It is possible to include additional option files from another option file. For example, to include /etc/mysql/dbserver1.cnf, an option file could contain:

Including Option File Directories

It is also possible to include the default option files in a directory from another option file. For example, to include the default option files in /etc/my.cnf.d/, an option file could contain:

Unlike with MariaDB server, this directive does not configure MariaDB Connector/C to include all option files ending in .cnf on Unix-like operating systems or all option files ending in .cnf and .ini files on Windows. Instead, it just configures MariaDB Connector/C to include the my.cnf in the given directory, and also the my.ini in the given directory if it's Windows. See for more information.

Checking Program Options

For many MariaDB clients, you can check which options a given program is going to use by using the command-line argument:

Option

Description

It must be given as the first argument on the command-line. Application developers who use MariaDB Connector/C in their application and rely on option files may also want to consider implementing this command-line argument. For example:

If it is installed on your system, then you can also check which options a given program is going to use by using the utility and providing the names of the option groups that the program reads.

For example:

See for more information.

MySQL 5.6 Obfuscated Authentication Credential Option File

MySQL 5.6 and above support an obfuscated authentication credential option file called .mylogin.cnf that is created with .

MariaDB Connector/C does not support this. The passwords in MySQL's .mylogin.cnf are only obfuscated, rather than encrypted, so the feature does not really add much from a security perspective. It is more likely to give users a false sense of security, rather than to seriously protect them.

Options

MariaDB Connector/C options can be set in client .

Unlike with the server, dashes (-) and underscores (_) in options are not interchangeable for MariaDB Connector/C. Options must be specified exactly as they are defined. See for more information.

Unlike with the server, the loose prefix has no meaning for MariaDB Connector/C. Unknown options will simply be ignored.

Custom Options

MariaDB Connector/C allows application developers to implement custom options in option files by defining a function that matches this signature:

And then assigning the function pointer to mysql->options.extension->set_option.

Default Options

These are the options supported in option files by MariaDB Connector/C by default.

These options can also be set inside your application with the function.

bind-address

Description: Specify the network interface from which to connect to MariaDB Server.
mysql_optionsv: MYSQL_OPT_BIND
Data Type: string
Default Value:

character-sets-dir

Description: Directory for files.
mysql_optionsv: MYSQL_SET_CHARSET_DIR
Data Type: string
Default Value:

compress

Description: Compress all information sent between the client and the server if both support compression.
mysql_optionsv: MYSQL_OPT_COMPRESS
Data Type: boolean
Default Value: false

connect-timeout, timeout

Description: Connect timeout in seconds. This value will be passed as an unsigned int parameter.
mysql_optionsv: MYSQL_OPT_CONNECT_TIMEOUT
Data Type: int
Default Value:

database

Description: Database to use.
mysql_optionsv: MARIADB_OPT_SCHEMA
Data Type: string
Default Value:

debug

Description:
mysql_optionsv: MARIADB_OPT_DEBUG
Data Type: string
Default Value:

default-auth

Description: Default authentication client-side plugin to use.
mysql_optionsv: MYSQL_DEFAULT_AUTH
Data Type: string
Default Value:

default-character-set

Description: Specify the default for the connection.
mysql_optionsv: MYSQL_SET_CHARSET_NAME
Data Type: string
Default Value:

disable-local-infile

Description: Disable the use of .
mysql_optionsv: N/A
Data Type: string
Default Value:

host

Description: Hostname or IP address of the server to connect to.
mysql_optionsv: MARIADB_OPT_HOST
Data Type: string
Default Value:

interactive-timeout

Description:
mysql_optionsv: MARIADB_OPT_INTERACTIVE
Data Type: none
Default Value:

init-command

Description: Command(s) which will be executed when connecting and reconnecting to the server.
mysql_optionsv: MYSQL_INIT_COMMAND
Data Type: string
Default Value:

local-infile

Description: Enable or disable the use of .
mysql_optionsv: MYSQL_OPT_LOCAL_INFILE
Data Type: boolean
Default Value: false

max-allowed-packet

Description: The maximum packet length to send to or receive from server. The default is 16MB, the maximum 1GB.
mysql_optionsv: MYSQL_OPT_MAX_ALLOWED_PACKET
Data Type: size_t
Default Value:

multi-results

Description: Indicates that the client is able to handle multiple result sets from stored procedures or multi statements. This option will be automatically set if multi-statements is set.
mysql_optionsv: MARIADB_OPT_MULTI_RESULTS
Data Type: none

multi-statements, multi-queries

Description: Allows the client to send multiple statements in one command. Statements will be divided by a semicolon.
mysql_optionsv: MARIADB_OPT_MULTI_STATEMENTS
Data Type: string
Default Value:

net-buffer-length

Description: The buffer size for TCP/IP and socket communication. Default is 16KB.
mysql_optionsv: MYSQL_OPT_NET_BUFFER_LENGTH
Data Type: size_t
Default Value:

password

Description: Password of the user to login to the server.
mysql_optionsv: MARIADB_OPT_PASSWORD
Data Type: string
Default Value:

pipe

Description: For Windows operating systems only: Use named pipes for client/server communication.
mysql_optionsv: MYSQL_OPT_NAMED_PIPE
Data Type: boolean
Default Value: false

plugin-dir

Description: Specify the location of client plugins.
- The plugin directory can also be specified with the MARIADB_PLUGIN_DIR environment variable.
mysql_optionsv: MYSQL_PLUGIN_DIR

port

Description: Port number to use for connection.
mysql_optionsv: MARIADB_OPT_PORT
Data Type: int
Default Value: 3306

protocol

Description: Specify the type of client/server protocol. Possible values are:
- 0 - Refers to MYSQL_PROTOCOL_DEFAULT
- 1 - Refers to MYSQL_PROTOCOL_TCP

reconnect

Description: Enable or disable automatic reconnect.
mysql_optionsv: MYSQL_OPT_RECONNECT
Data Type: boolean
Default Value: false

report-data-truncation

Description: Enable or disable reporting data truncation errors for prepared statements.
mysql_optionsv: MYSQL_REPORT_DATA_TRUNCATION
Data Type: boolean
Default Value:

return-found-rows

Description: Return the number of matched rows instead of number of changed rows.
mysql_optionsv: MARIADB_OPT_FOUND_ROWS
Data Type: none
Default Value:

secure-auth

Description: Refuse client connecting to server if it uses old (pre-MySQL4.1.1) protocol. Defaults to false (unlike MySQL since 5,6, which defaults to true).
mysql_optionsv: MYSQL_SECURE_AUTH
Data Type: boolean
Default Value:

server_public_key

Description: 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 client authentication plugin.
mysql_optionsv: MYSQL_SERVER_PUBLIC_KEY
Data Type: string

shared-memory-base-name

Description: Shared-memory name to use for Windows connections using shared memory to a local server (started with the --shared-memory option). Case-sensitive.
mysql_optionsv: MYSQL_SHARED_MEMORY_BASE_NAME
Data Type: string
Default Value:

socket

Description: For connections to localhost, the Unix socket file to use, or, on Windows, the name of the named pipe to use.
mysql_optionsv: MARIADB_OPT_UNIXSOCKET
Data Type: string
Default Value:

ssl-ca

Description: Defines a path to a PEM file that should contain one or more X509 certificates for trusted Certificate Authorities (CAs) to use for . This option requires that you use the absolute path, not a relative path.
- See for more information.
mysql_optionsv: MYSQL_OPT_SSL_CA

ssl-capath

Description: 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 . This option requires that you use the absolute path, not a relative path. The directory specified by this option needs to be run through the command.
- See for more information.
- This option is only supported if the connector was built with OpenSSL. If the connector was built with GnuTLS or Schannel, then this option is not supported. See for more information about which libraries are used on which platforms.

ssl-cert

Description: Defines a path to the X509 certificate file to use for . This option requires that you use the absolute path, not a relative path.
mysql_optionsv: MYSQL_OPT_SSL_CERT
Data Type: string

ssl-cipher

Description: List of permitted ciphers or cipher suites to use for .
mysql_optionsv: MYSQL_OPT_SSL_CIPHER
Data Type: string
Default Value:

ssl-crl

Description: Defines a path to a PEM file that should contain one or more revoked X509 certificates to use for . This option requires that you use the absolute path, not a relative path.
- See for more information.
- This option is only supported if the connector was built with OpenSSL or Schannel. If the connector was built with GnuTLS, then this option is not supported. See for more information about which libraries are used on which platforms.

ssl-crlpath

Description: Defines a path to a directory that contains one or more PEM files that should each contain one revoked X509 certificate to use for . This option requires that you use the absolute path, not a relative path. The directory specified by this option needs to be run through the command.
- See for more information.
- This option is only supported if the connector was built with OpenSSL. If the connector was built with GnuTLS or Schannel, then this option is not supported. See for more information about which libraries are used on which platforms.

ssl-enforce

Description: Whether to force .
mysql_optionsv: MYSQL_OPT_SSL_ENFORCE
Data Type: boolean
Default Value:

ssl-fp

Description: Specify the SHA1 fingerprint of a server certificate for validation during the handshake.
mysql_optionsv: MARIADB_OPT_SSL_FP
Data Type: string
Default Value:

ssl-fp-list, ssl-fplist

Description: Specify a file which contains one or more SHA1 fingerprints of server certificates for validation during the handshake.
mysql_optionsv: MARIADB_OPT_SSL_FP_LIST
Data Type: string

ssl-key

Description: Defines a path to a private key file to use for . This option requires that you use the absolute path, not a relative path. If the key is protected with a passphrase, the passphrase needs to be specified with ssl-passphrase option.
mysql_optionsv: MYSQL_OPT_SSL_KEY
Data Type: string

ssl-passphrase

Description: Specify a passphrase for a passphrase-protected private key, as configured by the 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. See for more information about which libraries are used on which platforms.
mysql_optionsv: MARIADB_OPT_TLS_PASSPHRASE

ssl-verify-server-cert

Description: Enables (or disables) .
mysql_optionsv: MYSQL_OPT_SSL_VERIFY_SERVER_CERT
Data Type: boolean
Default Value:

tls_version

Description: Defines which protocol versions are allowed. This should be a comma-separated list of TLS protocol versions to allow. Valid TLS protocol versions are TLSv1.0, TLSv1.1, TLSv1.2, and TLSv1.3. Both the client and server should support the allowed TLS protocol versions. See for information on which TLS libraries support which TLS protocol versions. See for more information about which TLS libraries are used on which platforms.
mysql_optionsv: MARIADB_OPT_TLS_VERSION

user

Description: User to login to the server.
mysql_optionsv: MARIADB_OPT_USER
Data Type: string
Default Value:

Connector/C

MariaDB Connector/C Overview

Integration with MariaDB Server

Installing MariaDB Connector/C

Installing MariaDB Connector/C on Windows

Installing MariaDB Connector/C on Linux

Installing with a Package Manager

Installing MariaDB Connector/C from Source

API - Function Reference

Configuring MariaDB Connector/C with Option Files

Known Bugs and Limitations

Reporting Bugs

Source Code

License

Install MariaDB Connector/C

Configure Package Repository (Linux)

ES Package Repository

CS Package Repository

Installation

Installation via Package Repository (Linux)

Install on CentOS, RHEL, Rocky Linux

Install on Debian, Ubuntu

Install on SLES

Install via Binary Tarball (Linux)

Install via MSI (Windows)

MariaDB Binlog/Replication API reference

MariaDB Connector/C Plugins

connection plugins

aurora

replication

pvio plugins

socket

npipe

shmem

io plugins

remote_io

auth plugins

mysql_native_password

dialog

client_ed25519

caching_sha2_password

sha256_password

auth_gssapi_client

mysql_old_password

mysql_clear_password

Building Connector/C From Source

Compiling Connector/C

Compiling on Windows

Prerequisites For Building Connector/C From Source

Windows

Linux / Mac OS X

MariaDB Connector/C API Functions

mariadb_cancel

Syntax

Description

mysql_affected_rows

Syntax

Description

mysql_autocommit

Syntax

mysql_character_set_name

Syntax

Description

mysql_close

Syntax

Description

mysql_commit

Syntax

Description

See also

mysql_data_seek

Syntax

Description

mysql_errno

Syntax

mysql_error

Syntax

Description

See also

mysql_escape_string