kore-doc

The kore documentation found under https://docs.kore.io/
Commits | Files | Refs | README | git clone https://git.kore.io/kore-doc.git

pgsql.md (7645B)



      1 # Pgsql
      2 
      3 The pgsql API in Kore allows you to use PostgreSQL in a straight forward manner. It supports both synchronous and asynchronous queries.
      4 
      5 Note that you must have built Kore with PGSQL=1 in order to use this API.
      6 
      7 ## Index
      8 
      9 * [kore\_pgsql\_init](#init)
     10 * [kore\_pgsql\_setup](#setup)
     11 * [kore\_pgsql\_bind\_request](#bindrequest)
     12 * [kore\_pgsql\_bind\_callback](#bindcallback)
     13 * [kore\_pgsql\_query](#query)
     14 * [kore\_pgsql\_query\_params](#queryparams)
     15 * [kore\_pgsql\_register](#register)
     16 * [kore\_pgsql\_cleanup](#cleanup)
     17 * [kore\_pgsql\_continue](#continue)
     18 * [kore\_pgsql\_logerror](#logerror)
     19 * [kore\_pgsql\_ntuples](#ntuples)
     20 * [kore\_pgsql\_nfields](#nfields)
     21 * [kore\_pgsql\_getlength](#getlength)
     22 * [kore\_pgsql\_getvalue](#getvalue)
     23 * [kore\_pgsql\_column\_binary](#binary)
     24 
     25 ---
     26 
     27 # kore\_pgsql\_init {#init}
     28 
     29 ### Synopsis
     30 
     31 ```
     32 void kore_pgsql_init(struct kore_pgsql *pgsql)
     33 ```
     34 
     35 ### Description
     36 
     37 Initialize a kore\_pgsql data structure for use.
     38 
     39 | Parameter | Description |
     40 | --- | --- |
     41 | pgsql | A pgsql data structure. |
     42 
     43 ### Returns
     44 
     45 Nothing.
     46 
     47 ---
     48 
     49 # kore\_pgsql\_setup {#setup}
     50 
     51 ### Synopsis
     52 
     53 ```
     54 int kore_pgsql_query_init(struct kore_pgsql *pgsql, const char *dbname, int flags)
     55 ```
     56 
     57 ### Description
     58 
     59 Setup a pgsql data structure for use.
     60 
     61 | Parameter | Description |
     62 | --- | --- |
     63 | pgsql | A pgsql data structure. |
     64 | dbname | The name of the database connection to be used. |
     65 | flags | Any additional flags. |
     66 
     67 | Flag | Meaning |
     68 | --- | --- |
     69 | KORE\_PGSQL\_ASYNC | Setup an asynchronous query. |
     70 | KORE\_PGSQL\_SYNC | Setup a synchronous query. |
     71 
     72 ### Returns
     73 
     74 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.
     75 
     76 ---
     77 
     78 # kore\_pgsql\_bind\_request {#bindrequest}
     79 
     80 ### Synopsis
     81 
     82 ```
     83 void kore_pgsql_bind_request(struct kore_pgsql *pgsql, struct http_request *req)
     84 ```
     85 
     86 ### Description
     87 
     88 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.
     89 
     90 | Parameter | Description |
     91 | --- | --- |
     92 | pgsql | A pgsql data structure. |
     93 | req | The HTTP request to be tied to. |
     94 
     95 ### Returns
     96 
     97 Nothing.
     98 
     99 ---
    100 
    101 # kore\_pgsql\_bind\_callback {#bindcallback}
    102 
    103 ### Synopsis
    104 
    105 ```
    106 void kore_pgsql_bind_callback(struct kore_pgsql *pgsql, void (*cb)(struct kore_pgsql *, void *), void *ar)
    107 ```
    108 
    109 ### Description
    110 
    111 Bind a kore\_pgsql data structure to a callback function. This function is called for any state change related to the pgsql data structure.
    112 
    113 | Parameter | Description |
    114 | --- | --- |
    115 | pgsql | A pgsql data structure. |
    116 | cb | Pointer to a C function. |
    117 
    118 ### Returns
    119 
    120 Nothing.
    121 
    122 ---
    123 
    124 # kore\_pgsql\_query {#query}
    125 
    126 ### Synopsis
    127 
    128 ```
    129 int kore_pgsql_query(struct kore_pgsql *pgsql, const char *query)
    130 ```
    131 
    132 ### Description
    133 
    134 Fires of a query.
    135 
    136 | Parameter | Description |
    137 | --- | --- |
    138 | pgsql | A previously initialized pgsql data structure. |
    139 | query | The query to be sent. |
    140 
    141 ### Returns
    142 
    143 KORE\_RESULT\_OK or KORE\_RESULT\_ERROR.
    144 
    145 ---
    146 
    147 # kore\_pgsql\_query\_params {#queryparams}
    148 
    149 ### Synopsis
    150 
    151 ```
    152 int kore_pgsql_query_params(struct kore_pgsql *pgsql, const char *query, int result, int count, ...)
    153 ```
    154 
    155 ### Description
    156 
    157 Creates and runs a parameterized query
    158 
    159 | Parameter | Description |
    160 | --- | --- |
    161 | pgsql | A previously initialized pgsql data structure. |
    162 | query | The query to send, has `$1`,`$2`,... in places where values are substituted |
    163 | result | 0 if the query's result should be a string, 1 if the query's result should be binary data. |
    164 | count | The number of parameters to substitute in a query |
    165 | ... | The parameters to substitute into the query. Parameters are passed in groups of 3 :`value`, `length`, `format`. |
    166 
    167 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`.
    168 
    169 ### Returns
    170 
    171 KORE\_RESULT\_OK or KORE\_RESULT\_ERROR.
    172 
    173 ### Macros
    174 
    175 Passing arguments in a pair of 3 is hard to remember, so Kore provides a few
    176 useful macros to make your life easier:
    177 
    178 * KORE\_PGSQL\_PARAM\_TEXT(data)
    179 * KORE\_PGSQL\_PARAM\_BINARY(data, len)
    180 * KORE\_PGSQL\_PARAM\_TEXT\_LEN(data, len)
    181 
    182 The above macros automatically expand to the correct 3-pair values required
    183 by the kore\_pgsql\_query\_params() function.
    184 
    185 ---
    186 
    187 # kore\_pgsql\_register {#register}
    188 
    189 ### Synopsis
    190 
    191 ```
    192 int kore_pgsql_register(const char *dbname, const char *connstring)
    193 ```
    194 
    195 ### Description
    196 
    197 Register a database connection.
    198 
    199 | Parameter | Description |
    200 | --- | --- |
    201 | dbname | The name to give to this connection. |
    202 | connstring | A PostgreSQL connection string. |
    203 
    204 ### Returns
    205 
    206 KORE\_RESULT\_OK or KORE\_RESULT\_ERROR if the dbname was already taken.
    207 
    208 ---
    209 
    210 # kore\_pgsql\_continue {#continue}
    211 
    212 ### Synopsis
    213 
    214 ```
    215 void kore_pgsql_continue(struct http_request *req, struct kore_pgsql *pgsql)
    216 ```
    217 
    218 ### Description
    219 
    220 Continue the asynchronous state machine. Usually called from HTTP state machines or callback functions.
    221 
    222 | Parameter | Description |
    223 | --- | --- |
    224 | req | The HTTP request we are dealing with. |
    225 | pgsql | The pgsql we are dealing with. |
    226 
    227 ### Returns
    228 
    229 Nothing
    230 
    231 ---
    232 
    233 # kore\_pgsql\_cleanup {#cleanup}
    234 
    235 ### Synopsis
    236 
    237 ```
    238 void kore_pgsql_cleanup(struct kore_pgsql *pgsql)
    239 ```
    240 
    241 ### Description
    242 
    243 Cleanup a previously initialized pgsql data structure and relinquish the database connection it held.
    244 
    245 | Parameter | Description |
    246 | --- | --- |
    247 |  |  |
    248 
    249 ### Returns
    250 
    251 Nothing
    252 
    253 ---
    254 
    255 # kore\_pgsql\_logerror {#logerror}
    256 
    257 ### Synopsis
    258 
    259 ```
    260 void kore_pgsql_logerror(struct kore_pgsql *pgsql)
    261 ```
    262 
    263 ### Description
    264 
    265 Log what error occurred to syslog with a LOG\_NOTICE priority.
    266 
    267 | Parameter | Description |
    268 | --- | --- |
    269 | pgsql | The pgsql data structure. |
    270 
    271 ### Returns
    272 
    273 Nothing
    274 
    275 ---
    276 
    277 # kore\_pgsql\_ntuples {#ntuples}
    278 
    279 ### Synopsis
    280 
    281 ```
    282 int kore_pgsql_ntuples(struct kore_pgsql *pgsql)
    283 ```
    284 
    285 ### Description
    286 
    287 Returns the number of rows (tuples) in the query result.
    288 
    289 | Parameter | Description |
    290 | --- | --- |
    291 | pgsql | The pgsql data structure. |
    292 
    293 ### Returns
    294 
    295 The number of rows (tuples) in the query result.
    296 
    297 ---
    298 
    299 # kore\_pgsql\_nfields {#nfields}
    300 
    301 ### Synopsis
    302 
    303 ```
    304 int kore_pgsql_nfields(struct kore_pgsql *pgsql)
    305 ```
    306 
    307 ### Description
    308 
    309 Returns the number of fields in the result.
    310 
    311 | Parameter | Description |
    312 | --- | --- |
    313 | pgsql | The pgsql data structure. |
    314 
    315 ### Returns
    316 
    317 The number of fields.
    318 
    319 ---
    320 
    321 # kore\_pgsql\_getlength {#getlength}
    322 
    323 ### Synopsis
    324 
    325 ```
    326 int kore_pgsql_getlength(struct kore_pgsql *pgsql, int row, int col)
    327 ```
    328 
    329 ### Description
    330 
    331 Returns the length of the data at row, col.
    332 
    333 | Parameter | Description |
    334 | --- | --- |
    335 | pgsql | The pgsql data structure. |
    336 | row | The row number. |
    337 | col | The column number. |
    338 
    339 ### Returns
    340 
    341 The length of the data at row, col.
    342 
    343 ---
    344 
    345 # kore\_pgsql\_getvalue {#getvalue}
    346 
    347 ### Synopsis
    348 
    349 ```
    350 char *kore_pgsql_getvalue(struct kore_pgsql *pgsql, int row, int col)
    351 ```
    352 
    353 ### Description
    354 
    355 Returns the value of the data at row, col.
    356 
    357 | Parameter | Description |
    358 | --- | --- |
    359 | pgsql | The pgsql data structure. |
    360 | row | The row number. |
    361 | col | The column number. |
    362 
    363 ### Returns
    364 
    365 A pointer to the data. This should not be freed by the caller.
    366 
    367 ---
    368 
    369 # kore\_pgsql\_column\_binary {#binary}
    370 
    371 ### Synopsis
    372 
    373 ```
    374 int kore_pgsql_column_binary(struct kore_pgsql *pgsql, int col)
    375 ```
    376 
    377 ### Description
    378 
    379 Test if the given column contains binary or text data.
    380 
    381 | Parameter | Description |
    382 | --- | --- |
    383 | pgsql | The pgsql data structure. |
    384 | col | The column number. |
    385 
    386 ### Returns
    387 
    388 Returns 1 if the column contains binary data or 0 if text.
    389 
    390 ---