#include <stdint.h>
#include <stdbool.h>
#include <event2/event.h>
#include "lib/err.h"
Go to the source code of this file.
Data Structures | |
| struct | evsql_item_binary |
| Value for use with EVSQL_TYPE_BINARY, this just a non-NUL-terminated char* and an explicit length. More... | |
| struct | evsql_item_info |
| Metadata about the format and type of an item, this does not hold any actual value. More... | |
| struct | evsql_item_info::evsql_item_flags |
| Various flags. More... | |
| union | evsql_item_value |
| An union to provide storage for the values of small types. More... | |
| struct | evsql_item |
| A generic structure containing the type and value of a query parameter or a result field. More... | |
| struct | evsql_query_info |
| Query meta-info, similar to a prepared statement. More... | |
| struct | evsql_query_params |
| Contains the query parameter types and their actual values. More... | |
| struct | evsql_result_info |
| Result layout metadata. More... | |
Defines | |
EVSQL_TYPE/PARAM_* | |
Magic macros for defining param/result info -lists
static struct evsql_query_params params = EVSQL_PARAMS(EVSQL_FMT_BINARY) { EVSQL_PARAM( UINT32 ), ..., EVSQL_PARAMS_END }; | |
| #define | EVSQL_TYPE(typenam) { EVSQL_FMT_BINARY, EVSQL_TYPE_ ## typenam } |
| A `struct evsql_item_info` initializer, using FMT_BINARY and the given EVSQL_TYPE_ -suffix. | |
| #define | EVSQL_TYPE_END { EVSQL_FMT_BINARY, EVSQL_TYPE_INVALID } |
| End marker for a `struct evsql_item_info` array. | |
| #define | EVSQL_PARAMS(result_fmt) { result_fmt, |
| Initializer block for an evsql_query_params struct. | |
| #define | EVSQL_PARAM(typenam) { EVSQL_TYPE(typenam) } |
| An evsql_item initializer. | |
| #define | EVSQL_PARAMS_END |
| Include the ending item and terminate the pseudo-block started using EVSQL_PARAMS. | |
Typedefs | |
evsql_*_cb | |
Callback definitions | |
| typedef void(* | evsql_query_cb )(struct evsql_result *res, void *arg) |
| Callback for handling query results. | |
| typedef void(* | evsql_error_cb )(struct evsql *evsql, void *arg) |
| Callback for handling global-level errors. | |
| typedef void(* | evsql_trans_error_cb )(struct evsql_trans *trans, void *arg) |
| Callback for handling transaction-level errors. | |
| typedef void(* | evsql_trans_ready_cb )(struct evsql_trans *trans, void *arg) |
| Callback for handling evsql_trans/evsql_query_abort completion. | |
| typedef void(* | evsql_trans_done_cb )(struct evsql_trans *trans, void *arg) |
| Callback for handling evsql_trans_commit completion. | |
Enumerations | |
| enum | evsql_trans_type { EVSQL_TRANS_DEFAULT, EVSQL_TRANS_SERIALIZABLE, EVSQL_TRANS_REPEATABLE_READ, EVSQL_TRANS_READ_COMMITTED, EVSQL_TRANS_READ_UNCOMMITTED } |
| Various transaction isolation levels for conveniance. More... | |
| enum | evsql_item_format { EVSQL_FMT_TEXT, EVSQL_FMT_BINARY } |
| An item can be in different formats, the classical text-based format (i.e. More... | |
| enum | evsql_item_type { EVSQL_TYPE_INVALID, EVSQL_TYPE_NULL_, EVSQL_TYPE_BINARY, EVSQL_TYPE_STRING, EVSQL_TYPE_UINT16, EVSQL_TYPE_UINT32, EVSQL_TYPE_UINT64, EVSQL_TYPE_MAX } |
| An item has a specific type, these correspond somewhat to the native database types. More... | |
Functions | |
| struct evsql * | evsql_new_pq (struct event_base *ev_base, const char *pq_conninfo, evsql_error_cb error_fn, void *cb_arg) |
| Create a new PostgreSQL/libpq (evpq) -based evsql using the given conninfo. | |
| void | evsql_close (struct evsql *evsql) |
| Close a connection. | |
| struct evsql_query * | evsql_query (struct evsql *evsql, struct evsql_trans *trans, const char *command, evsql_query_cb query_fn, void *cb_arg) |
| Queue the given query for execution. | |
| struct evsql_query * | evsql_query_params (struct evsql *evsql, struct evsql_trans *trans, const char *command, const struct evsql_query_params *params, evsql_query_cb query_fn, void *cb_arg) |
| Execute the given SQL query using the list of parameter types/values given via evsql_query_params. | |
| struct evsql_query * | evsql_query_exec (struct evsql *evsql, struct evsql_trans *trans, const struct evsql_query_info *query_info, evsql_query_cb query_fn, void *cb_arg,...) |
| Execute the given query_info's SQL query with the values given as variable arguments, using the query_info to resolve the types. | |
| void | evsql_query_abort (struct evsql_trans *trans, struct evsql_query *query) |
| Abort a query returned by Query interface that has not yet completed (query_fn has not been called yet). | |
| void | evsql_query_debug (const char *sql, const struct evsql_query_params *params) |
| Print out a textual dump of the given sql query and params using DEBUG. | |
| struct evsql_trans * | evsql_trans (struct evsql *evsql, enum evsql_trans_type type, evsql_trans_error_cb error_fn, evsql_trans_ready_cb ready_fn, evsql_trans_done_cb done_fn, void *cb_arg) |
| Create a new transaction. | |
| int | evsql_trans_commit (struct evsql_trans *trans) |
| Commit a transaction using "COMMIT TRANSACTION". | |
| void | evsql_trans_abort (struct evsql_trans *trans) |
| Abort a transaction, using "ROLLBACK TRANSACTION". | |
| const char * | evsql_trans_error (struct evsql_trans *trans) |
| Retrieve the transaction-specific error message from the underlying engine. | |
| int | evsql_param_binary (struct evsql_query_params *params, size_t param, const char *ptr, size_t len) |
| Sets the value of the parameter at the given index. | |
| int | evsql_param_string (struct evsql_query_params *params, size_t param, const char *ptr) |
| int | evsql_param_uint16 (struct evsql_query_params *params, size_t param, uint16_t uval) |
| int | evsql_param_uint32 (struct evsql_query_params *params, size_t param, uint32_t uval) |
| int | evsql_param_null (struct evsql_query_params *params, size_t param) |
| Sets the given parameter to NULL. | |
| int | evsql_params_clear (struct evsql_query_params *params) |
| Clears all the parameter values (sets them to NULL). | |
| err_t | evsql_result_check (struct evsql_result *res) |
| Check the result for errors. | |
| err_t | evsql_result_begin (struct evsql_result_info *info, struct evsql_result *res) |
| The iterator-based interface results interface. | |
| int | evsql_result_next (struct evsql_result *res,...) |
| Reads the next result row from the result prepared using evsql_result_begin. | |
| void | evsql_result_end (struct evsql_result *res) |
| Ends the result iteration, releasing any associated resources and the result itself. | |
| const char * | evsql_result_error (const struct evsql_result *res) |
| Get the error message associated with the result, intended for use after evsql_result_check/begin return an error code. | |
| size_t | evsql_result_rows (const struct evsql_result *res) |
| Get the number of data rows returned by the query. | |
| size_t | evsql_result_cols (const struct evsql_result *res) |
| Get the number of columns in the data results from the query. | |
| size_t | evsql_result_affected (const struct evsql_result *res) |
| Get the number of rows affected by an UPDATE/INSERT/etc query. | |
| int | evsql_result_binary (const struct evsql_result *res, size_t row, size_t col, const char **ptr, size_t *size, bool nullok) |
| Fetch the raw binary value for the given field, returning it via ptr/size. | |
| int | evsql_result_string (const struct evsql_result *res, size_t row, size_t col, const char **ptr, int nullok) |
| Fetch the textual value of the given field, returning it via ptr. | |
| int | evsql_result_uint16 (const struct evsql_result *res, size_t row, size_t col, uint16_t *uval, int nullok) |
| Use evsql_result_binary to read a binary field value, and then convert it using ntoh[slq], storing the value in *val. | |
| int | evsql_result_uint32 (const struct evsql_result *res, size_t row, size_t col, uint32_t *uval, int nullok) |
| int | evsql_result_uint64 (const struct evsql_result *res, size_t row, size_t col, uint64_t *uval, int nullok) |
| void | evsql_result_free (struct evsql_result *res) |
| Every result handle passed to evsql_query_cb() MUST be released by the user, using this function. | |
Provides support for queueing non-transactional requests, transaction support, parametrized queries and result iteration.
Currently, the API does not expose the underlying libpq data structures, but since it is currently the only underlying implementation, there is no guarantee that the same API will actually work with other databases' interface libraries...
The order of function calls and callbacks goes something like this:
| #define EVSQL_PARAMS_END |
Value:
{ EVSQL_TYPE_END } \
}
| #define EVSQL_TYPE | ( | typenam | ) | { EVSQL_FMT_BINARY, EVSQL_TYPE_ ## typenam } |
A `struct evsql_item_info` initializer, using FMT_BINARY and the given EVSQL_TYPE_ -suffix.
| typenam | the suffix of an evsql_item_type name |
enum evsql_item_type
| #define EVSQL_TYPE_END { EVSQL_FMT_BINARY, EVSQL_TYPE_INVALID } |
| typedef void(* evsql_error_cb)(struct evsql *evsql, void *arg) |
Callback for handling global-level errors.
The evsql is not useable anymore.
XXX: this is not actually called yet, as no retry logic is implemented, so an evsql itself never fails.
| typedef void(* evsql_query_cb)(struct evsql_result *res, void *arg) |
Callback for handling query results.
The query has completed, either succesfully or unsuccesfully.
Use the Result interface functions to manipulate the results, and call evsql_result_free() (or equivalent) once done.
| res | The result handle that must be result_free'd after use | |
| arg | The void* passed to Query interface |
| typedef void(* evsql_trans_done_cb)(struct evsql_trans *trans, void *arg) |
Callback for handling evsql_trans_commit completion.
The transaction was commited, and should not be used anymore.
| trans | the transaction in question | |
| arg | the void* passed to evsql_trans |
| typedef void(* evsql_trans_error_cb)(struct evsql_trans *trans, void *arg) |
Callback for handling transaction-level errors.
This may be called at any time during a transaction's lifetime, including from within the Query interface functions (but not always).
The transaction is not useable anymore.
| trans | the transaction in question | |
| arg | the void* passed to evsql_trans |
| typedef void(* evsql_trans_ready_cb)(struct evsql_trans *trans, void *arg) |
Callback for handling evsql_trans/evsql_query_abort completion.
The transaction is ready for use with Query interface.
| trans | the transaction in question | |
| arg | the void* passed to evsql_trans |
| enum evsql_item_format |
| enum evsql_item_type |
An item has a specific type, these correspond somewhat to the native database types.
| enum evsql_trans_type |
1.5.6