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

 *

    24

 *      -   evsql_query_abort()

    25

 *      -   evsql_query_cb()

    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

 * @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

 *

    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 {

   160

        bool null_ok : 1;

   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

         */

   212

        bool has_value : 1;

   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

 */

   287

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

   288

   289

/**

   290

 * End marker for a `struct evsql_item_info` array.

   291

 *

   292

 * @see struct evsql_item_info

   293

 */

   294

#define EVSQL_TYPE_END                          { EVSQL_FMT_BINARY, EVSQL_TYPE_INVALID      }

   295

   296

/**

   297

 * Initializer block for an evsql_query_params struct

   298

 */

   299

#define EVSQL_PARAMS(result_fmt)            { result_fmt, 

   300

   301

/**

   302

 * An evsql_item initializer

   303

 */

   304

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

   305

   306

/**

   307

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

   308

 */

   309

#define EVSQL_PARAMS_END                        { EVSQL_TYPE_END } \

   310

                                              } // <<<

   311

   312

// @}

   313

   314

/**

   315

 * Callback definitions

   316

 *

   317

 * @name evsql_*_cb

   318

 * @{

   319

 */

   320

   321

/**

   322

 * Callback for handling query results.

   323

 *

   324

 * The query has completed, either succesfully or unsuccesfully.

   325

 *

   327

 *

   328

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

   330

 *

   331

 * @see evsql_query

   332

 */

   333

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

   334

   335

/**

   336

 * Callback for handling global-level errors.

   337

 *

   338

 * The evsql is not useable anymore.

   339

 *

   340

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

   341

 *

   342

 * @see evsql_new_pq

   343

 */

   344

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

   345

   346

/**

   347

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

   349

 *

   350

 * The transaction is not useable anymore.

   351

 *

   352

 * @param trans the transaction in question

   353

 * @param arg the void* passed to evsql_trans

   354

 *

   355

 * @see evsql_trans

   356

 */

   357

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

   358

   359

/**

   361

 *

   362

 * @param trans the transaction in question

   363

 * @param arg the void* passed to evsql_trans

   364

 *

   365

 * @see evsql_trans

   366

 * @see evsql_query_abort

   367

 */

   368

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

   369

   370

/**

   371

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

   372

 *

   373

 * @param trans the transaction in question

   374

 * @param arg the void* passed to evsql_trans

   375

 *

   376

 * @see evsql_trans

   377

 * @see evsql_trans_commit

   378

 */

   379

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

   380

   381

// @}

   382

   383

/**

   384

 * Session functions

   385

 *

   386

 * @defgroup evsql_* Session interface

   387

 * @see evsql.h

   388

 * @{

   389

 */

   390

   391

/**

   392

 * Session creation functions

   393

 *

   394

 * @defgroup evsql_new_* Session creation interface

   395

 * @see evsql.h

   396

 * @{

   397

 */

   398

   399

/**

   400

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

   401

 *

   403

 *

   404

 * See the libpq reference manual for the syntax of pq_conninfo

   405

 *

   406

 * @param ev_base the libevent base to use

   407

 * @param pq_conninfo the libpq connection information

   408

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

   409

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

   410

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

   411

 */

   412

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

   413

    evsql_error_cb error_fn, 

   414

    void *cb_arg

   415

);

   416

   417

// @}

   418

   419

/**

   420

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

   421

 *

   422

 * XXX: not implemented yet.

   423

 *

   425

 */

   426

void evsql_close (struct evsql *evsql);

   427

   428

// @}

   429

   430

/**

   431

 * Query API

   432

 *

   433

 * @defgroup evsql_query_* Query interface

   434

 * @see evsql.h

   435

 * @{

   436

 */

   437

   438

/**

   439

 * Queue the given query for execution.

   440

 *

   442

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

   443

 * enqueued for later execution.

   444

 *

   447

 *

   449

 *

   451

 * @param trans the optional transaction handle from evsql_trans

   452

 * @param command the raw SQL command itself

   453

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

   454

 * @param cb_arg the void* passed to the above

   455

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

   456

 */

   457

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

   458

   459

/**

   460

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

   461

 *

   463

 *

   465

 *

   468

 *

   470

 * @param trans the optional transaction handle from evsql_trans

   471

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

   472

 * @param params the parameter types and values

   473

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

   474

 * @param cb_arg the void* passed to the above

   475

 * @see evsql_query

   476

 */

   477

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

   478

    const char *command, const struct evsql_query_params *params, 

   479

    evsql_query_cb query_fn, void *cb_arg

   480

);

   481

   482

/**