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 ---