1

#ifndef EVSQL_H

     2

#define EVSQL_H

     3

     4

/**

     5

 * @file src/evsql.h

     6

 *

     7

 * A SQL library designed for use with libevent and PostgreSQL's libpq. Provides support for queueing non-transactional

     8

 * requests, transaction support, parametrized queries and result iteration.

     9

 *

    10

 * Currently, the API does not expose the underlying libpq data structures, but since it is currently the only

    11

 * underlying implementation, there is no guarantee that the same API will actually work with other databases' interface

    12

 * libraries...

    13

 *

    14

 * The order of function calls and callbacks goes something like this:

    15

 *

    16

 *  -   evsql_new_pq 

    17

 *

    18

 *  -   evsql_trans 

    19

 *      -   evsql_trans_abort

    20

 *      -   evsql_trans_error_cb

    21

 *      -   evsql_trans_ready_cb

    22

 *

    23

 *  -   evsql_query, evsql_params_* + evsql_query_params, evsql_query_exec 

    24

 *      -   evsql_query_abort

    25

 *      -   evsql_query_cb

    26

 *          -   evsql_result_*

    27

 *          -   evsql_result_free

    28

 *

    29

 *  -   evsql_trans_commit

    30

 *      -   evsql_trans_done_cb

    31

 *

    32

 */

    33

    34

/**

    35

 * System includes

    36

 */

    37

#include <stdint.h>

    38

#include <stdbool.h>

    39

#include <event2/event.h>

    40

    41

/**

    42

 * For err_t.

    43

 */

    44

#include "lib/err.h"

    45

    46

/**

    47

 * The generic context handle used to manage a single "database connector" with multiple queries/transactions.

    48

 */

    49

struct evsql;

    50

    51

/**

    52

 * Opaque transaction handle

    53

 */

    54

struct evsql_trans;

    55

    56

/**

    57

 * Opaque query handle

    58

 */

    59

struct evsql_query;

    60

    61

/**

    62

 * Opaque result handle

    63

 */

    64

struct evsql_result;

    65

    66

/**

    67

 * Various transaction isolation levels for conveniance

    70

 */

    71

enum evsql_trans_type {

    72

    EVSQL_TRANS_DEFAULT,

    73

    EVSQL_TRANS_SERIALIZABLE,

    74

    EVSQL_TRANS_REPEATABLE_READ,

    75

    EVSQL_TRANS_READ_COMMITTED,

    76

    EVSQL_TRANS_READ_UNCOMMITTED,

    77

};

    78

    79

/**

    80

 * An item can be in different formats, the classical text-based format (i.e. snprintf "1234") or a more low-level

    81

 * binary format (i.e uint16_t 0x04F9 in network-byte order).

    82

 */

    83

enum evsql_item_format {

    84

    /** Format values as text strings */

    85

    EVSQL_FMT_TEXT,

    86

    87

    /** Type-specific binary encoding */

    88

    EVSQL_FMT_BINARY,

    89

};

    90

    91

/**

    92

 * An item has a specific type, these correspond somewhat to the native database types.

    93

 */

    94

enum evsql_item_type {

    95

    /** End marker, zero */

    96

    EVSQL_TYPE_INVALID,

    97

    98

    /** A SQL NULL */

    99

    EVSQL_TYPE_NULL_,

   100

   101

    /** A `struct evsql_item_binary` */

   102

    EVSQL_TYPE_BINARY,

   103

   104

    /** A NUL-terminated char* */

   105

    EVSQL_TYPE_STRING,

   106

   107

    /** A uint16_t value */

   108

    EVSQL_TYPE_UINT16,

   109

   110

    /** A uint32_t value */

   111

    EVSQL_TYPE_UINT32,

   112

   113

    /** A uint64_t value */

   114

    EVSQL_TYPE_UINT64,

   115

   116

    EVSQL_TYPE_MAX

   117

};

   118

   119

/**

   120

 * Value for use with EVSQL_TYPE_BINARY, this just a non-NUL-terminated char* and an explicit length

   121

 */

   122

struct evsql_item_binary {

   123

    /** The binary data */

   124

    const char *ptr;

   125

   126

    /** Number of bytes pointed to by ptr */

   127

    size_t len;

   128

};

   129

   130

/**

   131

 * Metadata about the format and type of an item, this does not hold any actual value.

   132

 */

   133

struct evsql_item_info {

   134

    /** The format */

   135

    enum evsql_item_format format;

   136

   137

    /** The type type */

   138

    enum evsql_item_type type;

   139

   140

    /** Various flags */

   141

    struct evsql_item_flags {

   142

        /**

   143

         * The value may be NULL; behaviour varies for query and result 

   144

         * XXX: document

   145

         */

   146

        bool null_ok : 1;

   147

    } flags;

   148

};

   149

   150

/**

   151

 * An union to provide storage for the values of small types

   154

 */

   155

union evsql_item_value {

   156

    /** 16-bit unsigned integer */

   157

    uint16_t uint16;

   158

   159

    /** 32-bit unsigned integer */

   160

    uint32_t uint32;

   161

   162

    /** 64-bit unsigned integer */

   163

    uint64_t uint64;

   164

};

   165

   166

/**

   167

 * A generic structure containing the type and value of a query parameter or a result field.

   172

 */

   173

struct evsql_item {

   174

    /** The "header" containing the type and format */

   175

    struct evsql_item_info info;

   176

   177

    /**

   178

     * Pointer to the raw databytes. 

   179

     * Set to NULL for SQL NULLs, otherwise &value or an external buf 

   180

     */

   181

    const char *bytes;

   182

   183

    /**

   184

     * Size of the byte array pointed to by bytes, zero for EVSQL_FMT_TEXT data.

   185

     */

   186

    size_t length;

   187

   188

    /**

   189

     * Inline storage for small values

   190

     */

   191

    union evsql_item_value value;

   192

   193

    /** Internal flags */

   194

    struct {

   195

        /**

   196

         * The item has a value stored in `value`

   197

         */

   198

        bool has_value : 1;

   199

    } flags;

   200

};

   201

   202

/**

   203

 * Query meta-info, similar to a prepared statement.

   204

 *

   205

 * Contains the literal SQL query and the types of the parameters, but no more.

   208

 */

   209

struct evsql_query_info {

   210

    /** The SQL query itself */

   211

    const char *sql;

   212

   213

    /** 

   214

     * A variable-length array of the item_info parameters, terminated by an EVSQL_TYPE_INVALID entry.

   215

     */

   216

    struct evsql_item_info params[];

   217

};

   218

   219

/**

   220

 * Contains the query parameter types and their actual values

   223

 */

   224

struct evsql_query_params {

   225

    /** Requested result format for this query. XXX: move elsewhere */

   226

    enum evsql_item_format result_format;

   227

   228

    /**

   229

     * A variable-length array of the item parameter-values, terminated by an EVSQL_TYPE_INVALID entry.

   230

     */

   231

    struct evsql_item list[];

   232

};

   233

   234

/**

   235

 * Result layout metadata. This contains the stucture needed to decode result rows.

   238

 */

   239

struct evsql_result_info {

   240

    /** XXX: make up something useful to stick here */

   241

    int _unused;

   242

   243

    /**

   244

     * A variable-length array of the item_info column types.

   245

     */

   246

    struct evsql_item_info columns[];

   247

};

   248

   249

/**

   250

 * Magic macros for defining param/result info -lists

   260

 *

   261

 * @name EVSQL_TYPE/PARAM_*

   262

 * @{

   263

 */

   264

   265

/**

   266

 * A `struct evsql_item_info` initializer, using FMT_BINARY and the given EVSQL_TYPE_ -suffix.

   267

 *

   270

 * @see struct evsql_item_info

   271

 * @see enum evsql_item_type

   272

 */

   273

#define EVSQL_TYPE(typenam)                     { EVSQL_FMT_BINARY, EVSQL_TYPE_ ## typenam  }

   274

   275

/**

   276

 * End marker for a `struct evsql_item_info` array.

   277

 *

   278

 * @see struct evsql_item_info

   279

 */

   280

#define EVSQL_TYPE_END                          { EVSQL_FMT_BINARY, EVSQL_TYPE_INVALID      }

   281

   282

/**

   284

 */

   285

#define EVSQL_PARAMS(result_fmt)            { result_fmt, 

   290

#define EVSQL_PARAM(typenam)                    { EVSQL_TYPE(typenam) }

   295

#define EVSQL_PARAMS_END                        { EVSQL_TYPE_END } \

   296

                                              } // <<<

   297

   298

// @}

   299

   300

/**

   301

 * Callback definitions

   302

 *

   303

 * @name evsql_*_cb

   304

 *

   305

 * @{

   306

 */

   307

   308

/**

   309

 * Callback for handling query results.

   310

 *

   311

 * The query has completed, either succesfully or unsuccesfully.

   312

 *

   313

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

   314

 *

   315

 * @param res The result handle that must be result_free'd after use

   316

 * @param arg The void* passed to evsql_query_*

   317

 *

   318

 * @see evsql_query

   319

 */

   320

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

   321

   322

/**

   323

 * Callback for handling global-level errors.

   324

 *

   325

 * The evsql is not useable anymore.

   326

 *

   327

 * XXX: this is not actually called yet, as no retry logic is implemented, so an evsql itself never fails.

   328

 *

   329

 * @see evsql_new_pq

   330

 */

   331

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

   332

   333

/**

   334

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

   335

 * including from within the evsql_query_* functions (but not always).

   336

 *

   337

 * The transaction is not useable anymore.

   338

 *

   339

 * @param trans the transaction in question

   340

 * @param arg the void* passed to evsql_trans

   341

 *

   342

 * @see evsql_trans

   343

 */

   344

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

   345

   346

/**

   347

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

   348

 *

   349

 * @param trans the transaction in question

   350

 * @param arg the void* passed to evsql_trans

   351

 *

   352

 * @see evsql_trans

   353

 * @see evsql_query_abort

   354

 */

   355

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

   356

   357

/**

   358

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

   359

 *

   360

 * @param trans the transaction in question

   361

 * @param arg the void* passed to evsql_trans

   362

 *

   363

 * @see evsql_trans

   364

 * @see evsql_trans_commit

   365

 */

   366

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

   367

   368

// @}

   369

   370

/**

   378

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

   379

 *

   380

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

   381

 *

   382

 * See the libpq reference manual for the syntax of pq_conninfo

   383

 *

   384

 * @param ev_base the libevent base to use

   385

 * @param pq_conninfo the libpq connection information

   386

 * @param error_fn XXX: not used, may be NULL

   387

 * @param cb_arg: XXX: not used, argument for error_fn

   388

 * @return the evsql context handle for use with other functions

   389

 */

   390

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

   391

    evsql_error_cb error_fn, 

   392

    void *cb_arg

   393

);

   394

   395

/**

   408

 * Query API

   409

 *

   410

 * @name evsql_query_*

   411

 * @{

   412

 */

   413

   414

/**

   415

 * Queue the given query for execution.

   416

 *

   417

 * If a trans is given (i.e. not NULL), then the transaction must be idle, and the query will be executed in that

   418

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

   419

 * enqueued for later execution.

   420

 *

   421

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

   422

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

   423

 *

   424

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

   425

 *

   426

 * @param evsql the context handle from evsql_new_*

   427

 * @param trans the optional transaction handle from evsql_trans

   428

 * @param command the raw SQL command itself

   429

 * @param query_fn the query_cb to call once the query is complete

   430

 * @param cb_arg the void* passed to the above

   431

 * @return the evsql_query handle that can be used to abort the query

   432

 */

   433

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

   434

   435

/**

   436

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

   437

 *

   438

 * Use the EVSQL_PARAMS macros to declare the struct, and the evsql_param_* functions to populate the values.

   439

 *

   440

 * See evsql_query for more info about behaviour.

   441

 *

   442

 * XXX: explain SQL param syntax...

   443

 *

   444

 * @param evsql the context handle from evsql_new_*

   445

 * @param trans the optional transaction handle from evsql_trans

   446

 * @param command the SQL command to bind the parameters to

   447

 * @param params the parameter types and values

   448

 * @param query_fn the query_cb to call once the query is complete

   449

 * @param cb_arg the void* passed to the above

   450

 * @see evsql_query

   451

 */

   452

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

   453

    const char *command, const struct evsql_query_params *params, 

   454

    evsql_query_cb query_fn, void *cb_arg

   455

);

   456

   457

/**

   458

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

   459

 * resolve the types.

   460

 *

   461

 * See evsql_query for more info about behaviour.

   462

 *

   463

 * @param evsql the context handle from evsql_new_*

   464

 * @param trans the optional transaction handle from evsql_trans

   465

 * @param query_info the SQL query information

   466

 * @param query_fn the query_cb to call once the query is complete

   467

 * @param cb_arg the void* passed to the above

   468

 * @see evsql_query

   469

 */

   470

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

   471

    const struct evsql_query_info *query_info,

   472

    evsql_query_cb query_fn, void *cb_arg,

   473

    ...

   474

);

   475

   476

/**

   477

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

   478

 *

   479

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

   480

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

   481

 *

   482

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

   483

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

   484

 * transaction is now idle again.