-
Notifications
You must be signed in to change notification settings - Fork 49
/
Copy pathREADME
154 lines (122 loc) · 8.45 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
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
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.