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(), \ref evsql_param_ + evsql_query_params(), evsql_query_exec()

    24

 *      -   evsql_query_abort()

    25

 *      -   evsql_query_cb()

    26

 *          -   \ref 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

/**

    43

 */

    45

    46

/**

    47

 * @struct evsql

    48

 *

    49

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

    50

 *

    51

 * @see \ref evsql_

    52

 */

    53

struct evsql;

    54

    55

/**

    56

 * @struct evsql_trans

    57

 *

    58

 * Opaque transaction handle returned by evsql_trans() and used for the \ref evsql_query_ functions

    59

 *

    60

 * @see \ref evsql_trans_

    61

 */

    62

struct evsql_trans;

    63

    64

/**

    65

 * @struct evsql_query

    66

 *

    67

 * Opaque query handle returned by the \ref evsql_query_ functions and used for evsql_query_abort()

    68

 *

    69

 * @see \ref evsql_query_

    70

 */

    71

struct evsql_query;

    72

    73

/**

    74

 * @struct evsql_result

    75

 *

    76

 * Opaque result handle received by evsql_query_cb(), and used with the \ref evsql_result_ functions

    77

 *

    78

 * @see evsql_query_cb

    79

 * @see \ref evsql_result_

    80

 */

    81

struct evsql_result;

    82

    83

/**

    84

 * Various transaction isolation levels for conveniance

    85

 *

    86

 * @see evsql_trans

    87

 */

    88

enum evsql_trans_type {

    89

    EVSQL_TRANS_DEFAULT,

    90

    EVSQL_TRANS_SERIALIZABLE,

    91

    EVSQL_TRANS_REPEATABLE_READ,

    92

    EVSQL_TRANS_READ_COMMITTED,

    93

    EVSQL_TRANS_READ_UNCOMMITTED,

    94

};

    95

    96

/**

    97

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

    98

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

    99

 */

   100

enum evsql_item_format {

   101

    /** Format values as text strings */

   102

    EVSQL_FMT_TEXT,

   103

   104

    /** Type-specific binary encoding */

   105

    EVSQL_FMT_BINARY,

   106

};

   107

   108

/**

   109

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

   110

 */

   111

enum evsql_item_type {

   112

    /** End marker, zero */

   113

    EVSQL_TYPE_INVALID,

   114

   115

    /** A SQL NULL */

   116

    EVSQL_TYPE_NULL_,

   117

   118

    /** A `struct evsql_item_binary` */

   119

    EVSQL_TYPE_BINARY,

   120

   121

    /** A NUL-terminated char* */

   122

    EVSQL_TYPE_STRING,

   123

   124

    /** A uint16_t value */

   125

    EVSQL_TYPE_UINT16,

   126

   127

    /** A uint32_t value */

   128

    EVSQL_TYPE_UINT32,

   129

   130

    /** A uint64_t value */

   131

    EVSQL_TYPE_UINT64,

   132

   133

    EVSQL_TYPE_MAX

   134

};

   135

   136

/**

   137

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

   138

 */

   139

struct evsql_item_binary {

   140

    /** The binary data */

   141

    const char *ptr;

   142

   143

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

   144

    size_t len;

   145

};

   146

   147

/**

   148

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

   149

 */

   150

struct evsql_item_info {

   151

    /** The format */

   152

    enum evsql_item_format format;

   153

   154

    /** The type type */

   155

    enum evsql_item_type type;

   156

   157

    /** Various flags */

   158

    struct evsql_item_flags {

   159

        /** The value may be NULL @see evsql_result_next */

   161

    } flags;

   162

};

   163

   164

/**

   165

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

   166

 *

   167

 * @see evsql_item

   168

 */

   169

union evsql_item_value {

   170

    /** 16-bit unsigned integer */

   171

    uint16_t uint16;

   172

   173

    /** 32-bit unsigned integer */

   174

    uint32_t uint32;

   175

   176

    /** 64-bit unsigned integer */

   177

    uint64_t uint64;

   178

};

   179

   180

/**

   181

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

   182

 *

   183

 * @see evsql_query_info

   184

 * @see evsql_query_params

   185

 * @see evsql_result_info

   186

 */

   187

struct evsql_item {

   188

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

   189

    struct evsql_item_info info;

   190

   191

    /**

   192

     * Pointer to the raw databytes. 

   193

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

   194

     */

   195

    const char *bytes;

   196

   197

    /**

   198

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

   199

     */

   200

    size_t length;

   201

   202

    /**

   203

     * Inline storage for small values

   204

     */

   205

    union evsql_item_value value;

   206

   207

    /** Internal flags */

   208

    struct {

   209

        /**

   210

         * The item has a value stored in `value`

   211

         */

   213

    } flags;

   214

};

   215

   216

/**

   217

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

   218

 *

   219

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

   220

 *

   221

 * @see evsql_query_exec

   222

 */

   223

struct evsql_query_info {

   224

    /** The SQL query itself */

   225

    const char *sql;

   226

   227

    /** 

   228

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

   229

     */

   230

    struct evsql_item_info params[];

   231

};

   232

   233

/**

   234

 * Contains the query parameter types and their actual values

   235

 *

   236

 * @see evsql_query_params

   237

 */

   238

struct evsql_query_params {

   239

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

   240

    enum evsql_item_format result_format;

   241

   242

    /**

   243

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

   244

     */

   245

    struct evsql_item list[];

   246

};

   247

   248

/**

   249

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

   250

 *

   251

 * @see evsql_result_begin

   252

 */

   253

struct evsql_result_info {

   254

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

   255

    int _unused;

   256

   257

    /**

   258

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

   259

     */

   260

    struct evsql_item_info columns[];

   261

};

   262

   263

/**

   264

 * Magic macros for defining param/result info -lists

   265

 *  

   266

 * @code

   267

 *  static struct evsql_query_params params = EVSQL_PARAMS(EVSQL_FMT_BINARY) {

   268

 *      EVSQL_PARAM( UINT32 ),

   269

 *      ...,

   270

 *

   271

 *      EVSQL_PARAMS_END

   272

 *  };

   273

 * @endcode

   274

 *

   275

 * @name EVSQL_TYPE/PARAM_*

   276

 * @{

   277

 */

   278

   279

/**

   280

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

   281

 *

   282

 * @param typenam the suffix of an evsql_item_type name

   283

 *

   284

 * @see struct evsql_item_info

   285

 * @see enum evsql_item_type

   286

 */

   289

   290

/**

   291

 * End marker for a `struct evsql_item_info` array.

   292

 *

   293

 * @see struct evsql_item_info

   294

 */

   296

   297

/**

   298

 * Initializer block for an evsql_query_params struct

   299

 */

   300

#define EVSQL_PARAMS(result_fmt)            { result_fmt, 

   301

   302

/**

   303

 * An evsql_item initializer

   304

 */

   305

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

   306

   307

/**

   308

 * Include the ending item and terminate the pseudo-block started using #EVSQL_PARAMS

   309

 */

   310

#define EVSQL_PARAMS_END                        { EVSQL_TYPE_END } \

   311

                                              } // <<<

   312

   313

// @}

   314

   315

/**

   316

 * Callback definitions

   317

 *

   318

 * @name evsql_*_cb

   319

 * @{

   320

 */

   321

   322

/**

   323

 * Callback for handling query results.

   324

 *

   325

 * The query has completed, either succesfully or unsuccesfully.

   326

 *

   327

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

   328

 *

   329

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

   330

 * @param arg The void* passed to \ref evsql_query_

   331

 *

   332

 * @see evsql_query

   333

 */

   334

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

   335

   336

/**

   337

 * Callback for handling global-level errors.

   338

 *

   339

 * The evsql is not useable anymore.

   340

 *

   341

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

   342

 *

   343

 * @see evsql_new_pq

   344

 */

   345

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

   346

   347

/**

   348

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

   349

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

   350

 *

   351

 * The transaction is not useable anymore.

   352

 *

   353

 * @param trans the transaction in question

   354

 * @param arg the void* passed to evsql_trans

   355

 *

   356

 * @see evsql_trans

   357

 */

   358

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

   359

   360

/**

   361

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

   362

 *

   363

 * @param trans the transaction in question

   364

 * @param arg the void* passed to evsql_trans

   365

 *

   366

 * @see evsql_trans

   367

 * @see evsql_query_abort

   368

 */

   369

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

   370

   371

/**

   372

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

   373

 *

   374

 * @param trans the transaction in question

   375

 * @param arg the void* passed to evsql_trans

   376

 *

   377

 * @see evsql_trans

   378

 * @see evsql_trans_commit

   379

 */

   380

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

   381

   382

// @}

   383

   384

/**

   385

 * Session functions

   386

 *

   387

 * @defgroup evsql_* Session interface

   388

 * @see evsql.h

   389

 * @{

   390

 */

   391

   392

/**

   393

 * Session creation functions

   394

 *

   395

 * @defgroup evsql_new_* Session creation interface

   396

 * @see evsql.h

   397

 * @{

   398

 */

   399

   400

/**

   401

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

   402

 *

   403

 * The given \a pq_conninfo pointer must stay valid for the duration of the evsql's lifetime.

   404

 *

   405

 * See the libpq reference manual for the syntax of pq_conninfo

   406

 *

   407

 * @param ev_base the libevent base to use

   408

 * @param pq_conninfo the libpq connection information

   409

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

   410

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

   411

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

   412

 */

   413

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

   414

    evsql_error_cb error_fn, 

   415

    void *cb_arg

   416

);

   417

   418

// @}

   419

   420

/**

   421

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

   422

 *

   423

 * XXX: not implemented yet.

   424

 *

   425

 * @param evsql the context handle from \ref evsql_new_

   426

 */

   427

void evsql_close (struct evsql *evsql);

   428

   429

// @}

   430

   431

/**

   432

 * Query API

   433

 *

   434

 * @defgroup evsql_query_* Query interface

   435

 * @see evsql.h

   436

 * @{

   437

 */

   438

   439

/**

   440

 * Queue the given query for execution.

   441

 *

   442

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

   443

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

   444

 * enqueued for later execution.

   445

 *

   446

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

   447

 * The callback can use the \ref evsql_result_ functions to manipulate the query results.

   448

 *

   449

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

   450

 *

   451

 * @param evsql the context handle from \ref evsql_new_

   452

 * @param trans the optional transaction handle from evsql_trans

   453

 * @param command the raw SQL command itself

   454

 * @param query_fn the evsql_query_cb() to call once the query is complete

   455

 * @param cb_arg the void* passed to the above

   456

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

   457

 */

   458

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

   459

   460

/**

   461

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

   462

 *

   463

 * Use the EVSQL_PARAMS macros to declare \a params, and the \ref evsql_param_ functions to populate the values.

   464

 *

   465

 * See evsql_query() for more info about behaviour.

   466

 *

   467

 * See the <a href="http://www.postgresql.org/docs/8.3/static/libpq-exec.html#LIBPQ-EXEC-MAIN">libpq PQexecParams tip</a>

   468

 * for the parameter syntax to use.

   469

 *

   470

 * @param evsql the context handle from \ref evsql_new_

   471

 * @param trans the optional transaction handle from evsql_trans

   472

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

   473

 * @param params the parameter types and values

   474

 * @param query_fn the evsql_query_cb() to call once the query is complete

   475

 * @param cb_arg the void* passed to the above

   476

 * @see evsql_query

   477

 */

   478

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

   479

    const char *command, const struct evsql_query_params *params, 

   480

    evsql_query_cb query_fn, void *cb_arg

   481

);

   482