author | Tero Marttila <terom@fixme.fi> |
Sat, 13 Dec 2008 20:32:17 +0200 | |
branch | new-evsql |
changeset 54 | 7dc8ff496da1 |
parent 53 | 0d6e07f4c9a1 |
child 55 | 0b92d553400a |
permissions | -rw-r--r-- |
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 |
||
54
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
27 |
@see \ref evsql_new_ |
53 | 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 |
||
54
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
38 |
@see \ref evsql_trans_ |
53 | 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 |
||
54
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
55 |
@see \ref evsql_query_ |
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
56 |
|
53 | 57 |
@section Parametrized Queries |
58 |
Evsql also provides functions to send parametrized queries, the behaviour of evsql_query explained above applies as |
|
59 |
well. |
|
60 |
||
61 |
The first of these is evsql_query_params, which takes the parametrized SQL command and a struct containing the |
|
62 |
parameter types and values as arguments. |
|
63 |
||
64 |
The second of these is evsql_query_exec, which takes a evsql_query_info struct containing the parametrized SQL command |
|
65 |
and the parameter types, and the parameter values themselves as a list of variable arguments (of the correct type!). |
|
66 |
||
54
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
67 |
@see \ref evsql_query_ |
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
68 |
@see \ref evsql_param_ |
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
69 |
|
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
70 |
@section Query Results |
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
71 |
Once a evsql_query completes (sucess or failure, unless the query/transaction is aborted), the query's callback is |
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
72 |
called. It receives a evsql_result handle, which can then be used with the \ref evsql_result_ "result interface" to |
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
73 |
get information about the number of rows returned, access induvidual fields, iterate over the rows, etc. It is |
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
74 |
important to note that the query callback is responsible for releasing the evsql_result using evsql_result_free() (or |
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
75 |
equivalent) once it is done with it. |
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
76 |
|
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
77 |
@see \ref evsql_result_ |
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
78 |
|
53 | 79 |
@section API Reference |
80 |
The entire API is defined in the top-level evsql.h header. |
|
81 |
||
82 |
*/ |