DBI.h

Go to the documentation of this file.

/* -*- mode: c++; indent-tabs-mode: nil -*- */
/*
    DBI.h

    Qore Programming Language

    Copyright (C) 2003 - 2018 Qore Technologies, s.r.o.

    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 DBI_CAP_HAS_RESULTSET_OUTPUT     (1 << 17) 

#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_GET_SERVER_VERSION        9
#define QDBI_METHOD_GET_CLIENT_VERSION       10
#define QDBI_METHOD_EXECRAW                  11
#define QDBI_METHOD_STMT_PREPARE             12
#define QDBI_METHOD_STMT_PREPARE_RAW         13
#define QDBI_METHOD_STMT_BIND                14
#define QDBI_METHOD_STMT_BIND_PLACEHOLDERS   15
#define QDBI_METHOD_STMT_BIND_VALUES         16
#define QDBI_METHOD_STMT_EXEC                17
#define QDBI_METHOD_STMT_FETCH_ROW           18
#define QDBI_METHOD_STMT_FETCH_ROWS          19
#define QDBI_METHOD_STMT_FETCH_COLUMNS       20
#define QDBI_METHOD_STMT_NEXT                21
#define QDBI_METHOD_STMT_CLOSE               22
#define QDBI_METHOD_STMT_AFFECTED_ROWS       23
#define QDBI_METHOD_STMT_GET_OUTPUT          24
#define QDBI_METHOD_STMT_GET_OUTPUT_ROWS     25
#define QDBI_METHOD_STMT_DEFINE              26
#define QDBI_METHOD_SELECT_ROW               27
#define QDBI_METHOD_OPT_SET                  28
#define QDBI_METHOD_OPT_GET                  29
#define QDBI_METHOD_STMT_DESCRIBE            30
#define QDBI_METHOD_DESCRIBE                 31
#define QDBI_METHOD_STMT_FREE                32
#define QDBI_METHOD_STMT_EXEC_DESCRIBE       33

#define QDBI_VALID_CODES 33

/* 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 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 QoreValue (*q_dbi_select_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);


typedef QoreValue (*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 QoreValue (*q_dbi_exec_t)(Datasource* ds, const QoreString* str, const QoreListNode* args, ExceptionSink* xsink);


typedef QoreValue (*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 QoreValue (*q_dbi_get_server_version_t)(Datasource* ds, ExceptionSink* xsink);


typedef QoreValue (*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 QoreValue val, ExceptionSink* xsink);
typedef QoreValue (*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 hashdecl qore_dbi_mlist_private;

private:
   hashdecl 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, define, and exec_describe
   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 hashdecl qore_dbi_private;

private:
   hashdecl 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();
};

hashdecl qore_dbi_dlist_private;


class DBIDriverList {
private:
   hashdecl 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, QoreValue v);


DLLEXPORT int DBI_concat_string(QoreString* str, QoreValue v, ExceptionSink* xsink);

#endif  // _QORE_DBI_H