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

Returns

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

If MYSQL_READ_DEFAULT_FILE is specified the [client] section will be always processed.

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_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_CONNECT_TIMEOUT: Connect timeout in seconds. This value will be passed as an unsigned int parameter.

    unsigned int timeout= 5;
    mysql_optionsv(mysql, MYSQL_OPT_CONNECT_TIMEOUT, (void *)&timeout);                   
    
  • MYSQL_OPT_LOCAL_INFILE: Enable or disable use of LOAD DATA LOCAL INFILE

    mysql_optionsv(mysql, MYSQL_OPT_LOCAL_INFILE, NULL);        /* disable */                  
    mysql_optionsv(mysql, MYSQL_OPT_LOCAL_INFILE, (void *)"1"); /* enable */                  
    
  • 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_OPT_NAMED_PIPE: For Windows operating systems only: Use named pipes for client/server communication.

    mysql_optionsv(mysql, MYSQL_OPT_NAMED_PIPE, NULL);
    
  • 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).

    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_PROTOCOL: Specify the type of client/server protocol. Possible values are: MYSQL_PROTOCOL_TCP, MYSQL_PROTOCOL_SOCKET, MYSQL_PROTOCOL_PIPE and MYSQL_PROTOCOL_MEMORY.

    enum mysql_protocol_type prot_type= MYSQL_PROTOCOL_SOCKET;
    mysql_optionsv(mysql, MYSQL_OPT_PROTOCOL, (void *)&prot_type);
    
  • 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 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 server.

    unsigned int timeout= 5;
    mysql_optionsv(mysql, MYSQL_OPT_WRITE_TIMEOUT, (void *)&timeout);
    
  • MYSQL_READ_DEFAULT_FILE: Read options from named option file instead of my.cnf

    mysql_optionsv(mysql, MYSQL_READ_DEFAULT_FILE, (void *)"./my_conf.cnf");
    
  • MYSQL_READ_DEFAULT_GROUP: Read options from the named group from my.cnf or the file specified with MYSQL_READ_DEFAULT_FILE.

    mysql_optionsv(mysql, MYSQL_READ_DEFAULT_GROUP, (void *)"my_section");
    
  • MYSQL_REPORT_DATA_TRUNCATION: Enable or disable reporting data truncation errors for prepared statement.

    mysql_optionsv(mysql, MYSQL_REPORT_DATA_TRUNCATION, NULL);        /* disable */
    mysql_optionsv(mysql, MYSQL_REPORT_DATA_TRUNCATION, (void *)"1"); /* enable */                 
    
  • MYSQL_SET_CHARSET_NAME: Specify the default character set 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_PLUGIN_DIR: Specify the location of client plugins.

    mysql_optionsv(mysql, MYSQL_PLUGIN_DIR, (void *)"/opt/mariadb/lib/plugins");
    
  • 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);
    
  • 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);
    

TLS options

  • MYSQL_OPT_SSL_KEY: Specify the name of a TLS key for a secure connection. If the key is protected with a passphrase, the passphrase needs to be specified with MARIADB_OPT_PASSPHRASE option.

    mysql_optionsv(mysql, MYSQL_OPT_SSL_KEY, (void *)"certs/client-key.pem");
    
  • MYSQL_OPT_SSL_CERT: Specify the name of a TLS certificate for a secure connection.

    mysql_optionsv(mysql, MYSQL_OPT_SSL_CERT, (void *)"certs/client-cert.pem");
    
  • MYSQL_OPT_SSL_CA: Specify the name of a file which contains one or more trusted TLS CAs.

    mysql_optionsv(mysql, MYSQL_OPT_SSL_CA, (void *)"certs/ca-cert.pem");
    
  • MYSQL_OPT_SSL_CAPATH: Specify the path which contains trusted CAs.

    mysql_optionsv(mysql, MYSQL_OPT_SSL_CAPATH, (void *)"certs/ca-cert.pem");
    
  • MYSQL_OPT_SSL_CIPHER: Specify a list of cipher suites for TLS encryption.

    mysql_optionsv(mysql, MYSQL_OPT_SSL_CIPHER, (void *)"DHE-RSA-AES256-SHA");
    
  • MYSQL_OPT_SSL_CRL: Specify a file with certificate revocation list.

    mysql_optionsv(mysql, MYSQL_OPT_SSL_CRL, (void *)"certs/crl.pem");
    
  • MYSQL_OPT_SSL_CRLPATH: Specify a directory with contains files with certificate revocation lists.

    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 TLS handshake.

    mysql_optionsv(mysql, MARIADB_OPT_SSL_FP, (void *)"3a079e1a14ad326953a5d280f996b93d772a5bea");
    
  • MARIADB_OPT_SSL_FP: Specify a file which contains one or more SHA1 fingerprints of server certificates for validation during TLS handshake.

    mysql_optionsv(mysql, MARIADB_OPT_SSL_FP_LIST, (void *)"certs/fingerprints.txt");
    
  • MARIADB_OPT_SSL_PASPHRASE: Specify a passphrase for a passphrase protected client key.

    mysql_optionsv(mysql, MARIADB_OPT_SSL_PASSPHRASE, (void *)"thisisashortpassphrase");
    
  • MYSQL_OPT_SSL_VERIFY_SERVER_CERT: Enable (or disable) the verification of the hostname against common name (CN) of the servers host certificate.

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

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

If 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_optionsv(mysql, MYSQL_OPT_CONNECT_ATTR_DELETE, (void *)"app_version");
    
  • MYSQL_OPT_CONNECT_ATTR_ADD: Adds an 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);
    

See also

Comments

Comments loading...