Dive into MariaDB Connectors with quickstart guides. Learn how to swiftly set up and use official client libraries (C, Java, Python, Node.js, ODBC) for seamless application connectivity.
Example
The following example illustrates the complete workflow of the Binlog API. It configures the connection by setting the required session variables, initializes and prepares the replication handle, retrieves all available events, processes each event type appropriately, and performs proper cleanup at the end.
Build MariaDB Connector/C from source. Download the package from MariaDB downloads or get the latest development version from the Connector/C GitHub repository.
Building MariaDB Connector/C from source requires CMake, a C compiler, and TLS/SSL libraries. Windows needs Visual Studio; Linux and macOS need gcc, with optional Curl or Kerberos.
Configure the MariaDB Connector/C build via CMake options including build type, TLS/SSL backend, install prefix, and client plugins such as authentication and connection handlers.
Compile MariaDB Connector/C after configuration using CMake on Windows or Unix. Supports Visual Studio builds and GNU make, with both IDE and command-line build options.
MariaDB Connector/C++ allows your C++ applications to connect to MariaDB databases, including support for TLS encryption. It provides an object-oriented design and leverages smart pointers for efficient memory management.
The most recent Stable (GA) release is MariaDB Connector/C++ 1.1.6.
Why Choose Connector/C++?
While you can use MariaDB Connector/C for C++ applications, Connector/C++ offers specific advantages for C++ development:
Feature
Connector/C++
Connector/C
To get started with MariaDB Connector/C++, you'll typically need to:
Download the Connector/C++ library. Look for the appropriate package for your operating system and development environment.
Integrate the library into your C++ project. This usually involves including header files and linking against the library during compilation.
Write C++ code to establish a connection, execute SQL queries, and process results using the object-oriented API.
Quickstart Guide for MySQL/OTP (Erlang/OTP Client)
MySQL/OTP is the native Erlang/OTP client for connecting Erlang applications to MariaDB and MySQL databases, offering a direct implementation of the MySQL protocol.
1. Installation
Add MySQL/OTP as a dependency in your rebar.config file (for rebar3 projects):
Erlang
{deps, [
{mysql, ".*", {git, "https://github.com/mysql-otp/mysql-otp.git", {tag, "2.0.0"}}} % Use the latest stable tag
]}.
Then, run rebar3 compile.
2. Basic Usage
Here are essential steps for connecting and interacting with your database:
a. Connect:
Erlang
Replace placeholder values with your actual database credentials.
Install MariaDB Connector/C on Linux, Windows, and macOS, with configuration and verification steps for production use.
MariaDB Connector/C reads connection settings from option files such as my.cnf, supporting default and custom file locations, option groups, and a full set of client options.
MariaDB Connector/C binlog and replication API reference, documenting the functions used to consume binary log events from a MariaDB server as a replication client.
Reference for the public data structures in MariaDB Connector/C, including MYSQL, MYSQL_RES, MYSQL_STMT, MYSQL_FIELD, MYSQL_BIND, and MYSQL_TIME with all member definitions.
MariaDB Connector/C supports loadable and built-in plugins across four categories: connection, pvio, I/O, and authentication, including remote_io and multiple auth methods.
Reference for MariaDB Connector/C types and definitions, including enumeration constants for field types, statement options, cursor types, indicator types, field flags, and server status.
Build MariaDB Connector/C from source: download the package from MariaDB downloads or get the latest development version from the Connector/C GitHub repository.
Detailed documentation on the MariaDB Connector/C API functions for connecting, querying, and managing data in C applications.
MariaDB Connector/C binlog and replication API reference, documenting the functions used to consume binary log events from a MariaDB server as a replication client.
The Binlog/Replication API enables client applications to connect to a MariaDB server and stream its binary log as replication events. When binary logging is enabled, the log records all data manipulation and definition changes.
This API is particularly useful for building change‑data capture (CDC) pipelines, custom replication consumers, and auditing tools.
All functions in the Binlog/Replication API are defined in include/mariadb_rpl.h
The Binlog/Replication API provides a low‑level interface for consuming and processing binary log events from a MariaDB server. It allows applications to configure replication handles, open streams, fetch and decode events, and manage errors.
Together, these functions enable developers to build custom replication clients and event processing tools.
An open replication handle initialized by and connected by .
event
An event returned by a previous call to mariadb_rpl_fetch. If this parameter is set to NULL, the function allocates new memory for the event. If a non‑NULL value is provided, the existing event structure is overwritten with the new data.
Return Value
Returns a pointer to a structure containing the next event on success, or NULL when the EOF packet is received or an error occurs.
Event memory must be freed by calling mariadb_free_rpl_event() when the event is no longer needed.
A pointer previously returned by . Passing NULL is safe and has no effect.
Return Value
None
Notes
Avoid calling this function on an event pointer that will be passed back to for reuse. Only call it when you are done processing the event and will not reuse the pointer.
Returns a pointer to a linked list of MARIADB_RPL_ROW structures on success, or NULL on failure. Each node in the list represents one row in the event.
A replication handle previously allocated by and and connected using
Notes
This function closes the replication stream and frees the MARIADB_RPL handle, but does not close the underlying database connection. To close the connection, call mysql_close() separately after mariadb_rpl_close().
MariaDB Connector/C supports loadable and built-in plugins across four categories: connection, pvio, I/O, and authentication, including remote_io and multiple auth methods.
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
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://.
These are authentication plugins. They are loaded automatically by the Connector/C when the server requests a specific authentication method.
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
Prerequisites For Building Connector/C From Source
Building MariaDB Connector/C from source requires CMake, a C compiler, and TLS/SSL libraries. Windows needs Visual Studio; Linux and macOS need gcc with optional Curl or Kerberos.
Windows
Visual Studio 2013 or newer (older versions of Visual Studio may also work but have not been tested).
cmake 3.12.0 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: Curl 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.2 or newer
cmake 3.12.0 or newer, available from the .
for Connector/C 3.0 remote-io plugin: libraries and include files
For GSSAPI plugin: libraries
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 Fink or MacPorts.
Compile MariaDB Connector/C after configuration using CMake on Windows or Unix. Supports Visual Studio builds and GNU make, with both IDE and command-line build options.
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
devenv mariadb_connector_c.sln
or via command line
cmake --build . --config RelWithDebInfo
Compiling on Unix
By default CMake creates build files for GNU make. On some system GNU make is renamed to gmake.
You can now build Connector/C with
mariadb_cancel immediately aborts a connection by making all subsequent read/write operations fail, without freeing the MYSQL structure or closing communication channels.
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, mysql_close() must be called.mariadb_cancel() is useful to break long queries in situations where sending KILL is not possible.
Return Value
Returns zero on success or a non-zero value on error.
conn_str- Connection string, containing connection parameters. A connection string contains key/value pairs, separated by a semicolon as used in ODBC. Supported keys are all configuration options which can be used in MariaDB configuration files. For a complete list check the chapter configuration files.
Return Value
Returns a MYSQL * handle or NULL on error.
The connection string must contain at least one semicolon, otherwise it will be interpreted as hostname.
Unknown or invalid keys will be ignored
mariadb_connect is not a function, but a macro which maps to mysql_real_connect: #define mariadb_connect(mysql, conn_str) mysql_real_connect((mysql),(conn_str), NULL, NULL, NULL, 0, NULL, 0)
attr: A pointer which returns extended metadata information
field: Specifies the field which contains extended metadata information
mariadb_reconnect
mariadb_reconnect attempts to re-establish a dropped MariaDB Connector/C connection using the original credentials, and requires the MYSQL_OPT_RECONNECT option to be set.
mariadb_reconnect() tries to reconnect to a server in case the connection died due to timeout or other errors. It uses the same credentials which were specified in mysql_real_connect().
Return Value
The function will return 0 on success. The function will return an error, if the option MYSQL_OPT_RECONNECT wasn't specified before.
mysql_affected_rows returns the number of rows affected by the last INSERT, UPDATE, DELETE, or REPLACE statement executed on a MariaDB Connector/C connection.
Returns the number of affected rows by the last operation associated with MySQL, if the operation was an "upsert" (, , or ) statement, or UINT64_MAX (0xffffffffffffffff) if the last query failed.
When using , MariaDB will not update columns where the new value is the same as the old value. This creates the possibility that mysql_affected_rows may not actually equal the number of rows matched, only the number of rows that were literally affected by the query.
The statement first deletes the record with the same primary key and then inserts the new record. This function returns the number of deleted records in addition to the number of inserted records.
Return Value
Returns the number of affected rows or -1 on error.
mysql_change_user changes the authenticated user and default database on an existing connection, resetting session state including transactions, temporary tables, and locks.
db - the default database. If desired, the NULL value may be passed resulting in only changing the user and not selecting a database. To select a database in this case use the function.
Changes the user and default database of the current connection.
In order to successfully change users a valid username and password parameters must be provided and that user must have sufficient permissions to access the desired database. If for any reason authorization fails, the current user authentication will remain.
Returns zero on success, nonzero if an error occurred.
Commits the current transaction for the specified database connection.
Return Value
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 moves the result set pointer to an arbitrary row offset in a buffered result set obtained via mysql_store_result, enabling random row access.
mysql_dump_debug_info instructs a MariaDB server to write connection status information to the error log, and requires the SUPER privilege for the current user.
This function is designed to be executed by an user with the SUPER privilege and is used to dump server status information into the log for the MariaDB Server relating to the connection.
Return Value
Returns zero on success, nonzero if an error occurred.
The server status information will be dumped into the file, which can usually be found in the data directory of your server installation.
Returns the last for the most recent function call that can succeed or fail. Zero means no error occurred.
Client error messages are listed in errmsg.h header file, server error messages are listed in mysqld_error.h header file of the server source distribution.
mysql_escape_string encodes a string using the default character set for safe use in SQL statements. Deprecated — use mysql_real_escape_string instead.
Syntax
unsigned long mysql_escape_string(char * to,
const char * from,
unsigned long);
mysql_fetch_field returns the definition of one result set column as a MYSQL_FIELD pointer; call it repeatedly to iterate over all columns in the result set.
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.
Return Value
A pointer of a MYSQL_FIELD structure, or NULL if there are no more fields.
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.
fieldnr - the field number. This value must be within the range from 0 to number of fields - 1
Description
Returns a pointer to a MYSQL_FIELD structure which contains field information from the specified result set.
Pointer to a MYSQL_FIELD structure. The caller must ensure that fieldnr is less than mysql_field_count(); specifying an out-of-range value results in undefined behavior, not a NULL return.
This function serves an identical purpose to the mysql_fetch_field() function with the single difference that instead of returning one field at a time for each field, the fields are returned as an array. Each field contains the definition for a column of the result set.
mysql_fetch_lengths returns an array of byte lengths for each column in the current row of a MariaDB result set, valid only after mysql_fetch_row is called.
Syntax
unsigned long * mysql_fetch_lengths(MYSQL_RES * result);
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.
Return Value
An array of unsigned long values . The size of the array can be determined by the number of fields in current result set.
mysql_fetch_lengths() is valid only for the current row of the result set. It returns NULL if you call it before calling mysql_fetch_row() or after retrieving all rows in the result.
Fetches one row of data from the result set and returns it as an array of char pointers (MYSQL_ROW), where each column is stored in an offset starting from 0 (zero). Each subsequent call to this function will return the next row within the result set, or NULL if there are no more rows.
If a column contains a NULL value the corresponding char pointer will be set to NULL.
Memory associated to MYSQL_ROW will be freed when calling mysql_free_result() function.
mysql_field_count returns the number of columns in the most recent query result for a MariaDB connection, useful for checking whether a result set is available.
Returns the number of columns for the most recent query on the connection represented by the link parameter as an unsigned integer. This function can be useful when using the mysql_store_result() function to determine if the query should have produced a non-empty result set or not without knowing the nature of the query.
Return Value
The number of columns for the most recent statement. The value is zero, if the statement didn't produce a result set.
The mysql_field_count() function should be used to determine if there is a result set available.
Return the offset of the field cursor used for the last mysql_fetch_field() call. This value can be used as a parameter for the function mysql_field_seek().
mysql_free_result releases the memory allocated for a MariaDB result set; row values obtained from prior mysql_fetch_row calls become invalid after this call.
mysql_get_character_set_info populates a MY_CHARSET_INFO structure with details about the current default character set for a MariaDB Connector/C connection.
Returns the name of the currently used cipher of the , or NULL for non TLS connections.
Return Value
Returns a zero terminated string containing the cipher suite used for a secure connection, or NULL if connection doesn't use TLS/SSL.
Notes
For using mysql_get_ssl_cipher() MariaDB Connector/C must be built with TLS/SSL support, otherwise the function will return NULL.
`mysql_get_ssl_cipher()' can be used to determine if the client server connection is secure.
Depending on the TLS library in use (OpenSSL, GnuTLS or Windows Schannel) the name of the cipher suites may differ. For example the cipher suite 0x002F (TLS_RSA_WITH_AES_128_CBC_SHA) has different names: AES128-SHA for OpenSSL and Schannel and TLS_RSA_AES_128_CBC_SHA1 for GnuTLS.
mysql_get_timeout_value_ms retrieves the current timeout value configured for asynchronous operations on the given connection, expressed in milliseconds.
The timeout value in milliseconds as an
mysql_hex_string
mysql_hex_string converts a binary buffer to a hex-encoded string for safe embedding in SQL; the output buffer must be at least 2*length+1 bytes.
Syntax
unsigned long mysql_hex_string(char * to,
const char * from,
unsigned long len);
Parameters
to - result buffer
from - the string which will be encoded
len - length of the string (from)
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.
mysql_init allocates and initializes a MYSQL structure for use with mysql_real_connect, and also initializes the thread subsystem if not already done.
mysql - a pointer to MYSQL or NULL. In case of passing a NULL pointer mysql_init() will allocate memory and return a pointer to a MYSQL structure.
Prepares and initializes a MYSQL structure to be used with .
mysql_init()
mysql_insert_id
mysql_insert_id returns the AUTO_INCREMENT value generated by the last INSERT or UPDATE statement on a MariaDB connection, or zero if no such value was produced.
mysql - a mysql handle, which was previously allocated by or .
The mysql_insert_id() function returns the ID generated by a query on a table with a column having the attribute or the value for the last usage of . If the last query wasn't an or statement or if the modified table does not have a column with the attribute and was not used, this function will return zero.
Returns the value of the modified column with AUTO_INCREMENT attribute. If the table doesn't contain an
mysql_kill
mysql_kill requests the MariaDB server to terminate the thread with the given process ID; use mysql_thread_id to obtain the ID of the current connection.
This function is used to ask the server to kill a MariaDB thread specified by the processid parameter. This value must be retrieved by . If trying to kill the own connection should be used.
mysql_library_end finalizes the MariaDB Connector/C library after use, performing memory cleanup and shutting down the embedded server if applicable.
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_library_init initializes the MariaDB Connector/C library before any other functions are called, starting the embedded server if used in that configuration.
Syntax
int mysql_library_init(int argc, char **argv, char **groups)
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.
The behavior of mysql_num_rows() depends on whether buffered or unbuffered result sets are being used. For unbuffered result sets, mysql_num_rows() will not return the correct number of rows until all the rows in the result have been retrieved.
Deprecated.mysql_eof is deprecated. To determine the end of a result set, check the return value of mysql_fetch_row instead: a NULL return indicates that all rows have been fetched.
When the result set was acquired via mysql_store_result(), mysql_eof always returns true because the entire result is buffered in memory at retrieval time.
The option to be set, followed by one or more values.
Options
Return Value
History
See also
type: Specifies type of metadata information. Supported types are MARIADB_FIELD_ATTR_DATA_TYPE_NAME and MARIADB_FIELD_ATTR_FORMAT_NAME.
Returns extended metadata information for pluggable field types like JSON and GEOMETRY.
Returns zero on success or non zero if the field doesn't provide extended metadata information.
Pluggable field type support is available in MariaDB server version 10.5.2 and later.
To check if the server supports pluggable field types, check the extended server capabilities which can be obtained by api function mariadb_get_info().
mariadb_field_attr was added in MariaDB Connector/C 3.1.8.
% Select data
{ok, ColumnNames, Rows} = mysql:query(Pid, <<"SELECT id, name FROM mytable WHERE status = ?">>, [<<"active">>]).
% Insert data
ok = mysql:query(Pid, "INSERT INTO mytable (col1, col2) VALUES (?, ?)", [<<"value1">>, 123]).
# Turn off autocommit
SET AUTOCOMMIT=0;
# Retrieve autocommit
SELECT @@autocommit;
+--------------+
| @@autocommit |
+--------------+
| 0 |
+--------------+
static int test_autocommit(MYSQL *mysql)
{
int rc;
unsigned int server_status;
/* Turn autocommit off */
rc= mysql_autocommit(mysql, 0);
if (rc)
return rc; /* Error */
/* If autocommit = 0 succeeded, the last OK packet updated the server status */
rc= mariadb_get_infov(mysql, MARIADB_CONNECTION_SERVER_STATUS, &server_status);
if (rc)
return rc; /* Error */
if (server_status & SERVER_STATUS_AUTOCOMMIT)
{
printf("Error: autocommit is on\n");
return 1;
}
printf("OK: autocommit is off\n");
return 0;
}
Return Value
mode only affects operations on transactional table types. To determine the current state of autocommit mode use the SQL command SELECT @@autocommit. Be aware: the mysql_rollback() function will not work if autocommit mode is switched on.
mysql_change_user will always cause the current database connection to behave as if was a completely new database connection, regardless of if the operation was completed successfully. This reset includes performing a rollback on any active transactions, closing all temporary tables, and unlocking all locked tables.
mysql_info returns a string with summary statistics about the last executed query, covering INSERT, UPDATE, ALTER TABLE, and LOAD DATA operations; returns NULL for SELECT.
A connection handle previously allocated by . Must be called before .
option
The option to set.
mysql_options4 is used to set extra connect options and affect behavior for a connection. This function may be called multiple times to set several options. It must be called after mysql_init() and before mysql_real_connect().
Returns zero on success, non-zero if the option is unknown or the value is invalid.
An overview of the possible options can be found in the description of the API function.
mysql_options sets extra connection options on a MYSQL handle before calling mysql_real_connect. Deprecated since Connector/C 3.0 — use mysql_optionsv instead.
Syntax
int mysql_options(MYSQL * mysql,
enum mysql_option,
const void * arg);
mysql_option - the option you want to set. See description below.
arg - the value for the option.
Used to set extra connect options and affect behavior for a connection. This function may be called multiple times to set several options. mysql_options() should be called after and before .
Returns zero on success, non zero if an error occurred (invalid option or value).
mysql_query sends a null-terminated SQL string to the MariaDB server for execution, returning zero on success; use mysql_real_query for binary-safe operation.
Syntax
int mysql_query(MYSQL * mysql,
const char * query);
query -a null terminated string containing the statement to be performed.
Description
Performs a statement pointed to by the null terminate string query against the database. Contrary to mysql_real_query(), mysql_query() is not binary safe.
mysql_next_result advances to the next result set from a multi-statement query, making it available for retrieval via mysql_store_result or mysql_use_result.
mysql_ping checks whether a MariaDB server connection is still active and attempts an automatic reconnect if the connection has dropped and reconnect is enabled.
Checks whether the connection to the server is working. If it has gone down, and global option reconnect is enabled an automatic reconnection is attempted.
This function can be used by clients that remain idle for a long while, to check whether the server has closed the connection and reconnect if necessary.
Return Value
Returns zero on success, nonzero if an error occurred.
If a reconnect occurred the thread_id will change. Also resources bundled to the connection (prepared statements, locks, temporary tables, ...) will be released.
This guide will help you quickly get started with MariaDB Connector/C, the client library used to connect C/C++ applications to MariaDB and MySQL databases. It's LGPL licensed and is being integrated directly into MariaDB Server distributions.
MariaDB Connector/C is often distributed with MariaDB Server packages, but you can also install it separately.
You can download MariaDB Connector/C packages directly:
From the downloads page: Select your desired version from the main MariaDB Connector/C download page.
MariaDB Connector/J Guide
Quickstart Guide for Connector/J
MariaDB Connector/J is the official Java Database Connectivity (JDBC) driver for connecting Java applications to MariaDB and MySQL databases. It allows Java programs to interact with databases using the standard JDBC API.
See for full content.
You can include MariaDB Connector/J in your project using build tools like Maven or Gradle, or by manually adding the JAR file to your project's classpath.
a. Using Maven:
Add the following dependency to your pom.xml file:
b. Using Gradle:
Add the following dependency to your build.gradle file:
MariaDB Connector/NET Guide
Quickstart guide for MysqlConnector for ADO.NET
MariaDB Connector/NET, also known as MySqlConnector, is an ADO.NET data provider that enables .NET applications to connect and interact with MariaDB and MySQL databases. It's written entirely in C# and offers high performance and features specific to MariaDB Server.
MySqlConnector is licensed under the MIT License. It provides robust connectivity with features like:
Zero-configuration SSL: For MariaDB Server 11.4+.
Server Redirection Logic: Based on the latest MariaDB specification for MariaDB Server 11.3+.
Connector/Node.js Guide
Quickstart guide for MariaDB Connector/Node.js
MariaDB Connector/Node.js is a client library that enables Node.js applications to connect and interact with MariaDB and MySQL databases. It's built natively in JavaScript and supports both Promise and Callback APIs, with the Promise API being the default and recommended approach. It is licensed under the LGPL.
The easiest way to install MariaDB Connector/Node.js is using npm (Node Package Manager):
The Promise API simplifies asynchronous operations with async/await. For optimal performance and resource management, it's recommended to use a connection pool.
a. Create a Connection Pool:
Replace localhost, 3306
Connector/ODBC Guide
Quickstart guide for MariaDB Connector/ODBC
MariaDB Connector/ODBC is a database driver that allows applications to connect to MariaDB and MySQL databases using the Open Database Connectivity (ODBC) API. It's fully compliant with the ODBC 3.5 standard, open-source (LGPL), and can serve as a drop-in replacement for MySQL Connector/ODBC. It supports both Unicode and ANSI modes and communicates primarily using the MariaDB/MySQL binary protocol.
ODBC (Open Database Connectivity) is a standard API for accessing database management systems (DBMS). It provides a common way for applications to communicate with different databases, abstracting away the specifics of each database's native communication protocol. MariaDB Connector/ODBC acts as the specific bridge for MariaDB.
Installation typically involves downloading the appropriate driver package for your operating system and configuring a Data Source Name (DSN).
a. Windows:
Connector/Ruby Guide
Quickstart guide for Connector/Ruby
While there isn't a separate "MariaDB Connector/Ruby" gem, the widely used mysql2 gem serves as the primary and highly compatible Ruby client for connecting to both MariaDB and MySQL databases. It provides a robust API for database interactions in Ruby applications.
The mysql2 gem provides a Ruby interface to the MariaDB/MySQL C client library (either libmysqlclient or MariaDB Connector/C). It allows Ruby applications to execute SQL queries, fetch results, and manage database connections efficiently. It's available on .
Before installing the mysql2 gem, you might need to install development libraries for MariaDB Connector/C or MySQL Client on your system.
Configuration Settings for Building Connector/C
Configure the MariaDB Connector/C build via CMake options including build type, TLS/SSL backend, install prefix, and client plugins such as authentication and connection handlers.
Connector/C specifies its build process with platform-independent CMake listfiles included in each directory of a source tree with the name CMakeLists.txt.
Configuration settings may be specified by passing the -D option to CMake command line interpreter.
Do not build Connector/C from the root of the source tree: Either create a subdirectory "build" inside the source tree or create a subdirectory outside of the source tree.
Example:
In case Connector/C was already configured, the
mariadb_get_infov
mariadb_get_infov retrieves generic or connection-specific information from a MariaDB Connector/C handle, accepting a value-type enum and a pointer to store the result.
mysql - a mysql handle, which was previously allocated by or . For general information which is not bound to connection this parameter might be null.
value - the type of value you want to retrieve. See description below.
mysql_debug
mysql_debug enables debug output for a MariaDB Connector/C client using the DBUG library, accepting a colon-separated control string to configure trace and logging options.
debug - a string representing the debug operation to perform. See description below.
Enables debug output for development and debug purposes by using Fred Fish's DBUG library. For using this function the mariadb-client library must be compiled with debug support.
Almost all MariaDB binaries use the DBUG library and one can get a trace of the program execution by using the command line option with the binary. This will only work if the binary is compiled for debugging (compiler option -DDBUG_ON).
mysql_get_optionv
mysql_get_optionv retrieves the current value of a connection option previously set with mysql_optionsv, supporting boolean, integer, string, and miscellaneous option types.
mysql - a mysql handle, which was previously allocated by or .
mysql_option - the option you want to retrieve. See description below.
mysql_more_results
mysql_more_results indicates whether additional result sets remain from a previous multi-statement query, returning 1 if more results are available.
mysql - a mysql handle, which was previously allocated by or .
Indicates if one or more result sets are available from a previous call to .
Returns 1 if more result sets are available, otherwise zero..
mysql_net_field_length
Parameter
Description
Returns the length of a length encoded field and increments the pointer to the beginning of the field.
Returns the length of the field.
mysql_get_client_version
mysql_get_client_version retrieves the client library version as an unsigned long; use mysql_get_client_info for the string representation.
Returns a number representing the client library version. The value has the format XXYYZZ: major version * 10000 + minor version * 100 + patch version.
A pointer to a pointer to the current position in the packet buffer.
Syntax
Parameter
Description
Return Value
This function is part of the low level protocol API and can be used to retrieve data if a callback function was provided for fetching results from prepared statements.
Optimized SET NAMES handling: Avoids unnecessary commands for MariaDB Server 11.5+.
MariaDB GSSAPI Authentication: Support for secure authentication methods.
Asynchronous Operations: Fully supports async/await patterns for non-blocking database interactions.
The recommended way to install MySqlConnector is via NuGet.
a. Using NuGet Package Manager Console (in Visual Studio):
b. Using PackageReference (in your .csproj file):
This section provides C# examples for connecting to MariaDB and performing common database operations.
a. Connection String:
A connection string defines how your application connects to the database. Replace placeholder values with your actual database details.
b. Opening and Closing a Connection:
Always ensure connections are properly opened and closed. The using statement is recommended as it ensures the connection is disposed of correctly, even if errors occur.
c. Executing a SELECT Query:
Use MySqlCommand to define your SQL query and ExecuteReaderAsync to retrieve data.
d. Executing INSERT/UPDATE/DELETE Queries:
Use ExecuteNonQueryAsync for operations that do not return a result set (like INSERT, UPDATE, DELETE). Always use parameterized queries to prevent SQL injection vulnerabilities.
Here's an async function example to get a connection, execute queries, and release the connection back to the pool.
If you need compatibility with older Node.js database drivers (mysql, mysql2), you can use the Callback API.
Error Handling: Always include robust error handling (try...catch for Promises, if (err) for Callbacks) in your database interactions.
Parameterized Queries: Always use parameterized queries (e.g., WHERE status = ?, VALUES (?, ?)) to prevent SQL injection attacks.
Connection Pooling: For production applications, always use a connection pool (mariadb.createPool()) instead of single connections to manage resources efficiently.
conn.release() vs. conn.end(): When using a pool, use conn.release() to return the connection to the pool. Use conn.end() or pool.end() only when gracefully shutting down your application.
a. Install System Dependencies (e.g., on Debian/Ubuntu):
On other systems (Fedora, CentOS, macOS), the package names might differ (e.g., mariadb-devel, mysql-devel).
b. Install the mysql2 gem:
Once the system dependencies are in place, install the gem using Bundler (recommended for Rails/Gemfile projects) or directly via gem install:
Here's how to connect to MariaDB and perform common database operations using the mysql2 gem:
a. Connect to the Database:
Replace localhost, 3306, your_username, your_password, and your_database_name with your actual database details.
b. Execute a SELECT Query:
The results object behaves like an enumerable, allowing you to iterate over rows. Column names are accessible as hash keys.
c. Execute INSERT/UPDATE/DELETE Queries:
For data manipulation, use query. For safety, always use prepared statements or proper escaping for user-provided input.
d. Prepared Statements (Recommended for security and performance):
Prepared statements allow you to separate the SQL query structure from the data, preventing SQL injection and improving performance for repeated queries.
Before Running:
Ensure you have a MariaDB server running and a database/table set up.
Replace placeholder values with your actual database credentials and table/column names.
Error Handling: Always wrap your database operations in begin...rescue...end blocks to catch Mysql2::Error exceptions.
Connection Closing: Ensure your Mysql2::Client connection is closed using client.close in a ensure block to release database resources.
Prepared Statements/Escaping: Never concatenate user-provided strings directly into SQL queries. Use prepared statements with placeholders (?) or client.escape() for string literals.
using MySqlConnector;
using System;
using System.Data;
using System.Threading.Tasks;
public class MariaDBConnectorNetQuickstart
{
private static string connectionString = "Server=localhost;Port=3306;Database=your_database_name;Uid=your_username;Pwd=your_password;";
public static async Task Main(string[] args)
{
Console.WriteLine("Connecting to MariaDB...");
try
{
await using var connection = new MySqlConnection(connectionString);
await connection.OpenAsync();
Console.WriteLine("Connection successful!");
// Call your data operations here
await SelectData(connection);
await InsertData(connection);
Console.WriteLine("Operations completed.");
}
catch (MySqlException ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
}
// ... (Data operation methods will go here)
}
private static async Task SelectData(MySqlConnection connection)
{
string query = "SELECT id, name FROM your_table_name;";
await using var command = new MySqlCommand(query, connection);
Console.WriteLine("\nRetrieving data:");
await using var reader = await command.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
int id = reader.GetInt32("id");
string name = reader.GetString("name");
Console.WriteLine($"ID: {id}, Name: {name}");
}
}
private static async Task InsertData(MySqlConnection connection)
{
string query = "INSERT INTO your_table_name (name, status) VALUES (@name, @status);";
await using var command = new MySqlCommand(query, connection);
command.Parameters.AddWithValue("@name", "New Item");
command.Parameters.AddWithValue("@status", "active");
int rowsAffected = await command.ExecuteNonQueryAsync();
Console.WriteLine($"\nRows inserted: {rowsAffected}");
}
npm install mariadb
const mariadb = require('mariadb');
const pool = mariadb.createPool({
host: 'localhost',
port: 3306,
user: 'your_username',
password: 'your_password',
database: 'your_database_name',
connectionLimit: 5 // Adjust as needed
});
console.log("Connection pool created.");
async function executeDatabaseOperations() {
let conn;
try {
conn = await pool.getConnection(); // Get a connection from the pool
// --- SELECT Query ---
const rows = await conn.query("SELECT id, name FROM your_table_name WHERE status = ?", ["active"]);
console.log("Selected Rows:", rows);
// --- INSERT Query (with parameters for security) ---
const res = await conn.query("INSERT INTO your_table_name (name, status) VALUES (?, ?)", ["New Entry", "pending"]);
console.log("Insert Result:", res); // res will contain { affectedRows: 1, insertId: ..., warningStatus: 0 }
} catch (err) {
console.error("Database operation error:", err);
throw err; // Re-throw to handle higher up
} finally {
if (conn) {
conn.release(); // Release connection back to the pool
console.log("Connection released to pool.");
}
}
}
// Call the async function
executeDatabaseOperations()
.then(() => console.log("All database operations attempted."))
.catch((err) => console.error("Overall operation failed:", err))
.finally(() => {
// Optional: End the pool when your application is shutting down
// pool.end();
// console.log("Connection pool ended.");
});
const mariadb = require('mariadb/callback');
// Create a single connection
mariadb.createConnection({
host: 'localhost',
port: 3306,
user: 'your_username',
password: 'your_password',
database: 'your_database_name'
}, (err, conn) => {
if (err) {
console.error("Connection error:", err);
return;
}
console.log("Connected using Callback API.");
// Execute a query
conn.query("SELECT 1 AS val", (queryErr, rows) => {
if (queryErr) {
console.error("Query error:", queryErr);
conn.end(); // Close connection on error
return;
}
console.log("Query Result (Callback):", rows);
// Close the connection when done
conn.end((endErr) => {
if (endErr) {
console.error("Error closing connection:", endErr);
} else {
console.log("Connection closed (Callback).");
}
});
});
});
sudo apt update
sudo apt install libmariadb-dev # Or libmysqlclient-dev
# If using Bundler (e.g., in a Rails project's Gemfile)
# Gemfile
# gem 'mysql2'
bundle install
# Or directly
gem install mysql2
require 'mysql2'
begin
client = Mysql2::Client.new(
host: 'localhost',
port: 3306,
username: 'your_username',
password: 'your_password',
database: 'your_database_name'
)
puts "Successfully connected to MariaDB!"
# ... database operations ...
rescue Mysql2::Error => e
puts "Error connecting to database: #{e.message}"
ensure
client&.close # Ensure the connection is closed
end
# Assuming 'client' is an open connection
results = client.query("SELECT id, name FROM your_table_name WHERE status = 'active'")
puts "\nSelected Rows:"
results.each do |row|
puts "ID: #{row['id']}, Name: #{row['name']}"
end
# INSERT Example (using prepared statement)
statement = client.prepare("INSERT INTO your_table_name (name, status) VALUES (?, ?)")
insert_result = statement.execute("New Item", "pending")
puts "\nRows inserted: #{insert_result.affected_rows}, Last ID: #{insert_result.last_id}"
# UPDATE Example
update_result = client.query("UPDATE your_table_name SET status = 'completed' WHERE name = 'New Item'")
puts "Rows updated: #{update_result.affected_rows}"
# DELETE Example
delete_result = client.query("DELETE FROM your_table_name WHERE name = 'New Item'")
puts "Rows deleted: #{delete_result.affected_rows}"
# Assuming 'client' is an open connection
statement = client.prepare("SELECT * FROM users WHERE login_count = ?")
# Execute with different parameters
result1 = statement.execute(1)
puts "\nUsers with login_count = 1:"
result1.each { |row| puts row.inspect }
result2 = statement.execute(5)
puts "\nUsers with login_count = 5:"
result2.each { |row| puts row.inspect }
Records: 3 Duplicates: 0 Warnings: 0
Rows matched: 40 Changed: 40 Warnings: 0
Records: 100 Duplicates: 0 Warnings: 0
Records: 3 Duplicates: 0 Warnings: 0
Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
Queries which do not fall into one of the preceding formats are not supported (e.g. ). In these situations, mysql_info() will return NULL.
By product selection: Choose "C/C++ connector" as the Product on the MariaDB downloads page.
If you're using Linux, the simplest way to install MariaDB Connector/C is via your system's package manager. Your system needs to be configured to install from a MariaDB repository (version 10.2 or later).
For RHEL, CentOS, Fedora, and similar distributions, use yum or dnf:
To install the shared library:
To install the development package (if you're building applications):
Install with apt-get (Debian, Ubuntu)
For Debian, Ubuntu, and similar distributions, use apt-get:
To install the shared library:
To install the development package (if you're building applications):
Install with zypper (SLES, OpenSUSE)
For SLES, OpenSUSE, and similar distributions, use zypper:
To install the shared library:
To install the development package (if you're building applications):
MariaDB Connector/C for Windows is distributed as MSI packages. The installation process is straightforward, with both 32-bit and 64-bit MSI packages available.
Double-to-string conversion for prepared statements may not work correctly.
Connector versions 3.0.7 and below do not support MySQL 8.0's default authentication protocol, caching_sha2_password. This should be supported in Connector/C 3.0.8 and above.
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 production applications, it's highly recommended to use a connection pool to manage database connections efficiently. MariaDB Connector/J can be used with external connection pooling libraries like HikariCP or Apache Commons DBCP, or its own MariaDbPoolDataSource.
MariaDbDataSource: Creates a new connection each time.
MariaDbPoolDataSource: Maintains a pool of connections for reuse.
When using an external pool, configure it to use org.mariadb.jdbc.Driver as the JDBC driver class.
Red Hat/CentOS:sudo rpm -i mariadb-connector-odbc-X.Y.Z.rpm
macOS: Run the .pkg installer.
Configure odbcinst.ini and odbc.ini:
The installer usually places the driver definition in /etc/odbcinst.ini (or a similar location).
Test DSN (Optional): You can use isql (from unixodbc-dev or unixodbc package) to test your DSN:
Once the MariaDB ODBC driver is installed and a DSN is configured, applications can connect to your MariaDB database using the standard ODBC API. The exact code will vary depending on the programming language and framework you are using (e.g., C++, Java with JDBC-ODBC Bridge, Python with pyodbc, PHP with odbc extension).
a. Connecting via DSN (Common for many applications):
Many applications and tools (like Microsoft Excel, reporting tools, or C++ applications using ODBC) will allow you to select a configured DSN directly.
b. Connecting via DSN-less Connection String:
You can also provide a full connection string directly in your application without pre-configuring a DSN. This is often used in scripting languages or when you need more dynamic control.
Replace {MariaDB ODBC Driver} with the exact driver name from your odbcinst.ini if different.
file needs to be removed first. In several cases, e.g. when cross compiling
CMakeFiles
subfolders need to be removed too.
If you want to use a different generator, e.g. for nmake on Windows, you need to specify the generator with the -G option. cmake --help lists the available generators for the used platform.
CMAKE_BUILD_TYPE
Build type: Release, RelWithDebInfo or Debug
CMAKE_INSTALL_PREFIX
Installation base directory
CMAKE_C_FLAGS
Flags for C-Compiler
Option
Default
Description
WITH_SSL
SCHANNEL (windows), otherwise OPENSSL
Specifies type of TLS/SSL library. Valid values are OPENSSL, GNUTLS, and SCHANNEL (Windows only).
Client plugins can be configured as dynamic plugins (DYNAMIC) or built-in plugins (STATIC) by specifying the plugin name followed by suffix _PLUGIN_TYPE as key, and "DYNAMIC" or "STATIC" as value.
E.g. for building dialog plugin as a built-in plugin, for versions < Connector/C 3.0.4
arg - pointer to a variable for storing value of the specified option.
... - variable argument list
Retrieves generic or connection specific information. Returns zero on success, non-zero if an error occurred (invalid option), This function was added in MariaDB Connector/C 3.0,
For these information types of parameters mysql needs to be set to NULL.
MARIADB_CHARSET_NAME: Retrieves the charset information for a character set by its literal representation.Parameter type: const MARIADB_CHARSET_INFO*.
MARIADB_CLIENT_ERRORS: Retrieve array of client errors. This can be used in plugins to set global error messages (which are not exported by MariaDB Connector/C).Parameter type: const char **.
MARIADB_CLIENT_VERSION: The client version in literal representation.Parameter type: const char *.
MARIADB_CLIENT_VERSION_ID: The client version in numeric format.Parameter type: unsigned int.
MARIADB_MAX_ALLOWED_PACKET: Retrieves value of maximum allowed packet size.Parameter type: size_t
MARIADB_NET_BUFFER_LENGTH: Retrieves the length of net buffer.Parameter type: size_t
MARIADB_TLS_LIBRARY: The TLS library MariaDB Connector/C is compiled against.Parameter type: const char *.
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_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: Retrieves 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 *.
MARIADB_TLS_PEER_CERT_INFO Retrieves peer certificate information for TLS connections. The returned pointer to a MARIADB_X509_INFO structure becomes invalid after the connection has been closed. (Added in version 3.4.0)
MARIADB_TLS_VERIFY_STATUS Retrieves the status of a previous peer certificate verification. The status is represented as a combination of . This option was added in version 3.4.1
Returns zero on success, non zero if an error occurred (e.g. if an invalid option was specified),
This function was added in MariaDB Connector/C 3.0,
/* get server port for current connection */
unsigned int port;
mariadb_get_infov(mysql, MARIADB_CONNECTION_PORT, void *)&port);
/* get user name for current connection */
const char *user;
mariadb_get_infov(mysql, MARIADB_CONNECTION_USER, (void *)&user);
Description
Value types
Generic information
Connection related information
Return Value
History
Examples
See Also
Returns void.
The debug control string is a sequence of colon separated fields as follows:
Each field consists of a mandatory flag character followed by an optional "," and comma separated list of modifiers:
The currently recognized flag characters are:
Option
Description
d
Enable output from DBUG_ macros for the current state. May be followed by a list of keywords which selects output only for the DBUG macros with that keyword. A null list of keywords implies output for all macros.
D
Delay after each debugger output line. The argument is the number of tenths of seconds to delay, subject to machine capabilities. I.E. -#D,20 is delay two seconds.
f
Limit debugging and/or tracing, and profiling to the list of named functions. Note that a null list will disable all functions. The appropriate "d" or "t" flags must still be given, this flag only limits their actions if they are enabled.
Instead of using the mysql_debug() function you also can set the environment variable MYSQL_DEBUG\
Enabling generation of debug information slows down the overall performance and generates huge files. In case you need debug information only for special places you can disable the generation of debug information by using mysql_debug_end().
This function is deprecated and not supported anymore.
See Also
arg - pointer to a variable for storing value of the specified option.
... - variable argument list
Retrieves the value for a given option which was previously set by mysql_optionsv.
Returns zero on success, non zero if an error occurred (invalid option).
This function was added in MariaDB Connector/C 3.0.0.
MYSQL_OPT_COMPRESS
MYSQL_OPT_NAMED_PIPE
MYSQL_OPT_RECONNECT
MYSQL_REPORT_DATA_TRUNCATION
MYSQL_OPT_NONBLOCK
MYSQL_OPT_SSL_VERIFY_SERVER_CERT
MARIADB_OPT_CONNECTION_READ_ONLY
MYSQL_SECURE_AUTH
MYSQL_OPT_CONNECT_TIMEOUT
MYSQL_OPT_READ_TIMEOUT
MYSQL_OPT_WRITE_TIMEOUT
MYSQL_OPT_LOCAL_INFILE
MYSQL_OPT_PROTOCOL
MYSQL_INIT_COMMAND
char **commands;
int elements;
rc = mysql_get_optionv(mysql, MYSQL_INIT_COMMAND, &commands, &elements);
MYSQL_READ_DEFAULT_FILE
MYSQL_READ_DEFAULT_GROUP
MYSQL_SET_CHARSET_NAME
MYSQL_PLUGIN_DIR
MYSQL_OPT_SSL_KEY
MYSQL_OPT_SSL_CERT
MYSQL_OPT_SSL_CA
MYSQL_OPT_SSL_CAPATH
MYSQL_OPT_SSL_CRL
MYSQL_OPT_SSL_CRLPATH
MYSQL_OPT_SSL_CIPHER
MARIADB_OPT_SSL_FP
MARIADB_OPT_SSL_FP_LIST
MARIADB_OPT_SSL_PASSPHRASE
MYSQL_DEFAULT_AUTH
MYSQL_OPT_BIND
MARIADB_OPT_CONNECTION_HANDLER
MYSQL_PROGRESS_CALLBACK: requires a function pointer *(const MYSQL *, uint, uint, double, const char *, uint))arg)
MYSQL_CONNECT_ATTRS: this option requires 5 parameters:
/* get number of connection attributes */
int i, elements= 0;
char **key, **value;
mysql_get_optionv(mysql, MYSQL_CONNECT_ATTRS, NULL, NULL, (void *)&elements);
key= (char **)malloc(sizeof(char *) * elements);
val= (char **)malloc(sizeof(char *) * elements);
mysql_get_optionv(mysql, MYSQL_OPT_CONNECT_ATTRS, &key, &val, &elements);
for (i=0; i < elements; i++)
printf("key: %s value: %s", key[i], val[i]);
MARIADB_OPT_USERDATA: retrieves userdata for a given key.
Multiple result sets can be obtained either by calling a stored procedure or by executing concatenated statements, e.g. SELECT a FROM t1;SELECT b, c FROM t2.
To obtain a string containing the client library version use the mysql_get_client_info() function.
Since MariaDB Server 10.2.6 and MariaDB Connector/C 3.0.1 the client library is bundled with server package and returns the server package version. To obtain the client version of the connector, please use the constant MARIADB_PACKAGE_VERSION_ID
MariaDB Connector/R2DBC allows Java developers to connect to MariaDB and MySQL databases using the Reactive Relational Database Connectivity (R2DBC) API. This enables non-blocking, asynchronous database operations, which are beneficial for building scalable and responsive applications.
1. Installation
Add the necessary dependency to your project's pom.xml (Maven) or build.gradle (Gradle) file. Choose the dependency based on the R2DBC Specification you are targeting.
a. For R2DBC 1.0.0 Specification (Recommended for new projects):
MariaDB Connector/R2DBC also integrates seamlessly with the Spring Data R2DBC framework, providing a higher-level abstraction for reactive database access, including repositories and entity mapping.
#include <mysql.h>
struct st_mysql_client_plugin *
mysql_load_plugin(struct st_mysql *mysql, const char *name, int type,
int argc, ...);
Parameters
Parameter
Description
mysql
A connection handle previously allocated by and connected by .
name
The name of the plugin to load.
mysql_load_plugin searches the client plugin directory for a plugin matching the given name and type, loads it, and calls its initialization function with any supplied arguments. If a plugin with that name is already loaded, the call fails and returns NULL (error "it is already loaded").
MYSQL_CLIENT_AUTHENTICATION_PLUGIN
MARIADB_CLIENT_PVIO_PLUGIN
MARIADB_CLIENT_REMOTEIO_PLUGIN
A pointer to the plugin handle, or NULL if an error occurred.
MARIADB_CLIENT_CONNECTION_PLUGIN or MARIADB_CLIENT_COMPRESSION_PLUGIN.
type
The plugin type, or -1 to accept any type.
argc
The number of optional arguments that follow.
...
Optional arguments passed to the plugin's initialization function.
Description
Valid Plugin Types
Return Value
If the type of the plugin is not known, -1 needs to be specified for parameter type.
The directory which contains the plugin can be specified either by the environment variable MARIADB_PLUGIN_DIR or it can be specified with mysql_optionsv() using the option MYSQL_PLUGIN_DIR.
plugin for client server communication via shared memory
PVIO_NPIPE
IO
static
plugin for client server communication via named pipe
DIALOG
Authentication
dynamic
Authentication for user input, e.g. for PAM authentication
MYSQL_OLD_PASSWORD
Authentication
static
Pre. 4.1 authentication (deprecated). Disabled by default in current versions; not built unless explicitly enabled.
MYSQL_NATIVE_PASSWORD
Authentication
static
Default authentication
MYSQL_CLEAR_PASSWORD
Authentication
dynamic
Sends password without hashing or encryption
AUTH_GSSAPI_CLIENT
Authentication
dynamic
Kerberos/GSSAPI authentication plugin
SHA256_PASSWORD
Authentication
dynamic
SHA256 password authentication plugin
REPLICATION
Connection
OFF
Replication/fail over plugin (experimental)
F
Identify the source file name for each line of debug or trace output.
i
Identify the process with the pid for each line of debug or trace output.
g
Enable profiling. Create a file called 'dbugmon.out' containing information that can be used to profile the program. May be followed by a list of keywords that select profiling only for the functions in that list. A null list implies that all functions are considered.
L
Identify the source file line number for each line of debug or trace output.
n
Print the current function nesting depth for each line of debug or trace output.
N
Number each line of dbug output.
o
Redirect the debugger output stream to the specified file. The default output is stderr.
O
As o but the file is really flushed between each write. When needed the file is closed and reopened between each write.
a
Like o, but opens for append.
A
Like O, but opens for append.
p
Limit debugger actions to specified processes. A process must be identified with the DBUG_PROCESS macro and match one in the list for debugger actions to occur.
P
Print the current process name for each line of debug or trace output.
r
When pushing a new state, do not inherit the previous state's function nesting level. Useful when the output is to start at the left margin.
S
Do function _sanity(file,line) at each debugged function until _sanity() returns something that differs from 0. (Mostly used with safemalloc)
t
Enable function call/exit trace lines. May be followed by a list (containing only one modifier) giving a numeric maximum trace level, beyond which no output will occur for either debugging or tracing macros. The default is a compile time option.
Complete MariaDB installation guide. Complete setup instructions for Linux, Windows, and macOS with configuration and verification for production use.
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:
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:
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:
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 .
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:
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:
To install MariaDB Connector/C on SLES, you can use ZYpp if you have the or configured.
Install MariaDB Connector/C and package dependencies:
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.
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.
Complete Connector/C reference: Windows MSI install, Linux packages (yum/apt/zypper), MariaDB-shared/devel libraries, and option file configuration.
MariaDB Connector/C is used to connect applications developed in C/C++ to MariaDB and MySQL databases.The client library is LGPL licensed.
MariaDB Connector/C is compatible with all MariaDB and MySQL server versions.
The following MariaDB Connector/C release series are currently supported:
Release Series
Stable (GA) Date
Replication API Types and Definitions
All enumerations and preprocessor definitions for the Binglog/Replication API are defined in include/mariadb_rpl.h.
The following API types and definitions are used by the Binlog/Replication API:
Type or Definition
Description
Checksums of the various releases of the mariadb_es_repo_setup script can be found in the section at the bottom of the page. Substitute ${checksum} in the example above with the latest checksum.
Checksums of the various releases of the mariadb_repo_setup script can be found in the section at the bottom of the page. Substitute ${checksum} in the example above with the latest checksum.
Configure the CS package repository using the mariadb_repo_setup utility:
Most users install MariaDB Connector/C from the packages distributed with MariaDB Server, which use the server's versioning scheme rather than the connector's. To find the installed Connector/C version, use the mariadb_config utility with the --cc_version option:
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.
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.
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.
MariaDB Connector/C is distributed in on Linux.
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 MariaDB Repository Configuration Tool.
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 apt-get. 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:
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, caching_sha2_password. This protocol should be supported in Connector/C 3.0.8 and above.
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.
The mariadb_config --version option returns the MariaDB Server package version, not the Connector/C version. Use --cc_version for the Connector/C version.
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
mariadb_row_event_type
Row operation type for write, update, and delete row events.
Flags
Bitmask constants for controlling binary log dump behaviour. Passed via the MARIADB_RPL_FLAGS option.
mariadb_rpl_option is the enumeration of options accepted by mariadb_rpl_optionsv() and mariadb_rpl_get_optionsv(). Options are used to configure a MARIADB_RPL handle before opening a binary log stream.
Option descriptions
MARIADB_RPL_FILENAME → Name of the binary log file to open, and its length in bytes.
MARIADB_RPL_START → Binary log position from which to start reading events.
MARIADB_RPL_SERVER_ID → The server ID to use when registering this client as a replica.
MARIADB_RPL_FLAGS → Bitmask of protocol flags controlling binary log dump behavior. See Flags for valid values.
MARIADB_RPL_GTID_CALLBACK → Pointer to a GTID callback function, called when a GTID event is received.
MARIADB_RPL_GTID_DATA → User data pointer passed to the GTID callback function.
MARIADB_RPL_BUFFER → Pre‑allocated buffer for event data, and its size.
mariadb_rpl_event is the enumeration of all binary log event types. The event_type field of MARIADB_RPL_EVENT is set to one of these values to indicate which event structure is active in the event union.
mariadb_row_event_type identifies the row operation performed by a WRITE_ROWS_EVENT, UPDATE_ROWS_EVENT, or DELETE_ROWS_EVENT.
Value
Constant
Description
0
WRITE_ROWS
A row was inserted. The row_data field contains the new row image.
1
UPDATE_ROWS
A row was updated.
The following flags are passed as a bitmask to the MARIADB_RPL_FLAGS option via mariadb_rpl_optionsv(). Multiple flags can be combined using the bitwise OR operator (|) to control binary log dump behavior.
MariaDB Connector/Python is the official Python client library for connecting applications to MariaDB and MySQL databases. It implements the Python DB API 2.0 (PEP-249) standard, ensuring compatibility with common Python database programming patterns.
Version 2.0 offers flexible distribution options:
Pure Python - Works everywhere, no compiler or dependencies required
C extension - Maximum performance (2-12× faster on data-heavy workloads)
2
DELETE_ROWS
A row was deleted. The row_data field contains the deleted row image.
Pre-compiled wheels - No MariaDB Connector/C installation needed
Async/await support - Native asynchronous operations for modern Python applications
Connection API - Connection parameters, methods, and attributes
Cursor API - Cursor parameters, methods, and attributes
Before installing MariaDB Connector/Python, ensure you have:
Python: Version 3.9 or later
MariaDB Connector/C: Version 3.3.1 or later (optional - only required for C extension from source)
Version 1.1 (stable / GA)
A plain pip install installs the latest stable release (1.1). It always installs the C extension and requires MariaDB Connector/C to be pre-installed; connection pooling is included by default.
To pin to a specific 1.1 release:
Version 2.0 (Release Candidate)
Version 2.0 is a pre-release, so the --pre flag is required — without it, pip installs the latest GA release (1.1). Choose the option that best fits your needs:
Here's a simple Python example demonstrating how to connect to MariaDB, execute queries, and manage transactions.
Using Dictionary Configuration (All Versions):
Using URI Connection String (Since Version 2.0):
Before Running:
Replace your_username, your_password, and your_database_name with your actual MariaDB server credentials.
Ensure you have a MariaDB server running and the specified database exists.
The example assumes your_table_name is users with columns id, name, email. Adjust the table/column names as needed.
Parameterized Queries: Always use parameterized queries (e.g., VALUES (?, ?)) to prevent SQL injection vulnerabilities. Parameters are passed as a tuple or list to the execute() method.
Transactions (conn.commit() / conn.rollback()): By default, autocommit is disabled. Call conn.commit() to save changes or conn.rollback() to undo them.
Error Handling: Use try...except mariadb.Error blocks to gracefully handle database-related exceptions.
Resource Management: Always close your cursor and connection objects in a finally block to ensure resources are released, even if errors occur.
URI Connections: Version 2.0 supports standard URI connection strings for cleaner configuration.
Binary Protocol: Use binary=True for prepared statements and better performance with repeated queries.
For modern async applications (FastAPI, Starlette, etc.):
import mariadb
import sys
# 1. Database Connection URI (Available since MariaDB Connector/Python 2.0)
DATABASE_URL = "mariadb://your_username:your_password@localhost:3306/your_database_name"
def run_db_operations():
conn = None
cursor = None
try:
# 2. Establish a Connection
print("Connecting to MariaDB...")
conn = mariadb.connect(DATABASE_URL)
print("Connection successful!")
# 3. Create a Cursor Object
cursor = conn.cursor()
# --- Example: Create a Table (if it doesn't exist) ---
try:
cursor.execute("""
CREATE TABLE IF NOT EXISTS users (
id INT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) UNIQUE
)
""")
conn.commit() # Commit the transaction for DDL
print("Table 'users' created or already exists.")
except mariadb.Error as e:
print(f"Error creating table: {e}")
conn.rollback() # Rollback in case of DDL error
# --- Example: Insert Data (Parameterized Query) ---
print("\nInserting data...")
insert_query = "INSERT INTO users (name, email) VALUES (?, ?)"
try:
cursor.execute(insert_query, ("Alice Wonderland", "alice@example.com"))
cursor.execute(insert_query, ("Bob Builder", "bob@example.com"))
conn.commit() # Commit the transaction for DML
print(f"Inserted {cursor.rowcount} rows.")
print(f"Last inserted ID: {cursor.lastrowid}")
except mariadb.IntegrityError as e:
print(f"Error inserting data (might be duplicate email): {e}")
conn.rollback()
except mariadb.Error as e:
print(f"Error inserting data: {e}")
conn.rollback()
# --- Example: Select Data ---
print("\nSelecting data...")
select_query = "SELECT id, name, email FROM users WHERE name LIKE ?"
cursor.execute(select_query, ("%Alice%",)) # Note the comma for single parameter tuple
print("Fetched data:")
for row in cursor:
print(f"ID: {row[0]}, Name: {row[1]}, Email: {row[2]}")
# --- Example: Update Data ---
print("\nUpdating data...")
update_query = "UPDATE users SET name = ? WHERE email = ?"
cursor.execute(update_query, ("Alicia Wonderland", "alice@example.com"))
conn.commit()
print(f"Rows updated: {cursor.rowcount}")
# --- Example: Delete Data ---
print("\nDeleting data...")
delete_query = "DELETE FROM users WHERE name = ?"
cursor.execute(delete_query, ("Bob Builder",))
conn.commit()
print(f"Rows deleted: {cursor.rowcount}")
except mariadb.Error as e:
print(f"An error occurred: {e}")
sys.exit(1)
finally:
# 4. Close Cursor and Connection
if cursor:
cursor.close()
print("Cursor closed.")
if conn:
conn.close()
print("Connection closed.")
if __name__ == "__main__":
run_db_operations()
import asyncio
import mariadb
async def async_operations():
# Connect asynchronously
conn = await mariadb.asyncConnect(
"mariadb://your_username:your_password@localhost/your_database_name"
)
try:
cursor = await conn.cursor()
# Execute async query
await cursor.execute("SELECT id, name, email FROM users WHERE id = ?", (1,))
user = await cursor.fetchone()
print(f"User: {user}")
await cursor.close()
finally:
await conn.close()
# Run async function
asyncio.run(async_operations())
import asyncio
import mariadb
async def main():
# Create async pool
pool = await mariadb.create_async_pool(
"mariadb://user:password@localhost/mydb",
min_size=5,
max_size=20
)
# Use pool
async with await pool.acquire() as conn:
async with conn.cursor() as cursor:
await cursor.execute("SELECT COUNT(*) FROM users")
count = (await cursor.fetchone())[0]
print(f"Total users: {count}")
await pool.close()
asyncio.run(main())
API Reference
1. Prerequisites
2. Installation
Version 1.1 is the latest stable (GA) release; version 2.0 is currently a Release Candidate (RC). Choose the version that fits your needs below. Do not use non-stable (non-GA) releases in production.
3. Basic Usage
Important Notes:
4. Async/Await Support (New in 2.0)
Further Resources:
MariaDB Connector/C Data Structures
Reference for the public data structures in MariaDB Connector/C, including MYSQL, MYSQL_RES, MYSQL_STMT, MYSQL_FIELD, MYSQL_BIND, and MYSQL_TIME with all member definitions.
This page describes the public data structures used by MariaDB Connector/C.
MYSQL
The MYSQL structure represents one database connection and is used by most of MariaDB Connector/C's API functions. The MYSQL structure needs to be allocated and initialized by the mysql_init() API function. It will be released by the mysql_close() function.
The MYSQL structure should be considered as opaque; copying or changing values of its members might produce unexpected results, errors or program crashes.
The MYSQL_RES structure should be considered as opaque; copying or changing values of its members might produce unexpected results, errors or program crashes.
MYSQL_ROW
MYSQL_ROW represents an array of character pointers, pointing to the columns of the actual data row.
Data will be received by the function. The size of the array is the number of columns for the current row.
The MYSQL_STMT structure represents a prepared statement handle and is used by MariaDB Connector/C's prepared statement API functions. The MYSQL_STMT structure needs to be allocated and initialized by the function and needs to be released by the function.
The MYSQL_FIELD structure describes the metadata of a column. It can be obtained by the function.
It has the following members:
Type
Member
Description
The MYSQL_BIND structure is used to provide parameters for prepared statements or to receive output column value from prepared statements.
Type
Member
Description
The MYSQL_TIME structure is used for date and time values in prepared statements. It has the following members:
Type
Member
Description
The MARIADB_X509_INFO structure contains information about the peer certificate. This information is only available for TLS/SSL connections.
Type
Member
Description
MARIADB_X509_INFO was added in MariaDB Connector/C 3.4.1
Reference for MariaDB Connector/C types and definitions, including enumeration constants for field types, statement options, cursor types, indicator types, field flags, and server status.
MariaDB Connector/C provides the following types and definitions.
enum mysql_option is used as a parameter in and API functions. For a list of integral constants and their meanings, please check the documentation of .
enum enum_mysql_timestamp_type is used in the MYSQL_TIME structure and indicates the type. It has the following constants:
Array of indicator variables for bulk operation parameter
unsigned long
buffer_length
Length of buffer
enum enum_field_types
buffer_type
unsigned long
length_value
Used if address of length_value is assigned to MYSQL_BIND::length
my_bool
error_value
Used if address of error_value is assigned to MYSQL_BIND::error
my_bool
is_null_value
Used if address of is_null_value is assigned to MYSQL_BIND::is_null
my_bool
is_unsigned
Set if integer type is unsigned
unsigned int
day
Day
unsigned int
hour
Hour
unsigned int
minute
Minute
unsigned int
second
Second
unsigned long
second_part
Fractional seconds (max. 6 digits)
my_bool
neg
Negative value
enum enum_mysql_timestamp_type
time_type
Time Type
char *
subject
Subject of peer certificate
char[129]
fingerprint
Fingerprint (SHA256, 384 or 512)
struct tm
not_before
Start date of peer certificate
struct tm
not_after
Expiration date of peer certificate
char *
name
The name of the column
unsigned int
name_length
The length of column name
unsigned long *
length
Pointer for the length of the buffer (not used for parameters). The length is ignored for numeric and fixed size data types, as the buffer_type value determines the size of the data.
my_bool *
is_null
Pointer which indicates if column is NULL (not used for parameters)
unsigned int
year
Year
unsigned int
month
Month
int
version
Peer certificate version
char *
issuer
Issuer of peer certificate
After freeing the result set with mysql_free_result()MYSQL_ROW becomes invalid.
MYSQL_STMT
The MYSQL_STMT structure should be considered as opaque; copying or changing values of its members might produce unexpected results, errors or program crashes.
All structures and type definitions for the Binglog/Replication API are defined in include/mariadb_rpl.h.
The following structures are used by the Binlog/Replication API:
Structure
Description
MARIADB_STRING
Stores a string together with its length.
MARIADB_TIMESTAMP
MARIADB_STRING is a simple structure that stores a string together with its length. It is equivalent to MYSQL_STRING and MYSQL_LEX_STRING.
str → Pointer to the character data.
length → Length of the string in bytes.
MARIADB_TIMESTAMP stores timestamp values for MYSQL_TYPE_TIMESTAMP and MYSQL_TYPE_TIMESTAMP2 column data. It was introduced in MariaDB Connector/C 3.3.19 and 3.4.9 versions.
second → Represents the whole seconds portion of the timestamp.
second_part → Represents the fractional seconds (microseconds).
MARIADB_GTID represents a Global Transaction ID (GTID).. A GTID uniquely specifies a transaction across a replication topology and is defined by three components: domain ID, server ID, and sequence number.
domain_id → The replication domain identifier.
server_id → The ID of the server that originally committed the transaction.
sequence_nr → The transaction’s sequence number within the domain.
MARIADB_RPL is the generic replication handle. It represents a replication connection and is passed to all Binlog/Replication API calls.
The MARIADB_RPL structure is opaque. Its internal members should not be accessed directly.
To configure replication options, use mariadb_rpl_optionsv().
To retrieve replication options, use mariadb_rpl_get_optionsv()
MARIADB_RPL_EVENT is the structure returned by mariadb_rpl_fetch() API function. It contains a common event header followed by a union of event-specific structures. The active union member is determined by the value of event_type.
Field Validation
memroot → Internal memory pool used to allocate event data.
checksum → CRC32 checksum of the event (if binlog checksums are enabled).
ok → Non-zero if the event was received without error.
The event union defines one member for each supported replication event type. Only the member that corresponds to the current event_type value contains valid data.
The following sections describe each event type and its associated structure:
ANNOTATE_ROWS_EVENT
event_type value= 160 (0xA0)
This event contains the statement that produced the subsequent row‑change event in the binary log stream. It is only generated if the client connects with the MARIADB_RPL_BINLOG_SEND_ANNOTATE_ROWS flag enabled.
statement → The SQL statement that triggered the row‑change event.
Notes
ANNOTATE_ROWS_EVENT is sent only when the replication handle was opened with the MARIADB_RPL_BINLOG_SEND_ANNOTATE_ROWS flag, set through mariadb_rpl_optionsv().
If the flag is not set, this event will not be included in the binary log stream.
BINLOG_CHECKPOINT_EVENT
event_type value= 161 (0xA1)
Written to the binary log to record the oldest binary log file that is still required for recovery. This event ensures that replication and recovery processes know which binary log files must be retained to guarantee consistency.
filename → The name of the oldest binary log file needed for crash recovery and replication consistency.
START_ENCRYPTION_EVENT
event_type value= 164 (0xA4)
Written to the binary log when encryption is enabled on the source server. This event records the encryption scheme and key version used for subsequent event
scheme → Encryption scheme identifier.
key_version → Version of the encryption key used for encrypted log data.
nonce → Nonce (number used once) used in the encryption process.
FORMAT_DESCRIPTION_EVENT
event_type value= 15 (0x0F)
Written at the beginning of every binary log file, at position 4. This event describes the format of all subsequent events in the file. For MariaDB 10.0 and later, the format field is always set to 4.
format → Binary log format version. Always 4 for MariaDB 10.0 and later.
server_version → Version string of the server that created the binary log.
timestamp
GTID_EVENT
event_type value= 162 (0xA2)
Marks the start of a new global transaction event group. This event is written to the binary log before the events belonging to the transaction.
sequence_nr → Sequence number of the transaction within the replication domain.
domain_id → Identifier of the replication domain.
flags → Bitmask of event flags.
Notes:
The GTID_EVENT ensures that each transaction is uniquely identified across the replication topology.
It captures all events belonging to the transaction, ensuring replication consumers can group and track them consistently.
GTID_LIST_EVENT
event_type value= 163 (0xA3)
Written at the start of every binary log file to record the current replication state. This event contains the last GTID seen for each replication domain, allowing replicas to determine where to resume replication after a reconnect.
gtid_cnt → Number of GTID entries in the gtid array.
gtid → Array of MARIADB_GTID structures, one per replication domain.
HEARTBEAT_LOG_EVENT
event_type value= 27 (0x1B)
Sent over the network by the source server to replicas when there are no binary log events to transmit. This event confirms that the source server is still alive. It is never written to the binary log file itself.
filename → Name of the current binary log file on the source server.
INTVAR_EVENT
event_type value=5 (0x05)
Written to the binary log immediately before a QUERY_EVENT whenever the statement uses an AUTO_INCREMENT value or the LAST_INSERT_ID() function.
value → The integer value, either the next auto‑increment value or the result of LAST_INSERT_ID().
type → Indicates the variable type.
Valid values for type are:
Value
Constant
Description
QUERY_EVENT
event_type value=2 (0x02)
Contains a SQL statement. This event is written to the binary log when:
The server binlog_format is set to STATEMENT (statement‑based replication).
A DDL statement is executed.
A COMMIT
thread_id → ID of the client thread that executed the statement on the source server.
seconds → Time in seconds that the statement took to execute.
database → Name of the default database at the time the statement was executed.
RAND_EVENT
event_type value=13 (0x0D)
Written to the binary log immediately before a QUERY_EVENT that uses the RAND() function. This event records the seed values so that replicas can reproduce the same pseudo‑random sequence.
first_seed → First seed value for the RAND() function.
second_seed → Second seed value for the RAND() function.
ROTATE_EVENT
event_type value=4 (0x04)
Written at the end of a binary log file to indicate that the next event will appear in a new binary log file.
position → Starting position in the new binary log file.
filename → Name of the new binary log file.
Notes:
The ROTATE_EVENT signals the transition between binary log files, ensuring replication clients know where to continue reading.
It is always written at the end of a binary log file and points to the beginning of the next file.
Row events are written to the binary log when the server binlog_format is set to ROW. All three event types share the same structure; the type field distinguishes the specific row operation (insert, update, or delete).
type → Row operation type: write (insert), update, or delete. See Replication API Types and Definitions.
table_id → References the table mapped by the preceding TABLE_MAP_EVENT.
flags
TABLE_MAP_EVENT
event_type value=19 (0x13)
Written before each row event (in row‑based replication) to map a table ID to a fully qualified table name and provide column metadata for the rows that follow.
table_id → Numeric table ID used in subsequent row events to reference this table.
database → Name of the database containing the table.
table → Name of the table.
USERVAR_EVENT
event_type value=14 (0x0E)
Written to the binary log before a QUERY_EVENT that references a user variable. This event records the variable’s name, type, and value so the replica can set it before executing the statement.
name → Name of the user variable.
is_null → Non‑zero if the variable’s value is NULL.
type
XID_EVENT
event_type value=16 (0x10)
Written to the binary log when a transactional storage engine commits a transaction. This event records the XA transaction number and signals the end of the transaction’s event group.
transaction_nr → The XA transaction number for this commit.
Notes:
The XID_EVENT marks the successful commit of a transaction in engines that support XA transactions.
It serves as the boundary marker for the transaction’s event group, ensuring replicas apply the transaction atomically.
event_type → Identifies the event type and determines which union member is active.
timestamp → Unix timestamp (seconds since epoch) when the event was created.
server_id → Server ID of the server that generated the event.
event_length → Total length of the event in bytes, including the header.
next_event_pos → Binary log position of the next event.
flags → Bitmask of event flags (see Replication API types and definitions for flag values).
→ Unix timestamp of when the binary log file was created.
header_len → Length of the fixed event header in bytes.
post_header_lengths → Array of post‑header lengths for each event type. Added in Connector/C 3.3.5.
commit_id → Commit ID used to coordinate parallel replication.
format_id → Format identifier of the XA transaction, when the group commits an XA transaction.
gtrid_len → Length of the global transaction identifier part of the XID.
bqual_len → Length of the branch qualifier part of the XID.
xid → XA transaction identifier associated with the transaction.
is issued for a non‑transactional storage engine.
errornr → Error number if the statement produced an error; 0 on success.
status → Status variables blob (encoded server status at the time of execution).
statement → The SQL statement text.
DELETE_ROWS_EVENT_V1 → 25 (0x19)
→ Row event flags bitmask.
column_count → Number of columns in the table.
column_bitmap → Bitmap of columns present in the row image; one bit per column.
column_update_bitmap → For UPDATE_ROWS_EVENT: bitmap of columns present in the after‑image. NULL for write and delete events.
null_bitmap → Bitmap indicating which columns hold a NULL value in the row image.
row_data_size → Size in bytes of row_data.
row_data → Raw encoded row data. Use mariadb_rpl_extract_rows() to decode.
extra_data_size → Size in bytes of extra_data.
extra_data → Raw encoded extra row-event data, when present.
compressed → Non‑zero if the row data is compressed.
row_count → Number of rows contained in the event.
column_count → Number of columns in the table.
column_types → Array of column type identifiers, one byte per column.
metadata → Type‑specific metadata for each column (length varies by column type).
null_indicator → Bitmap indicating which columns are nullable; one bit per column.
signed_indicator → Bitmap indicating which numeric columns are signed.
column_names → Optional metadata listing the column names.
geometry_types → Optional metadata listing the geometry subtypes for spatial columns.
default_charset → Default character set applied to string columns.
column_charsets → Optional metadata listing per‑column character sets.
simple_primary_keys → Optional metadata listing primary-key columns without a prefix length.
prefixed_primary_keys → Optional metadata listing primary-key columns that use a prefix length.
set_values → Optional metadata listing the possible values for SET columns.
enum_values → Optional metadata listing the possible values for ENUM columns.
enum_set_default_charset → Default character set applied to ENUM and SET columns.
enum_set_column_charsets → Optional metadata listing per‑column character sets for ENUM and SET columns.
→ Data type of the variable value.
charset_nr → Collation ID for string values.
value → Encoded value of the variable. Empty if is_null is non‑zero.
flags → Reserved flags field.
Stores a timestamp value used in MYSQL_TYPE_TIMESTAMP and MYSQL_TYPE_TIMESTAMP2 columns.
MARIADB_GTID
Stores a global transaction ID (domain ID, server ID, and sequence number).
MARIADB_RPL
Opaque replication handle representing a replication connection.
MARIADB_RPL_EVENT
Contains a common event header and a union of all event-specific structures returned by mariadb_rpl_fetch().
0x01
LAST_INSERT_ID
Value is the result of LAST_INSERT_ID().
0x02
INSERT_ID
Value is the next AUTO_INCREMENT value.
MARIADB_STRING
MARIADB_TIMESTAMP
MARIADB_GTID
MARIADB_RPL
Events
MARIADB_RPL_EVENT
Event Union Behavior
Encrypted event data is available only when reading directly from a binary log file.
When a client connects to a live source server, the server always sends unencrypted events, even if encryption is enabled at rest.
This event always appears at the start of a binary log file (position 4).
It defines the structure and header lengths for all subsequent events, ensuring compatibility between server and client replication components.
The GTID_LIST_EVENT provides a snapshot of the replication state at the beginning of a binary log file.
By recording the last GTID for each domain, it ensures replicas can safely resume replication after interruptions.
QUERY_EVENT is central to statement‑based replication, ensuring that SQL statements are replayed consistently on replicas.
Even in row‑based replication, certain operations (like DDL or non‑transactional commits) still generate QUERY_EVENT entries.
The RAND_EVENT ensures deterministic replication of statements that rely on pseudo‑random values.
By recording both seed values, replicas can generate the same sequence of random numbers as the source server, maintaining consistency across the replication topology.
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.
The MariaDB Connector/C API provides functions for establishing connections, executing statements, retrieving and navigating result sets, managing transactions, and configuring connection options, plugins, and metadata.
Function Overview
Function
Description
Immediately aborts a connection by making all subsequent read/write operations fail, without freeing the MYSQL structure or closing communication channels.
Attempts to re-establish a dropped MariaDB Connector/C connection using the original credentials, and requires the MYSQL_OPT_RECONNECT option to be set.
Changes the authenticated user and default database on an existing connection, resetting session state including transactions, temporary tables, and locks.
Enables debug output for a MariaDB Connector/C client using the DBUG library, accepting a colon-separated control string to configure trace and logging options.
Retrieves the current value of a connection option previously set with mysql_optionsv, supporting boolean, integer, string, and miscellaneous option types.
Returns a string with summary statistics about the last executed query, covering INSERT, UPDATE, ALTER TABLE, and LOAD DATA operations; returns NULL for SELECT.
Resets session state on a MariaDB Connector/C connection — rolling back transactions and clearing variables — without disconnecting or reauthenticating.
Retrieves the first session state change notification from the server, covering schema changes, system variables, and state flags. Added in Connector/C 3.0.
Retrieves subsequent session state change notifications after mysql_session_track_get_first, called repeatedly until a nonzero value signals end of data.
Releases thread-local memory allocated by mysql_thread_init and must be called explicitly before a thread exits to avoid memory leaks. Deprecated in Connector/C 3.0.
Initializes thread-local variables for multi-threaded Connector/C clients; called automatically by mysql_init if not invoked explicitly. Deprecated in Connector/C 3.0.
mysql_optionsv sets connection, TLS, plugin, and option-file options on a MariaDB Connector/C handle before mysql_real_connect, supporting a variable argument list.
mysql_option - the option to set. See description below.
arg - the value for the option.
... - variable argument list.
Used to set extra connect options and affect behavior for a connection. This function may be called multiple times to set several options. All calls pass numeric literal values for a const void *. mysql_optionsv() should be called after .
Some of these options can also be set in , such as my.cnf.
Returns zero on success, non-zero if an error occurred (invalid option or value).
The following table shows the C variable type required for the arg parameter of each option:
Variable type
Options
MYSQL_INIT_COMMAND: lets you specify a command to execute immediately after connecting (and also after a reconnect if enabled).
Each call adds one SQL statement to an internal list; all stored commands are executed in order.
You cannot concatenate multiple statements with semicolons; each statement must be added with a separate call.
Some of these options can also be set as arguments to the function.
MARIADB_OPT_HOST: Hostname or IP address of the server to connect to.
MARIADB_OPT_USER: User to login to the server.
MARIADB_OPT_PASSWORD: Password of the user to login to the server.
MYSQL_OPT_SSL_KEY: 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 MARIADB_OPT_TLS_PASSPHRASE option.
MYSQL_OPT_SSL_CERT: 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_DEFAULT_AUTH: Default authentication client-side plugin to use.
MYSQL_ENABLE_CLEARTEXT_PLUGIN: This option is supported to be compatible with MySQL client libraries. MySQL client libraries use this option to determine whether the authentication plugin can be used. However, MariaDB clients and client libraries do not need to set any options in order to use this authentication plugin. Therefore, this option does not actually do anything in MariaDB Connector/C.
MARIADB_OPT_STATUS_CALLBACK: Specifies a callback function that is invoked whenever the server sends a status change or session tracking information to the client. This can be used to monitor server status flags and session variable changes without polling.
The callback function must match the following signature:
Parameters
Parameter
Type
Description
Variadic Parameters (vary by type)
When type is STATUS_TYPE:
Position
Type
Description
When type is SESSION_TRACK_TYPE:
Position
Type
Description
An example implementation can be found in the Connector/C source tree at unittest/libmariadb/connection.c (function test_status_callback). Added in MariaDB Connector/C 3.3.2 version.
MARIADB_OPT_RPL_REGISTER_REPLICA: Specifies the host name and port that the Binlog API will report when registering this client as a replica with the connected server. When this option is set, mariadb_rpl_open() will register the client using the provided host, port, and the server ID configured via mariadb_rpl_optionsv(). The registration is visible in the output of SHOW SLAVE STATUS on the server.
Added in MariaDB Connector/C 3.3.1 version. See .
MYSQL_READ_DEFAULT_FILE: Read options from an .
MYSQL_READ_DEFAULT_GROUP: Read options from the named from an .
These options work together, according to the following rules:
if both are set to NULL, then no option files are read.
if MYSQL_READ_DEFAULT_FILE is set to an empty string (or NULL and MYSQL_READ_DEFAULT_GROUP is set) then all are read.
As defined by the , a client may prefix its first packet with a proxy protocol header. The server will parse this header and treat the IP address it contains as the client's actual IP address, rather than the address of the connecting process.
MARIADB_OPT_PROXY_HEADER: Specifies the proxy protocol header to prefix to the first packet sent to the server. The option requires two additional arguments:
a void * pointer to the header buffer, and
a size_t
Connection attributes are stored in the and Performance Schema tables.
By default, MariaDB Connector/C sends the following connection attributes to the server:
_client_name: always "libmariadb"
_client_version: version of MariaDB Connector/C
_os: operation system
_pid: process id
MYSQL_OPT_CONNECT_ATTR_DELETE: Deletes a connection attribute for the given key.
MYSQL_OPT_CONNECT_ATTR_ADD: Adds a key/value pair to connection attributes.
MYSQL_OPT_CONNECT_ATTR_RESET: Clears the current list of connection attributes.
Note: When multiple option files are used, init_command entries are aggregated from all files read (for example, /etc/my.cnf and ~/.my.cnf). The resulting combined list of statements executes on every connection and reconnection, without any clear indication that they originated from different sources. If unexpected statements run during a connection, review all active option files to identify their source.
MYSQL_OPT_CONNECT_TIMEOUT: Connect timeout in seconds. This value will be passed as an unsigned int parameter.
unsigned int timeout= 5;
mysql_optionsv(mysql, MYSQL_OPT_CONNECT_TIMEOUT, (void *)&timeout);
MYSQL_PROGRESS_CALLBACK: Specifies a callback function which will be able to visualize the progress of certain long running statements (i.e. or ).
MYSQL_OPT_NONBLOCK: Specify stack size for non-blocking operations.
The argument for MYSQL_OPT_NONBLOCK is the size of the stack used to save the state of a non-blocking operation while it is waiting for I/O and the application is doing other processing. Normally, applications will not have to change this, and it can be passed as zero to use the default value.
mysql_optionsv(mysql, MYSQL_OPT_NONBLOCK, 0);
MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS: If this option is set, the client indicates that it will be able to handle expired passwords by setting the CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS capability flag.
If the password has expired and CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS is set, the server will not return an error when connecting, but put the connection in sandbox mode, where all commands will return error 1820 (ER_MUST_CHANGE_PASSWORD) unless a new password was set. This option was added in MariaDB Connector/C 3.0.4
MYSQL_OPT_PROTOCOL: Specify the type of client/server protocol. Possible values are:
MYSQL_PROTOCOL_TCP
MYSQL_PROTOCOL_SOCKET
MYSQL_PROTOCOL_PIPE
MYSQL_PROTOCOL_MEMORY.
MARIADB_OPT_FOUND_ROWS: Return the number of matched rows instead of number of changed rows.
mysql_optionsv(mysql, MARIADB_OPT_FOUND_ROWS, 1);
MYSQL_OPT_COMPRESS: Use the compressed protocol for client server communication. If the server doesn't support compressed protocol, the default protocol will be used.
mysql_optionsv(mysql, MYSQL_OPT_COMPRESS, NULL);
MYSQL_OPT_ZSTD_COMPRESSION_LEVEL: The compression level to use for connections that use the zstd compression algorithm. Acceptable values are integers in the range 1 (fastest) to 22 (maximum compression). This option has no effect if zstd compression is not in use. Added in MariaDB Connector/C 3.3.14 and 3.4.4 versions.
MYSQL_OPT_LOCAL_INFILE: Enable or disable the use of
MARIADB_OPT_MULTI_RESULTS: Indicates that the client is able to handle multiple result sets from stored procedures or multi statements. This option will be automatically set if MARIADB_OPT_MULTI_STATEMENTS is set.
MYSQL_SHARED_MEMORY_BASE_NAME: Shared-memory name to use for Windows connections using shared memory to a local server (started with the --shared-memory option). Case-sensitive.
MYSQL_OPT_SSL_CA: 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_OPT_SSL_CAPATH: 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 openssl rehash 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.
MYSQL_OPT_SSL_CRL: 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.
MYSQL_OPT_SSL_CRLPATH: 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 openssl rehash 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.
MARIADB_OPT_SSL_FP: Specify the fingerprint hash of a server certificate for validation during the handshake. Before version 3.4.0, Connector/C accepted only SHA1 hashes. Starting with version 3.4.0, support was extended to include SHA256, SHA384, and SHA512. This option is deprecated. Use MARIADB_OPT_TLS_PEER_FP instead.
MARIADB_OPT_SSL_FP_LIST: Specify a file containing one or more fingerprint hashes of server certificates for validation during the handshake. Before version 3.4.0, Connector/C accepted only SHA1 hashes. Starting with version 3.4.0, support was extended to include SHA256, SHA384, and SHA512. This is deprecated. Use MARIADB_OPT_TLS_PEER_FP_LIST instead.
MARIADB_OPT_TLS_PASSPHRASE: Specify a passphrase for a passphrase-protected private key, as configured by the MYSQL_OPT_SSL_KEY 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.
MARIADB_OPT_TLS_VERSION: 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.
Note: Despite the option name, this does not enforce TLS. If the server does not support TLS, the connection falls back to unencrypted communication without error. To prevent fallback and enforce TLS, use MYSQL_OPT_SSL_VERIFY_SERVER_CERT instead.
MARIADB_OPT_TLS_CIPHER_STRENGTH: Deprecated. This option is no longer in use and has no effect. Cipher strength. This value will be passed as an unsigned int parameter.
unsigned int cipher_strength= 128;
mysql_optionsv(mysql, MARIADB_OPT_TLS_CIPHER_STRENGTH, (void*)&cipher_strength);
MARIADB_OPT_CONNECTION_HANDLER: Specify the name of a connection handler plugin.
MARIADB_OPT_RESTRICTED_AUTH: Specifies a comma-separated list of authentication plugins that are permitted for authenticating this connection. If the server requests an authentication plugin that is not in this list, MariaDB Connector/C returns an error and the connection is refused. This option can be used to prevent the use of weaker authentication methods.
Added in MariaDB Connector/C 3.3.0 version.
c mysql_optionsv(mysql, MARIADB_OPT_RESTRICTED_AUTH, (void *)"ed25519,caching_sha2_password");
MARIADB_OPT_USERDATA: Bundle user data to the current connection, e.g. for use in connection handler plugins. This option requires 4 parameters: connection, option, key and value.
MARIADB_OPT_CONNECTION_READ_ONLY: This option is used by connection handler plugins and indicates that the current connection will be used for read operations only.
MARIADB_OPT_SKIP_READ_RESPONSE: Disables server response packet reading in the binary protocol. Designed for specialized connection handlers, not for typical application use. Added in Connector/C 3.1.13 version.
MYSQL_PLUGIN_DIR: Specify the location of client plugins. The plugin directory can also be specified with the MARIADB_PLUGIN_DIR environment variable.
MYSQL_SECURE_AUTH: Refuse to connect to the server if the server uses the authentication plugin. This mode is off by default, which is a difference in behavior compared to MySQL 5.6 and later, where it is on by default.
mysql_optionsv(mysql, MYSQL_SECURE_AUTH, 1);
MYSQL_SERVER_PUBLIC_KEY: 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. It was introduced in Connector/C 3.1.0.
If track_type is SESSION_TRACK_SYSTEM_VARIABLES: the variable value.
if MYSQL_READ_DEFAULT_FILE is set to a non-empty string, then it is interpreted as a path to a custom option file, and only that option file is read.
if MYSQL_READ_DEFAULT_GROUP is an empty string (or NULL and MYSQL_READ_DEFAULT_FILE is set) then only default groups — [client], [client-server], [client-mariadb] are read.
if MYSQL_READ_DEFAULT_GROUP is a non-empty string, then it is interpreted as a custom option group, and that custom option group is read in addition to default groups from above.
value for the buffer length.
_platform: e.g. x86 or x64
_server_host: the hostname (as specified in mysql_real_connect). This attribute was added in Connector/C 3.0.5
When a status callback is registered, the connector’s built‑in session tracking functions are disabled. After calling mysql_optionsv() with MARIADB_OPT_STATUS_CALLBACK, the functions mysql_session_track_get_first() and mysql_session_track_get_next() will no longer provide session tracking data. Instead, all session tracking must be managed within the callback itself.
Replication/Binlog API Options
Option File Options
Proxy Settings
Connection Attribute Options
If the is disabled, connection attributes will not be stored on server.
MariaDB Connector/C reads connection settings from option files such as my.cnf, supporting default and custom file locations, option groups, and a full set of client options.
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:
MYSQL_READ_DEFAULT_FILE is exclusive: if the application calls it more than once, the second call replaces the value set by the first. To read both a custom option file and the default option files, pass the custom file path in a single call; reading default files is controlled separately via MYSQL_READ_DEFAULT_GROUP.
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
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.
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.
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.
The syntax of the MariaDB option files are:
Lines starting with
Empty lines are ignored.
Option groups use the syntax [group-name]. See the section below for more information on available 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:
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.
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:
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.
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 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.
MariaDB Connector/C options can be set in client .
Underscores (_) in option names are treated the same as dashes (-) for MariaDB Connector/C. See for more information.
Unlike with the server, the loose prefix has no meaning for MariaDB Connector/C. Unknown options will simply be ignored.
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.
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
character-sets-dir
Description: Directory for files.
mysql_optionsv: MYSQL_SET_CHARSET_DIR
Data Type: string
compress
Description: Compress all information sent between the client and the server if both support compression.
mysql_optionsv: MYSQL_OPT_COMPRESS
Data Type: boolean
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
database
Description: Database to use.
mysql_optionsv: MARIADB_OPT_SCHEMA
Data Type: string
debug
Description:
mysql_optionsv: MARIADB_OPT_DEBUG
Data Type: string
default-auth
Description: Default authentication client-side plugin to use.
mysql_optionsv: MYSQL_DEFAULT_AUTH
Data Type: string
default-character-set
Description: Specify the default for the connection.
mysql_optionsv: MYSQL_SET_CHARSET_NAME
Data Type: string
disable-local-infile
Description: Disable the use of .
mysql_optionsv: N/A
Data Type: string
host
Description: Hostname or IP address of the server to connect to.
mysql_optionsv: MARIADB_OPT_HOST
Data Type: string
interactive-timeout
Description:
mysql_optionsv: MARIADB_OPT_INTERACTIVE
Data Type: none
init-command
Description: Command(s) which will be executed when connecting and reconnecting to the server.
mysql_optionsv: MYSQL_INIT_COMMAND
Data Type: string
local-infile
Description: Enable or disable the use of .
mysql_optionsv: MYSQL_OPT_LOCAL_INFILE
Data Type: boolean
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
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: boolean
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: boolean
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
password
Description: Password of the user to login to the server.
mysql_optionsv: MARIADB_OPT_PASSWORD
Data Type: string
pipe
Description: For Windows operating systems only: Use named pipes for client/server communication.
mysql_optionsv: MYSQL_OPT_NAMED_PIPE
Data Type: boolean
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
protocol
Description: Specify the type of client/server protocol. Possible values are:
0 - Refers to MYSQL_PROTOCOL_DEFAULT
1
reconnect
Description: Enable or disable automatic reconnect.
mysql_optionsv: MYSQL_OPT_RECONNECT
Data Type: boolean
report-data-truncation
Description: Enable or disable reporting data truncation errors for prepared statements.
mysql_optionsv: MYSQL_REPORT_DATA_TRUNCATION
Data Type: boolean
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
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
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
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
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
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
ssl-fp
Description: Description: Specify the fingerprint hash of a server certificate for validation during the handshake. handshake. In Connector/C versions prior to 3.4.0, only SHA1 hashes are accepted. From version 3.4.0 onward, SHA256, SHA384, and SHA512 hashes are also supported.
mysql_optionsv: MARIADB_OPT_SSL_FP
ssl-fp-list, ssl-fplist
Description: Description: Specify a file which contains one or more fingerprint hashes of server certificates for validation during the handshake. In Connector/C versions prior to 3.4.0, only SHA1 hashes are accepted. From version 3.4.0 onward, SHA256, SHA384, and SHA512 hashes are also supported.
mysql_optionsv: MARIADB_OPT_SSL_FP_LIST
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
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_HOME is the containing the path to the directory holding the server-specific my.cnf file.
The same option group can appear multiple times.
The !include directive can be used to include other option files. See the Including Option Files section below for more information on this syntax.
Unlike with the server, the !includedir directive does not include all .cnf files (and potentially .ini files) in a given directory. Instead, it reads the my.cnf and (potentially the my.ini) in the given directory. See CONC-396 for more information. See the Including Option File Directories section below for more information on this syntax.
Dashes (-) and underscores (_) in options are interchangeable in MariaDB Connector C 3.1.1 and later. In versions before that, options must be specified exactly as they are defined. See CONC-395 for more information.
MariaDB Connector/C does not support the that are supported by MariaDB Server. See CONC-415 for more information.
See the Options section below for information about available options.
Read this extra option file after all other option files are read.
[client]
Options read by all MariaDB and MySQL client programs, which includes both MariaDB and MySQL clients. For example, mysqldump.
[client-server]
Options read by all MariaDB client programs and the MariaDB Server. This is useful for options like socket and port, which is common between the server and the clients.
Read options from option files, print all option values, and then exit the program.
mysqldump --print-defaults
mysqldump would have been started with the following arguments:
--ssl_cert=/etc/my.cnf.d/certificates/client-cert.pem --ssl_key=/etc/my.cnf.d/certificates/client-key.pem --ssl_ca=/etc/my.cnf.d/certificates/ca.pem --ssl-verify-server-cert --max_allowed_packet=1GB
Environment variable precedence: If the $MARIADB_HOME environment variable is set, MariaDB Connector/C reads $MARIADB_HOME/my.cnf and ignores $MYSQL_HOME entirely. Only if $MARIADB_HOME is not set will the connector fall back to $MYSQL_HOME/my.cnf. If neither variable is set, this location is skipped.
$HOME and the ~/.my.cnf path: If $HOME is unset in the shell environment, the connector will not locate ~/.my.cnf and will silently skip it without returning an error.
Default Option File Locations on Windows
Environment variable precedence: If the %MARIADB_HOME% environment variable is set, MariaDB Connector/C reads %MARIADB_HOME%\my.ini (or %MARIADB_HOME%\my.cnf) and ignores %MYSQL_HOME% entirely. Only if %MARIADB_HOME% is not set will the connector fall back to %MYSQL_HOME%.
Default Option File Hierarchy
Custom Option File Locations
Option File Syntax
Option Groups
Custom Option Groups
MYSQL_READ_DEFAULT_GROUP is an exclusive option: calling it more than once replaces the previously specified custom group name. Only one non‑default group can be defined in this way. Options are applied in the order their [group] sections appear in the option file, with a later section's values overriding earlier ones — the custom group does not have inherent precedence over the built‑in default groups ([client], [client-server], [client-mariadb]); its effect depends on where its section appears relative to theirs. Passing an empty string causes only the default groups to be read, with no custom group applied:
MySQL compatibility note: MySQL Connector/C recognizes only [client] as a default group. To ensure option files work with both connectors, place shared settings in [client] and MariaDB‑specific settings in [client-mariadb]. A MySQL connector ignores [client-mariadb], while a MariaDB connector reads [client] first and then applies overrides from [client-mariadb].
Including Option Files
Including Option File Directories
Checking Program Options
Numeric suffixes such as K, M, or G are not supported in option file values. The connector reads only the numeric portion and silently discards any trailing non‑numeric characters. Always specify byte counts as plain integer values in option files.
MySQL 5.6 Obfuscated Authentication Credential Option File
Options
Custom Options
Default Options
Unlike most options, init-command is a multi-element option. Each occurrence in an option file appends the statement to an internal list rather than replacing the previous value. If init-command is specified in both /etc/my.cnf and ~/.my.cnf, all statements will execute on each connect and reconnect, in an unspecified order. Remember to use this option with caution, especially when multiple option files are in use, as statements defined in system‑wide files may not be visible when editing user‑level files.