53
|
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 |
*/
|