sql-api.h revision 27a44fcfd8d19bffe0f267f20a2b5d3fe7600fdd
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainen/* This SQL API is designed to work asynchronously. The underlying drivers
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainen however may not. */
ccffb125d94adff0ad776de5a96e22f864d6fb0aTimo Sirainen /* Set if queries are not executed asynchronously */
6b2738c39a868ff9291867138c55029fc40cf105Timo Sirainen /* Set if database wants to use connection pooling */
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainen#define SQL_DEF_STRUCT(name, struct_name, type, c_type) \
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainen { (type) + COMPILE_ERROR_IF_TYPES_NOT_COMPATIBLE( \
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainen#define SQL_DEF_STRUCT_STR(name, struct_name) \
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainen SQL_DEF_STRUCT(name, struct_name, SQL_TYPE_STR, const char *)
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainen#define SQL_DEF_STRUCT_UINT(name, struct_name) \
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainen SQL_DEF_STRUCT(name, struct_name, SQL_TYPE_UINT, unsigned int)
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainen#define SQL_DEF_STRUCT_ULLONG(name, struct_name) \
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainen SQL_DEF_STRUCT(name, struct_name, SQL_TYPE_ULLONG, unsigned long long)
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainen#define SQL_DEF_STRUCT_BOOL(name, struct_name) \
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainen SQL_DEF_STRUCT(name, struct_name, SQL_TYPE_BOOL, bool)
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainentypedef void sql_query_callback_t(struct sql_result *result, void *context);
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainentypedef void sql_commit_callback_t(const char *error, void *context);
0371406d952fe51367c7be91703e5634b7d9d225Timo Sirainen/* register all built-in SQL drivers */
0371406d952fe51367c7be91703e5634b7d9d225Timo Sirainenvoid sql_driver_register(const struct sql_db *driver);
0371406d952fe51367c7be91703e5634b7d9d225Timo Sirainenvoid sql_driver_unregister(const struct sql_db *driver);
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainen/* Initialize database connections. db_driver is the database driver name,
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainen eg. "mysql" or "pgsql". connect_string is driver-specific. */
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainenstruct sql_db *sql_init(const char *db_driver, const char *connect_string);
ccffb125d94adff0ad776de5a96e22f864d6fb0aTimo Sirainen/* Returns SQL database state flags. */
ccffb125d94adff0ad776de5a96e22f864d6fb0aTimo Sirainenenum sql_db_flags sql_get_flags(struct sql_db *db);
a0b89f3b1df99b3a32f44623f13ad1893118825bTimo Sirainen/* Explicitly connect to the database. It's not required to call this function
a0b89f3b1df99b3a32f44623f13ad1893118825bTimo Sirainen though. Returns -1 if we're not connected, 0 if we started connecting or
a0b89f3b1df99b3a32f44623f13ad1893118825bTimo Sirainen 1 if we are fully connected now. */
9349a0afffad990e45d3ad33081e1d2d9e68a753Timo Sirainen/* Explicitly disconnect from database and abort pending auth requests. */
24ce0c343cefe54af841871fa39dbc3464028b06Timo Sirainen/* Escape the given string if needed and return it. */
13a8c553f293349248b161ff851743498916e26eTimo Sirainenconst char *sql_escape_string(struct sql_db *db, const char *string);
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainen/* Execute SQL query without waiting for results. */
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainenvoid sql_exec(struct sql_db *db, const char *query);
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainen/* Execute SQL query and return result in callback. If fields list is given,
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainen the returned fields are validated to be of correct type, and you can use
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainen sql_result_next_row_get() */
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainenvoid sql_query(struct sql_db *db, const char *query,
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainen sql_query_callback_t *callback, void *context);
27a44fcfd8d19bffe0f267f20a2b5d3fe7600fddTimo Sirainen#define sql_query(db, query, callback, context) \
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainen/* Execute blocking SQL query and return result. */
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainenstruct sql_result *sql_query_s(struct sql_db *db, const char *query);
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainenvoid sql_result_setup_fetch(struct sql_result *result,
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainen/* Go to next row, returns 1 if ok, 0 if this was the last row or -1 if error
137ea7ca34005345aa2304a940149b7f3774d727Timo Sirainen occurred. This needs to be the first call for result. */
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainenint sql_result_next_row(struct sql_result *result);
3656c91dcb8336814bebd4500e81c3dde25233e6Timo Sirainenvoid sql_result_ref(struct sql_result *result);
3656c91dcb8336814bebd4500e81c3dde25233e6Timo Sirainen/* Needs to be called only with sql_query_s() or when result has been
3656c91dcb8336814bebd4500e81c3dde25233e6Timo Sirainen explicitly referenced. */
3656c91dcb8336814bebd4500e81c3dde25233e6Timo Sirainenvoid sql_result_unref(struct sql_result *result);
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainen/* Return number of fields in result. */
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainenunsigned int sql_result_get_fields_count(struct sql_result *result);
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainen/* Return name of the given field index. */
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainenconst char *sql_result_get_field_name(struct sql_result *result,
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainen unsigned int idx);
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainen/* Return field index for given name, or -1 if not found. */
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainenint sql_result_find_field(struct sql_result *result, const char *field_name);
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainen/* Returns value of given field as string. */
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainenconst char *sql_result_get_field_value(struct sql_result *result,
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainen unsigned int idx);
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainenconst unsigned char *
1ac19c5c2b66a12f5598792aad15114ee3eb62e2Timo Sirainensql_result_get_field_value_binary(struct sql_result *result,
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainenconst char *sql_result_find_field_value(struct sql_result *result,
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainen/* Return all values of current row. */
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainenconst char *const *sql_result_get_values(struct sql_result *result);
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainen/* Return last error message in result. */
6c2c5f20760b06bfb4a40b0ee2ef5ab016bc41f0Timo Sirainenconst char *sql_result_get_error(struct sql_result *result);
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainen/* Begin a new transaction. Currently you're limited to only one open
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainen transaction at a time. */
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainenstruct sql_transaction_context *sql_transaction_begin(struct sql_db *db);
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainen/* Commit transaction. */
d5cebe7f98e63d4e2822863ef2faa4971e8b3a5dTimo Sirainenvoid sql_transaction_commit(struct sql_transaction_context **ctx,
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainen sql_commit_callback_t *callback, void *context);
27a44fcfd8d19bffe0f267f20a2b5d3fe7600fddTimo Sirainen#define sql_transaction_commit(ctx, callback, context) \
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainen/* Synchronous commit. Returns 0 if ok, -1 if error. */
d5cebe7f98e63d4e2822863ef2faa4971e8b3a5dTimo Sirainenint sql_transaction_commit_s(struct sql_transaction_context **ctx,
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainen const char **error_r);
d5cebe7f98e63d4e2822863ef2faa4971e8b3a5dTimo Sirainenvoid sql_transaction_rollback(struct sql_transaction_context **ctx);
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainen/* Execute query in given transaction. */
dc9de21d4375faeedbe5b7e941502ac578650da9Timo Sirainenvoid sql_update(struct sql_transaction_context *ctx, const char *query);
bfdf0fd7b6186f64cbdcbf1cb2bf9c42a9007b77Timo Sirainen/* Save the number of rows updated by this query. The value is set before
bfdf0fd7b6186f64cbdcbf1cb2bf9c42a9007b77Timo Sirainen commit callback is called. */
bfdf0fd7b6186f64cbdcbf1cb2bf9c42a9007b77Timo Sirainenvoid sql_update_get_rows(struct sql_transaction_context *ctx, const char *query,
bfdf0fd7b6186f64cbdcbf1cb2bf9c42a9007b77Timo Sirainen unsigned int *affected_rows);