Pgsql
The pgsql API in Kore allows you to use PostgreSQL in a straight forward manner. It supports both synchronous and asynchronous queries.
Note that you must have built Kore with PGSQL=1 in order to use this API.
Index
- kore_pgsql_init
- kore_pgsql_setup
- kore_pgsql_bind_request
- kore_pgsql_bind_callback
- kore_pgsql_query
- kore_pgsql_query_params
- kore_pgsql_register
- kore_pgsql_cleanup
- kore_pgsql_continue
- kore_pgsql_logerror
- kore_pgsql_ntuples
- kore_pgsql_nfields
- kore_pgsql_getlength
- kore_pgsql_getvalue
- kore_pgsql_column_binary
kore_pgsql_init
Synopsis
void kore_pgsql_init(struct kore_pgsql *pgsql)
Description
Initialize a kore_pgsql data structure for use.
Parameter | Description |
---|---|
pgsql | A pgsql data structure. |
Returns
Nothing.
kore_pgsql_setup
Synopsis
int kore_pgsql_query_init(struct kore_pgsql *pgsql, const char *dbname, int flags)
Description
Setup a pgsql data structure for use.
Parameter | Description |
---|---|
pgsql | A pgsql data structure. |
dbname | The name of the database connection to be used. |
flags | Any additional flags. |
Flag | Meaning |
---|---|
KORE_PGSQL_ASYNC | Setup an asynchronous query. |
KORE_PGSQL_SYNC | Setup a synchronous query. |
Returns
KORE_RESULT_OK or KORE_RESULT_ERROR. If KORE_RESULT_ERROR was returned but the pgsql->state is still set to KORE_PGSQL_STATE_INIT then you can try again.
kore_pgsql_bind_request
Synopsis
void kore_pgsql_bind_request(struct kore_pgsql *pgsql, struct http_request *req)
Description
Bind a kore_pgsql data structure to an HTTP request. This causes the HTTP request to be notified for any changes to the pgsql data structure.
Parameter | Description |
---|---|
pgsql | A pgsql data structure. |
req | The HTTP request to be tied to. |
Returns
Nothing.
kore_pgsql_bind_callback
Synopsis
void kore_pgsql_bind_callback(struct kore_pgsql *pgsql, void (*cb)(struct kore_pgsql *, void *), void *ar)
Description
Bind a kore_pgsql data structure to a callback function. This function is called for any state change related to the pgsql data structure.
Parameter | Description |
---|---|
pgsql | A pgsql data structure. |
cb | Pointer to a C function. |
Returns
Nothing.
kore_pgsql_query
Synopsis
int kore_pgsql_query(struct kore_pgsql *pgsql, const char *query)
Description
Fires of a query.
Parameter | Description |
---|---|
pgsql | A previously initialized pgsql data structure. |
query | The query to be sent. |
Returns
KORE_RESULT_OK or KORE_RESULT_ERROR.
kore_pgsql_query_params
Synopsis
int kore_pgsql_query_params(struct kore_pgsql *pgsql, const char *query, int result, int count, ...)
Description
Creates and runs a parameterized query
Parameter | Description |
---|---|
pgsql | A previously initialized pgsql data structure. |
query | The query to send, has $1 ,$2 ,... in places where values are substituted |
result | 0 if the query's result should be a string, 1 if the query's result should be binary data. |
count | The number of parameters to substitute in a query |
... | The parameters to substitute into the query. Parameters are passed in groups of 3 :value , length , format . |
The format
argument may be 0 (value
is a null-terminated string) or 1 (value
is binary data of length length
binary). If format
is 0, length
may be set to 0 to have the system find the length of value
.
Returns
KORE_RESULT_OK or KORE_RESULT_ERROR.
Macros
Passing arguments in a pair of 3 is hard to remember, so Kore provides a few useful macros to make your life easier:
- KORE_PGSQL_PARAM_TEXT(data)
- KORE_PGSQL_PARAM_BINARY(data, len)
- KORE_PGSQL_PARAM_TEXT_LEN(data, len)
The above macros automatically expand to the correct 3-pair values required by the kore_pgsql_query_params() function.
kore_pgsql_register
Synopsis
int kore_pgsql_register(const char *dbname, const char *connstring)
Description
Register a database connection.
Parameter | Description |
---|---|
dbname | The name to give to this connection. |
connstring | A PostgreSQL connection string. |
Returns
KORE_RESULT_OK or KORE_RESULT_ERROR if the dbname was already taken.
kore_pgsql_continue
Synopsis
void kore_pgsql_continue(struct http_request *req, struct kore_pgsql *pgsql)
Description
Continue the asynchronous state machine. Usually called from HTTP state machines or callback functions.
Parameter | Description |
---|---|
req | The HTTP request we are dealing with. |
pgsql | The pgsql we are dealing with. |
Returns
Nothing
kore_pgsql_cleanup
Synopsis
void kore_pgsql_cleanup(struct kore_pgsql *pgsql)
Description
Cleanup a previously initialized pgsql data structure and relinquish the database connection it held.
Parameter | Description |
---|---|
Returns
Nothing
kore_pgsql_logerror
Synopsis
void kore_pgsql_logerror(struct kore_pgsql *pgsql)
Description
Log what error occurred to syslog with a LOG_NOTICE priority.
Parameter | Description |
---|---|
pgsql | The pgsql data structure. |
Returns
Nothing
kore_pgsql_ntuples
Synopsis
int kore_pgsql_ntuples(struct kore_pgsql *pgsql)
Description
Returns the number of rows (tuples) in the query result.
Parameter | Description |
---|---|
pgsql | The pgsql data structure. |
Returns
The number of rows (tuples) in the query result.
kore_pgsql_nfields
Synopsis
int kore_pgsql_nfields(struct kore_pgsql *pgsql)
Description
Returns the number of fields in the result.
Parameter | Description |
---|---|
pgsql | The pgsql data structure. |
Returns
The number of fields.
kore_pgsql_getlength
Synopsis
int kore_pgsql_getlength(struct kore_pgsql *pgsql, int row, int col)
Description
Returns the length of the data at row, col.
Parameter | Description |
---|---|
pgsql | The pgsql data structure. |
row | The row number. |
col | The column number. |
Returns
The length of the data at row, col.
kore_pgsql_getvalue
Synopsis
char *kore_pgsql_getvalue(struct kore_pgsql *pgsql, int row, int col)
Description
Returns the value of the data at row, col.
Parameter | Description |
---|---|
pgsql | The pgsql data structure. |
row | The row number. |
col | The column number. |
Returns
A pointer to the data. This should not be freed by the caller.
kore_pgsql_column_binary
Synopsis
int kore_pgsql_column_binary(struct kore_pgsql *pgsql, int col)
Description
Test if the given column contains binary or text data.
Parameter | Description |
---|---|
pgsql | The pgsql data structure. |
col | The column number. |
Returns
Returns 1 if the column contains binary data or 0 if text.