1

#ifndef EVSQL_H

     2

#define EVSQL_H

     3

     4

/*

     5

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

     6

 */

     7

     8

#include <stdint.h>

     9

#include <event2/event.h>

    10

    12

    13

/*

    14

 * The generic context handle

    15

 */

    16

struct evsql;

    17

    18

/*

    19

 * Transaction handle

    20

 */

    21

struct evsql_trans;

    22

    23

/*

    24

 * A query handle

    25

 */

    26

struct evsql_query;

    27

    28

/*

    29

 * A result handle

    30

 */

    31

struct evsql_result;

    32

    33

    34

/*

    35

 * Transaction type

    36

 */

    37

enum evsql_trans_type {

    38

    EVSQL_TRANS_DEFAULT,

    39

    EVSQL_TRANS_SERIALIZABLE,

    40

    EVSQL_TRANS_REPEATABLE_READ,

    41

    EVSQL_TRANS_READ_COMMITTED,

    42

    EVSQL_TRANS_READ_UNCOMMITTED,

    43

};

    44

    45

/*

    46

 * Parameters and Result fields are both items

    47

 */

    48

enum evsql_item_format {

    49

    EVSQL_FMT_TEXT,

    50

    EVSQL_FMT_BINARY,

    51

};

    52

    53

enum evsql_item_type {

    54

    EVSQL_TYPE_INVALID,

    55

    56

    EVSQL_TYPE_NULL_,

    57

    58

    EVSQL_TYPE_BINARY,

    59

    EVSQL_TYPE_STRING,

    60

    EVSQL_TYPE_UINT16,

    61

    EVSQL_TYPE_UINT32,

    62

    EVSQL_TYPE_UINT64,

    63

};

    64

    65

struct evsql_item_binary {

    66

    const char *ptr;

    67

    size_t len;

    68

};

    69

    70

/*

    71

 * Metadata about the type of an item

    72

 */

    73

struct evsql_item_info {

    74

    // format

    75

    enum evsql_item_format format;

    76

    77

    // type

    78

    enum evsql_item_type type;

    79

    80

    // flags

    81

    struct evsql_item_flags {

    82

        uint8_t null_ok : 1;

    83

    } flags;

    84

};

    85

    86

/*

    96

 * The type and value of an item

    97

 */

    98

struct evsql_item {

    99

    // "header"

   100

    struct evsql_item_info info;

   101

   103

    const char *bytes;

   104

   105

    // size of byte array pointed to by bytes, zero for text

   106

    size_t length;

   107

   108

    // the decoded value

   115

};

   116

   117

/*

   118

 * Query info, similar to prepared statements

   119

 *

   120

 * Contains the literal SQL query and the types of the arguments

   121

 */

   122

struct evsql_query_info {

   123

    // the SQL query itself

   124

    const char *sql;

   125

   126

    // the list of items

   127

    struct evsql_item_info params[];

   128

};

   129

   130

/*

   131

 * Contains the query parameter types and their values

   132

 */

   133

struct evsql_query_params {

   134

    // result format

   135

    enum evsql_item_format result_format;

   136

   137

    // list of params

   138

    struct evsql_item list[];

   139

};

   140

   141

/*

   142

 * Result info

   143

 *

   144

 * Contains the types of the result columns

   145

 */

   146

struct evsql_result_info {

   147

    // XXX: put something useful here?

   148

    int _unused;

   149

   150

    // the list of fields

   151

    struct evsql_item_info columns[];

   152

};

   153

   154

/*

   155

 * Callback for handling query results.

   156

 *

   158

 *

   160

 */

   161

typedef void (*evsql_query_cb)(struct evsql_result *res, void *arg);

   162

   163

/*

   164

 * Callback for handling global-level errors.

   165

 *

   166

 * The evsql is not useable anymore.

   167

 *

   168

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

   169

 */

   170

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

   171

   172

/*

   175

 *

   176

 * The transaction is not useable anymore.

   177

 */

   178

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

   179

   180

/*

   182

 */

   183

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

   184

   185

/*

   187

 */

   188

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

   189

   190

/*

   191

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

   192

 *

   193

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

   194

 */

   199

   200

/*

   201

 * Create a new transaction.

   202

 *

   205

 *

   208

 *

   214

 */

   221

   222

/*

   223

 * Queue the given query for execution.

   224

 *

   225

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

   228

 *

   234

 */

   235

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

   236

   237

/*

   241

 */

   242

struct evsql_query *evsql_query_params (struct evsql *evsql, struct evsql_trans *trans, 

   243

    const char *command, const struct evsql_query_params *params, 

   244

    evsql_query_cb query_fn, void *cb_arg

   245

);

   246

   247

/*

   252

 */

   253

struct evsql_query *evsql_query_exec (struct evsql *evsql, struct evsql_trans *trans, 

   254

    const struct evsql_query_info *query_info,

   255

    evsql_query_cb query_fn, void *cb_arg,

   256

    ...

   257

);

   258

   259

/*

   261

 *

   264

 *

   265

 * If the query is part of a transaction, then trans must be given, and the query must be the query that is currently

   268

 */

   269

void evsql_query_abort (struct evsql_trans *trans, struct evsql_query *query);

   270

   271

/*

   273

 *

   276

 *

   277

 * You cannot abort a COMMIT, calling trans_abort on trans after a succesful trans_commit is a FATAL error.

   280

 */

   281

int evsql_trans_commit (struct evsql_trans *trans);

   282

   283

/*

   288

 *

   289

 * You cannot abort a COMMIT, calling trans_abort on trans after a succesful trans_commit is a FATAL error.

   292

 */

   293

void evsql_trans_abort (struct evsql_trans *trans);

   294

   295

/*

   296

 * Transaction-handling functions

   297

 */

   298

   299

// error string, meant to be called from evsql_trans_error_cb

   300

const char *evsql_trans_error (struct evsql_trans *trans);

   301

   302

/*

   303

 * Param-building functions

   304

 */

   305

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

   306

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

   307

int evsql_param_uint16 (struct evsql_query_params *params, size_t param, uint16_t uval);

   308

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

   309

int evsql_param_null   (struct evsql_query_params *params, size_t param);

   310

int evsql_params_clear (struct evsql_query_params *params);

   311

   312

/*

   313

 * Query-handling functions

   314

 */

   315

   316

// print out a textual repr of the given query/params via DEBUG

   317

void evsql_query_debug (const char *sql, const struct evsql_query_params *params);

   318

   319

/*

   320

 * Result-handling functions

   321

 */

   322

   330

   331

/*

   333

 *

   343

 */

   344

err_t evsql_result_begin (struct evsql_result_info *info, struct evsql_result *res);

   352

int evsql_result_next (struct evsql_result *res, ...);

   362

void evsql_result_end (struct evsql_result *res);

   363

   368

// number of rows in the result

   369

size_t evsql_result_rows (const struct evsql_result *res);

   370

   371

// number of columns in the result

   372

size_t evsql_result_cols (const struct evsql_result *res);

   373

   374

// number of affected rows for UPDATE/INSERT

   375

size_t evsql_result_affected (const struct evsql_result *res);

   376

   377

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

   378

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

   379

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

   380

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

   381

   382

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

   383

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

   384

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

   385

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

   386

   387

// release the result set, freeing its memory

   388

void evsql_result_free (struct evsql_result *res);

   389

   390

/*

   391

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

   392

 *

   393

 * XXX: not implemented yet.

   394

 */

   395

void evsql_close (struct evsql *evsql);

   396

   397

#endif /* EVSQL_H */