1 of 100

Connectors

MariaDB Connectors

Explore documentation for MariaDB Connectors. Learn about official client libraries for various programming languages (e.g., C, Java, Python, ODBC) to enable seamless application connectivity.

Quickstart Guides

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.

MariaDB Connector/C++ Guide

Quickstart Guide for Connector/C++

MariaDB Connector/C++ Quickstart Guide

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:

Next Steps

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.

Erlang Guide

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

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.

b. Execute Query:

Erlang

c. Close Connection:

Erlang

Further Resources:

Connector/ODBC Guide

Quickstart guide for MariaDB Connector/ODBC

Quickstart Guide: 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.

1. What is ODBC?

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.

2. Installation

Installation typically involves downloading the appropriate driver package for your operating system and configuring a Data Source Name (DSN).

a. Windows:

Download: Go to the MariaDB Connector/ODBC Downloads page and download the appropriate .msi installer for your Windows version (32-bit or 64-bit).
Run Installer: Execute the downloaded .msi file and follow the on-screen instructions. This will install the necessary driver files.
Configure DSN:
- Open the ODBC Data Source Administrator:
  - For 64-bit systems, search for "ODBC Data Sources (64-bit)".
  - For 32-bit systems, search for "ODBC Data Sources (32-bit)".
- Go to the "User DSN" or "System DSN" tab (System DSN is generally preferred for broader application access).
- Click "Add...".
- Select "MariaDB ODBC Driver" (or "MariaDB ODBC 3.1 Driver" depending on the version) from the list and click "Finish".
- A configuration dialog will appear. Fill in the details:
  - Data Source Name: A descriptive name for your DSN (e.g., MyMariaDBDSN).
  - TCP/IP Server: localhost or the IP address/hostname of your MariaDB server.
  - Port: 3306 (default MariaDB port).
  - User: Your database username.
  - Password: Your database password.
  - Database: The specific database you want to connect to.
- Click "Test" to verify the connection. Click "OK" to save the DSN.

b. Linux / macOS:

Download: Download the appropriate .deb, .rpm, or .pkg package from the MariaDB Connector/ODBC Downloads page.
Install Package:
- Debian/Ubuntu: sudo dpkg -i mariadb-connector-odbc_X.Y.Z.deb
- 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).
You need to create or modify ~/.odbc.ini (for user DSNs) or /etc/odbc.ini (for system DSNs) to define your data source.

Example odbcinst.ini (Driver Definition - usually installed automatically):

[MariaDB ODBC Driver]
Description = MariaDB Connector/ODBC
Driver = /usr/lib/x86_64-linux-gnu/odbc/libmaodbc.so # Adjust path for your system
Setup = /usr/lib/x86_64-linux-gnu/odbc/libmaodbc.so # Adjust path for your system
UsageCount = 1
FileUsage = 1
CPTimeout =
CPReconnect =

Example odbc.ini (DSN Definition):

[MyMariaDBDSN]
Description = My MariaDB Database
Driver = MariaDB ODBC Driver # Matches the name from odbcinst.ini
SERVER = localhost
PORT = 3306
DATABASE = your_database_name
UID = your_username
PASSWORD = your_password
OPTION =

Test DSN (Optional): You can use isql (from unixodbc-dev or unixodbc package) to test your DSN:
```
isql MyMariaDBDSN your_username your_password
```

3. Basic Usage (Connecting from Applications)

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.

Driver={MariaDB ODBC Driver};Server=localhost;Port=3306;Database=your_database_name;Uid=your_username;Pwd=your_password;

Replace {MariaDB ODBC Driver} with the exact driver name from your odbcinst.ini if different.

Further Resources:

Connector/Ruby Guide

Quickstart guide for Connector/Ruby

Quickstart Guide: MariaDB Connector/Ruby (using `mysql2` gem)

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.

1. Overview

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 rubygems.org/gems/mysql2.

2. Installation

Before installing the mysql2 gem, you might need to install development libraries for MariaDB Connector/C or MySQL Client on your system.

a. Install System Dependencies (e.g., on Debian/Ubuntu):

sudo apt update
sudo apt install libmariadb-dev # Or libmysqlclient-dev

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:

# If using Bundler (e.g., in a Rails project's Gemfile)
# Gemfile
# gem 'mysql2'
bundle install

# Or directly
gem install mysql2

3. Basic Usage

Here's how to connect to MariaDB and perform common database operations using the mysql2 gem:

a. Connect to the Database:

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

Replace localhost, 3306, your_username, your_password, and your_database_name with your actual database details.

b. Execute a SELECT Query:

# 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

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.

# 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}"

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.

# 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 }

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.

Important Notes:

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.

Further Resources:

Connector/C

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

MariaDB Binlog/Replication API reference

These are currently documented on the .

MariaDB Connector/C Plugins

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

connection plugins

aurora

replication

pvio plugins

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

socket

npipe

shmem

io plugins

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

remote_io

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

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

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

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

auth plugins

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

mysql_native_password

dialog

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

client_ed25519

caching_sha2_password

sha256_password

auth_gssapi_client

mysql_old_password

mysql_clear_password

Compiling Connector/C

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

Compiling on Windows

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

or via command line

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

Prerequisites For Building Connector/C From Source

Windows

Visual Studio 2013 or newer (older versions of Visual Studio may also work but have not been tested).
cmake 2.8.12 or newer, available from the CMake website.
for Connector/C 2.x: OpenSSL libraries and include files.
for Connector/C 3.0 remote-io plugin: 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 or newer
cmake 2.8.12 or newer, available from the CMake website.
for Connector/C 3.0 remote-io plugin: Curl libraries and include files
For GSSAPI plugin: Kerberos V5 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.

MariaDB Connector/C API Functions

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

mariadb_cancel

Syntax

int mariadb_cancel(MYSQL * mysql);

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

Description

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

mariadb_cancel() was added in Connector/C 3.0

mariadb_get_infov

Syntax

int mariadb_get_infov(MYSQL * mysql,
                      enum mariadb_value value,
                      void * arg,
                      ...);

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect(). 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.
arg - pointer to a variable for storing value of the specified option.
... - variable argument list

Description

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,

Value types

Generic information

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 capability flags of the connected MariaDB server.Parameter type: unsigned long.
MARIADB_CONNECTION_HOST: Retrieves connection's host name. Parameter type: const char *.
MARIADB_CONNECTION_INFO: Retrieves generic info for last used command.Parameter type: const char *.
MARIADB_CONNECTION_PORT: Retrieves the port number of server host.Parameter type: unsigned int.
MARIADB_CONNECTION_PROTOCOL_VERSION_ID: Retrieves the protocol version number.Parameter type: unsigned int.
MARIADB_CONNECTION_PVIO_TYPE: Retrives the pvio plugin used for specified connection.Parameter type: unsigned int.
MARIADB_CONNECTION_SCHEMA: Retrieves the current schema.Parameter type: const char*.
MARIADB_CONNECTION_SERVER_CAPABILITIES: Returns the capability flags 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 *.

Examples

/* 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);

mariadb_reconnect

Syntax

my_bool  mariadb_reconnect(MYSQL * mysql)

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

Description

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().

The function will return 0 on sucess.

The function will return an error, if the option MYSQL_OPT_RECONNECT wasn't specified before.

This function was added in Connector/C 3.0.

mysql_affected_rows

Syntax

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

Description

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.

mysql_autocommit

Syntax

mysql - a mysql handle, identifier, which was previously allocated by or .
auto_mode - whether to turn on or not.

Description

Toggles autocommit mode on or off for the current database connection. Autocommit mode will be set if mode=1 or unset if mode=0. Returns zero on success, or nonzero if an error occurred. Parameters

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 function will not work if autocommit mode is switched on.

Turning off autocommit in sql

mysql_change_user

Syntax

my_bool mysql_change_user(MYSQL * mysql,
                          const char * user,
                          const char * passwd,
                          const char * db);

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
user - the user name for server authentication
passwd - the password for server authentication
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 mysql_select_db() function.

Description

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

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_character_set_name

Syntax

const char * mysql_character_set_name(MYSQL * mysql);

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

Description

Returns the default client for the specified connection.

mysql_close

Syntax

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

Description

Closes a previously opened connection.

mysql_commit

Syntax

my_bool mysql_commit(MYSQL * mysql);

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

Description

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

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

mysql_data_seek

Syntax

void mysql_data_seek(MYSQL_RES * result,
                     my_ulonglong offset);

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

Description

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

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

mysql_dump_debug_info

Syntax

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

Description

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.

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.

mysql_errno

Syntax

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

Description

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_error

Syntax

const char * mysql_error(MYSQL * mysql);

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

Description

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

mysql_escape_string

Syntax

Description

Escapes a string using the default character set.

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

mysql_fetch_field

Syntax

result - a result set identifier returned by or .

Description

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

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

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

mysql_fetch_field_direct

Syntax

res - a result set identifier returned by or .
fieldnr - 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.

The total number of fields can be obtained by mysql_field_count()

mysql_fetch_fields

Syntax

res - a result set identifier returned by or .

Description

This function serves an identical purpose to the 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.

The total number of fields can be obtained by .

mysql_fetch_lengths

Syntax

result - a result set identifier returned by or .

Description

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

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

mysql_fetch_row

Syntax

result - a result set identifier returned by or .

Description

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

mysql_field_count

Syntax

unsigned int mysql_field_count(MYSQL * mysql);

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

Description

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.

The mysql_field_count() function should be used to determine if there is a result set available.

mysql_field_seek

Syntax

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES * result,
                                    MYSQL_FIELD_OFFSET offset);

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

Description

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

Returns the previous value of the field cursor.

The number of fields can be obtained from mysql_field_count().

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

mysql_field_tell

Syntax

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES * result);

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

Description

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().

Returns the current offset of the field cursor

mysql_free_result

Syntax

void mysql_free_result(MYSQL_RES * result);

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

Description

Frees the memory associated with a result set. Returns void.

You should always free your result set with mysql_free_result() as soon it's not needed anymore

Row values obtained by a prior mysql_fetch_row() call will become invalid after calling mysql_free_result().

mysql_get_character_set_info

Syntax

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

Description

Returns information about the current default for the specified connection.

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

mysql_get_client_info

Syntax

Description

Returns a string representing the client library version

To obtain the numeric value of the client library version use .

mysql_get_client_version

Syntax

unsigned long mysql_get_client_version(void);

Description

Returns a number representing the client library version.

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

mysql_get_host_info

Syntax

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

Description

Describes the type of connection in use for the connection, including the server host name. Returns a string, or NULL if the connection is not valid.

mysql_get_proto_info

Syntax

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

Description

Returns the protocol version number for the specified connection

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

mysql_get_server_info

Syntax

const char * mysql_get_server_info(MYSQL * mysql);

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

Description

Returns the server version or NULL on failure.

To obtain the numeric server version please use mysql_get_server_version().

mysql_get_server_version

Syntax

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

Description

Returns an integer representing the version of connected server.

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

mysql_get_ssl_cipher

Syntax

const char *mysql_get_ssl_cipher(MYSQL *mysql)

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

Description

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

mysql_hex_string

Syntax

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

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

Description

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

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

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

The encoded string does not contain a leading X'.

mysql_init

Syntax

MYSQL * mysql_init(MYSQL * mysql);

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.

Description

Prepares and initializes a MYSQL structure to be used with mysql_real_connect().

If mysql_thread_init() was not called before, mysql_init() will also initialize the thread subsystem for the current thread.

Members of the MYSQL structure are not intended for application use.

Any subsequent calls to any mysql function (except mysql_options()) will fail until mysql_real_connect() was called.

Memory allocated by mysql_init() must be freed with mysql_close().

mysql_insert_id

Syntax

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

Description

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.

When performing a multi-insert statement, mysql_insert_id() will return the value of the first row.

mysql_library_end

Syntax

void mysql_library_end(void)

Description

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

mysql_server_end() is an alias.

mysql_library_init

Syntax

Description

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

Call to clean up after completion.

mysql_server_init() is an alias.

mysql_more_results

Syntax

my_bool mysql_more_results(MYSQL * mysql);

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

Description

Indicates if one or more result sets are available from a previous call to mysql_real_query(). Returns 1 if more result sets are available, otherwise zero. .

The function mysql_set_server_option() enables or disables multi statement support.

mysql_next_result

Syntax

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

Description

Prepares next result set from a previous call to which can be retrieved by or . Returns zero on success, nonzero if an error occurred.

If a multi query contains errors the return value of /error() might change and there will be no result set available.

mysql_num_fields

Syntax

unsigned int mysql_num_fields(MYSQL_RES * );

MYSQL RES * - A result set identifier returned by mysql_store_result() or mysql_use_result().

Description

Returns number of fields in a specified result set.

mysql_num_rows

Syntax

my_ulonglong mysql_num_rows(MYSQL_RES * );

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

Description

Returns number of rows in a result set.

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 correbct number of rows until all the rows in the result have been retrieved.

mysql_options

Syntax

mysql - a mysql handle, which was previously allocated by or .
mysql_option - the option you want to set. See description below.
arg - the value for the option.

Description

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

This function is deprecated as of MariaDB Connector/C 3.0 and will be removed in future releases. It's preferable to use .

Options

See .

mysql_ping

Syntax

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

Description

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.

Returns zero on success, nonzero if an error occured.

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.

If a reconnect occurred the thread_id will change. Also resources bundled to the connection (prepared statements, locks, temporary tables, ...) will be released.

mysql_query

Syntax

int mysql_query(MYSQL * mysql,
                const char * query);

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
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.

Returns zero on success, non zero on failure

For executing multi statements the statements within the null terminated string statements must be separated by a semicolon.

If your statement contains binary data you should use mysql_real_query() or escape your data with mysql_hex_string().

To determine if a statement returned a result set use the function mysql_num_fields().

mysql_read_query_result

Syntax

int mysql_read_query_result(MYSQL * mysql);

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

Returns zero on success, otherwise non-zero.

Description

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

mysql_real_escape_string

Syntax

mysql - a MySQL handle, which was previously allocated by or .
to - buffer for the encoded string. The size of this buffer must be length * 2 + 1 bytes: in the worst case every character of the from string needs to be escaped. Additionally, a trailing 0 character will be appended.
from - a string which will be encoded by mysql_real_escape_string().
long - the length of the from string.

Description

This function is used to create a legal SQL string that you can use in an SQL statement. The given string is encoded to an escaped SQL string, taking into account the current character set of the connection.

Returns the length of the encoded (to) string.

mysql_real_query

Syntax

mysql - a mysql handle, which was previously allocated by or .
query - a string containing the statement to be performed.
long - length of the string.

Description

mysql_real_query() is a binary-safe function for executing a statement on the database server. Returns zero on success, otherwise non-zero.

Contrary to the function, mysql_real_query is binary safe.

To determine if mysql_real_query returns a result set, use the function.

mysql_refresh

Syntax

int mysql_refresh(MYSQL * mysql,
  unsigned int options);

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
options - a bit masked composed integer. See below.

Description

Flushes different types of information stored on the server. The bit-masked parameter options specify which kind of information will be flushed. options can be any combination of the following:

Option

Description

REFRESH_GRANT

Refresh grant tables.

REFRESH_LOG

Flush logs.

REFRESH_TABLES

Flush table cache.

REFRESH_HOSTS

Flush host cache.

REFRESH_STATUS

Reset status variables.

REFRESH_THREADS

Flush thread cache.

REFRESH_SLAVE

Reset master server information and restart slaves.

REFRESH_MASTER

Remove binary log files.

REFRESH_READ_LOCK

REFRESH_FAST

Returns zero on success, otherwise nonzero.

To combine different values in the options parameter, use the OR operator '|'. The function mysql_reload() is an alias for mysql_refresh().

mysql_reset_connection

Syntax

int mysql_reset_connection(MYSQL * mysql);

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

Description

Resets the current connection and clears session state. Similar to mysql_change_user() or mariadb_reconnect(), mysql_reset_connection() resets session status, but without disconnecting, opening, or reauthenticating.

On client side mysql_reset_connection()

clears pending or unprocessed result sets
clears status like affected_rows, info or last_insert_id
invalidates active prepared statements

On server side mysql_reset_connection()

drops temporary table(s)
rollbacks active transaction
resets auto commit mode
releases table locks
initializes session variables (and sets them to the value of corresponding global variables)
closes active prepared statements
clears user variables

Returns zero on success, non-zero if an error occurred.

This function was added in MariaDB Connector/C 3.0.0.

mysql_rollback

Syntax

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

Description

Rolls back the current transaction for the database. Returns zero on success, nonzero if an error occurred.

mysql_rollback() will not work as expected if mode was set or the storage engine does not support transactions.

mysql_row_seek

Syntax

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

Description

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

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

mysql_row_tell

Syntax

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES * res);

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

Description

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

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

mysql_select_db

Syntax

mysql - a mysql handle, which was previously allocated by or .
db - the default database name

Description

Selects a database as default. Returns zero on success, non-zero on failure

The SQL command will return the name of the default database.

The default database can also be set by the db parameter in .

mysql_send_query

Syntax

mysql - a mysql handle, which was previously allocated by or .
query - the query to execute.
length - length of query.

Returns zero on success, otherwise non-zero.

Description

mysql_send_query() executes a SQL statement without waiting for the result. The main purpose of this function is to perform batch execution of DML statements.

Each successful call tomysql_send_query() must be followed by a call to . Multiple calls to mysql_send_query() can be made before the calls to are done.

mysql_server_end

Syntax

Description

mysql_server_end() is an alias for .

mysql_server_init

Syntax

Description

mysql_server_init() is an alias for .

mysql_session_track_get_first

Syntax

int mysql_session_track_get_first(MYSQL * mysql,enum enum_session_state_type type, const char **data, size_t *length );

mysql - mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
type - type of information. Valid values are
- SESSION_TRACK_SYSTEM_VARIABLES
- SESSION_TRACK_SCHEMA
- SESSION_TRACK_STATE_CHANGE
- SESSION_TRACK_GTIDS (unsupported)
data - pointer to data, which must be declared as const char *
length - pointer to a size_t variable, which will contain the length of data

Description

mysql_session_track_get_first() retrieves the first session status change information received from the server.

Depending on the specified type the read only data pointer will contain the following information:

SESSION_TRACK_SCHEMA: The name of the default schema (database)
SESSION_TRACK_SYSTEM_VARIABLES: If a session system variable is changed, the first call contains the name of the changed system variable, the second call contains the new value. Both name and value are represented as strings.
SESSION_TRACK_STATE_CHANGE: shows whether the session status has changed. The value is changed as string "1" (changed) or "0" (unchanged).

Further data needs to be obtained by calling mysql_session_track_get_next().

mysql_session_track_get_first() was added in Connector/C 3.0 and MariaDB Server 10.2.

Returns

Zero for success, nonzero if an error occurred.

mysql_session_track_get_next

Syntax

mysql - mysql handle, which was previously allocated by or .
type - type of information. Valid values are
- SESSION_TRACK_SYSTEM_VARIABLES
- SESSION_TRACK_SCHEMA
- SESSION_TRACK_STATE_CHANGE
- SESSION_TRACK_GTIDS (unsupported)
data - pointer to data, which must be declared as const char *
length - pointer to a size_t variable, which will contain the length of data

Description

mysql_session_track_get_next() retrieves the session status change information received from the server after a successful call to .

mysql_session_track_get_next() needs to be called repeatedly until a non-zero return value indicates the end of data.

mysql_session_track_get_next() was added in Connector/C 3.0 and MariaDB Server 10.2.

Returns

Zero for success, nonzero if an error occurred.

mysql_set_server_option

Syntax

mysql - a mysql handle, which was previously allocated by or .
enum_mysql_set_option - server option (see below)

Description

Server option, which can be one of the following values:

Option

Description

Returns zero on success, non-zero on failure.

mysql_shutdown

Syntax

mysql - a mysql handle, which was previously allocated by or .
mysql_enum_shutdown_level - currently only one shutdown level, SHUTDOWN_DEFAULT is supported.

Description

Sends a shutdown message to the server. To shut down the database server, the user for the current connection must have SHUTDOWN privileges.

Returns zero on success, non-zero on failure.

mysql_sqlstate

Syntax

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

Description

Returns a string containing the error code for the most recently invoked function that can succeed or fail. The error code consists of five characters. '00000' means no error. The values are specified by ANSI SQL and ODBC

Please note that not all client library error codes are mapped to SQLSTATE errors. Errors which can't be mapped will be returned as value HY000.

mysql_stat

Syntax

const char * mysql_stat(MYSQL * mysql);

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

Description

mysql_stat() returns a string with the current server status for uptime, threads, queries, open tables, flush tables and queries per second.

For a complete list of other status variables, you have to use the SQL command.

mysql_store_result

Syntax

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

Description

Returns a buffered result set from the last executed query.

mysql_store_result() returns NULL in case an error occurred or if the query didn't return data (e.g. when executing an or query.

indicates if there will be a result set available.

The memory allocated by mysql_store_result() needs to be released by calling the function .

mysql_thread_end

Syntax

Description

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

Unlike mysql_thread_end() will not be invoked automatically if the thread ends. To avoid memory leaks mysql_thread_end() must be called explicitly.

mysql_thread_id

Syntax

unsigned long mysql_thread_id(MYSQL * mysql);

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

Description

The mysql_thread_id() function returns the thread id for the current connection.

The current connection can be killed with mysql_kill(). If reconnect option is enabled the thread id might change if the client reconnects to the server.

Note that connector will return only the first 32connectionsbits value. If your database might expect to create more than 4.3 billion connections without a restart, it's better to query 'select CONNECTION_ID()'

mysql_thread_init

Syntax

Description

Thread initialization for multi-threaded clients. Multi-threaded clients should call mysql_thread_init() at the beginning of the thread initialization to initialize thread specific client library variables. If _{mysql_thread_init()} was not called explicitly, it will be called automatically by or .

Returns zero if successful or 1 if an error occurred.

Before a client thread ends the function must be called to release memory - otherwise the client library will report an error.

mysql_thread_safe

Syntax

unsigned int mysql_thread_safe(void );

Description

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

By default the mariadb client library is compiled as thread safe.

MariaDB Connector/C Types and Definitions

MariaDB Connector/C provides the following types and definitions.

Enumeration Types

enum mysql_option

enum mysql_option is used as a parameter in mysql_optionsv() and mysql_get_optionsv() API functions. For a list of integral constants and their meanings, please check the documentation of mysql_get_optionsv().

enum enum_mysql_timestamp_type

enum enum_mysql_timestamp_type is used in the MYSQL_TIME structure and indicates the type. It has the following constants:

MYSQL_TIMESTAMP_NONE
MYSQL_TIMESTAMP_ERROR
MYSQL_TIMESTAMP_DATE
MYSQL_TIMESTAMP_DATETIME
MYSQL_TIMESTAMP_TIME

enum mysql_set_option

enum mysql_set_option is used as a parameter in mysql_set_server_option() and has the following constants:

MYSQL_OPTIONS_MULTI_STATEMENTS_ON
MYSQL_OPTIONS_MULTI_STATEMENTS_OFF

enum enum_field_types

enum field_types describes the different field types used by MariaDB and has the following constants:

MYSQL_TYPE_DECIMAL
MYSQL_TYPE_TINY
MYSQL_TYPE_SHORT
MYSQL_TYPE_LONG
MYSQL_TYPE_FLOAT
MYSQL_TYPE_DOUBLE
MYSQL_TYPE_NULL
MYSQL_TYPE_TIMESTAMP
MYSQL_TYPE_LONGLONG
MYSQL_TYPE_INT24
MYSQL_TYPE_DATE
MYSQL_TYPE_TIME
MYSQL_TYPE_DATETIME
MYSQL_TYPE_YEAR
MYSQL_TYPE_NEWDATE
MYSQL_TYPE_VARCHAR
MYSQL_TYPE_BIT
MYSQL_TYPE_TIMESTAMP2
MYSQL_TYPE_DATETIME2
MYSQL_TYPE_TIME2
MYSQL_TYPE_JSON
MYSQL_TYPE_NEWDECIMAL
MYSQL_TYPE_ENUM
MYSQL_TYPE_SET
MYSQL_TYPE_TINY_BLOB
MYSQL_TYPE_MEDIUM_BLOB
MYSQL_TYPE_LONG_BLOB
MYSQL_TYPE_BLOB
MYSQL_TYPE_VAR_STRING
MYSQL_TYPE_STRING
MYSQL_TYPE_GEOMETRY

enum mysql_enum_shutdown_level

enum mysql_enum_shutdown_level is used as a parameter in mysql_server_shutdown() and has the following constants:

SHUTDOWN_DEFAULT
KILL_QUERY
KILL_CONNECTION

enum enum_stmt_attr_type

enum_stmt_attr_type is used to set different statement options. For a detailed description please check mysql_stmt_attr_set() function.

enum enum_cursor_type

enum_cursor_type specifies the cursor type and is used in mysql_stmt_attr_set() function. Currently the following constants are supported:

CURSOR_TYPE_READ_ONLY
CURSOR_TYPE_NO_CURSOR

enum enum_indicator_type

enum_indicator_type describes the type of indicator used for prepared statements bulk operations.

STMT_INDICATOR_NTS

String is zero terminated

STMT_INDICATOR_NONE

No indicator in use

STMT_INDICATOR_NULL

Value is NULL

STMT_INDICATOR_DEFAULT

Use default value

STMT_INDICATOR_IGNORE

Ignore the specified value

STMT_INDICATOR_IGNORE_ROW

Skip the current row

Definitions

Field Flags

The following field flags are used in MYSQL_FIELD structure.

Flag

Value

Description

NOT_NULL_FLAG

Field can't be NULL

PRI_KEY_FLAG

Field is part of primary key

UNIQUE_KEY_FLAG

Field is part of unique key

MULTIPLE_KEY_FLAG

Field is part of a key

BLOB_FLAG

Field is a blob

UNSIGNED_FLAG

Field is unsigned integer

ZEROFILL_FLAG

Field is zero filled

BINARY_FLAG

128

Field is binary

ENUM_FLAG

256

Field is enum

AUTO_INCREMENT_FLAG

512

Field is an autoincrement field

TIMESTAMP_FLAG

1024

Field is a timestamp

SET_FLAG

2048

Field is a set

NO_DEFAULT_VALUE_FLAG

4096

Field has no default value

ON_UPDATE_NOW_FLAG

8192

If a field is updated it will get the current time value (NOW())

NUM_FLAG

32768

Field is numeric

Server Status

The server_status can be obtained by the mariadb_get_infov() function using the MARIADB_CONNECTION_SERVER_STATUS option.

SERVER_STATUS_IN_TRANS

A transaction is currently active

SERVER_STATUS_AUTOCOMMIT

Autocommit mode is set

SERVER_MORE_RESULTS_EXISTS

more results exists (more packet follow)

SERVER_QUERY_NO_GOOD_INDEX_USED

SERVER_QUERY_NO_INDEX_USED

SERVER_STATUS_CURSOR_EXISTS

when using COM_STMT_FETCH, indicate that current cursor still has result

SERVER_STATUS_LAST_ROW_SENT

128

when using COM_STMT_FETCH, indicate that current cursor has finished to send results

SERVER_STATUS_DB_DROPPED

1<<8

database has been dropped

SERVER_STATUS_NO_BACKSLASH_ESCAPES

1<<9

current escape mode is "no backslash escape"

SERVER_STATUS_METADATA_CHANGED

1<<10

A DDL change did have an impact on an existing PREPARE (an automatic reprepare has been executed)

SERVER_QUERY_WAS_SLOW

1<<11

Last statement took more than the time value specified in server variable long_query_time.

SERVER_PS_OUT_PARAMS

1<<12

this resultset contain stored procedure output parameter

SERVER_STATUS_IN_TRANS_READONLY

1<<13

current transaction is a read-only transaction

SERVER_SESSION_STATE_CHANGED

1<<14

session state change. see Session change type for more information

Macros

IS_PRI_KEY(flag)

True if the field is part of a primary key

IS_NOT_NULL(flags)

True if the field is defined as not NULL

IS_BLOB(flags)

True if the field is a text or blob field

IS_NUM(column_type)

True if the column type is numeric

IS_LONGDATA(column_type)

True if the column is a blob or text field

mysql_optionsv

Syntax

int mysql_optionsv(MYSQL * mysql,
                   enum mysql_option,
                   const void * arg,
                   ...);

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
mysql_option - the option you want to set. See description below.
arg - the value for the option.
... - variable argument list

Description

Used to set extra connect options and affect behavior for a connection. This function may be called multiple times to set several options. mysql_optionsv() should be called after mysql_init().

Some of these options can also be set in option files, such as my.cnf.

Returns

Returns zero on success, non zero if an error occurred (invalid option or value).

Options

MYSQL_INIT_COMMAND: Command(s) which will be executed when connecting and reconnecting to the server.
```
mysql_optionsv(mysql, MYSQL_INIT_COMMAND, (void *)"CREATE TABLE ...");
```
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);
```

MARIADB_OPT_VERIFY_LOCAL_INFILE_CALLBACK: Specifies a callback function for filename and/or directory verification. This option was added in Connector/C 2.3.0

int my_verify_filename(void *data, const char *filename)
{
 return strcmp((char *)data, filename);
}
...
char *filename= "mydata.csv";
mysql_optionsv(mysql, MARIADB_OPT_VERIFY_LOCAL_INFILE_CALLBACK, my_verify_filename, (void *)filename);

MYSQL_PROGRESS_CALLBACK: Specifies a callback function which will be able to visualize the progress of certain long running statements (i.e. or ).

static void report_progress(const MYSQL *mysql __attribute__((unused)),
 uint stage, uint max_stage,
 double progress __attribute__((unused)),
 const char *proc_info __attribute__((unused)),
 uint proc_info_length __attribute__((unused)))
{
 ...
}
mysql_optionsv(mysql, MYSQL_PROGRESS_CALLBACK, (void *)report_progress);

MYSQL_OPT_RECONNECT: Enable or disable automatic reconnect.

my_bool reconnect= 1; /* enable reconnect */
mysql_optionsv(mysql, MYSQL_OPT_RECONNECT, (void *)&reconnect);

MYSQL_OPT_READ_TIMEOUT: Specifies the timeout in seconds for reading packets from the server.
```
unsigned int timeout= 5;
mysql_optionsv(mysql, MYSQL_OPT_READ_TIMEOUT, (void *)&timeout);
```
MYSQL_OPT_WRITE_TIMEOUT: Specifies the timeout in seconds for sending packets to the server.
```
unsigned int timeout= 5;
mysql_optionsv(mysql, MYSQL_OPT_WRITE_TIMEOUT, (void *)&timeout);
```

MYSQL_REPORT_DATA_TRUNCATION: Enable or disable reporting data truncation errors for prepared statements.

mysql_optionsv(mysql, MYSQL_REPORT_DATA_TRUNCATION, NULL); /* disable */
mysql_optionsv(mysql, MYSQL_REPORT_DATA_TRUNCATION, (void *)"1"); /* enable */

MYSQL_SET_CHARSET_DIR: files.

mysql_optionsv(mysql, MYSQL_SET_CHARSET_DIR, (void *)"/usr/local/mysql/share/mysql/charsets");

MYSQL_SET_CHARSET_NAME: Specify the default for the connection.
```
mysql_optionsv(mysql, MYSQL_SET_CHARSET_NAME, (void *)"utf8");
```
MYSQL_OPT_BIND: Specify the network interface from which to connect to MariaDB Server.
```
mysql_optionsv(mysql, MYSQL_OPT_BIND, (void *)"192.168.8.3");
```
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_optionsv(mysql, MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS, 1);
```
MYSQL_OPT_MAX_ALLOWED_PACKET: The maximum packet length to send to or receive from server. The default is 16MB, the maximum 1GB.
```
mysql_optionsv(mysql, MYSQL_OPT_MAX_ALLOWED_PACKET, 0x40000000);
```
MYSQL_OPT_NET_BUFFER_LENGTH: The buffer size for TCP/IP and socket communication. Default is 16KB.
```
mysql_optionsv(mysql, MYSQL_OPT_NET_BUFFER_LENGTH, 0x40000000);
```

Connection Options

Some of these options can also be set as arguments to the mysql_real_connect function.

MARIADB_OPT_HOST: Hostname or IP address of the server to connect to.
```
mysql_optionsv(mysql, MARIADB_OPT_HOST, (void *)"dbserver.example.com");
```

MARIADB_OPT_USER: User to login to the server.

mysql_optionsv(mysql, MARIADB_OPT_USER, (void *)"myuser");

MARIADB_OPT_PASSWORD: Password of the user to login to the server.
```
mysql_optionsv(mysql, MARIADB_OPT_PASSWORD, (void *)"horsebattery");
```

MARIADB_OPT_SCHEMA: Database to use.

mysql_optionsv(mysql, MARIADB_OPT_SCHEMA, (void *)"mydb");

MARIADB_OPT_PORT: Port number to use for connection.
```
mysql_optionsv(mysql, MARIADB_OPT_PORT, 3307);
```
MARIADB_OPT_UNIXSOCKET: For connections to localhost, the Unix socket file to use, or, on Windows, the name of the named pipe to use.
```
mysql_optionsv(mysql, MARIADB_OPT_UNIXSOCKET, (void *)"/var/lib/mysql/mysql.sock");
```
MYSQL_OPT_NAMED_PIPE: For Windows operating systems only: Use named pipes for client/server communication.
```
mysql_optionsv(mysql, MYSQL_OPT_NAMED_PIPE, NULL);
```
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.
  enum mysql_protocol_type prot_type= MYSQL_PROTOCOL_SOCKET; mysql_optionsv(mysql, MYSQL_OPT_PROTOCOL, (void *)&prot_type);
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_LOCAL_INFILE: Enable or disable the use of

unsigned int enable= 1, disable= 0;
mysql_optionsv(mysql, MYSQL_OPT_LOCAL_INFILE, (void *)&disable);/* disable */
mysql_optionsv(mysql, MYSQL_OPT_LOCAL_INFILE, (void *)NULL);     /* enable */
mysql_optionsv(mysql, MYSQL_OPT_LOCAL_INFILE, (void *)&enable); /* enable */

MARIADB_OPT_MULTI_STATEMENTS: Allows the client to send multiple statements in one command. Statements will be divided by a semicolon.
```
mysql_optionsv(mysql, MARIADB_OPT_MULTI_STATEMENTS, (void *)"");
```
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_optionsv(mysql, MARIADB_OPT_MULTI_RESULTS, 1);
```
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_optionsv(mysql, MYSQL_SHARED_MEMORY_BASE_NAME, (void *)"mariadb");
```

TLS Options

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_optionsv(mysql, MYSQL_OPT_SSL_KEY, (void *)"certs/client-key.pem");
```
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_optionsv(mysql, MYSQL_OPT_SSL_CERT, (void *)"certs/client-cert.pem");
```
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_optionsv(mysql, MYSQL_OPT_SSL_CA, (void *)"certs/ca-cert.pem");
```
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_optionsv(mysql, MYSQL_OPT_SSL_CAPATH, (void *)"certs/ca-cert.pem");
```
MYSQL_OPT_SSL_CIPHER: Defines a list of permitted ciphers or cipher suites to use for .
```
mysql_optionsv(mysql, MYSQL_OPT_SSL_CIPHER, (void *)"DHE-RSA-AES256-SHA");
```
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_optionsv(mysql, MYSQL_OPT_SSL_CAPATH, (void *)"certs/ca-cert.pem");\\\\<<code>>mysql_optionsv(mysql, MYSQL_OPT_SSL_CRL, (void *)"certs/crl.pem");
```
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.
```
mysql_optionsv(mysql, MYSQL_OPT_SSL_CAPATH, (void *)"certs/ca-cert.pem");\\\\<<code>>mysql_optionsv(mysql, MYSQL_OPT_SSL_CRLPATH, (void *)"certs/crls");
```
MARIADB_OPT_SSL_FP: Specify the SHA1 fingerprint of a server certificate for validation during the handshake. This is deprecated. Use MARIADB_OPT_TLS_PEER_FP instead.
```
mysql_optionsv(mysql, MARIADB_OPT_SSL_FP, (void *)"3a079e1a14ad326953a5d280f996b93d772a5bea");
```
MARIADB_OPT_TLS_PEER_FP: Specify the SHA1 fingerprint of a server certificate for validation during the handshake.
```
mysql_optionsv(mysql, MARIADB_OPT_TLS_PEER_FP, (void *)"3a079e1a14ad326953a5d280f996b93d772a5bea");
```
MARIADB_OPT_SSL_FP_LIST: Specify a file which contains one or more SHA1 fingerprints of server certificates for validation during the handshake. This is deprecated. Use MARIADB_OPT_TLS_PEER_FP_LIST instead.
```
mysql_optionsv(mysql, MARIADB_OPT_SSL_FP_LIST, (void *)"certs/fingerprints.txt");
```
MARIADB_OPT_TLS_PEER_FP_LIST: Specify a file which contains one or more SHA1 fingerprints of server certificates for validation during the handshake.
```
mysql_optionsv(mysql, MARIADB_OPT_TLS_PEER_FP_LIST, (void *)"certs/fingerprints.txt");
```
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.
```
mysql_optionsv(mysql, MARIADB_OPT_SSL_PASSPHRASE, (void *)"thisisashortpassphrase");
```
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.
```
mysql_optionsv(mysql, MARIADB_OPT_TLS_VERSION, (void *)"TLSv1.2,TLSv1.3");
```

MYSQL_OPT_SSL_VERIFY_SERVER_CERT: Enables (or disables) .

my_bool verify= 1;
mysql_optionsv(mysql, MYSQL_OPT_SSL_VERIFY_SERVER_CERT, (void *)&verify);

MYSQL_OPT_SSL_ENFORCE: Whether to force . This enables TLS with the default system settings. It does not prevent the connection from being created if the server does not support TLS.
```
my_bool enforce_tls= 1;
mysql_optionsv(mysql, MYSQL_OPT_SSL_ENFORCE, (void *)&enforce_tls);
```

MARIADB_OPT_TLS_CIPHER_STRENGTH: 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);

Plugin Options

MYSQL_DEFAULT_AUTH: Default authentication client-side plugin to use.
```
mysql_optionsv(mysql, MYSQL_DEFAULT_AUTH, (void *)"ed25519");
```
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.
```
mysql_optionsv(mysql, MYSQL_ENABLE_CLEARTEXT_PLUGIN, 1);
```
MARIADB_OPT_CONNECTION_HANDLER: Specify the name of a connection handler plugin.
```
mysql_optionsv(mysql, MARIADB_OPT_CONNECTION_HANDLER, (void *)"aurora");
```
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.
```
mysql_optionsv(mysql, MARIADB_OPT_USERDATA, (void *)"ssh_user", (void *)ssh_user);
```
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.
```
my_bool read_only= 1;
mysql_optionsv(mysql, MARIADB_OPT_CONNECTION_READ_ONLY, (void *)&read_only);
```
MYSQL_PLUGIN_DIR: Specify the location of client plugins. The plugin directory can also be specified with the MARIADB_PLUGIN_DIR environment variable.
```
mysql_optionsv(mysql, MYSQL_PLUGIN_DIR, (void *)"/opt/mariadb/lib/plugins");
```
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.
```
mysql_optionsv(mysql, MYSQL_SERVER_PUBLIC_KEY, (void *)(void *)"certs/server-cert.pem);
```

Option File Options

MYSQL_READ_DEFAULT_FILE: Read options from an option file.
MYSQL_READ_DEFAULT_GROUP: Read options from the named option group from an option file.

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 default option files are read.
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.

Connection Attribute Options

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
_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

If the is disabled, connection attributes will not be stored on server.

MYSQL_OPT_CONNECT_ATTR_DELETE: Deletes a connection attribute for the given key.
```
mysql_optionsv(mysql, MYSQL_OPT_CONNECT_ATTR_DELETE, (void *)"app_version");
```

MYSQL_OPT_CONNECT_ATTR_ADD: Adds a key/value pair to connection attributes.

mysql_optionsv(mysql, MYSQL_OPT_CONNECT_ATTR_ADD, (void *)"app_version", (void *)"2.0.1");

MYSQL_OPT_CONNECT_ATTR_RESET: Clears the current list of connection attributes.
```
mysql_optionsv(mysql, MYSQL_OPT_CONNECT_ATTR_RESET, 0);
```

Configuring MariaDB Connector/C with Option Files

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

Default Option File Locations

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

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

mysql_optionsv(mysql, MYSQL_READ_DEFAULT_FILE, NULL);

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 cmake 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

/etc/my.cnf

/etc/mysql/my.cnf

$MYSQL_HOME/my.cnf

~/.my.cnf

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

Location

DEFAULT_SYSCONFDIR/my.cnf

$MYSQL_HOME/my.cnf

~/.my.cnf

Default Option File Locations on Windows

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

Location

System Windows Directory\my.ini

System Windows Directory\my.cnf

Windows Directory\my.ini

Windows Directory\my.cnf

C:\my.ini

C:\my.cnf

EXEDIR\my.ini

EXEDIR\my.cnf

%MYSQL_HOME%\my.ini

%MYSQL_HOME%\my.cnf

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

echo %WINDIR%

The Windows Directory is the directory returned by the GetWindowsDirectory 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 GetSystemWindowsDirectory function.
EXEDIR is the parent directory of the executable program that MariaDB Connector/C is linked with.
MYSQL_HOME is the containing the path to the directory holding the server-specific my.cnf file.

Default Option File Hierarchy

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

Custom Option File Locations

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

mysql_optionsv(mysql, MYSQL_READ_DEFAULT_FILE, (void *)"./my_conf.cnf");

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

=path

Only read options from the given option file.

=path

Read this extra option file after all other option files are read.

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

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

Option File Syntax

The syntax of the MariaDB option files are:

Lines starting with

are comments.

Empty lines are ignored.
Option groups use the syntax [group-name]. See the Option Groups section below for more information on available option groups.
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.

Option Groups

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

Group

Description

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

[client-mariadb]

Options read by all MariaDB client programs.

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

For example:

mysql_optionsv(mysql, MYSQL_READ_DEFAULT_GROUP, NULL);

Custom Option Groups

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

For example:

mysql_optionsv(mysql, MYSQL_READ_DEFAULT_GROUP, (void *)"my_section");

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

=suffix

In addition to the default option groups, also read option groups with the given suffix.

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

Including Option Files

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

[client-mariadb]
...
!include /etc/mysql/dbserver1.cnf

Including Option File Directories

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

[client-mariadb]
...
!includedir /etc/my.cnf.d/

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 CONC-396 for more information.

Checking Program Options

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

Option

Description

Read options from option files, print all option values, and then exit the program.

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:

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

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:

my_print_defaults my_section client client-server client-mariadb
--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

See for more information.

MySQL 5.6 Obfuscated Authentication Credential Option File

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

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

Options

MariaDB Connector/C options can be set in client option groups.

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

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

Custom Options

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

my_bool (*set_option)(MYSQL *mysql, const char *config_option, const char *config_value);

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

Default Options

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

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

bind-address

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

character-sets-dir

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

compress

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

connect-timeout, timeout

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

database

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

debug

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

default-auth

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

default-character-set

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

disable-local-infile

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

host

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

interactive-timeout

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

init-command

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

local-infile

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

max-allowed-packet

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

multi-results

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

multi-statements, multi-queries

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

net-buffer-length

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

password

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

pipe

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

plugin-dir

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

port

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

protocol

Description: Specify the type of client/server protocol. Possible values are:
- 0 - Refers to MYSQL_PROTOCOL_DEFAULT
- 1 - Refers to MYSQL_PROTOCOL_TCP
- 2 - Refers to MYSQL_PROTOCOL_SOCKET
- 3 - Refers to MYSQL_PROTOCOL_PIPE
- 4 - Refers to MYSQL_PROTOCOL_MEMORY
mysql_optionsv: MYSQL_OPT_PROTOCOL
Data Type: int
Default Value:

reconnect

Description: Enable or disable automatic reconnect.
mysql_optionsv: MYSQL_OPT_RECONNECT
Data Type: boolean
Default Value: false
Introduced: MariaDB Connector/C 3.0.0

report-data-truncation

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

return-found-rows

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

secure-auth

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

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
Default Value:
Introduced: MariaDB Connector/C 3.1.0

shared-memory-base-name

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

socket

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

ssl-ca

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

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 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_optionsv: MYSQL_OPT_SSL_CAPATH
Data Type: string
Default Value:

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
Default Value:

ssl-cipher

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

ssl-crl

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

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 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_optionsv: MYSQL_OPT_SSL_CRLPATH
Data Type: string
Default Value:
Introduced: MariaDB Connector/C 3.1.1

ssl-enforce

Description: Whether to force .
mysql_optionsv: MYSQL_OPT_SSL_ENFORCE
Data Type: boolean
Default Value:
Introduced: MariaDB Connector/C 3.1.1

ssl-fp

Description: Specify the SHA1 fingerprint of a server certificate for validation during the handshake.
mysql_optionsv: MARIADB_OPT_SSL_FP
Data Type: string
Default Value:
Introduced: MariaDB Connector/C 3.0.0

ssl-fp-list, ssl-fplist

Description: Specify a file which contains one or more SHA1 fingerprints of server certificates for validation during the handshake.
mysql_optionsv: MARIADB_OPT_SSL_FP_LIST
Data Type: string
Default Value:
Introduced: MariaDB Connector/C 3.0.0

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
Default Value:

ssl-passphrase

Description: Specify a passphrase for a passphrase-protected private key, as configured by the 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.
mysql_optionsv: MARIADB_OPT_TLS_PASSPHRASE
Data Type: string
Default Value:
Introduced: MariaDB Connector/C 3.0.0

ssl-verify-server-cert

Description: Enables (or disables) .
mysql_optionsv: MYSQL_OPT_SSL_VERIFY_SERVER_CERT
Data Type: boolean
Default Value:
Introduced: MariaDB Connector/C 3.0.0

tls_version

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

user

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

List of MariaDB Connector/C Releases

<< back to MariaDB Connector/C Overview

Date

Release

Status

included in MariaDB

Release Notes

Changelog

21 Aug 2025

3.4.7

Stable (GA)

, , ,

9 Apr 2025

3.4.5

Stable (GA)

11 Feb 2025

3.4.4

Stable (GA)

12 Nov 2024

3.4.3

Stable (GA)

20 Aug 2024

3.4.1

Stable (GA)

Date

Release

Status

included in MariaDB

Release Notes

Changelog

21 Aug 2025

3.3.17

Stable (GA)

9 Apr 2025

3.3.15

Stable (GA)

11 Feb 2015

3.3.14

Stable (GA)

12 Nov 2024

3.3.13

Stable (GA)

20 Aug 2024

3.3.11

Stable (GA)

21 Jun 2024

3.3.10

Stable (GA)

19 Feb 2024

3.3.9

Stable (GA)

29 Nov 2023

3.3.8

Stable (GA)

, ,

14 Sep 2023

3.3.7

Stable (GA)

22 May 2023

3.3.5

Stable (GA)

, ,

7 Feb 2023

3.3.4

Stable (GA)

, ,

7 Nov 2022

3.3.3

Stable (GA)

22 Aug 2022

3.3.2

Stable (GA)

25 May 2022

3.3.1

Stable (GA)

15 Feb 2022

3.3.0

Date

Release

Status

included in MariaDB

Release Notes

Changelog

25 May 2022

3.2.7

Stable (GA)

15 Feb 2022

3.2.6

Stable (GA)

10 Nov 2021

3.2.5

Stable (GA)

9 Aug 2021

3.2.4

Stable (GA)

7 Jul 2021

3.2.3

Stable (GA)

29 Jun 2021

3.2.2

10 Jun 2021

3.2.0

Beta

Date

Release

Status

included in MariaDB

Release Notes

Changelog

09 Apr 2025

3.1.28

Stable (GA)

11 Feb 2025

3.1.27

Stable (GA)

12 Nov 2024

3.1.26

Stable (GA)

18 Jun 2024

3.1.24

Stable (GA)

29 Nov 2023

3.1.23

Stable (GA)

1 Sep 2023

3.1.22

Stable (GA)

22 May 2023

3.1.21

Stable (GA)

, ,

7 Feb 2023

3.1.20

Stable (GA)

, ,

7 Nov 2022

3.1.19

Stable (GA)

, ,

22 Aug 2022

3.1.18

Stable (GA)

, ,

25 May 2022

3.1.17

Stable (GA)

, , ,

15 Feb 2022

3.1.16

Stable (GA)

, , ,

10 Nov 2021

3.1.15

Stable (GA)

, , ,

11 Aug 2021

3.1.14

Stable (GA)

, , ,

11 May 2021

3.1.13

Stable (GA)

, , ,

23 Feb 2021

3.1.12

Stable (GA)

, , ,

4 Nov 2020

3.1.11

Stable (GA)

, , ,

17 Sep 2020

3.1.10

Stable (GA)

24 Jun 2020

3.1.9

Stable (GA)

, , ,

14 May 2020

3.1.8

Stable (GA)

, , ,

29 Jan 2020

3.1.7

Stable (GA)

, ,

12 Dec 2019

3.1.6

Stable (GA)

, ,

11 Nov 2019

3.1.5

Stable (GA)

, ,

11 Sep 2019

3.1.4

Stable (GA)

, ,

1 Aug 2019

3.1.3

Stable (GA)

19 Jun 2019

3.1.2

Stable (GA)

06 Jun 2019

3.1.1

09 Apr 2019

3.1.0

Alpha

Date

Release

Status

included in MariaDB

Release Notes

Changelog

13 May 2019

3.0.10

Stable (GA)

11 Feb 2019

3.0.9

Stable (GA)

21 Dec 2018

3.0.8

Stable (GA)

14 Nov 2018

3.0.7

Stable (GA)

2 Aug 2018

3.0.6

Stable (GA)

7 Jun 2018

3.0.5

Stable (GA)

25 Apr 2018

3.0.4

Stable (GA)

18 Jan 2018

3.0.3

Stable (GA)

20 Jul 2017

3.0.2

Stable (GA)

18 Jan 2017

3.0.1

Beta

20 Jan 2016

3.0.0

Alpha

Date

Release

Status

included in MariaDB

Release Notes

Changelog

7 Sep 2018

2.3.7

Stable (GA)

7 Jun 2018

2.3.6

Stable (GA)

18 Jan 2018

2.3.5

Stable (GA)

4 Dec 2017

2.3.4

Stable (GA)

31 May 2017

2.3.3

Stable (GA)

18 Jan 2017

2.3.2

Stable (GA)

4 Aug 2016

2.3.1

Stable (GA)

1 Jul 2016

2.3.0

Stable (GA)

26 Apr 2016

2.2.3

Stable (GA)

9 Dec 2015

2.2.2

Stable (GA)

18 Nov 2015

2.2.1

Stable (GA)

29 Sep 2015

2.2.0

Stable (GA)

29 Jan 2015

2.1.0

Stable (GA)

2 Apr 2014

MariaDB Client Library for C 2.0.0

Stable (GA)

29 Nov 2012

MariaDB Client Library for C 1.0.0

Stable (GA)

Connectors

MariaDB Connectors

Quickstart Guides

MariaDB Connector/C++ Guide

MariaDB Connector/C++ Quickstart Guide

Why Choose Connector/C++?

Next Steps

Erlang Guide

1. Installation

2. Basic Usage

Further Resources:

Connector/ODBC Guide

Quickstart Guide: MariaDB Connector/ODBC

1. What is ODBC?

2. Installation

3. Basic Usage (Connecting from Applications)

Further Resources:

Connector/Ruby Guide

Quickstart Guide: MariaDB Connector/Ruby (using mysql2 gem)

1. Overview

2. Installation

3. Basic Usage

Important Notes:

Further Resources:

Connector/C

MariaDB Binlog/Replication API reference

MariaDB Connector/C Plugins

connection plugins

aurora

replication

pvio plugins

socket

npipe

shmem

io plugins

remote_io

auth plugins

mysql_native_password

dialog

client_ed25519

caching_sha2_password

sha256_password

auth_gssapi_client

mysql_old_password

mysql_clear_password

Compiling Connector/C

Compiling on Windows

Compiling on Unix

Prerequisites For Building Connector/C From Source

Windows

Linux / Mac OS X

MariaDB Connector/C API Functions

mariadb_cancel

Syntax

Description

mariadb_get_infov

Syntax

Description

Value types

Generic information

Connection related information

Examples

See also

mariadb_reconnect

Syntax

Description

See also

mysql_affected_rows

Syntax

Description

See also

mysql_autocommit

Syntax

Description

Turning off autocommit in sql

mysql_change_user

Syntax

Description

mysql_character_set_name

Syntax

Quickstart Guide: MariaDB Connector/Ruby (using `mysql2` gem)