mirror of
https://github.com/mariadb-corporation/mariadb-connector-cpp.git
synced 2025-07-20 16:35:25 +00:00
a36ff95ac6
If not selected otherwise. The connection option `trustServerCertificate` responsible for that is now properly documented in the README(.md) It is true by default that means that certificate is not verified. If not set to false it now causes also that certificate verification is explictitly turned off. That enables connector to work without problem with C/C 3.4
157 lines
8.5 KiB
Plaintext
157 lines
8.5 KiB
Plaintext
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"));
|
|
|
|
|
|
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|
|
|
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
|
|
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
|
|
|
|
|
|
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.
|