1

#ifndef EVSQL_H

     2

#define EVSQL_H

     3

     4

/*

     5

 * An event-based (Postgre)SQL client API using libevent

     6

 */

     7

     8

// XXX: libpq

     9

#include <postgresql/libpq-fe.h>

    10

#include <event2/event.h>

    11

    12

/*

    13

 * The generic context handle

    14

 */

    15

struct evsql;

    16

    17

/*

    18

 * A query handle

    19

 */

    20

struct evsql_query;

    21

    22

/*

    23

 * Transaction handle

    24

 */

    25

struct evsql_trans;

    26

    27

/*

    28

 * Transaction type

    29

 */

    30

enum evsql_trans_type {

    31

    EVSQL_TRANS_DEFAULT,

    32

    EVSQL_TRANS_SERIALIZABLE,

    33

    EVSQL_TRANS_REPEATABLE_READ,

    34

    EVSQL_TRANS_READ_COMMITTED,

    35

    EVSQL_TRANS_READ_UNCOMMITTED,

    36

};

    37

    38

/*

    39

 * Parameter type

    40

 */

    41

enum evsql_param_format {

    42

    EVSQL_FMT_TEXT,

    43

    EVSQL_FMT_BINARY,

    44

};

    45

    46

enum evsql_param_type {

    47

    EVSQL_PARAM_INVALID,

    48

    49

    EVSQL_PARAM_NULL,

    50

    51

    EVSQL_PARAM_STRING,

    52

    EVSQL_PARAM_UINT16,

    53

    EVSQL_PARAM_UINT32,

    54

    EVSQL_PARAM_UINT64,

    55

};

    56

    57

/*

    58

 * Query parameter info.

    59

 *

    60

 * Use the EVSQL_PARAM_* macros to define the value of list

    61

 */

    62

struct evsql_query_params {

    63

    // nonzero to get results in binary format

    64

    enum evsql_param_format result_fmt;

    65

    66

    // the list of parameters, terminated by { 0, 0 }

    67

    struct evsql_query_param {

    68

        // the param type

    69

        enum evsql_param_type type;

    70

    71

        // pointer to the raw data

    72

        const char *data_raw;

    73

    74

        // the value

    75

        union {

    76

            uint16_t uint16;

    77

            uint32_t uint32;

    78

            uint64_t uint64;

    79

        } data;

    80

    81

        // the explicit length of the parameter if it's binary, zero for text.

    82

        // set to -1 to indicate that the value is still missing

    83

        ssize_t length;

    84

    } list[];

    85

};

    86

    87

// macros for defining evsql_query_params

    88

#define EVSQL_PARAMS(result_fmt)            { result_fmt, 

    89

#define EVSQL_PARAM(typenam)                    { EVSQL_PARAM_ ## typenam, NULL }

    90

#define EVSQL_PARAMS_END                        { EVSQL_PARAM_INVALID, NULL } \

    91

                                              } // <<<

    92

    93

/*

    94

 * Result type

    95

 */

    96

struct evsql_result_info {

    97

    struct evsql *evsql;

    98

    struct evsql_trans *trans;

    99

   100

    int error;

   101

   102

    union evsql_result {

   103

        // libpq

   104

        PGresult *pq;

   105

    } result;

   106

};

   107

   108

/*

   109

 * Callback for handling query results.

   110

 *

   111

 * The query has completed, either succesfully or unsuccesfully (nonzero .error).

   112

 *

   113

 * Use the evsql_result_* functions to manipulate the results.

   114

 */

   115

typedef void (*evsql_query_cb)(const struct evsql_result_info *res, void *arg);

   116

   117

/*

   118

 * Callback for handling global-level errors.

   119

 *

   120

 * The evsql is not useable anymore.

   121

 *

   122

 * XXX: this is not actually called yet, no retry logic implemented.

   123

 */

   124

typedef void (*evsql_error_cb)(struct evsql *evsql, void *arg);

   125

   126

/*

   127

 * Callback for handling transaction-level errors.

   128

 *

   129

 * The transaction is not useable anymore.

   130

 */

   131

typedef void (*evsql_trans_error_cb)(struct evsql_trans *trans, void *arg);

   132

   133

/*

   134

 * The transaction is ready for use.

   135

 */

   136

typedef void (*evsql_trans_ready_cb)(struct evsql_trans *trans, void *arg);

   137

   138

/*

   139

 * The transaction was commited, and should not be used anymore.

   140

 */

   141

typedef void (*evsql_trans_done_cb)(struct evsql_trans *trans, void *arg);

   142

   143

/*

   144

 * Create a new PostgreSQL/libpq(evpq) -based evsql using the given conninfo.

   145

 *

   146

 * The given conninfo must stay valid for the duration of the evsql's lifetime.

   147

 */

   148

struct evsql *evsql_new_pq (struct event_base *ev_base, const char *pq_conninfo, evsql_error_cb error_fn, void *cb_arg);

   149

   150

/*

   151

 * Create a new transaction.

   152

 *

   153

 * Transactions are separate connections that provide transaction-isolation.

   154

 *

   155

 * Once the transaction is ready for use, ready_fn will be called. If the transaction fails, any pending query will be

   156

 * forgotten, and error_fn called. This also includes some (but not all) cases where evsql_query returns nonzero.

   157

 *

   158

 */

   159

struct evsql_trans *evsql_trans (struct evsql *evsql, enum evsql_trans_type type, evsql_trans_error_cb error_fn, evsql_trans_ready_cb ready_fn, evsql_trans_done_cb done_fn, void *cb_arg);

   160

   161

/*

   162

 * Queue the given query for execution.

   163

 *

   164

 * If trans is specified (not NULL), then the transaction must be idle, and the query will be executed in that

   165

 * transaction's context. Otherwise, the query will be executed without a transaction, andmay be executed immediately,

   166

 * or if other similar queries are running, it will be queued for later execution.

   167

 *

   168

 * Once the query is complete (got a result, got an error, the connection failed), then the query_cb will be triggered.

   169

 */

   170

struct evsql_query *evsql_query (struct evsql *evsql, struct evsql_trans *trans, const char *command, evsql_query_cb query_fn, void *cb_arg);

   171

   172

/*

   173

 * Same as evsql_query, but uses the SQL-level support for binding parameters.

   174

 */

   175

struct evsql_query *evsql_query_params (struct evsql *evsql, struct evsql_trans *trans, const char *command, const struct evsql_query_params *params, evsql_query_cb query_fn, void *cb_arg);

   176

   177

/*

   188

 * Commit a transaction, calling done_fn if it was succesfull (error_fn otherwise).

   193

 */

   194

int evsql_trans_commit (struct evsql_trans *trans);

   195

   196

/*

   200

 */

   202

   203

/*

   204

 * Transaction-handling functions

   205

 */

   206

   207

// error string, meant to be called from evsql_trans_error_cb

   208

const char *evsql_trans_error (struct evsql_trans *trans);

   209

   210

// commit the transaction, calling 

   211

   212

/*

   213

 * Param-building functions

   214

 */

   215

int evsql_param_string (struct evsql_query_params *params, size_t param, const char *ptr);

   216

int evsql_param_uint32 (struct evsql_query_params *params, size_t param, uint32_t uval);

   217

   218

/*

   219

 * Result-handling functions

   220

 */

   221

   222

// get error message associated with function

   223

const char *evsql_result_error (const struct evsql_result_info *res);

   224

   225

// number of rows in the result

   226

size_t evsql_result_rows (const struct evsql_result_info *res);

   227

   228

// number of columns in the result

   229

size_t evsql_result_cols (const struct evsql_result_info *res);

   230

   231

// fetch the raw binary value from a result set, and return it via ptr

   232

// if size is nonzero, check that the size of the field data matches

   233

int evsql_result_binary (const struct evsql_result_info *res, size_t row, size_t col, const char **ptr, size_t size, int nullok);

   234

int evsql_result_string (const struct evsql_result_info *res, size_t row, size_t col, const char **ptr, int nullok);

   235

   236

// fetch certain kinds of values from a binary result set

   237

int evsql_result_uint16 (const struct evsql_result_info *res, size_t row, size_t col, uint16_t *uval, int nullok);

   238

int evsql_result_uint32 (const struct evsql_result_info *res, size_t row, size_t col, uint32_t *uval, int nullok);

   239

int evsql_result_uint64 (const struct evsql_result_info *res, size_t row, size_t col, uint64_t *uval, int nullok);

   240

   241

// release the result set, freeing its memory

   242

void evsql_result_free (const struct evsql_result_info *res);

   243

   244

// platform-dependant aliases

   245

#define evsql_result_ushort evsql_result_uint16

   246

   247

#if _LP64

   248

#define evsql_result_ulong evsql_result_uint64

   249

#else

   250

#define evsql_result_ulong evsql_result_uint32

   251

#endif /* _LP64 */

   252

   253

/*

   254

 * Close a connection. Callbacks for waiting queries will not be run.

   255

 *

   256

 * XXX: not implemented yet.

   257

 */

   258

void evsql_close (struct evsql *evsql);

   259

   260

#endif /* EVSQL_H */