1 /** |
1 /** |
2 @mainpage evsql |
2 @mainpage evsql |
3 @author Tero Marttila |
3 @author Tero Marttila |
4 |
4 |
5 @section Introduction |
5 @section introduction Introduction |
6 Evsql is a C-language SQL library designed for use with libevent, and primarily PostgreSQL's libpq. |
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>. |
7 |
8 |
8 Evsql was born as a result of wanting to use a SQL database from within a libevent application, and discovering |
9 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 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 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 for parametrized queries and such along the way. |
12 |
13 |
13 The evsql API doesn't expose the underlying database library's API, although since the only currently existing |
14 The evsql.h 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 implementation is libpq, this should really be thought of as a generically-named PostgreSQL library rather than a |
15 database-agnostic API... |
16 database-agnostic API... |
16 |
17 |
17 @section Usage |
18 @section usage Usage |
18 Include the top-level evsql.h header, making sure you also have the evpq and lib modules available. |
19 Include the top-level evsql.h header, making sure you also have the evpq and lib modules available. |
19 |
20 |
20 @section Connecting |
21 @section connecting Connecting |
21 Evsql sessions are represented using an opaque struct, called simply evsql. Use the \ref evsql_ evsql_new_ function corresponding to your |
22 Evsql sessions are represented using an opaque struct, called simply evsql. Use the \ref evsql_ "evsql_new_*" function |
22 database engine (PostgreSQL -> evsql_new_pq()) to allocate this handle. It is valid for use immediately, although the |
23 corresponding to your database engine (PostgreSQL -> evsql_new_pq()) to allocate this handle. It is valid for use |
23 initial connection may not yet be complete. |
24 immediately, although the initial connection may not yet be complete. |
24 |
25 |
25 There is an evsql_close function, but it is currently not implemented. |
26 There is an evsql_close() function, but it is currently not implemented. |
26 |
27 |
27 @see \ref evsql_new_ |
28 @see \ref evsql_new_ |
28 |
29 |
29 @section Transactions |
30 @section transactions Transactions |
30 Evsql supports both non-transactional queries and transactional queries. A transaction is allocated its own dedicated |
31 Evsql supports both non-transactional queries and transactional queries. A evsql_trans 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 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 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 "COMMIT TRANSACTION" and "ROLLBACK TRANSACTION" queries. |
34 |
35 |
35 Note, however, that transactions can only handle one outstanding query at a time, whereas transactionless queries can |
36 @see evsql_trans() |
36 be enqueued by evsql itself. |
|
37 |
|
38 @see \ref evsql_trans_ |
37 @see \ref evsql_trans_ |
39 |
38 |
40 @section Querying |
39 @section queries Querying |
41 There is a single evsql_query function used for both transactional and non-transactional queries; you can pass NULL |
40 There is a single evsql_query() function used for both transactional and non-transactional queries; you can pass NULL |
42 as the trans argument. |
41 as the \a trans argument. |
43 |
42 |
44 The given callback function is invoked once the query has been processed and the result is available, or the query |
43 The given evsql_query_cb() callback function is invoked once the query has been processed and the evsql_result is |
45 failed. |
44 available, or the query failed. |
46 |
45 |
47 The important distinction between transactional and non-transactional queries is that transactions only support one |
46 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 |
47 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 |
48 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. |
49 execution if no idle connections are available. |
51 |
50 |
52 evsql_query returns a handle that can be passed to evsql_query_abort to abort the query, ensuring that the callback |
51 evsql_query() returns an evsql_query handle that can be passed to evsql_query_abort() to abort the query, ensuring |
53 given to evsql_query is not invoked, and any associated resources released. |
52 that the evsql_query_cb() given to evsql_query() is not invoked, and any associated resources released. |
54 |
53 |
|
54 @see evsql_query() |
55 @see \ref evsql_query_ |
55 @see \ref evsql_query_ |
56 |
56 |
57 @section Parametrized Queries |
57 @section param_queries Parametrized Queries |
58 Evsql also provides functions to send parametrized queries, the behaviour of evsql_query explained above applies as |
58 Evsql also provides functions to send parametrized queries, the behaviour of evsql_query explained above applies as |
59 well. |
59 well. |
60 |
60 |
61 The first of these is evsql_query_params, which takes the parametrized SQL command and a struct containing the |
61 The first of these is evsql_query_params(), which takes the parametrized SQL command and a evsql_query_params containing the |
62 parameter types and values as arguments. |
62 parameter types and values as arguments. |
63 |
63 |
64 The second of these is evsql_query_exec, which takes a evsql_query_info struct containing the parametrized SQL command |
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!). |
65 and the parameter types, and the parameter values themselves as a list of variable arguments (of the correct type!). |
66 |
66 |
67 @see \ref evsql_query_ |
67 @see \ref evsql_query_ |
68 @see \ref evsql_param_ |
68 @see \ref evsql_param_ |
69 |
69 |
70 @section Query Results |
70 @section query_results Query Results |
71 Once a evsql_query completes (sucess or failure, unless the query/transaction is aborted), the query's callback is |
71 Once a evsql_query completes (sucess or failure, unless the query/transaction is aborted), the query's evsql_query_cb() is |
72 called. It receives a evsql_result handle, which can then be used with the \ref evsql_result_ "result interface" to |
72 called. It receives a evsql_result handle, which can then be used with the \ref evsql_result_ "result interface" to |
73 get information about the number of rows returned, access induvidual fields, iterate over the rows, etc. It is |
73 get information about the number of rows returned, access induvidual fields, iterate over the rows, etc. It is |
74 important to note that the query callback is responsible for releasing the evsql_result using evsql_result_free() (or |
74 important to note that the query callback is responsible for releasing the evsql_result using evsql_result_free() (or |
75 equivalent) once it is done with it. |
75 equivalent) once it is done with it. |
76 |
76 |
|
77 @see evsql_query_cb |
77 @see \ref evsql_result_ |
78 @see \ref evsql_result_ |
78 |
79 |
79 @section API Reference |
80 @section API Reference |
80 The entire API is defined in the top-level evsql.h header. |
81 The entire API is defined in the top-level evsql.h header, divided into various groups. |
81 |
82 |
82 */ |
83 */ |