terom@53: /**
terom@53: @mainpage evsql
terom@53: @author Tero Marttila
terom@53:
terom@55: @section introduction Introduction
terom@55: Evsql is a C-language SQL library designed for use with libevent,
terom@55: and primarily PostgreSQL's libpq.
terom@53:
terom@53: Evsql was born as a result of wanting to use a SQL database from within a libevent application, and discovering
terom@53: libpq's asynchronous API. Since the libpq API is somewhat cumbersome to use, I wrote a separate interface that
terom@53: drives libpq using libevent and makes writing asynchronous SQL clients a lot easier - plus adding some conveniance
terom@53: for parametrized queries and such along the way.
terom@53:
terom@55: The evsql.h API doesn't expose the underlying database library's API, although since the only currently existing
terom@53: implementation is libpq, this should really be thought of as a generically-named PostgreSQL library rather than a
terom@53: database-agnostic API...
terom@53:
terom@55: @section usage Usage
terom@53: Include the top-level evsql.h header, making sure you also have the evpq and lib modules available.
terom@53:
terom@55: @section connecting Connecting
terom@55: Evsql sessions are represented using an opaque struct, called simply evsql. Use the \ref evsql_ "evsql_new_*" function
terom@55: corresponding to your database engine (PostgreSQL -> evsql_new_pq()) to allocate this handle. It is valid for use
terom@55: immediately, although the initial connection may not yet be complete.
terom@53:
terom@55: There is an evsql_close() function, but it is currently not implemented.
terom@53:
terom@54: @see \ref evsql_new_
terom@53:
terom@55: @section transactions Transactions
terom@55: Evsql supports both non-transactional queries and transactional queries. A evsql_trans is allocated its own dedicated
terom@53: connection which it can use for its queries without being interfered by other queries/transactions. Evsql takes care of
terom@53: sending the initial "BEGIN TRANSACTION" query, and provides evsql_trans_commit()/evsql_trans_abort() functions to send the
terom@53: "COMMIT TRANSACTION" and "ROLLBACK TRANSACTION" queries.
terom@53:
terom@55: @see evsql_trans()
terom@54: @see \ref evsql_trans_
terom@53:
terom@55: @section queries Querying
terom@55: There is a single evsql_query() function used for both transactional and non-transactional queries; you can pass NULL
terom@55: as the \a trans argument.
terom@53:
terom@55: The given evsql_query_cb() callback function is invoked once the query has been processed and the evsql_result is
terom@55: available, or the query failed.
terom@53:
terom@53: The important distinction between transactional and non-transactional queries is that transactions only support one
terom@55: outstanding query at a time, meaning that you must wait for your callback to be invoked before calling evsql_query()
terom@53: again for the transaction. Non-transactional queries are sent using an idle connection, and will be enqueued for later
terom@53: execution if no idle connections are available.
terom@53:
terom@55: evsql_query() returns an evsql_query handle that can be passed to evsql_query_abort() to abort the query, ensuring
terom@55: that the evsql_query_cb() given to evsql_query() is not invoked, and any associated resources released.
terom@53:
terom@55: @see evsql_query()
terom@54: @see \ref evsql_query_
terom@54:
terom@55: @section param_queries Parametrized Queries
terom@53: Evsql also provides functions to send parametrized queries, the behaviour of evsql_query explained above applies as
terom@53: well.
terom@53:
terom@55: The first of these is evsql_query_params(), which takes the parametrized SQL command and a evsql_query_params containing the
terom@53: parameter types and values as arguments.
terom@53:
terom@55: The second of these is evsql_query_exec(), which takes a evsql_query_info struct containing the parametrized SQL command
terom@53: and the parameter types, and the parameter values themselves as a list of variable arguments (of the correct type!).
terom@53:
terom@54: @see \ref evsql_query_
terom@54: @see \ref evsql_param_
terom@54:
terom@55: @section query_results Query Results
terom@55: Once a evsql_query completes (sucess or failure, unless the query/transaction is aborted), the query's evsql_query_cb() is
terom@54: called. It receives a evsql_result handle, which can then be used with the \ref evsql_result_ "result interface" to
terom@54: get information about the number of rows returned, access induvidual fields, iterate over the rows, etc. It is
terom@54: important to note that the query callback is responsible for releasing the evsql_result using evsql_result_free() (or
terom@54: equivalent) once it is done with it.
terom@54:
terom@55: @see evsql_query_cb
terom@54: @see \ref evsql_result_
terom@54:
terom@53: @section API Reference
terom@55: The entire API is defined in the top-level evsql.h header, divided into various groups.
terom@53:
terom@53: */