1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements. See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License. You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 /* Overview of what this is and does:
18 * http://www.apache.org/~niq/dbd.html
21 #ifndef APR_DBD_INTERNAL_H
22 #define APR_DBD_INTERNAL_H
32 #define TXN_IGNORE_ERRORS(t) \
33 ((t) && ((t)->mode & APR_DBD_TRANSACTION_IGNORE_ERRORS))
34 #define TXN_NOTICE_ERRORS(t) \
35 ((t) && !((t)->mode & APR_DBD_TRANSACTION_IGNORE_ERRORS))
37 #define TXN_DO_COMMIT(t) (!((t)->mode & APR_DBD_TRANSACTION_ROLLBACK))
38 #define TXN_DO_ROLLBACK(t) ((t)->mode & APR_DBD_TRANSACTION_ROLLBACK)
40 #define TXN_MODE_BITS \
41 (APR_DBD_TRANSACTION_ROLLBACK|APR_DBD_TRANSACTION_IGNORE_ERRORS)
43 struct apr_dbd_driver_t {
47 /** init: allow driver to perform once-only initialisation.
48 * Called once only. May be NULL
50 void (*init)(apr_pool_t *pool);
52 /** native_handle: return the native database handle of the underlying db
54 * @param handle - apr_dbd handle
55 * @return - native handle
57 void *(*native_handle)(apr_dbd_t *handle);
59 /** open: obtain a database connection from the server rec.
60 * Must be explicitly closed when you're finished with it.
61 * WARNING: only use this when you need a connection with
62 * a lifetime other than a request
64 * @param pool - a pool to use for error messages (if any).
65 * @param params - connection parameters.
66 * @param error - descriptive error.
67 * @return database handle, or NULL on error.
69 apr_dbd_t *(*open)(apr_pool_t *pool, const char *params,
72 /** check_conn: check status of a database connection
74 * @param pool - a pool to use for error messages (if any).
75 * @param handle - the connection to check
76 * @return APR_SUCCESS or error
78 apr_status_t (*check_conn)(apr_pool_t *pool, apr_dbd_t *handle);
80 /** close: close/release a connection obtained from open()
82 * @param handle - the connection to release
83 * @return APR_SUCCESS or error
85 apr_status_t (*close)(apr_dbd_t *handle);
87 /** set_dbname: select database name. May be a no-op if not supported.
89 * @param pool - working pool
90 * @param handle - the connection
91 * @param name - the database to select
92 * @return 0 for success or error code
94 int (*set_dbname)(apr_pool_t* pool, apr_dbd_t *handle, const char *name);
96 /** transaction: start a transaction. May be a no-op.
98 * @param pool - a pool to use for error messages (if any).
99 * @param handle - the connection
100 * @param trans - ptr to a transaction. May be null on entry
101 * @return 0 for success or error code
103 int (*start_transaction)(apr_pool_t *pool, apr_dbd_t *handle,
104 apr_dbd_transaction_t **trans);
106 /** end_transaction: end a transaction
107 * (commit on success, rollback on error).
110 * @param trans - the transaction.
111 * @return 0 for success or error code
113 int (*end_transaction)(apr_dbd_transaction_t *trans);
115 /** query: execute an SQL query that doesn't return a result set
117 * @param handle - the connection
118 * @param nrows - number of rows affected.
119 * @param statement - the SQL statement to execute
120 * @return 0 for success or error code
122 int (*query)(apr_dbd_t *handle, int *nrows, const char *statement);
124 /** select: execute an SQL query that returns a result set
126 * @param pool - pool to allocate the result set
127 * @param handle - the connection
128 * @param res - pointer to result set pointer. May point to NULL on entry
129 * @param statement - the SQL statement to execute
130 * @param random - 1 to support random access to results (seek any row);
131 * 0 to support only looping through results in order
132 * (async access - faster)
133 * @return 0 for success or error code
135 int (*select)(apr_pool_t *pool, apr_dbd_t *handle, apr_dbd_results_t **res,
136 const char *statement, int random);
138 /** num_cols: get the number of columns in a results set
140 * @param res - result set.
141 * @return number of columns
143 int (*num_cols)(apr_dbd_results_t *res);
145 /** num_tuples: get the number of rows in a results set
146 * of a synchronous select
148 * @param res - result set.
149 * @return number of rows, or -1 if the results are asynchronous
151 int (*num_tuples)(apr_dbd_results_t *res);
153 /** get_row: get a row from a result set
155 * @param pool - pool to allocate the row
156 * @param res - result set pointer
157 * @param row - pointer to row pointer. May point to NULL on entry
158 * @param rownum - row number, or -1 for "next row". Ignored if random
159 * access is not supported.
160 * @return 0 for success, -1 for rownum out of range or data finished
162 int (*get_row)(apr_pool_t *pool, apr_dbd_results_t *res,
163 apr_dbd_row_t **row, int rownum);
165 /** get_entry: get an entry from a row
167 * @param row - row pointer
168 * @param col - entry number
169 * @param val - entry to fill
170 * @return 0 for success, -1 for no data, +1 for general error
172 const char* (*get_entry)(const apr_dbd_row_t *row, int col);
174 /** error: get current error message (if any)
176 * @param handle - the connection
177 * @param errnum - error code from operation that returned an error
178 * @return the database current error message, or message for errnum
179 * (implementation-dependent whether errnum is ignored)
181 const char *(*error)(apr_dbd_t *handle, int errnum);
183 /** escape: escape a string so it is safe for use in query/select
185 * @param pool - pool to alloc the result from
186 * @param string - the string to escape
187 * @param handle - the connection
188 * @return the escaped, safe string
190 const char *(*escape)(apr_pool_t *pool, const char *string,
193 /** prepare: prepare a statement
195 * @param pool - pool to alloc the result from
196 * @param handle - the connection
197 * @param query - the SQL query
198 * @param label - A label for the prepared statement.
199 * use NULL for temporary prepared statements
200 * (eg within a Request in httpd)
201 * @param nargs - number of parameters in the query
202 * @param nvals - number of values passed in p[b]query/select
203 * @param types - pointer to an array with types of parameters
204 * @param statement - statement to prepare. May point to null on entry.
205 * @return 0 for success or error code
207 int (*prepare)(apr_pool_t *pool, apr_dbd_t *handle, const char *query,
208 const char *label, int nargs, int nvals,
209 apr_dbd_type_e *types, apr_dbd_prepared_t **statement);
211 /** pvquery: query using a prepared statement + args
213 * @param pool - working pool
214 * @param handle - the connection
215 * @param nrows - number of rows affected.
216 * @param statement - the prepared statement to execute
217 * @param args - args to prepared statement
218 * @return 0 for success or error code
220 int (*pvquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
221 apr_dbd_prepared_t *statement, va_list args);
223 /** pvselect: select using a prepared statement + args
225 * @param pool - working pool
226 * @param handle - the connection
227 * @param res - pointer to query results. May point to NULL on entry
228 * @param statement - the prepared statement to execute
229 * @param random - Whether to support random-access to results
230 * @param args - args to prepared statement
231 * @return 0 for success or error code
233 int (*pvselect)(apr_pool_t *pool, apr_dbd_t *handle,
234 apr_dbd_results_t **res,
235 apr_dbd_prepared_t *statement, int random, va_list args);
237 /** pquery: query using a prepared statement + args
239 * @param pool - working pool
240 * @param handle - the connection
241 * @param nrows - number of rows affected.
242 * @param statement - the prepared statement to execute
243 * @param args - args to prepared statement
244 * @return 0 for success or error code
246 int (*pquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
247 apr_dbd_prepared_t *statement, const char **args);
249 /** pselect: select using a prepared statement + args
251 * @param pool - working pool
252 * @param handle - the connection
253 * @param res - pointer to query results. May point to NULL on entry
254 * @param statement - the prepared statement to execute
255 * @param random - Whether to support random-access to results
256 * @param args - args to prepared statement
257 * @return 0 for success or error code
259 int (*pselect)(apr_pool_t *pool, apr_dbd_t *handle,
260 apr_dbd_results_t **res, apr_dbd_prepared_t *statement,
261 int random, const char **args);
264 /** get_name: get a column title from a result set
266 * @param res - result set pointer
267 * @param col - entry number
268 * @return param name, or NULL if col is out of bounds.
270 const char* (*get_name)(const apr_dbd_results_t *res, int col);
272 /** transaction_mode_get: get the mode of transaction
274 * @param trans - the transaction.
275 * @return mode of transaction
277 int (*transaction_mode_get)(apr_dbd_transaction_t *trans);
279 /** transaction_mode_set: get the mode of transaction
281 * @param trans - the transaction.
282 * @param mode - new mode of the transaction
283 * @return the mode of transaction in force after the call
285 int (*transaction_mode_set)(apr_dbd_transaction_t *trans, int mode);
287 /** format of prepared statement parameters */
290 /** pvbquery: query using a prepared statement + binary args
292 * @param pool - working pool
293 * @param handle - the connection
294 * @param nrows - number of rows affected.
295 * @param statement - the prepared statement to execute
296 * @param args - binary args to prepared statement
297 * @return 0 for success or error code
299 int (*pvbquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
300 apr_dbd_prepared_t *statement, va_list args);
302 /** pvbselect: select using a prepared statement + binary args
304 * @param pool - working pool
305 * @param handle - the connection
306 * @param res - pointer to query results. May point to NULL on entry
307 * @param statement - the prepared statement to execute
308 * @param random - Whether to support random-access to results
309 * @param args - binary args to prepared statement
310 * @return 0 for success or error code
312 int (*pvbselect)(apr_pool_t *pool, apr_dbd_t *handle,
313 apr_dbd_results_t **res,
314 apr_dbd_prepared_t *statement, int random, va_list args);
316 /** pbquery: query using a prepared statement + binary args
318 * @param pool - working pool
319 * @param handle - the connection
320 * @param nrows - number of rows affected.
321 * @param statement - the prepared statement to execute
322 * @param args - binary args to prepared statement
323 * @return 0 for success or error code
325 int (*pbquery)(apr_pool_t *pool, apr_dbd_t *handle, int *nrows,
326 apr_dbd_prepared_t *statement,const void **args);
328 /** pbselect: select using a prepared statement + binary args
330 * @param pool - working pool
331 * @param handle - the connection
332 * @param res - pointer to query results. May point to NULL on entry
333 * @param statement - the prepared statement to execute
334 * @param random - Whether to support random-access to results
335 * @param args - binary args to prepared statement
336 * @return 0 for success or error code
338 int (*pbselect)(apr_pool_t *pool, apr_dbd_t *handle,
339 apr_dbd_results_t **res, apr_dbd_prepared_t *statement,
340 int random, const void **args);
342 /** datum_get: get a binary entry from a row
344 * @param row - row pointer
345 * @param col - entry number
346 * @param type - type of data to get
347 * @param data - pointer to data, allocated by the caller
348 * @return APR_SUCCESS, an error code on error or if col is out of bounds
350 apr_status_t (*datum_get)(const apr_dbd_row_t *row, int col,
351 apr_dbd_type_e type, void *data);
354 /* Export mutex lock/unlock for drivers that need it
355 * deprecated; create a per-dbd mutex within the (*init) function
356 * to avoid blocking other providers running on other threads
358 APU_DECLARE(apr_status_t) apr_dbd_mutex_lock(void);
359 APU_DECLARE(apr_status_t) apr_dbd_mutex_unlock(void);