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

    11

#include "lib/err.h"

    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

/*

    87

 * Storage for various scalar values

    88

 */

    89

union evsql_item_value {

    90

    uint16_t uint16;

    91

    uint32_t uint32;

    92

    uint64_t uint64;

    93

};

    94

    95

/*

    96

 * The type and value of an item

    97

 */

    98

struct evsql_item {

    99

    // "header"

   100

    struct evsql_item_info info;

   101

   102

    // pointer to the raw databytes. Set to NULL to indicate SQL-NULL, &value, or an external buf

   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

   109

    union evsql_item_value value;

   110

   111

    // (internal) flags

   112

    struct {

   113

        uint8_t has_value : 1;

   114

    } flags;

   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

 * Macros for defining param/result infos/lists

   156

 */

   157

#define EVSQL_PARAMS(result_fmt)            { result_fmt, 

   160

                                              } // <<<

   161

   165

   166

/*

   167

 * Callback for handling query results.

   168

 *

   169

 * The query has completed, either succesfully or unsuccesfully.

   170

 *

   171

 * Use the evsql_result_* functions to manipulate the results, and call evsql_result_free (or equivalent) once done.

   172

 */

   173

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

   174

   175

/*

   176

 * Callback for handling global-level errors.

   177

 *

   178

 * The evsql is not useable anymore.

   179

 *

   180

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

   181

 */

   182

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

   183

   184

/*

   185

 * Callback for handling transaction-level errors. This may be called at any time during a transaction's lifetime,

   186

 * including from within the evsql_query_* functions.

   187

 *

   188

 * The transaction is not useable anymore.

   189

 */

   190

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

   191

   192

/*

   193

 * Callback for handling evsql_trans/evsql_query_abort completion. The transaction is ready for use with evsql_query_*.

   194

 */

   195

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

   196

   197

/*

   198

 * Callback for handling evsql_trans_commit completion. The transaction was commited, and should not be used anymore.

   199

 */

   200

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

   201

   202

/*

   203

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

   204

 *

   205

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

   206

 */

   207

struct evsql *evsql_new_pq (struct event_base *ev_base, const char *pq_conninfo, 

   208

    evsql_error_cb error_fn, 

   209

    void *cb_arg

   210

);

   211

   212

/*

   213

 * Create a new transaction.

   214

 *

   215

 * A transaction will be allocated its own connection, and the "BEGIN TRANSACTION ..." query will be sent (use the

   216

 * evsql_trans_type argument to specify this). 

   217

 *

   218

 * Once the transaction has been opened, the given evsql_trans_ready_cb will be triggered, and the transaction can then

   219

 * be used (see evsql_query_*).

   220

 *

   221

 * If, at any point, the transaction-connection fails, and pending query will be forgotten (i.e. the query callback

   222

 * will NOT be called), and the given evsql_trans_error_cb will be called. Note that this includes some, but not all,

   223

 * cases where evsql_query_* returns an error.

   224

 *

   225

 * Once you are done with the transaction, call either evsql_trans_commit or evsql_trans_abort.

   226

 */

   227

struct evsql_trans *evsql_trans (struct evsql *evsql, enum evsql_trans_type type, 

   228

    evsql_trans_error_cb error_fn, 

   229

    evsql_trans_ready_cb ready_fn, 

   230

    evsql_trans_done_cb done_fn, 

   231

    void *cb_arg

   232

);

   233

   234

/*

   235

 * Queue the given query for execution.

   236

 *

   237

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

   238

 * transaction's context. Otherwise, the query will be executed without a transaction using an idle connection, or

   239

 * enqueued for later execution.

   240

 *

   241

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

   242

 * The callback can used the evsql_result_* functions to manipulate it.

   243

 *

   244

 * The returned evsql_query handle can be passed to evsql_query_abort at any point before query_fn being called. 

   245

 *

   246

 */

   247

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

   248

   249

/*

   250

 * Execute the given SQL query using the list of parameter types/values given via evsql_query_params.

   251

 *

   252

 * See evsql_query for more info about behaviour.

   253

 */

   254

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

   255

    const char *command, const struct evsql_query_params *params, 

   256

    evsql_query_cb query_fn, void *cb_arg

   257

);

   258

   259

/*

   260

 * Execute the given query_info's SQL query using the values given as variable arguments, using the evsql_query_info to

   261

 * resolve the types.

   262

 *

   263

 * See evsql_query for more info about behaviour.

   264

 */

   265

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

   266

    const struct evsql_query_info *query_info,

   267

    evsql_query_cb query_fn, void *cb_arg,

   268

    ...

   269

);

   270

   271

/*

   272

 * Abort a query returned by evsql_query_* that has not yet completed (query_fn has not been called yet).

   273

 *

   274

 * The actual query itself may or may not be aborted (and hence may or may not be executed on the server), but query_fn

   275

 * will not be called anymore, and the query will dispose of itself and any results returned.

   276

 *

   277

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

   278

 * executing on that trans. The transaction's ready_fn will be called once the query has been aborted and the

   279

 * transaction is now idle again.

   280

 */

   281

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

   282

   283

/*

   284

 * Commit a transaction using "COMMIT TRANSACTION".

   285

 *

   286

 * The transaction must be idle, just like for evsql_query. Once the transaction has been commited, the transaction's

   287

 * done_fn will be called, after which the transaction must not be used.

   288

 *

   289

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

   290

 *

   291

 * Note that done_fn will never be called directly, always indirectly via the event loop.

   292

 */

   293

int evsql_trans_commit (struct evsql_trans *trans);

   294

   295

/*

   296

 * Abort a transaction, using "ROLLBACK TRANSACTION".

   297

 *

   298

 * No more transaction callbacks will be called, if there was a query running, it will be aborted, and the transaction

   299

 * then rollback'd.

   300

 *

   301

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

   302

 * 

   303

 * Do not call evsql_trans_abort from within evsql_trans_error_cb!

   304

 */

   305

void evsql_trans_abort (struct evsql_trans *trans);

   306

   307

/*

   308

 * Transaction-handling functions

   309

 */

   310

   311

// error string, meant to be called from evsql_trans_error_cb

   312

const char *evsql_trans_error (struct evsql_trans *trans);

   313

   314

/*

   315

 * Param-building functions

   316

 */

   317

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

   318

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

   319

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

   320

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

   321

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

   322

int evsql_params_clear (struct evsql_query_params *params);

   323

   324

/*

   325

 * Query-handling functions

   326

 */

   327

   328

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

   329

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

   330

   331

/*

   332

 * Result-handling functions

   333

 */

   334

   335

/*

   336

 * Check the result for errors. Intended for use with non-data queries, i.e. CREATE, etc.

   337

 *

   338

 * Returns zero if the query was OK, err otherwise. EIO indicates an SQL error, the error message can be retrived

   339

 * using evsql_result_error.

   340

 */

   341

err_t evsql_result_check (struct evsql_result *res);

   342

   343

/*

   344

 * The iterator-based interface results interface.

   345

 *

   346

 * Define an evsql_result_info struct that describes the columns returned by the query, and call evsql_result_begin on

   347

 * the evsql_result. This verifies the query result, and then prepares it for iteration using evsql_result_next.

   348

 *

   349

 * Call evsql_result_end once you've stopped iteration.

   350

 *

   351

 * Returns zero if the evsql_result is ready for iteration, err otherwise. EIO indicates an SQL error, the error

   352

 * message can be retreived using evsql_result_error.

   353

 *

   354

 * Note: currently the iterator state is simply stored in evsql_result, so only one iterator at a time per evsql_result.

   355

 */

   356

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

   357

   358

/*

   359

 * Reads the next result row, storing the field values into the pointer arguments given. The types are resolved using

   360

 * the evsql_result_info given to evsql_result_begin.

   361

 *

   362

 * Returns >0 when a row was read, 0 when there are no more rows, and -err if there was an error.

   363

 */

   364

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

   365

   366

/*

   367

 * Ends the result iteration, releasing any associated resources and the result itself.

   368

 *

   369

 * The result should not be iterated or accessed anymore.

   370

 *

   371

 * Note: this does the same thing as evsql_result_free, and works regardless of evsql_result_begin returning

   372

 * succesfully or not.

   373

 */

   374

void evsql_result_end (struct evsql_result *res);

   375

   376

   377

// get error message associated with function

   378

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

   379

   380

// number of rows in the result

   381

size_t evsql_result_rows (const struct evsql_result *res);

   382

   383

// number of columns in the result

   384

size_t evsql_result_cols (const struct evsql_result *res);

   385

   386

// number of affected rows for UPDATE/INSERT

   387

size_t evsql_result_affected (const struct evsql_result *res);

   388

   389

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

   390

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

   391

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

   392

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

   393

   394

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

   395

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

   396

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

   397

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

   398

   399

// release the result set, freeing its memory

   400

void evsql_result_free (struct evsql_result *res);

   401

   402

/*

   403

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

   404

 *

   405

 * XXX: not implemented yet.

   406

 */

   407

void evsql_close (struct evsql *evsql);

   408

   409

#endif /* EVSQL_H */