5

@section introduction Introduction

     6

Evsql is a C-language SQL library designed for use with <a href="http://monkey.org/~provos/libevent/">libevent</a>, 

     7

and primarily <a href="http://www.postgresql.org/">PostgreSQL</a>'s <a href="http://www.postgresql.org/docs/8.3/static/libpq.html">libpq</a>.

    14

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

    18

@section usage Usage

    21

@section connecting Connecting

    22

Evsql sessions are represented using an opaque struct, called simply evsql. Use the \ref evsql_ "evsql_new_*" function

    23

corresponding to your database engine (PostgreSQL -> evsql_new_pq()) to allocate this handle. It is valid for use

    24

immediately, although the initial connection may not yet be complete.

    26

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

    30

@section transactions Transactions

    31

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

    36

@see evsql_trans()

    39

@section queries Querying

    40

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

    41

as the \a trans argument.

    43

The given evsql_query_cb() callback function is invoked once the query has been processed and the evsql_result is

    44

available, or the query failed.

    47

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

    51

evsql_query() returns an evsql_query handle that can be passed to evsql_query_abort() to abort the query, ensuring

    52

that the evsql_query_cb() given to evsql_query() is not invoked, and any associated resources released.

    54

@see evsql_query()

    57

@section param_queries Parametrized Queries

    61

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

    64

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

    70

@section query_results Query Results

    71

Once a evsql_query completes (sucess or failure, unless the query/transaction is aborted), the query's evsql_query_cb() is

    77

@see evsql_query_cb

    81

The entire API is defined in the top-level evsql.h header, divided into various groups.