mirror of
https://github.com/mariadb-corporation/mariadb-connector-cpp.git
synced 2025-07-24 12:19:55 +00:00
96efd9e142
The feature is enabled with useBulkStmts boolean options, that is off by default. Works only with MariaDB servers >= 10.2.7. It won't be used with streaming parameters.
152 lines
8.2 KiB
Plaintext
152 lines
8.2 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
|
|
|
|
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
|
|
|
|
|
|
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.
|