Webinar | Powering the Agent-Driven Enterprise: The Shift to a Unified Data Platform
Watch Now
Ctrlk
Download MariaDBContact Us
For the complete documentation index, see llms.txt. This page is also available as Markdown.
ChatGPT

mysql_optionsv

mysql_optionsv sets connection, TLS, plugin, and option-file options on a MariaDB Connector/C handle before mysql_real_connect, supporting a variable argument list.

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 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. All calls pass numeric literal values for a const void *. mysql_optionsv() should be called after mysql_init().

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

Return Value

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

Variable Types

The following table shows the C variable type required for the arg parameter of each option:

Variable type
Options

my_bool, unsigned char

MYSQL_OPT_RECONNECT, MYSQL_SECURE_AUTH, MYSQL_REPORT_DATA_TRUNCATION, MYSQL_OPT_SSL_ENFORCE, MYSQL_OPT_SSL_VERIFY_SERVER_CERT, MARIADB_OPT_SKIP_READ_RESPONSE, MYSQL_OPT_ZSTD_COMPRESSION_LEVEL

unsigned int

MARIADB_OPT_PORT, MYSQL_OPT_LOCAL_INFILE, MYSQL_OPT_CONNECT_TIMEOUT, MYSQL_OPT_PROTOCOL, MYSQL_OPT_READ_TIMEOUT, MYSQL_OPT_WRITE_TIMEOUT

unsigned long

MYSQL_OPT_NET_BUFFER_LENGTH, MYSQL_OPT_MAX_ALLOWED_PACKET

const char *

MYSQL_INIT_COMMAND, MARIADB_OPT_UNIXSOCKET, MARIADB_OPT_PASSWORD , MARIADB_OPT_USER, MARIADB_OPT_HOST, MARIADB_OPT_SCHEMA, MYSQL_OPT_SSL_KEY, MYSQL_OPT_SSL_CERT, MYSQL_OPT_SSL_CA, MYSQL_OPT_SSL_CAPATH, MYSQL_SET_CHARSET_NAME, MYSQL_SET_CHARSET_DIR, MYSQL_OPT_SSL_CIPHER, MYSQL_SHARED_MEMORY_BASE_NAME, MYSQL_PLUGIN_DIR, MYSQL_DEFAULT_AUTH, MARIADB_OPT_SSL_FP, MARIADB_OPT_SSL_FP_LIST, MARIADB_OPT_TLS_PASSPHRASE, MARIADB_OPT_TLS_VERSION, MYSQL_OPT_BIND, MYSQL_OPT_CONNECT_ATTR_DELETE, MYSQL_OPT_CONNECT_ATTR_ADD, MARIADB_OPT_CONNECTION_HANDLER, MYSQL_SERVER_PUBLIC_KEY, MARIADB_OPT_RESTRICTED_AUTH

const char*, unsigned int

MARIADB_OPT_RPL_REGISTER_REPLICA

-

MYSQL_OPT_CONNECT_ATTR_RESET

void *

MARIADB_OPT_PROXY_HEADER

Options

  • MYSQL_INIT_COMMAND: lets you specify a command to execute immediately after connecting (and also after a reconnect if enabled).

    • Each call adds one SQL statement to an internal list; all stored commands are executed in order.

    • You cannot concatenate multiple statements with semicolons; each statement must be added with a separate call.

    Note: When multiple option files are used, init_command entries are aggregated from all files read (for example, /etc/my.cnf and ~/.my.cnf). The resulting combined list of statements executes on every connection and reconnection, without any clear indication that they originated from different sources. If unexpected statements run during a connection, review all active option files to identify their source.

  • MYSQL_OPT_CONNECT_TIMEOUT: Connect timeout in seconds. This value will be passed as an unsigned int parameter.

  • MYSQL_PROGRESS_CALLBACK: Specifies a callback function which will be able to visualize the progress of certain long running statements (i.e. LOAD DATA LOCAL INFILE or ALTER TABLE).

  • MYSQL_OPT_RECONNECT: Enable or disable automatic reconnect.

  • MYSQL_OPT_READ_TIMEOUT: Specifies the timeout in seconds for reading packets from the server.

  • MYSQL_OPT_WRITE_TIMEOUT: Specifies the timeout in seconds for sending packets to the server.

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

  • MYSQL_SET_CHARSET_DIR: character set files.

  • MYSQL_SET_CHARSET_NAME: Specify the default character set for the connection.

  • MYSQL_OPT_BIND: Specify the network interface from which to connect to MariaDB Server.

  • 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_OPT_CAN_HANDLE_EXPIRED_PASSWORDS: If this option is set, the client indicates that it will be able to handle expired passwords by setting the CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS capability flag. If the password has expired and CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS is set, the server will not return an error when connecting, but put the connection in sandbox mode, where all commands will return error 1820 (ER_MUST_CHANGE_PASSWORD) unless a new password was set. This option was added in MariaDB Connector/C 3.0.4

  • MYSQL_OPT_MAX_ALLOWED_PACKET: The maximum packet length to send to or receive from server. The default is 16MB, the maximum 1GB.

  • MYSQL_OPT_NET_BUFFER_LENGTH: The buffer size for TCP/IP and socket communication. Default is 16KB.

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.

  • MARIADB_OPT_USER: User to login to the server.

  • MARIADB_OPT_PASSWORD: Password of the user to login to the server.

  • MARIADB_OPT_SCHEMA: Database to use.

  • MARIADB_OPT_PORT: Port number to use for connection.

  • 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_OPT_NAMED_PIPE: For Windows operating systems only: Use named pipes for client/server communication.

  • MYSQL_OPT_PROTOCOL: Specify the type of client/server protocol. Possible values are:

    • MYSQL_PROTOCOL_TCP

    • MYSQL_PROTOCOL_SOCKET

    • MYSQL_PROTOCOL_PIPE

    • MYSQL_PROTOCOL_MEMORY.

  • MARIADB_OPT_FOUND_ROWS: Return the number of matched rows instead of number of changed rows.

  • MYSQL_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_OPT_ZSTD_COMPRESSION_LEVEL: The compression level to use for connections that use the zstd compression algorithm. Acceptable values are integers in the range 1 (fastest) to 22 (maximum compression). This option has no effect if zstd compression is not in use. Added in MariaDB Connector/C 3.3.14 and 3.4.4 versions.

  • MYSQL_OPT_LOCAL_INFILE: Enable or disable the use of LOAD DATA LOCAL INFILE

  • MARIADB_OPT_MULTI_STATEMENTS: Allows the client to send multiple statements in one command. Statements will be divided by a semicolon.

  • MARIADB_OPT_MULTI_RESULTS: Indicates that the client is able to handle multiple result sets from stored procedures or multi statements. This option will be automatically set if MARIADB_OPT_MULTI_STATEMENTS is set.

  • MYSQL_SHARED_MEMORY_BASE_NAME: Shared-memory name to use for Windows connections using shared memory to a local server (started with the --shared-memory option). Case-sensitive.

TLS Options

  • MYSQL_OPT_SSL_KEY: Defines a path to a private key file to use for TLS. This option requires that you use the absolute path, not a relative path. If the key is protected with a passphrase, the passphrase needs to be specified with MARIADB_OPT_TLS_PASSPHRASE option.

  • MYSQL_OPT_SSL_CERT: Defines a path to the X509 certificate file to use for TLS. This option requires that you use the absolute path, not a relative path.

  • 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 TLS. This option requires that you use the absolute path, not a relative path. See Secure Connections Overview: Certificate Authorities (CAs) for more information.

  • MYSQL_OPT_SSL_CAPATH: Defines a path to a directory that contains one or more PEM files that should each contain one X509 certificate for a trusted Certificate Authority (CA) to use for TLS. 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 Secure Connections Overview: Certificate Authorities (CAs) 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 TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.

  • MYSQL_OPT_SSL_CIPHER: Defines a list of permitted ciphers or cipher suites to use for TLS.

  • MYSQL_OPT_SSL_CRL: Defines a path to a PEM file that should contain one or more revoked X509 certificates to use for TLS. This option requires that you use the absolute path, not a relative path. See Secure Connections Overview: Certificate Revocation Lists (CRLs) 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 TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.

  • MYSQL_OPT_SSL_CRLPATH: Defines a path to a directory that contains one or more PEM files that should each contain one revoked X509 certificate to use for TLS. 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 Secure Connections Overview: Certificate Revocation Lists (CRLs) 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 TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.

  • MARIADB_OPT_SSL_FP: Specify the fingerprint hash of a server certificate for validation during the TLS handshake. Before version 3.4.0, Connector/C accepted only SHA1 hashes. Starting with version 3.4.0, support was extended to include SHA256, SHA384, and SHA512. This option is deprecated. Use MARIADB_OPT_TLS_PEER_FP instead.

  • MARIADB_OPT_TLS_PEER_FP: Specify the SHA1 fingerprint of a server certificate for validation during the TLS handshake.

  • MARIADB_OPT_SSL_FP_LIST: Specify a file containing one or more fingerprint hashes of server certificates for validation during the TLS handshake. Before version 3.4.0, Connector/C accepted only SHA1 hashes. Starting with version 3.4.0, support was extended to include SHA256, SHA384, and SHA512. This is deprecated. Use MARIADB_OPT_TLS_PEER_FP_LIST instead.

  • MARIADB_OPT_TLS_PEER_FP_LIST: Specify a file which contains one or more SHA1 fingerprints of server certificates for validation during the TLS handshake.

  • 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 TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.

  • MARIADB_OPT_TLS_VERSION: Defines which TLS 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 Secure Connections Overview: TLS Protocol Version Support for information on which TLS libraries support which TLS protocol versions. See TLS and Cryptography Libraries Used by MariaDB for more information about which TLS libraries are used on which platforms.

  • MYSQL_OPT_SSL_VERIFY_SERVER_CERT: Enables (or disables) server certificate verification.

  • MYSQL_OPT_SSL_ENFORCE: Enables TLS using the default system settings. Does not require TLS certificates, keys, or CAs to be explicitly configured.

  • Note: Despite the option name, this does not enforce TLS. If the server does not support TLS, the connection falls back to unencrypted communication without error. To prevent fallback and enforce TLS, use MYSQL_OPT_SSL_VERIFY_SERVER_CERT instead.

  • MARIADB_OPT_TLS_CIPHER_STRENGTH: Deprecated. This option is no longer in use and has no effect. Cipher strength. This value will be passed as an unsigned int parameter.

Plugin Options

  • MYSQL_DEFAULT_AUTH: Default authentication client-side plugin to use.

  • MYSQL_ENABLE_CLEARTEXT_PLUGIN: This option is supported to be compatible with MySQL client libraries. MySQL client libraries use this option to determine whether the mysql_clear_password authentication plugin can be used. However, MariaDB clients and client libraries do not need to set any options in order to use this authentication plugin. Therefore, this option does not actually do anything in MariaDB Connector/C.

  • MARIADB_OPT_CONNECTION_HANDLER: Specify the name of a connection handler plugin.

  • MARIADB_OPT_RESTRICTED_AUTH: Specifies a comma-separated list of authentication plugins that are permitted for authenticating this connection. If the server requests an authentication plugin that is not in this list, MariaDB Connector/C returns an error and the connection is refused. This option can be used to prevent the use of weaker authentication methods. Added in MariaDB Connector/C 3.3.0 version.

  • MARIADB_OPT_USERDATA: Bundle user data to the current connection, e.g. for use in connection handler plugins. This option requires 4 parameters: connection, option, key and value.

  • MARIADB_OPT_CONNECTION_READ_ONLY: This option is used by connection handler plugins and indicates that the current connection will be used for read operations only.

  • MARIADB_OPT_SKIP_READ_RESPONSE: Disables server response packet reading in the binary protocol. Designed for specialized connection handlers, not for typical application use. Added in Connector/C 3.1.13 version.

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

  • MYSQL_SECURE_AUTH: Refuse to connect to the server if the server uses the mysql_old_password 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_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 caching_sha2_password client authentication plugin. It was introduced in Connector/C 3.1.0.

Callback Options

  • MARIADB_OPT_STATUS_CALLBACK: Specifies a callback function that is invoked whenever the server sends a status change or session tracking information to the client. This can be used to monitor server status flags and session variable changes without polling.

    The callback function must match the following signature:

Parameters

Parameter
Type
Description

data

void *

The pointer passed as the second argument when registering the callback (typically a connection handle or application context)

type

enum enum_mariadb_status_info

Indicates the category of information being delivered. Either STATUS_TYPE or SESSION_TRACK_TYPE.

Variadic Parameters (vary by type)

When type is STATUS_TYPE:

Position
Type
Description

1st

unsigned int

The current server status flags.

When type is SESSION_TRACK_TYPE:

Position
Type
Description

1st

enum enum_session_state_type

The session tracking type.

2nd

MARIADB_CONST_STRING *

If track_type is SESSION_TRACK_SYSTEM_VARIABLES: the variable name.

3rd

MARIADB_CONST_STRING *

If track_type is SESSION_TRACK_SYSTEM_VARIABLES: the variable value.

When a status callback is registered, the connector’s built‑in session tracking functions are disabled. After calling mysql_optionsv() with MARIADB_OPT_STATUS_CALLBACK, the functions mysql_session_track_get_first() and mysql_session_track_get_next() will no longer provide session tracking data. Instead, all session tracking must be managed within the callback itself.

An example implementation can be found in the Connector/C source tree at unittest/libmariadb/connection.c (function test_status_callback). Added in MariaDB Connector/C 3.3.2 version.

Replication/Binlog API Options

  • MARIADB_OPT_RPL_REGISTER_REPLICA: Specifies the host name and port that the Binlog API will report when registering this client as a replica with the connected server. When this option is set, mariadb_rpl_open() will register the client using the provided host, port, and the server ID configured via mariadb_rpl_optionsv(). The registration is visible in the output of SHOW SLAVE STATUS on the server.

    Added in MariaDB Connector/C 3.3.1 version. See Replication API Reference.

Option File Options

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.

Proxy Settings

As defined by the proxy protocol specification, a client may prefix its first packet with a proxy protocol header. The server will parse this header and treat the IP address it contains as the client's actual IP address, rather than the address of the connecting process.

  • MARIADB_OPT_PROXY_HEADER: Specifies the proxy protocol header to prefix to the first packet sent to the server. The option requires two additional arguments:

    • a void * pointer to the header buffer, and

    • a size_t value for the buffer length.

Connection Attribute Options

Connection attributes are stored in the session_connect_attrs and session_account_connect_attrs 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 Performance Schema is disabled, connection attributes will not be stored on server.

  • MYSQL_OPT_CONNECT_ATTR_DELETE: Deletes a connection attribute for the given key.

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

  • MYSQL_OPT_CONNECT_ATTR_RESET: Clears the current list of connection attributes.

See Also

This page is: Copyright © 2026 MariaDB. All rights reserved.

spinner
Previousmysql_optionsNextmysql_ping

Last updated

Was this helpful?