1

#ifndef EVSQL_H

     2

#define EVSQL_H

     3

     4

/**

     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

    12

 * libraries...

    32

 */

    33

    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

    68

 */

    69

enum evsql_trans_type {

    70

    EVSQL_TRANS_DEFAULT,

    71

    EVSQL_TRANS_SERIALIZABLE,

    72

    EVSQL_TRANS_REPEATABLE_READ,

    73

    EVSQL_TRANS_READ_COMMITTED,

    74

    EVSQL_TRANS_READ_UNCOMMITTED,

    75

};

    76

    77

/**

    78

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

    79

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

    80

 */

    81

enum evsql_item_format {

    82

    /** Format values as text strings */

    83

    EVSQL_FMT_TEXT,

    84

    85

    /** Type-specific binary encoding */

    86

    EVSQL_FMT_BINARY,

    87

};

    88

    89

/**

    90

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

    91

 */

    92

enum evsql_item_type {

    93

    /** End marker, zero */

    94

    EVSQL_TYPE_INVALID,

    95

    96

    /** A SQL NULL */

    97

    EVSQL_TYPE_NULL_,

    98

    99

    /** A `struct evsql_item_binary` */

   100

    EVSQL_TYPE_BINARY,

   101

   102

    /** A NUL-terminated char* */

   103

    EVSQL_TYPE_STRING,

   104

   105

    /** A uint16_t value */

   106

    EVSQL_TYPE_UINT16,

   107

   108

    /** A uint32_t value */

   109

    EVSQL_TYPE_UINT32,

   110

   111

    /** A uint64_t value */

   112

    EVSQL_TYPE_UINT64,

   113

   114

    EVSQL_TYPE_MAX

   115

};

   116

   117

/**

   118

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

   119

 */

   120

struct evsql_item_binary {

   122

    const char *ptr;

   125

    size_t len;

   126

};

   127

   128

/**

   129

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

   130

 */

   131

struct evsql_item_info {

   132

    /** The format */

   133

    enum evsql_item_format format;

   134

   135

    /** The type type */

   136

    enum evsql_item_type type;

   137

   138

    /** Various flags */

   139

    struct evsql_item_flags {

   140

        /**

   141

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

   142

         * XXX: document

   143

         */

   144

        bool null_ok : 1;

   145

    } flags;

   146

};

   147

   148

/**

   149

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

   150

 */

   151

union evsql_item_value {

   153

    uint16_t uint16;

   156

    uint32_t uint32;

   159

    uint64_t uint64;

   160

};

   161

   162

/**

   163

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

   164

 */

   165

struct evsql_item {

   166

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

   167

    struct evsql_item_info info;

   168

   169

    /**

   170

     * Pointer to the raw databytes. 

   171

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

   172

     */

   173

    const char *bytes;

   174

   175

    /**

   176

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

   177

     */

   178

    size_t length;

   179

   180

    /**

   181

     * Inline storage for small values

   182

     */

   183

    union evsql_item_value value;

   184

   185

    /** Internal flags */

   186

    struct {

   187

        /**

   188

         * The item has a value stored in `value`

   189

         */

   190

        bool has_value : 1;

   191

    } flags;

   192

};

   193

   194

/**

   195

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

   196

 *

   197

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

   198

 */

   199

struct evsql_query_info {

   200

    /** The SQL query itself */

   201

    const char *sql;

   202

   203

    /** 

   204

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

   205

     */

   206

    struct evsql_item_info params[];

   207

};

   208

   209

/**

   210

 * Contains the query parameter types and their actual values

   211

 */

   212

struct evsql_query_params {

   213

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

   214

    enum evsql_item_format result_format;

   215

   216

    /**

   217

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

   218

     */

   219

    struct evsql_item list[];

   220

};

   221

   222

/**

   223

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

   224

 */

   225

struct evsql_result_info {

   227

    int _unused;

   228

   229

    /**

   230

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

   231

     */

   232

    struct evsql_item_info columns[];

   233

};

   234

   235

/**

   236

 * Magic macros for defining param/result info -lists

   240

 */

   241

   242

/**

   243

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

   244

 *

   245

 * @see struct evsql_item_info

   246

 * @see enum evsql_item_type

   247

 */

   248

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

   249

   250

/**

   251

 * End marker for a `struct evsql_item_info` array.

   252

 *

   253

 * @see struct evsql_item_info

   254

 */

   255

#define EVSQL_TYPE_END                          { EVSQL_FMT_BINARY, EVSQL_TYPE_INVALID      }

   256

   257

/**

   258

 * Initializer block for a `struct evsql_query_params` struct. EVSQL_PARAMS/EVSQL_PARAMS_END should be used as a

   259

 * pseudo-block with the following layout:

   260

 *

   261

 *  static struct evsql_query_params params = EVSQL_PARAMS(EVSQL_FMT_BINARY) {

   262

 *      EVSQL_PARAM(...),

   263

 *      ...,

   264

 *

   265

 *      EVSQL_PARAMS_END

   266

 *  };

   267

 */

   268

#define EVSQL_PARAMS(result_fmt)            { result_fmt, 

   269

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

   270

#define EVSQL_PARAMS_END                        { EVSQL_TYPE_END } \

   271

                                              } // <<<

   272

   282

   283

/**

   284

 * Callback for handling query results.

   285

 *

   286

 * The query has completed, either succesfully or unsuccesfully.

   287

 *

   288

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

   289

 *

   290

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

   291

 * @param arg The void* passed to evsql_query_*

   292

 *

   293

 * @see evsql_query

   294

 */

   295

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

   296

   297

/**

   298

 * Callback for handling global-level errors.

   299

 *

   300

 * The evsql is not useable anymore.

   301

 *

   302

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

   303

 *

   304

 * @see evsql_new_pq

   305

 */

   306

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

   307

   308

/**

   309

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

   310

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

   311

 *

   312

 * The transaction is not useable anymore.

   313

 *

   314

 * @param trans the transaction in question

   315

 * @param arg the void* passed to evsql_trans

   316

 *

   317

 * @see evsql_trans

   318

 */

   319

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

   320

   321

/**

   322

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

   323

 *

   324

 * @param trans the transaction in question

   325

 * @param arg the void* passed to evsql_trans

   326

 *

   327

 * @see evsql_trans

   328

 * @see evsql_query_abort

   329

 */

   330

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

   331

   332

/**

   333

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

   334

 *

   335

 * @param trans the transaction in question

   336

 * @param arg the void* passed to evsql_trans

   337

 *

   338

 * @see evsql_trans

   339

 * @see evsql_trans_commit

   340

 */

   341

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

   342

   345

/**

   346

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

   347

 *

   348

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

   349

 *

   350

 * See the libpq reference manual for the syntax of pq_conninfo

   351

 *

   352

 * @param ev_base the libevent base to use

   353

 * @param pq_conninfo the libpq connection information

   354

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

   355

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

   356

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

   357

 */

   358

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

   359

    evsql_error_cb error_fn, 

   360

    void *cb_arg

   361

);

   362

   363

/**

   365

 *

   368

 */

   369

   370

/**

   371

 * Queue the given query for execution.

   372

 *

   373

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

   374

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

   375

 * enqueued for later execution.

   376

 *

   377

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

   378

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

   379

 *

   380

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

   381

 *

   382

 * @param evsql the context handle from evsql_new_*

   383

 * @param trans the optional transaction handle from evsql_trans

   384

 * @param command the raw SQL command itself

   385

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

   386

 * @param cb_arg the void* passed to the above

   387

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

   388

 */

   389

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

   390

   391

/**

   392

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

   393

 *

   394

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

   395

 *

   396

 * See evsql_query for more info about behaviour.

   397

 *

   398

 * XXX: explain SQL param syntax...

   399

 *

   402

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

   403

 * @param params the parameter types and values

   406

 * @see evsql_query

   407

 */

   408

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

   409

    const char *command, const struct evsql_query_params *params, 

   410

    evsql_query_cb query_fn, void *cb_arg

   411

);

   412

   413

/**

   414

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

   415

 * resolve the types.

   416

 *

   417

 * See evsql_query for more info about behaviour.

   418

 *

   421

 * @param query_info the SQL query information

   424

 * @see evsql_query

   425

 */

   426

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

   427

    const struct evsql_query_info *query_info,

   428

    evsql_query_cb query_fn, void *cb_arg,

   429

    ...

   430

);

   431

   432

/**

   433

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

   434

 *

   435

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

   436

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

   437

 *

   438

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

   439

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

   440

 * transaction is now idle again.

   441

 *

   442

 * @param trans if the query is part of a transaction, then it MUST be given here

   443

 * @param query the in-progress query to abort

   444

 */

   445

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

   446

   447

/**