1 /**

     2 @mainpage evsql

     3 @author Tero Marttila

     4 

     5 @section Introduction

     6 Evsql is a C-language SQL library designed for use with libevent, and primarily PostgreSQL's libpq.

     7 

     8 Evsql was born as a result of wanting to use a SQL database from within a libevent application, and discovering

     9 libpq's asynchronous API. Since the libpq API is somewhat cumbersome to use, I wrote a separate interface that

    10 drives libpq using libevent and makes writing asynchronous SQL clients a lot easier - plus adding some conveniance

    11 for parametrized queries and such along the way.

    12 

    13 The evsql API doesn't expose the underlying database library's API, although since the only currently existing

    14 implementation is libpq, this should really be thought of as a generically-named PostgreSQL library rather than a

    15 database-agnostic API...

    16 

    17 @section Usage

    18 Include the top-level evsql.h header, making sure you also have the evpq and lib modules available.

    19 

    20 @section Connecting

    21 Evsql sessions are represented using an opaque struct, called simply evsql. Use the \ref evsql_ evsql_new_ function corresponding to your

    22 database engine (PostgreSQL -> evsql_new_pq()) to allocate this handle. It is valid for use immediately, although the 

    23 initial connection may not yet be complete.

    24 

    25 There is an evsql_close function, but it is currently not implemented.

    26 

    27 \ref evsql_

    28 

    29 @section Transactions

    30 Evsql supports both non-transactional queries and transactional queries. A transaction is allocated its own dedicated

    31 connection which it can use for its queries without being interfered by other queries/transactions. Evsql takes care of

    32 sending the initial "BEGIN TRANSACTION" query, and provides evsql_trans_commit()/evsql_trans_abort() functions to send the

    33 "COMMIT TRANSACTION" and "ROLLBACK TRANSACTION" queries.

    34 

    35 Note, however, that transactions can only handle one outstanding query at a time, whereas transactionless queries can

    36 be enqueued by evsql itself.

    37 

    38 \ref evsql_trans_

    39 

    40 @section Querying

    41 There is a single evsql_query function used for both transactional and non-transactional queries; you can pass NULL

    42 as the trans argument.

    43 

    44 The given callback function is invoked once the query has been processed and the result is available, or the query

    45 failed.

    46 

    47 The important distinction between transactional and non-transactional queries is that transactions only support one

    48 outstanding query at a time, meaning that you must wait for your callback to be invoked before calling evsql_query

    49 again for the transaction. Non-transactional queries are sent using an idle connection, and will be enqueued for later

    50 execution if no idle connections are available.

    51 

    52 evsql_query returns a handle that can be passed to evsql_query_abort to abort the query, ensuring that the callback

    53 given to evsql_query is not invoked, and any associated resources released.

    54 

    55 @section Parametrized Queries

    56 Evsql also provides functions to send parametrized queries, the behaviour of evsql_query explained above applies as

    57 well. 

    58 

    59 The first of these is evsql_query_params, which takes the parametrized SQL command and a struct containing the

    60 parameter types and values as arguments.

    61 

    62 The second of these is evsql_query_exec, which takes a evsql_query_info struct containing the parametrized SQL command

    63 and the parameter types, and the parameter values themselves as a list of variable arguments (of the correct type!).

    64 

    65 @section API Reference

    66 The entire API is defined in the top-level evsql.h header.

    67 

    68 */