$darkmode
Qore Programming Language - C/C++ Library 1.19.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 - 2023 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 
35 #include <string>
36 
38 
39 // DBI Driver capabilities
40 #define DBI_CAP_NONE 0
41 #define DBI_CAP_TIME_ZONE_SUPPORT (1 << 0)
42 #define DBI_CAP_CHARSET_SUPPORT (1 << 1)
43 #define DBI_CAP_TRANSACTION_MANAGEMENT (1 << 2)
44 #define DBI_CAP_STORED_PROCEDURES (1 << 3)
45 #define DBI_CAP_LOB_SUPPORT (1 << 4)
46 #define DBI_CAP_BIND_BY_VALUE (1 << 5)
47 #define DBI_CAP_BIND_BY_PLACEHOLDER (1 << 6)
48 #define DBI_CAP_HAS_EXECRAW (1 << 7)
49 #define DBI_CAP_HAS_STATEMENT (1 << 8)
50 #define DBI_CAP_HAS_SELECT_ROW (1 << 9)
51 #define DBI_CAP_HAS_NUMBER_SUPPORT (1 << 10)
52 #define DBI_CAP_HAS_OPTION_SUPPORT (1 << 11)
53 #define DBI_CAP_SERVER_TIME_ZONE (1 << 12)
54 #define DBI_CAP_AUTORECONNECT (1 << 13)
55 #define DBI_CAP_EVENTS (1 << 14)
56 #define DBI_CAP_HAS_DESCRIBE (1 << 15)
57 #define DBI_CAP_HAS_ARRAY_BIND (1 << 16)
58 #define DBI_CAP_HAS_RESULTSET_OUTPUT (1 << 17)
59 #define DBI_CAP_OPTION_PASSTHRU (1 << 18)
60 
61 #define BN_PLACEHOLDER 0
62 #define BN_VALUE 1
63 
64 #define DBI_DEFAULT_STR_LEN 512
65 
66 // DBI method codes
67 #define QDBI_METHOD_OPEN 1
68 #define QDBI_METHOD_CLOSE 2
69 #define QDBI_METHOD_SELECT 3
70 #define QDBI_METHOD_SELECT_ROWS 4
71 #define QDBI_METHOD_EXEC 5
72 #define QDBI_METHOD_COMMIT 6
73 #define QDBI_METHOD_ROLLBACK 7
74 #define QDBI_METHOD_BEGIN_TRANSACTION 8
75 #define QDBI_METHOD_GET_SERVER_VERSION 9
76 #define QDBI_METHOD_GET_CLIENT_VERSION 10
77 #define QDBI_METHOD_EXECRAW 11
78 #define QDBI_METHOD_STMT_PREPARE 12
79 #define QDBI_METHOD_STMT_PREPARE_RAW 13
80 #define QDBI_METHOD_STMT_BIND 14
81 #define QDBI_METHOD_STMT_BIND_PLACEHOLDERS 15
82 #define QDBI_METHOD_STMT_BIND_VALUES 16
83 #define QDBI_METHOD_STMT_EXEC 17
84 #define QDBI_METHOD_STMT_FETCH_ROW 18
85 #define QDBI_METHOD_STMT_FETCH_ROWS 19
86 #define QDBI_METHOD_STMT_FETCH_COLUMNS 20
87 #define QDBI_METHOD_STMT_NEXT 21
88 #define QDBI_METHOD_STMT_CLOSE 22
89 #define QDBI_METHOD_STMT_AFFECTED_ROWS 23
90 #define QDBI_METHOD_STMT_GET_OUTPUT 24
91 #define QDBI_METHOD_STMT_GET_OUTPUT_ROWS 25
92 #define QDBI_METHOD_STMT_DEFINE 26
93 #define QDBI_METHOD_SELECT_ROW 27
94 #define QDBI_METHOD_OPT_SET 28
95 #define QDBI_METHOD_OPT_GET 29
96 #define QDBI_METHOD_STMT_DESCRIBE 30
97 #define QDBI_METHOD_DESCRIBE 31
98 #define QDBI_METHOD_STMT_FREE 32
99 #define QDBI_METHOD_STMT_EXEC_DESCRIBE 33
100 #define QDBI_METHOD_GET_DRIVER_REAL_NAME 34
101 
102 #define QDBI_VALID_CODES 34
103 
104 /* DBI EVENT Types
105  all DBI events must have the following keys:
106  - user: db username (if available)
107  - db: db name (if available)
108  - eventtype: integer event code
109 */
110 // warning events have the following additional keys: warning, desc, [info]
111 #define QDBI_EVENT_WARNING 1
112 
113 class Datasource;
114 class ExceptionSink;
115 class QoreString;
116 class QoreListNode;
117 class QoreHashNode;
118 class QoreNamespace;
119 class SQLStatement;
120 
121 // DBI method signatures - note that only get_client_version uses a "const Datasource"
122 // the others do not so that automatic reconnects can be supported (which will normally
123 // require writing to the Datasource)
124 
126 
130 typedef int (*q_dbi_open_t)(Datasource* ds, ExceptionSink* xsink);
131 
133 
137 typedef int (*q_dbi_close_t)(Datasource* ds);
138 
140 
147 typedef QoreValue (*q_dbi_select_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
148 
150 
157 typedef QoreValue (*q_dbi_select_rows_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
158 
160 
168 typedef QoreHashNode* (*q_dbi_select_row_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
169 
171 
178 typedef QoreValue (*q_dbi_exec_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
179 
181 
187 typedef QoreValue (*q_dbi_execraw_t)(Datasource* ds, const QoreString* str, ExceptionSink* xsink);
188 
190 
195 typedef int (*q_dbi_commit_t)(Datasource* ds, ExceptionSink* xsink);
196 
198 
203 typedef int (*q_dbi_rollback_t)(Datasource* ds, ExceptionSink* xsink);
204 
206 
212 
214 
220 
222 
228 
230 
235 typedef QoreStringNode* (*q_dbi_get_driver_real_name_t)(Datasource* ds, ExceptionSink* xsink);
236 
238 
240 typedef int (*q_dbi_stmt_prepare_t)(SQLStatement* stmt, const QoreString& str, const QoreListNode* args, ExceptionSink* xsink);
241 
243 
245 typedef int (*q_dbi_stmt_prepare_raw_t)(SQLStatement* stmt, const QoreString& str, ExceptionSink* xsink);
246 
248 
250 typedef int (*q_dbi_stmt_bind_t)(SQLStatement* stmt, const QoreListNode& l, ExceptionSink* xsink);
251 
253 
255 typedef int (*q_dbi_stmt_exec_t)(SQLStatement* stmt, ExceptionSink* xsink);
256 
258 
261 
263 
265 typedef QoreHashNode* (*q_dbi_stmt_get_output_t)(SQLStatement* stmt, ExceptionSink* xsink);
266 
268 
270 typedef QoreHashNode* (*q_dbi_stmt_get_output_rows_t)(SQLStatement* stmt, ExceptionSink* xsink);
271 
272 typedef int (*q_dbi_stmt_define_t)(SQLStatement* stmt, ExceptionSink* xsink);
273 typedef QoreHashNode* (*q_dbi_stmt_fetch_row_t)(SQLStatement* stmt, ExceptionSink* xsink);
274 typedef QoreHashNode* (*q_dbi_stmt_fetch_columns_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
275 typedef QoreListNode* (*q_dbi_stmt_fetch_rows_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
276 typedef bool (*q_dbi_stmt_next_t)(SQLStatement* stmt, ExceptionSink* xsink);
277 typedef int (*q_dbi_stmt_close_t)(SQLStatement* stmt, ExceptionSink* xsink);
278 
279 typedef int (*q_dbi_option_set_t)(Datasource* ds, const char* opt, const QoreValue val, ExceptionSink* xsink);
280 typedef QoreValue (*q_dbi_option_get_t)(const Datasource* ds, const char* opt);
281 
283 
290 typedef QoreHashNode* (*q_dbi_describe_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
291 
293 #define DBI_OPT_NUMBER_OPT "optimal-numbers"
295 #define DBI_OPT_NUMBER_STRING "string-numbers"
297 #define DBI_OPT_NUMBER_NUMERIC "numeric-numbers"
299 #define DBI_OPT_TIMEZONE "timezone"
300 
302 
305  friend struct qore_dbi_mlist_private;
306 
307 private:
308  struct qore_dbi_mlist_private* priv; // private implementation
309 
310  // not implemented
312  DLLLOCAL qore_dbi_method_list& operator=(const qore_dbi_method_list&);
313 
314 public:
315  DLLEXPORT qore_dbi_method_list();
316  DLLEXPORT ~qore_dbi_method_list();
317 
318  // covers open, commit, rollback, and begin transaction
319  DLLEXPORT void add(int code, q_dbi_open_t method);
320  // for close
321  DLLEXPORT void add(int code, q_dbi_close_t method);
322  // covers select, select_rows, select, and exec
323  DLLEXPORT void add(int code, q_dbi_select_t method);
324  // covers select_row
325  DLLEXPORT void add(int code, q_dbi_select_row_t method);
326  // covers execRaw
327  DLLEXPORT void add(int code, q_dbi_execraw_t method);
328  // covers get_server_version
329  DLLEXPORT void add(int code, q_dbi_get_server_version_t method);
330  // covers get_client_version
331  DLLEXPORT void add(int code, q_dbi_get_client_version_t method);
332  // covers get_driver_real_name
333  DLLEXPORT void add(int code, q_dbi_get_driver_real_name_t method);
334 
335  // covers prepare
336  DLLEXPORT void add(int code, q_dbi_stmt_prepare_t method);
337  // covers prepare_raw
338  DLLEXPORT void add(int code, q_dbi_stmt_prepare_raw_t method);
339  // covers bind, bind_placeholders, bind_values
340  DLLEXPORT void add(int code, q_dbi_stmt_bind_t method);
341  // covers exec, close, affected_rows, define, and exec_describe
342  DLLEXPORT void add(int code, q_dbi_stmt_exec_t method);
343  // covers fetch_row, get_output, and get_output_rows
344  DLLEXPORT void add(int code, q_dbi_stmt_fetch_row_t method);
345  // covers fetch_columns
346  DLLEXPORT void add(int code, q_dbi_stmt_fetch_columns_t method);
347  // covers fetch_rows
348  DLLEXPORT void add(int code, q_dbi_stmt_fetch_rows_t method);
349  // covers next
350  DLLEXPORT void add(int code, q_dbi_stmt_next_t method);
351 
352  // covers set option
353  DLLEXPORT void add(int code, q_dbi_option_set_t method);
354  // covers get option
355  DLLEXPORT void add(int code, q_dbi_option_get_t method);
356 
357  // for registering valid options
358  DLLEXPORT void registerOption(const char* name, const char* desc, const QoreTypeInfo* type = 0);
359 };
360 
362 
367 class DBIDriver {
368  friend struct qore_dbi_private;
369 
370 private:
372  struct qore_dbi_private* priv;
373 
375  DLLLOCAL DBIDriver(const DBIDriver&);
377  DLLLOCAL DBIDriver& operator=(const DBIDriver&);
378 
379 public:
381 
384  DLLEXPORT const char* getName() const;
385 
387  DLLEXPORT bool hasStatementAPI() const;
388 
390 
396  DLLEXPORT QoreHashNode* getOptionHash() const;
397 
398  DLLLOCAL DBIDriver(struct qore_dbi_private* p);
399  DLLLOCAL ~DBIDriver();
400 };
401 
402 struct qore_dbi_dlist_private;
403 
405 
410 private:
412  struct qore_dbi_dlist_private *priv;
413 
414  DLLLOCAL DBIDriver* find_intern(const char* name) const;
415 
416 public:
418 
425  DLLEXPORT DBIDriver* registerDriver(const char* name, const qore_dbi_method_list &methods, int caps);
426 
428 
435  DLLEXPORT DBIDriver* find(const char* name) const;
436 
438 
446  DLLEXPORT DBIDriver* find(const char* name, ExceptionSink* xsink) const;
447 
448  DLLLOCAL DBIDriverList();
449  DLLLOCAL ~DBIDriverList();
450  DLLLOCAL QoreListNode* getDriverList() const;
451 };
452 
454 DLLEXPORT extern DBIDriverList DBI;
455 
457 DLLEXPORT QoreHashNode* parseDatasource(const char* ds, ExceptionSink* xsink);
458 
460 DLLEXPORT void DBI_concat_numeric(QoreString* str, QoreValue v);
461 
463 
466 DLLEXPORT int DBI_concat_string(QoreString* str, QoreValue v, ExceptionSink* xsink);
467 
468 #endif // _QORE_DBI_H
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:203
QoreValue(* q_dbi_get_client_version_t)(const Datasource *ds, ExceptionSink *xsink)
signature for the "get_client_version" method
Definition: DBI.h:227
QoreStringNode *(* q_dbi_get_driver_real_name_t)(Datasource *ds, ExceptionSink *xsink)
signature for the "get_driver_real_name" method
Definition: DBI.h:235
DLLEXPORT void DBI_concat_numeric(QoreString *str, QoreValue v)
concatenates a numeric value to the QoreString from the value
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:168
DLLEXPORT QoreHashNode * parseDatasource(const char *ds, ExceptionSink *xsink)
parses a datasource string and returns a hash of the component parts
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:178
int(* q_dbi_stmt_exec_t)(SQLStatement *stmt, ExceptionSink *xsink)
execute statement
Definition: DBI.h:255
int(* q_dbi_stmt_prepare_raw_t)(SQLStatement *stmt, const QoreString &str, ExceptionSink *xsink)
prepare statement with no bind parsing
Definition: DBI.h:245
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:147
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:157
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:211
DLLEXPORT DBIDriverList DBI
list of DBI drivers currently reigsted by the Qore library
int(* q_dbi_stmt_bind_t)(SQLStatement *stmt, const QoreListNode &l, ExceptionSink *xsink)
bind input values and optionally describe output parameters
Definition: DBI.h:250
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:195
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:130
int(* q_dbi_close_t)(Datasource *ds)
signature for the DBI "close" method - must be defined in each DBI driver
Definition: DBI.h:137
QoreValue(* q_dbi_get_server_version_t)(Datasource *ds, ExceptionSink *xsink)
signature for the "get_server_version" method
Definition: DBI.h:219
int(* q_dbi_stmt_affected_rows_t)(SQLStatement *stmt, ExceptionSink *xsink)
get number of affected rows
Definition: DBI.h:260
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:187
DLLEXPORT int DBI_concat_string(QoreString *str, QoreValue v, ExceptionSink *xsink)
concatenates a string value to the QoreString from the value
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:240
this class provides the internal link to the database driver for Qore's DBI layer
Definition: DBI.h:367
DLLEXPORT const char * getName() const
this is the only public exported function available in this class
DLLEXPORT QoreHashNode * getOptionHash() const
returns the valid options for this driver with descriptions
DLLEXPORT bool hasStatementAPI() const
returns true if the driver supports the statement API
this class is used to register and find DBI drivers loaded in qore
Definition: DBI.h:409
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...
DLLEXPORT DBIDriver * registerDriver(const char *name, const qore_dbi_method_list &methods, int caps)
registers a new DBI driver
the base class for accessing databases in Qore through a Qore DBI driver
Definition: Datasource.h:55
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:50
This is the hash or associative list container type in Qore, dynamically allocated only,...
Definition: QoreHashNode.h:50
This is the list container type in Qore, dynamically allocated only, reference counted.
Definition: QoreListNode.h:52
contains constants, classes, and subnamespaces in QoreProgram objects
Definition: QoreNamespace.h:65
Qore's string type supported by the QoreEncoding class.
Definition: QoreString.h:93
Qore's string value type, reference counted, dynamically-allocated only.
Definition: QoreStringNode.h:50
This is the public class for DBI drivers supporting Qore's new prepared statement API.
Definition: SQLStatement.h:38
this is the data structure Qore DBI drivers will use to pass the supported DBI methods
Definition: DBI.h:304
The main value class in Qore, designed to be passed by value.
Definition: QoreValue.h:276