DBI.h
Go to the documentation of this file.
/* -*- mode: c++; indent-tabs-mode: nil -*- */
/*
DBI.h
Qore Programming Language
Copyright (C) 2003 - 2015 David Nichols
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
Note that the Qore library is released under a choice of three open-source
licenses: MIT (as above), LGPL 2+, or GPL 2+; see README-LICENSE for more
information.
*/
#ifndef _QORE_DBI_H
#define _QORE_DBI_H
// DBI Driver capabilities
#define DBI_CAP_NONE 0
#define DBI_CAP_TIME_ZONE_SUPPORT (1 << 0)
#define DBI_CAP_CHARSET_SUPPORT (1 << 1)
#define DBI_CAP_TRANSACTION_MANAGEMENT (1 << 2)
#define DBI_CAP_STORED_PROCEDURES (1 << 3)
#define DBI_CAP_LOB_SUPPORT (1 << 4)
#define DBI_CAP_BIND_BY_VALUE (1 << 5)
#define DBI_CAP_BIND_BY_PLACEHOLDER (1 << 6)
#define DBI_CAP_HAS_EXECRAW (1 << 7)
#define DBI_CAP_HAS_STATEMENT (1 << 8)
#define DBI_CAP_HAS_SELECT_ROW (1 << 9)
#define DBI_CAP_HAS_NUMBER_SUPPORT (1 << 10)
#define DBI_CAP_HAS_OPTION_SUPPORT (1 << 11)
#define DBI_CAP_SERVER_TIME_ZONE (1 << 12)
#define DBI_CAP_AUTORECONNECT (1 << 13)
#define DBI_CAP_EVENTS (1 << 14)
#define DBI_CAP_HAS_DESCRIBE (1 << 15)
#define DBI_CAP_HAS_ARRAY_BIND (1 << 16)
#define BN_PLACEHOLDER 0
#define BN_VALUE 1
#define DBI_DEFAULT_STR_LEN 512
// DBI method codes
#define QDBI_METHOD_OPEN 1
#define QDBI_METHOD_CLOSE 2
#define QDBI_METHOD_SELECT 3
#define QDBI_METHOD_SELECT_ROWS 4
#define QDBI_METHOD_EXEC 5
#define QDBI_METHOD_COMMIT 6
#define QDBI_METHOD_ROLLBACK 7
#define QDBI_METHOD_BEGIN_TRANSACTION 8
#define QDBI_METHOD_ABORT_TRANSACTION_START 9
#define QDBI_METHOD_GET_SERVER_VERSION 10
#define QDBI_METHOD_GET_CLIENT_VERSION 11
#define QDBI_METHOD_EXECRAW 12
#define QDBI_METHOD_STMT_PREPARE 13
#define QDBI_METHOD_STMT_PREPARE_RAW 14
#define QDBI_METHOD_STMT_BIND 15
#define QDBI_METHOD_STMT_BIND_PLACEHOLDERS 16
#define QDBI_METHOD_STMT_BIND_VALUES 17
#define QDBI_METHOD_STMT_EXEC 18
#define QDBI_METHOD_STMT_FETCH_ROW 19
#define QDBI_METHOD_STMT_FETCH_ROWS 20
#define QDBI_METHOD_STMT_FETCH_COLUMNS 21
#define QDBI_METHOD_STMT_NEXT 22
#define QDBI_METHOD_STMT_CLOSE 23
#define QDBI_METHOD_STMT_AFFECTED_ROWS 24
#define QDBI_METHOD_STMT_GET_OUTPUT 25
#define QDBI_METHOD_STMT_GET_OUTPUT_ROWS 26
#define QDBI_METHOD_STMT_DEFINE 27
#define QDBI_METHOD_SELECT_ROW 28
#define QDBI_METHOD_OPT_SET 29
#define QDBI_METHOD_OPT_GET 30
#define QDBI_METHOD_STMT_DESCRIBE 31
#define QDBI_METHOD_DESCRIBE 32
#define QDBI_VALID_CODES 32
/* DBI EVENT Types
all DBI events must have the following keys:
- user: db username (if available)
- db: db name (if available)
- eventtype: integer event code
*/
// warning events have the following additional keys: warning, desc, [info]
#define QDBI_EVENT_WARNING 1
class Datasource;
class ExceptionSink;
class QoreString;
class QoreListNode;
class AbstractQoreNode;
class QoreHashNode;
class QoreNamespace;
class SQLStatement;
// DBI method signatures - note that only get_client_version uses a "const Datasource"
// the others do not so that automatic reconnects can be supported (which will normally
// require writing to the Datasource)
typedef int (*q_dbi_open_t)(Datasource* ds, ExceptionSink* xsink);
typedef int (*q_dbi_close_t)(Datasource* ds);
typedef AbstractQoreNode* (*q_dbi_select_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
typedef AbstractQoreNode* (*q_dbi_select_rows_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
typedef QoreHashNode* (*q_dbi_select_row_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
typedef AbstractQoreNode* (*q_dbi_exec_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
typedef AbstractQoreNode* (*q_dbi_execraw_t)(Datasource* ds, const QoreString* str, ExceptionSink* xsink);
typedef int (*q_dbi_commit_t)(Datasource* ds, ExceptionSink* xsink);
typedef int (*q_dbi_rollback_t)(Datasource* ds, ExceptionSink* xsink);
typedef int (*q_dbi_begin_transaction_t)(Datasource* ds, ExceptionSink* xsink);
typedef int (*q_dbi_abort_transaction_start_t)(Datasource* ds, ExceptionSink* xsink);
typedef AbstractQoreNode* (*q_dbi_get_server_version_t)(Datasource* ds, ExceptionSink* xsink);
typedef AbstractQoreNode* (*q_dbi_get_client_version_t)(const Datasource* ds, ExceptionSink* xsink);
// FIXME: document
typedef int (*q_dbi_stmt_prepare_t)(SQLStatement* stmt, const QoreString& str, const QoreListNode* args, ExceptionSink* xsink);
typedef int (*q_dbi_stmt_prepare_raw_t)(SQLStatement* stmt, const QoreString& str, ExceptionSink* xsink);
typedef int (*q_dbi_stmt_bind_t)(SQLStatement* stmt, const QoreListNode& l, ExceptionSink* xsink);
typedef int (*q_dbi_stmt_exec_t)(SQLStatement* stmt, ExceptionSink* xsink);
typedef int (*q_dbi_stmt_affected_rows_t)(SQLStatement* stmt, ExceptionSink* xsink);
typedef QoreHashNode* (*q_dbi_stmt_get_output_t)(SQLStatement* stmt, ExceptionSink* xsink);
typedef QoreHashNode* (*q_dbi_stmt_get_output_rows_t)(SQLStatement* stmt, ExceptionSink* xsink);
typedef int (*q_dbi_stmt_define_t)(SQLStatement* stmt, ExceptionSink* xsink);
typedef QoreHashNode* (*q_dbi_stmt_fetch_row_t)(SQLStatement* stmt, ExceptionSink* xsink);
typedef QoreHashNode* (*q_dbi_stmt_fetch_columns_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
typedef QoreListNode* (*q_dbi_stmt_fetch_rows_t)(SQLStatement* stmt, int rows, ExceptionSink* xsink);
typedef bool (*q_dbi_stmt_next_t)(SQLStatement* stmt, ExceptionSink* xsink);
typedef int (*q_dbi_stmt_close_t)(SQLStatement* stmt, ExceptionSink* xsink);
typedef int (*q_dbi_option_set_t)(Datasource* ds, const char* opt, const AbstractQoreNode* val, ExceptionSink* xsink);
typedef AbstractQoreNode* (*q_dbi_option_get_t)(const Datasource* ds, const char* opt);
typedef QoreHashNode* (*q_dbi_describe_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);
#define DBI_OPT_NUMBER_OPT "optimal-numbers"
#define DBI_OPT_NUMBER_STRING "string-numbers"
#define DBI_OPT_NUMBER_NUMERIC "numeric-numbers"
#define DBI_OPT_TIMEZONE "timezone"
class qore_dbi_method_list {
friend struct qore_dbi_mlist_private;
private:
struct qore_dbi_mlist_private* priv; // private implementation
// not implemented
DLLLOCAL qore_dbi_method_list(const qore_dbi_method_list&);
DLLLOCAL qore_dbi_method_list& operator=(const qore_dbi_method_list&);
public:
DLLEXPORT qore_dbi_method_list();
DLLEXPORT ~qore_dbi_method_list();
// covers open, commit, rollback, and begin transaction
DLLEXPORT void add(int code, q_dbi_open_t method);
// for close
DLLEXPORT void add(int code, q_dbi_close_t method);
// covers select, select_rows, select, and exec
DLLEXPORT void add(int code, q_dbi_select_t method);
// covers select_row
DLLEXPORT void add(int code, q_dbi_select_row_t method);
// covers execRaw
DLLEXPORT void add(int code, q_dbi_execraw_t method);
// covers get_server_version
DLLEXPORT void add(int code, q_dbi_get_server_version_t method);
// covers get_client_version
DLLEXPORT void add(int code, q_dbi_get_client_version_t method);
// covers prepare
DLLEXPORT void add(int code, q_dbi_stmt_prepare_t method);
// covers prepare_raw
DLLEXPORT void add(int code, q_dbi_stmt_prepare_raw_t method);
// covers bind, bind_placeholders, bind_values
DLLEXPORT void add(int code, q_dbi_stmt_bind_t method);
// covers exec, close, affected_rows, and define
DLLEXPORT void add(int code, q_dbi_stmt_exec_t method);
// covers fetch_row, get_output, and get_output_rows
DLLEXPORT void add(int code, q_dbi_stmt_fetch_row_t method);
// covers fetch_columns
DLLEXPORT void add(int code, q_dbi_stmt_fetch_columns_t method);
// covers fetch_rows
DLLEXPORT void add(int code, q_dbi_stmt_fetch_rows_t method);
// covers next
DLLEXPORT void add(int code, q_dbi_stmt_next_t method);
// covers set option
DLLEXPORT void add(int code, q_dbi_option_set_t method);
// covers get option
DLLEXPORT void add(int code, q_dbi_option_get_t method);
// for registering valid options
DLLEXPORT void registerOption(const char* name, const char* desc, const QoreTypeInfo* type = 0);
};
class DBIDriver {
friend struct qore_dbi_private;
private:
struct qore_dbi_private* priv;
DLLLOCAL DBIDriver(const DBIDriver&);
DLLLOCAL DBIDriver& operator=(const DBIDriver&);
public:
DLLEXPORT const char* getName() const;
DLLEXPORT bool hasStatementAPI() const;
DLLEXPORT QoreHashNode* getOptionHash() const;
DLLLOCAL DBIDriver(struct qore_dbi_private* p);
DLLLOCAL ~DBIDriver();
};
struct qore_dbi_dlist_private;
class DBIDriverList {
private:
struct qore_dbi_dlist_private *priv;
DLLLOCAL DBIDriver* find_intern(const char* name) const;
public:
DLLEXPORT DBIDriver* registerDriver(const char* name, const qore_dbi_method_list &methods, int caps);
DLLEXPORT DBIDriver* find(const char* name) const;
DLLEXPORT DBIDriver* find(const char* name, ExceptionSink* xsink) const;
DLLLOCAL DBIDriverList();
DLLLOCAL ~DBIDriverList();
DLLLOCAL QoreListNode* getDriverList() const;
};
DLLEXPORT extern DBIDriverList DBI;
DLLEXPORT QoreHashNode* parseDatasource(const char* ds, ExceptionSink* xsink);
DLLEXPORT void DBI_concat_numeric(QoreString* str, const AbstractQoreNode* v);
DLLEXPORT int DBI_concat_string(QoreString* str, const AbstractQoreNode* v, ExceptionSink* xsink);
#endif // _QORE_DBI_H
q_dbi_execraw_t
AbstractQoreNode *(* 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:182
q_dbi_abort_transaction_start_t
int(* q_dbi_abort_transaction_start_t)(Datasource *ds, ExceptionSink *xsink)
signature for the rollback method to be executed when the first statement in an explicit transaction ...
Definition: DBI.h:216
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:132
QoreHashNode
This is the hash or associative list container type in Qore, dynamically allocated only...
Definition: QoreHashNode.h:49
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:248
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:163
q_dbi_get_client_version_t
AbstractQoreNode *(* q_dbi_get_client_version_t)(const Datasource *ds, ExceptionSink *xsink)
signature for the "get_client_version" method
Definition: DBI.h:232
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:206
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:243
AbstractQoreNode
The base class for all value and parse types in Qore expression trees.
Definition: AbstractQoreNode.h:55
QoreNamespace
contains constants, classes, and subnamespaces in QoreProgram objects
Definition: QoreNamespace.h:58
DBIDriver
this class provides the internal link to the database driver for Qore's DBI layer ...
Definition: DBI.h:359
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:125
DBIDriver::hasStatementAPI
DLLEXPORT bool hasStatementAPI() const
returns true if the driver supports the statement API
q_dbi_select_t
AbstractQoreNode *(* 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:142
DBIDriver::getOptionHash
DLLEXPORT QoreHashNode * getOptionHash() const
returns the valid options for this driver with descriptions
QoreString
Qore's string type supported by the QoreEncoding class.
Definition: QoreString.h:82
QoreListNode
This is the list container type in Qore, dynamically allocated only, reference counted.
Definition: QoreListNode.h:52
DBI
DLLEXPORT DBIDriverList DBI
list of DBI drivers currently reigsted by the Qore library
Datasource
the base class for accessing databases in Qore through a Qore DBI driver
Definition: Datasource.h:54
DBIDriver::getName
DLLEXPORT const char * getName() const
this is the only public exported function available in this class
qore_dbi_method_list
this is the data structure Qore DBI drivers will use to pass the supported DBI methods ...
Definition: DBI.h:298
SQLStatement
This is the public class for DBI drivers supporting Qore's new prepared statement API...
Definition: SQLStatement.h:40
q_dbi_stmt_exec_t
int(* q_dbi_stmt_exec_t)(SQLStatement *stmt, ExceptionSink *xsink)
execute statement
Definition: DBI.h:253
ExceptionSink
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:43
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:198
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:238
DBIDriverList::registerDriver
DLLEXPORT DBIDriver * registerDriver(const char *name, const qore_dbi_method_list &methods, int caps)
registers a new DBI driver
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:190
DBIDriverList
this class is used to register and find DBI drivers loaded in qore
Definition: DBI.h:401
q_dbi_get_server_version_t
AbstractQoreNode *(* q_dbi_get_server_version_t)(Datasource *ds, ExceptionSink *xsink)
signature for the "get_server_version" method
Definition: DBI.h:224
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:258
parseDatasource
DLLEXPORT QoreHashNode * parseDatasource(const char *ds, ExceptionSink *xsink)
parses a datasource string and returns a hash of the component parts
DBI_concat_numeric
DLLEXPORT void DBI_concat_numeric(QoreString *str, const AbstractQoreNode *v)
concatenates a numeric value to the QoreString from the QoreNode
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...
DBI_concat_string
DLLEXPORT int DBI_concat_string(QoreString *str, const AbstractQoreNode *v, ExceptionSink *xsink)
concatenates a string value to the QoreString from the AbstractQoreNode