author | Tero Marttila <terom@fixme.fi> |
Sat, 13 Dec 2008 20:58:27 +0200 | |
branch | new-evsql |
changeset 55 | 0b92d553400a |
parent 54 | 7dc8ff496da1 |
permissions | -rw-r--r-- |
53 | 1 |
/** |
2 |
@mainpage evsql |
|
3 |
@author Tero Marttila |
|
4 |
||
55 | 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>. |
|
53 | 8 |
|
9 |
Evsql was born as a result of wanting to use a SQL database from within a libevent application, and discovering |
|
10 |
libpq's asynchronous API. Since the libpq API is somewhat cumbersome to use, I wrote a separate interface that |
|
11 |
drives libpq using libevent and makes writing asynchronous SQL clients a lot easier - plus adding some conveniance |
|
12 |
for parametrized queries and such along the way. |
|
13 |
||
55 | 14 |
The evsql.h API doesn't expose the underlying database library's API, although since the only currently existing |
53 | 15 |
implementation is libpq, this should really be thought of as a generically-named PostgreSQL library rather than a |
16 |
database-agnostic API... |
|
17 |
||
55 | 18 |
@section usage Usage |
53 | 19 |
Include the top-level evsql.h header, making sure you also have the evpq and lib modules available. |
20 |
||
55 | 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. |
|
53 | 25 |
|
55 | 26 |
There is an evsql_close() function, but it is currently not implemented. |
53 | 27 |
|
54
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
28 |
@see \ref evsql_new_ |
53 | 29 |
|
55 | 30 |
@section transactions Transactions |
31 |
Evsql supports both non-transactional queries and transactional queries. A evsql_trans is allocated its own dedicated |
|
53 | 32 |
connection which it can use for its queries without being interfered by other queries/transactions. Evsql takes care of |
33 |
sending the initial "BEGIN TRANSACTION" query, and provides evsql_trans_commit()/evsql_trans_abort() functions to send the |
|
34 |
"COMMIT TRANSACTION" and "ROLLBACK TRANSACTION" queries. |
|
35 |
||
55 | 36 |
@see evsql_trans() |
54
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
37 |
@see \ref evsql_trans_ |
53 | 38 |
|
55 | 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. |
|
53 | 42 |
|
55 | 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. |
|
53 | 45 |
|
46 |
The important distinction between transactional and non-transactional queries is that transactions only support one |
|
55 | 47 |
outstanding query at a time, meaning that you must wait for your callback to be invoked before calling evsql_query() |
53 | 48 |
again for the transaction. Non-transactional queries are sent using an idle connection, and will be enqueued for later |
49 |
execution if no idle connections are available. |
|
50 |
||
55 | 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. |
|
53 | 53 |
|
55 | 54 |
@see evsql_query() |
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 |
|
55 | 57 |
@section param_queries Parametrized Queries |
53 | 58 |
Evsql also provides functions to send parametrized queries, the behaviour of evsql_query explained above applies as |
59 |
well. |
|
60 |
||
55 | 61 |
The first of these is evsql_query_params(), which takes the parametrized SQL command and a evsql_query_params containing the |
53 | 62 |
parameter types and values as arguments. |
63 |
||
55 | 64 |
The second of these is evsql_query_exec(), which takes a evsql_query_info struct containing the parametrized SQL command |
53 | 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 |
|
55 | 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 |
|
54
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 |
|
55 | 77 |
@see evsql_query_cb |
54
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
78 |
@see \ref evsql_result_ |
7dc8ff496da1
evsql documentation further improved
Tero Marttila <terom@fixme.fi>
parents:
53
diff
changeset
|
79 |
|
53 | 80 |
@section API Reference |
55 | 81 |
The entire API is defined in the top-level evsql.h header, divided into various groups. |
53 | 82 |
|
83 |
*/ |