22 database engine (PostgreSQL -> evsql_new_pq()) to allocate this handle. It is valid for use immediately, although the |
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. |
23 initial connection may not yet be complete. |
24 |
24 |
25 There is an evsql_close function, but it is currently not implemented. |
25 There is an evsql_close function, but it is currently not implemented. |
26 |
26 |
27 \ref evsql_ |
27 @see \ref evsql_new_ |
28 |
28 |
29 @section Transactions |
29 @section Transactions |
30 Evsql supports both non-transactional queries and transactional queries. A transaction is allocated its own dedicated |
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 |
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 |
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. |
33 "COMMIT TRANSACTION" and "ROLLBACK TRANSACTION" queries. |
34 |
34 |
35 Note, however, that transactions can only handle one outstanding query at a time, whereas transactionless queries can |
35 Note, however, that transactions can only handle one outstanding query at a time, whereas transactionless queries can |
36 be enqueued by evsql itself. |
36 be enqueued by evsql itself. |
37 |
37 |
38 \ref evsql_trans_ |
38 @see \ref evsql_trans_ |
39 |
39 |
40 @section Querying |
40 @section Querying |
41 There is a single evsql_query function used for both transactional and non-transactional queries; you can pass NULL |
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. |
42 as the trans argument. |
43 |
43 |
50 execution if no idle connections are available. |
50 execution if no idle connections are available. |
51 |
51 |
52 evsql_query returns a handle that can be passed to evsql_query_abort to abort the query, ensuring that the callback |
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. |
53 given to evsql_query is not invoked, and any associated resources released. |
54 |
54 |
|
55 @see \ref evsql_query_ |
|
56 |
55 @section Parametrized Queries |
57 @section Parametrized Queries |
56 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 |
57 well. |
59 well. |
58 |
60 |
59 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 struct containing the |
60 parameter types and values as arguments. |
62 parameter types and values as arguments. |
61 |
63 |
62 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 |
63 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!). |
64 |
66 |
|
67 @see \ref evsql_query_ |
|
68 @see \ref evsql_param_ |
|
69 |
|
70 @section Query Results |
|
71 Once a evsql_query completes (sucess or failure, unless the query/transaction is aborted), the query's callback is |
|
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 |
|
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. |
|
76 |
|
77 @see \ref evsql_result_ |
|
78 |
65 @section API Reference |
79 @section API Reference |
66 The entire API is defined in the top-level evsql.h header. |
80 The entire API is defined in the top-level evsql.h header. |
67 |
81 |
68 */ |
82 */ |