| Qore Programming Language - C/C++ Library 1.12.2

DBI.h
Go to the documentation of this file.
1 /* -*- mode: c++; indent-tabs-mode: nil -*- */
2 /*
3 DBI.h
4
5 Qore Programming Language
6
7 Copyright (C) 2003 - 2022 Qore Technologies, s.r.o.
8
9 Permission is hereby granted, free of charge, to any person obtaining a
10 copy of this software and associated documentation files (the "Software"),
11 to deal in the Software without restriction, including without limitation
12 the rights to use, copy, modify, merge, publish, distribute, sublicense,
13 and/or sell copies of the Software, and to permit persons to whom the
14 Software is furnished to do so, subject to the following conditions:
15
16 The above copyright notice and this permission notice shall be included in
17 all copies or substantial portions of the Software.
18
19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
25 DEALINGS IN THE SOFTWARE.
26
27 Note that the Qore library is released under a choice of three open-source
28 licenses: MIT (as above), LGPL 2+, or GPL 2+; see README-LICENSE for more
29 information.
30 */
31
32 #ifndef _QORE_DBI_H
33 #define _QORE_DBI_H
34
36
37 // DBI Driver capabilities
38 #define DBI_CAP_NONE 0
39 #define DBI_CAP_TIME_ZONE_SUPPORT (1 << 0)
40 #define DBI_CAP_CHARSET_SUPPORT (1 << 1)
41 #define DBI_CAP_TRANSACTION_MANAGEMENT (1 << 2)
42 #define DBI_CAP_STORED_PROCEDURES (1 << 3)
43 #define DBI_CAP_LOB_SUPPORT (1 << 4)
44 #define DBI_CAP_BIND_BY_VALUE (1 << 5)
45 #define DBI_CAP_BIND_BY_PLACEHOLDER (1 << 6)
46 #define DBI_CAP_HAS_EXECRAW (1 << 7)
47 #define DBI_CAP_HAS_STATEMENT (1 << 8)
48 #define DBI_CAP_HAS_SELECT_ROW (1 << 9)
49 #define DBI_CAP_HAS_NUMBER_SUPPORT (1 << 10)
50 #define DBI_CAP_HAS_OPTION_SUPPORT (1 << 11)
51 #define DBI_CAP_SERVER_TIME_ZONE (1 << 12)
52 #define DBI_CAP_AUTORECONNECT (1 << 13)
53 #define DBI_CAP_EVENTS (1 << 14)
54 #define DBI_CAP_HAS_DESCRIBE (1 << 15)
55 #define DBI_CAP_HAS_ARRAY_BIND (1 << 16)
56 #define DBI_CAP_HAS_RESULTSET_OUTPUT (1 << 17)
57 #define DBI_CAP_OPTION_PASSTHRU (1 << 18)
58
59 #define BN_PLACEHOLDER 0
60 #define BN_VALUE 1
61
62 #define DBI_DEFAULT_STR_LEN 512
63
64 // DBI method codes
65 #define QDBI_METHOD_OPEN 1
66 #define QDBI_METHOD_CLOSE 2
67 #define QDBI_METHOD_SELECT 3
68 #define QDBI_METHOD_SELECT_ROWS 4
69 #define QDBI_METHOD_EXEC 5
70 #define QDBI_METHOD_COMMIT 6
71 #define QDBI_METHOD_ROLLBACK 7
72 #define QDBI_METHOD_BEGIN_TRANSACTION 8
73 #define QDBI_METHOD_GET_SERVER_VERSION 9
74 #define QDBI_METHOD_GET_CLIENT_VERSION 10
75 #define QDBI_METHOD_EXECRAW 11
76 #define QDBI_METHOD_STMT_PREPARE 12
77 #define QDBI_METHOD_STMT_PREPARE_RAW 13
78 #define QDBI_METHOD_STMT_BIND 14
79 #define QDBI_METHOD_STMT_BIND_PLACEHOLDERS 15
80 #define QDBI_METHOD_STMT_BIND_VALUES 16
81 #define QDBI_METHOD_STMT_EXEC 17
82 #define QDBI_METHOD_STMT_FETCH_ROW 18
83 #define QDBI_METHOD_STMT_FETCH_ROWS 19
84 #define QDBI_METHOD_STMT_FETCH_COLUMNS 20
85 #define QDBI_METHOD_STMT_NEXT 21
86 #define QDBI_METHOD_STMT_CLOSE 22
87 #define QDBI_METHOD_STMT_AFFECTED_ROWS 23
88 #define QDBI_METHOD_STMT_GET_OUTPUT 24
89 #define QDBI_METHOD_STMT_GET_OUTPUT_ROWS 25
90 #define QDBI_METHOD_STMT_DEFINE 26
91 #define QDBI_METHOD_SELECT_ROW 27
92 #define QDBI_METHOD_OPT_SET 28
93 #define QDBI_METHOD_OPT_GET 29
94 #define QDBI_METHOD_STMT_DESCRIBE 30
95 #define QDBI_METHOD_DESCRIBE 31
96 #define QDBI_METHOD_STMT_FREE 32
97 #define QDBI_METHOD_STMT_EXEC_DESCRIBE 33
98
99 #define QDBI_VALID_CODES 33
100
101 /* DBI EVENT Types
102 all DBI events must have the following keys:
103 - user: db username (if available)
104 - db: db name (if available)
105 - eventtype: integer event code
106 */
107 // warning events have the following additional keys: warning, desc, [info]
108 #define QDBI_EVENT_WARNING 1
109
110 class Datasource;
111 class ExceptionSink;
112 class QoreString;
113 class QoreListNode;
114 class QoreHashNode;
115 class QoreNamespace;
116 class SQLStatement;
117
118 // DBI method signatures - note that only get_client_version uses a "const Datasource"
119 // the others do not so that automatic reconnects can be supported (which will normally
120 // require writing to the Datasource)
121
123
127 typedef int (*q_dbi_open_t)(Datasource* ds, ExceptionSink* xsink);
128
130
134 typedef int (*q_dbi_close_t)(Datasource* ds);
135
137
144 typedef QoreValue (*q_dbi_select_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
145
147
154 typedef QoreValue (*q_dbi_select_rows_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
155
157
165 typedef QoreHashNode* (*q_dbi_select_row_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
166
168
175 typedef QoreValue (*q_dbi_exec_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
176
178
184 typedef QoreValue (*q_dbi_execraw_t)(Datasource* ds, const QoreString* str, ExceptionSink* xsink);
185
187
192 typedef int (*q_dbi_commit_t)(Datasource* ds, ExceptionSink* xsink);
193
195
200 typedef int (*q_dbi_rollback_t)(Datasource* ds, ExceptionSink* xsink);
201
203
208 typedef int (*q_dbi_begin_transaction_t)(Datasource* ds, ExceptionSink* xsink);
209
211
216 typedef QoreValue (*q_dbi_get_server_version_t)(Datasource* ds, ExceptionSink* xsink);
217
219
224 typedef QoreValue (*q_dbi_get_client_version_t)(const Datasource* ds, ExceptionSink* xsink);
225
227
229 typedef int (*q_dbi_stmt_prepare_t)(SQLStatement* stmt, const QoreString& str, const QoreListNode* args, ExceptionSink* xsink);
230
232
234 typedef int (*q_dbi_stmt_prepare_raw_t)(SQLStatement* stmt, const QoreString& str, ExceptionSink* xsink);
235
237
239 typedef int (*q_dbi_stmt_bind_t)(SQLStatement* stmt, const QoreListNode& l, ExceptionSink* xsink);
240
242
244 typedef int (*q_dbi_stmt_exec_t)(SQLStatement* stmt, ExceptionSink* xsink);
245
247
249 typedef int (*q_dbi_stmt_affected_rows_t)(SQLStatement* stmt, ExceptionSink* xsink);
250
252
254 typedef QoreHashNode* (*q_dbi_stmt_get_output_t)(SQLStatement* stmt, ExceptionSink* xsink);
255
257
259 typedef QoreHashNode* (*q_dbi_stmt_get_output_rows_t)(SQLStatement* stmt, ExceptionSink* xsink);
260
261 typedef int (*q_dbi_stmt_define_t)(SQLStatement* stmt, ExceptionSink* xsink);
262 typedef QoreHashNode* (*q_dbi_stmt_fetch_row_t)(SQLStatement* stmt, ExceptionSink* xsink);
263 typedef QoreHashNode* (*q_dbi_stmt_fetch_columns_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
264 typedef QoreListNode* (*q_dbi_stmt_fetch_rows_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
265 typedef bool (*q_dbi_stmt_next_t)(SQLStatement* stmt, ExceptionSink* xsink);
266 typedef int (*q_dbi_stmt_close_t)(SQLStatement* stmt, ExceptionSink* xsink);
267
268 typedef int (*q_dbi_option_set_t)(Datasource* ds, const char* opt, const QoreValue val, ExceptionSink* xsink);
269 typedef QoreValue (*q_dbi_option_get_t)(const Datasource* ds, const char* opt);
270
272
279 typedef QoreHashNode* (*q_dbi_describe_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
280
282 #define DBI_OPT_NUMBER_OPT "optimal-numbers"
284 #define DBI_OPT_NUMBER_STRING "string-numbers"
286 #define DBI_OPT_NUMBER_NUMERIC "numeric-numbers"
288 #define DBI_OPT_TIMEZONE "timezone"
289
291
293 class qore_dbi_method_list {
294 friend struct qore_dbi_mlist_private;
295
296 private:
297 struct qore_dbi_mlist_private* priv; // private implementation
298
299 // not implemented
300 DLLLOCAL qore_dbi_method_list(const qore_dbi_method_list&);
301 DLLLOCAL qore_dbi_method_list& operator=(const qore_dbi_method_list&);
302
303 public:
304 DLLEXPORT qore_dbi_method_list();
305 DLLEXPORT ~qore_dbi_method_list();
306
307 // covers open, commit, rollback, and begin transaction
308 DLLEXPORT void add(int code, q_dbi_open_t method);
309 // for close
310 DLLEXPORT void add(int code, q_dbi_close_t method);
311 // covers select, select_rows, select, and exec
312 DLLEXPORT void add(int code, q_dbi_select_t method);
313 // covers select_row
314 DLLEXPORT void add(int code, q_dbi_select_row_t method);
315 // covers execRaw
316 DLLEXPORT void add(int code, q_dbi_execraw_t method);
317 // covers get_server_version
318 DLLEXPORT void add(int code, q_dbi_get_server_version_t method);
319 // covers get_client_version
320 DLLEXPORT void add(int code, q_dbi_get_client_version_t method);
321
322 // covers prepare
323 DLLEXPORT void add(int code, q_dbi_stmt_prepare_t method);
324 // covers prepare_raw
325 DLLEXPORT void add(int code, q_dbi_stmt_prepare_raw_t method);
326 // covers bind, bind_placeholders, bind_values
327 DLLEXPORT void add(int code, q_dbi_stmt_bind_t method);
328 // covers exec, close, affected_rows, define, and exec_describe
329 DLLEXPORT void add(int code, q_dbi_stmt_exec_t method);
330 // covers fetch_row, get_output, and get_output_rows
331 DLLEXPORT void add(int code, q_dbi_stmt_fetch_row_t method);
332 // covers fetch_columns
333 DLLEXPORT void add(int code, q_dbi_stmt_fetch_columns_t method);
334 // covers fetch_rows
335 DLLEXPORT void add(int code, q_dbi_stmt_fetch_rows_t method);
336 // covers next
337 DLLEXPORT void add(int code, q_dbi_stmt_next_t method);
338
339 // covers set option
340 DLLEXPORT void add(int code, q_dbi_option_set_t method);
341 // covers get option
342 DLLEXPORT void add(int code, q_dbi_option_get_t method);
343
344 // for registering valid options
345 DLLEXPORT void registerOption(const char* name, const char* desc, const QoreTypeInfo* type = 0);
346 };
347
349
354 class DBIDriver {
355 friend struct qore_dbi_private;
356
357 private:
359 struct qore_dbi_private* priv;
360
362 DLLLOCAL DBIDriver(const DBIDriver&);
364 DLLLOCAL DBIDriver& operator=(const DBIDriver&);
365
366 public:
368
371 DLLEXPORT const char* getName() const;
372
374 DLLEXPORT bool hasStatementAPI() const;
375
377
383 DLLEXPORT QoreHashNode* getOptionHash() const;
384
385 DLLLOCAL DBIDriver(struct qore_dbi_private* p);
386 DLLLOCAL ~DBIDriver();
387 };
388
389 struct qore_dbi_dlist_private;
390
392
396 class DBIDriverList {
397 private:
399 struct qore_dbi_dlist_private *priv;
400
401 DLLLOCAL DBIDriver* find_intern(const char* name) const;
402
403 public:
405
412 DLLEXPORT DBIDriver* registerDriver(const char* name, const qore_dbi_method_list &methods, int caps);
413
415
422 DLLEXPORT DBIDriver* find(const char* name) const;
423
425
433 DLLEXPORT DBIDriver* find(const char* name, ExceptionSink* xsink) const;
434
435 DLLLOCAL DBIDriverList();
436 DLLLOCAL ~DBIDriverList();
437 DLLLOCAL QoreListNode* getDriverList() const;
438 };
439
441 DLLEXPORT extern DBIDriverList DBI;
442
444 DLLEXPORT QoreHashNode* parseDatasource(const char* ds, ExceptionSink* xsink);
445
447 DLLEXPORT void DBI_concat_numeric(QoreString* str, QoreValue v);
448
450
453 DLLEXPORT int DBI_concat_string(QoreString* str, QoreValue v, ExceptionSink* xsink);
454
455 #endif // _QORE_DBI_H
q_dbi_rollback_t
int(* q_dbi_rollback_t)(Datasource *ds, ExceptionSink *xsink)
signature for the DBI "rollback" method - must be defined in each DBI driver
Definition: DBI.h:200
q_dbi_get_client_version_t
QoreValue(* q_dbi_get_client_version_t)(const Datasource *ds, ExceptionSink *xsink)
signature for the "get_client_version" method
Definition: DBI.h:224
DBI_concat_numeric
DLLEXPORT void DBI_concat_numeric(QoreString *str, QoreValue v)
concatenates a numeric value to the QoreString from the value
q_dbi_select_row_t
QoreHashNode *(* q_dbi_select_row_t)(Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)
signature for the DBI "selectRow" method - must be defined in each DBI driver
Definition: DBI.h:165
parseDatasource
DLLEXPORT QoreHashNode * parseDatasource(const char *ds, ExceptionSink *xsink)
parses a datasource string and returns a hash of the component parts
q_dbi_exec_t
QoreValue(* q_dbi_exec_t)(Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)
signature for the DBI "execSQL" method - must be defined in each DBI driver
Definition: DBI.h:175
q_dbi_stmt_exec_t
int(* q_dbi_stmt_exec_t)(SQLStatement *stmt, ExceptionSink *xsink)
execute statement
Definition: DBI.h:244
q_dbi_stmt_prepare_raw_t
int(* q_dbi_stmt_prepare_raw_t)(SQLStatement *stmt, const QoreString &str, ExceptionSink *xsink)
prepare statement with no bind parsing
Definition: DBI.h:234
q_dbi_select_t
QoreValue(* q_dbi_select_t)(Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)
signature for the DBI "select" method - must be defined in each DBI driver
Definition: DBI.h:144
q_dbi_select_rows_t
QoreValue(* q_dbi_select_rows_t)(Datasource *ds, const QoreString *str, const QoreListNode *args, ExceptionSink *xsink)
signature for the DBI "selectRows" method - must be defined in each DBI driver
Definition: DBI.h:154
q_dbi_begin_transaction_t
int(* q_dbi_begin_transaction_t)(Datasource *ds, ExceptionSink *xsink)
signature for the DBI "begin_transaction" method, should only be defined for drivers needing this to ...
Definition: DBI.h:208
DBI
DLLEXPORT DBIDriverList DBI
list of DBI drivers currently reigsted by the Qore library
q_dbi_stmt_bind_t
int(* q_dbi_stmt_bind_t)(SQLStatement *stmt, const QoreListNode &l, ExceptionSink *xsink)
bind input values and optionally describe output parameters
Definition: DBI.h:239
q_dbi_commit_t
int(* q_dbi_commit_t)(Datasource *ds, ExceptionSink *xsink)
signature for the DBI "commit" method - must be defined in each DBI driver
Definition: DBI.h:192
q_dbi_open_t
int(* q_dbi_open_t)(Datasource *ds, ExceptionSink *xsink)
signature for the DBI "open" method - must be defined in each DBI driver
Definition: DBI.h:127
q_dbi_close_t
int(* q_dbi_close_t)(Datasource *ds)
signature for the DBI "close" method - must be defined in each DBI driver
Definition: DBI.h:134
q_dbi_get_server_version_t
QoreValue(* q_dbi_get_server_version_t)(Datasource *ds, ExceptionSink *xsink)
signature for the "get_server_version" method
Definition: DBI.h:216
q_dbi_stmt_affected_rows_t
int(* q_dbi_stmt_affected_rows_t)(SQLStatement *stmt, ExceptionSink *xsink)
get number of affected rows
Definition: DBI.h:249
q_dbi_execraw_t
QoreValue(* q_dbi_execraw_t)(Datasource *ds, const QoreString *str, ExceptionSink *xsink)
signature for the DBI "execRawSQL" method - must be defined in each DBI driver
Definition: DBI.h:184
DBI_concat_string
DLLEXPORT int DBI_concat_string(QoreString *str, QoreValue v, ExceptionSink *xsink)
concatenates a string value to the QoreString from the value
q_dbi_stmt_prepare_t
int(* q_dbi_stmt_prepare_t)(SQLStatement *stmt, const QoreString &str, const QoreListNode *args, ExceptionSink *xsink)
prepare statement and process placeholder specifications and bind parameters
Definition: DBI.h:229
DBIDriver
this class provides the internal link to the database driver for Qore's DBI layer
Definition: DBI.h:354
DBIDriver::getName
DLLEXPORT const char * getName() const
this is the only public exported function available in this class
DBIDriver::getOptionHash
DLLEXPORT QoreHashNode * getOptionHash() const
returns the valid options for this driver with descriptions
DBIDriver::hasStatementAPI
DLLEXPORT bool hasStatementAPI() const
returns true if the driver supports the statement API
DBIDriverList
this class is used to register and find DBI drivers loaded in qore
Definition: DBI.h:396
DBIDriverList::find
DLLEXPORT DBIDriver * find(const char *name) const
finds a driver, will try to load the driver using the ModuleManager if no such driver is already pres...
DBIDriverList::registerDriver
DLLEXPORT DBIDriver * registerDriver(const char *name, const qore_dbi_method_list &methods, int caps)
registers a new DBI driver
Datasource
the base class for accessing databases in Qore through a Qore DBI driver
Definition: Datasource.h:55
ExceptionSink
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:48
QoreHashNode
This is the hash or associative list container type in Qore, dynamically allocated only,...
Definition: QoreHashNode.h:50
QoreListNode
This is the list container type in Qore, dynamically allocated only, reference counted.
Definition: QoreListNode.h:52
QoreNamespace
contains constants, classes, and subnamespaces in QoreProgram objects
Definition: QoreNamespace.h:65
QoreString
Qore's string type supported by the QoreEncoding class.
Definition: QoreString.h:93
SQLStatement
This is the public class for DBI drivers supporting Qore's new prepared statement API.
Definition: SQLStatement.h:38
qore_dbi_method_list
this is the data structure Qore DBI drivers will use to pass the supported DBI methods
Definition: DBI.h:293
QoreValue
The main value class in Qore, designed to be passed by value.
Definition: QoreValue.h:275