MariaDB Connector/C++ 1.0 GA
-------------------------------

This is a GA release of the MariaDB Connector/C++.
MariaDB Connector/C++ is released under version 2.1 of the
GNU Lesser Public License.

License information can be found in the COPYING file.

To report issues: https://jira.mariadb.org/projects/CONCPP/issues/

Documentation: https://mariadb.com/docs/appdev/connector-cpp/

Basic Use
---------

Connector implements JDBC API with minimal extensions and minimal
reductions of methods, that do not make sense in C++

To be able to use API, a program should include its definition in ConnCpp.h
header

#include  <mariadb/conncpp.hpp>

To obtain driver instance:
sql::Driver* driver= sql::mariadb::get_driver_instance();

To connect
sql::SQLString url("jdbc:mariadb://localhost:3306/db");
sql::Properties properties({{"user", "root"}, {"password", "someSecretWord"}});
std::unique_ptr<Connection> conn(driver->connect(url, properties));

Alternatively, connection object can be obtained via DriverManager class. In this case Driver object is not needed,
and the connector throws exception, if connection could not be established for whatever reason. Please note, that
for conencting via DriverManager only "jdbc:mariadb://" type of URL can be used.

sql::SQLString url("jdbc:mariadb://localhost:3306/db");
sql::Properties properties({{"user", "roor"}, {"password", "someSecretWord"}});
std::unique_ptr<Connection> conn(DriverManager::getConnection(url, properties));
// or
sql::SQLString url2("jdbc:mariadb://localhost:3306/db?user=root&password=someSecretWord");
std::unique_ptr<Connection> conn2(DriverManager::getConnection(url));
// or
std::unique_ptr<Connection> conn3(DriverManager::getConnection(url, "root", "someSecretWord"));
// or
MariaDbDataSource ds(url);
// Connections obrained via DataSource object are taken from the connetion pool, that automatically created in this case
std::unique_ptr<Connection> conn4(ds.getConnection("root", "someSecretWord"));
std::unique_ptr<Connection> conn5(ds.getConnection()); // ds remembers user/passwd after first call, alternatively ds.setUser() andsetPassword() can be used
// ds.close() would close the pool making conn4 and conn5 unusable
// thus conn4 and conn5 should be either reset before ds.close() call, or released after

// or
sql::SQLString failoverUrl("jdbc:mariadb:sequential://localhost:3306,failoverhost1.com,[::1]:3307,failoverhost2.com:3307/db?user=root&password=someSecretWord");
std::unique_ptr<Connection> conn6(DriverManager::getConnection(failoverUrl));


For URL syntax you may find at https://mariadb.com/kb/en/about-mariadb-connector-j/

The list of supported options:

Option      Description                                                              Type   Aliases
------      -----------                                                              ----   -------
useServerPrepStmts Whether to use Server Side Prepared Statements(SSPS) for
                   PreparedStatement by default, and not client side ones(CSPS)      bool   
connectTimeout     The connect timeout value, in milliseconds, or zero for no
                   timeout.                                                          int
socketTimeout      Specifies the timeout in seconds for reading packets from the
                   server. Value of 0 disables this timeout.                         int    OPT_READ_TIMEOUT
autoReconnect      Enable or disable automatic reconnect.                            bool   OPT_RECONNECT

tcpRcvBuf   The buffer size for TCP/IP and socket communication. `tcpSndBuf` changes
            the same buffer value, and the biggest value of the two is selected      int    tcpSndBuf
tcpSndBuf   The buffer size for TCP/IP and socket communication. `tcpRcvBuf` changes
            the same buffer value, and the biggest value of the two is selected      int    tcpRcvBuf
localSocket For connections to localhost, the Unix socket file to use.               string
pipe        On Windows, specify the named pipe name to connect.                      string
useTls      Whether to force TLS. This enables TLS with the default system settings. bool   useSsl,useSSL
tlsKey      File path to a private key file                                          string sslKey
keyPassword Password for the private key                                             string MARIADB_OPT_TLS_PASSPHRASE
tlsCert     Path to the X509 certificate file                                        string sslCert
tlsCA       A path to a PEM file that should contain one or more X509 certificates
            for trusted Certificate Authorities (CAs)                                string tlsCa,sslCA
tlsCAPath   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                                                              string tlsCaPath, sslCAPath

enabledTlsCipherSuites  A list of permitted ciphers or cipher suites to use for TLS  string enabledSslCipherSuites, enabledSSLCipherSuites

tlsCRL      path to a PEM file that should contain one or more revoked X509
            certificates                                                             string tlsCrl, sslCRL
tlsCRLPath  A path to a directory that contains one or more PEM files that should
            each contain one revoked X509 certificate. The directory specified by
            this option needs to be run through the openssl rehash command. This
            option is only supported if the connector was built with OpenSSL.        string tlsCrlPath, sslCRLPath
tlsPeerFP   A SHA1 fingerprint of a server certificate for validation during the TLS
            handshake.                                                               string tlsPeerFp, MARIADB_OPT_SSL_FP

tlsPeerFPList  A file containing one or more SHA1 fingerprints of server certificates
               for validation during the TLS handshake.                              string tlsPeerFpList, MARIADB_OPT_SSL_FP_LIST

trustServerCertificate  When using TLS, do not check server's certificate(def. true) bool

serverRsaPublicKeyFile  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  string rsaKey

useCompression           Compresses the exchange with the database                    bool  CLIENT_COMPRESS
jdbcCompliantTruncation  Truncation error will be thrown as error, and not as warning bool(default=true)
useCharacterEncoding     Character set used for text encoding                         string OPT_SET_CHARSET_NAME,useCharset
credentialType           Default authentication client-side plugin to use.            string defaultAuth
defaultFetchSize         The driver will call setFetchSize(n) with this value on all
                         newly-created Statements                                     int
pool                     Use connections pool(default false).                         bool
maxPoolSize              The maximum number of physical connections that the pool
                         should contain(default 8)                                    int
minPoolSize              When connections are removed due to not being used for
                         longer than than "maxIdleTime", connections are closed and
                         removed from the pool. "minPoolSize" indicates the number of
                         physical connections the pool should keep available at all
                         times. Should be less or equal to maxPoolSize(default
                         maxPoolSize value)                                           int
maxIdleTime              The maximum amount of time in seconds that a connection can
                         stay in the pool if not used. This value must always be below
                         @wait_timeout value - 45s. Default: 600 in seconds
                         (=10 minutes), minimum value is 60 seconds                   int
poolValidMinDelay        When the pool is requested for a connection, it will validate
                         the connection state. "poolValidMinDelay" allows to disable
                         this validation if the connection has been used recently,
                         avoiding useless verifications in case of frequent reuse of
                         connections. 0 means validation is done each time the
                         connection is requested(default 1000)                        int
allowLocalInfile         Permits loading data from local file(on the client) with
                         LOAD DATA LOCAL INFILE statement(false)                      bool
useResetConnection       Makes Connection::reset() method to issue conenction reset
                         command at the server. This option existed from first version,
                         but was not documented. Since 1.1.1 its default changed to
                         true                                                         bool
allowLocalInfile         Permits loading data from local file(on the client) with
                         LOAD DATA LOCAL INFILE statement(false)                      bool
useResetConnection       Makes Connection::reset() method to issue conenction reset
                         command at the server. Its default is false                  bool
rewriteBatchedStatements For insert queries, rewrites batchedStatement to execute in
            a single executeQuery. Example: insert into ab (i) values (?) with first
            batch values = 1, second = 2 will be rewritten as
            INSERT INTO ab (i) VALUES (1), (2).
            If query cannot be rewriten in "multi-values", rewrite will use
            multi-queries : INSERT INTO TABLE(col1) VALUES (?)
            ON DUPLICATE KEY UPDATE col2=? with values [1,2] and [2,3]
            will be rewritten as
            INSERT INTO TABLE(col1) VALUES (1) ON DUPLICATE KEY UPDATE col2=2;INSERT
            INTO TABLE(col1) VALUES (3) ON DUPLICATE KEY UPDATE col2=4
            If active, the useServerPrepStmts option is set to false. Default false   bool
useBulkStmts             Use dedicated COM_STMT_BULK_EXECUTE protocol for
            executeBatch if possible. Can be significanlty faster.
            (works only with server MariaDB >= 10.2.7). Default false                 bool
cachePrepStmts           Enable/disable Server Side Prepared Statement cache.
                         (default false)                                              bool
prepStmtCacheSize        This sets the number of prepared statements that the driver
                         will cache per connection if "cachePrepStmts" is enabled.
                         (default 250)                                                int
prepStmtCacheSqlLimit    This is the maximum length of a (SQL query length + schema
                         name length + 1) for the statement that the driver will cache
                         if "cachePrepStmts" is enabled(default 2048)                 int
connectionAttributes     If performance_schema is enabled, permits to send server
                         some client information in a key:value pair format
                         (example: connectionAttributes=key1:value1,key2,value2)      string
log`                     The logging level. Setting it to non-zero effectively turns
                         on the logging. The levels are 1- error, 2- warning, 3- info,
                         4 - debug, 5-trace                                           uint
logname                  Name of the file to write the log in. If the name is set,
                         and the log level is not, the level will be set to 'error'.
                         The option does not have default value, but the logger has
                         default name and location for the log file. The name is
                         mariadbccpp.log, the location is %TMP% or %USERPROFILE% or
                         current dir on Windows, or $HOME or /tmp on other systems.   string


Properties is map of strings, and is another way to pass optional parameters.

In addition to Connector/J URL style and JDBC connect method, Connector/C++ supports
following connect methods:

sql::SQLString user("root");
sql::SQLString pwd("root");
std::unique_ptr<sql::Connection> conn(driver->connect("tcp://localhost:3306/test", user, pwd));

and

sql::Properties properties;
properties["hostName"]= "127.0.0.1";
properties["userName"]= "root";
properties["password"]= "root";
std::unique_ptr<sql::Connection> conn(driver->connect(properties));

Host in former case can be defined as  (tcp|unix|pipe)://\<host\>[:port][/<db>]
Properties in the latter case are the same, as in the first variant of the connect
method, plus additionally supported
  - hostName
  - pipe
  - socket
  - schema
  - userName(alias for user)
  - password

std::string variables can be passed, where parameters are expected to be sql::SQLString

For further use one may refer to JDBC specs.

Except Driver object, normally this is application's responsibility to delete
objects returned by the connector.
