DBD routines

Macros
#define	APR_DBD_TRANSACTION_COMMIT   0x00
#define	APR_DBD_TRANSACTION_ROLLBACK   0x01
#define	APR_DBD_TRANSACTION_IGNORE_ERRORS   0x02

Typedefs
typedef struct apr_dbd_driver_t	apr_dbd_driver_t
typedef struct apr_dbd_t	apr_dbd_t
typedef struct apr_dbd_transaction_t	apr_dbd_transaction_t
typedef struct apr_dbd_results_t	apr_dbd_results_t
typedef struct apr_dbd_row_t	apr_dbd_row_t
typedef struct apr_dbd_prepared_t	apr_dbd_prepared_t

Enumerations
enum	apr_dbd_type_e {   APR_DBD_TYPE_NONE , APR_DBD_TYPE_TINY , APR_DBD_TYPE_UTINY , APR_DBD_TYPE_SHORT ,   APR_DBD_TYPE_USHORT , APR_DBD_TYPE_INT , APR_DBD_TYPE_UINT , APR_DBD_TYPE_LONG ,   APR_DBD_TYPE_ULONG , APR_DBD_TYPE_LONGLONG , APR_DBD_TYPE_ULONGLONG , APR_DBD_TYPE_FLOAT ,   APR_DBD_TYPE_DOUBLE , APR_DBD_TYPE_STRING , APR_DBD_TYPE_TEXT , APR_DBD_TYPE_TIME ,   APR_DBD_TYPE_DATE , APR_DBD_TYPE_DATETIME , APR_DBD_TYPE_TIMESTAMP , APR_DBD_TYPE_ZTIMESTAMP ,   APR_DBD_TYPE_BLOB , APR_DBD_TYPE_CLOB , APR_DBD_TYPE_NULL }

Functions
	APU_DECLARE (apr_status_t) apr_dbd_init(apr_pool_t *pool)
	APU_DECLARE (const char *) apr_dbd_name(const apr_dbd_driver_t *driver)
	APU_DECLARE (void *) apr_dbd_native_handle(const apr_dbd_driver_t *driver
	APU_DECLARE_NONSTD (int) apr_dbd_pvquery(const apr_dbd_driver_t *driver

Variables
const char *	name
const char const apr_dbd_driver_t **	driver
apr_pool_t *	pool
apr_pool_t const char *	params
apr_pool_t const char apr_dbd_t **	handle
apr_pool_t const char apr_dbd_t const char **	error
apr_pool_t apr_dbd_t apr_dbd_transaction_t **	trans
apr_dbd_transaction_t int	mode
apr_dbd_t int *	nrows
apr_dbd_t int const char *	statement
apr_pool_t apr_dbd_t apr_dbd_results_t **	res
apr_pool_t apr_dbd_t apr_dbd_results_t const char int	random
apr_pool_t apr_dbd_results_t apr_dbd_row_t **	row
apr_pool_t apr_dbd_results_t apr_dbd_row_t int	rownum
apr_dbd_row_t int	col
apr_dbd_t int	errnum
apr_pool_t const char *	string
apr_pool_t apr_dbd_t const char *	query
apr_pool_t apr_dbd_t const char const char *	label
apr_pool_t apr_dbd_t int apr_dbd_prepared_t int	nargs
apr_pool_t apr_dbd_t int apr_dbd_prepared_t int const char **	args
apr_pool_t apr_dbd_t int apr_dbd_prepared_t apr_pool_t apr_dbd_t apr_dbd_results_t apr_dbd_prepared_t int apr_dbd_row_t int apr_dbd_type_e	type
apr_pool_t apr_dbd_t int apr_dbd_prepared_t apr_pool_t apr_dbd_t apr_dbd_results_t apr_dbd_prepared_t int apr_dbd_row_t int apr_dbd_type_e void *	data

Detailed Description

Macro Definition Documentation

APR_DBD_TRANSACTION_COMMIT

#define APR_DBD_TRANSACTION_COMMIT   0x00

commit the transaction

Definition at line 239 of file apr_dbd.h.

APR_DBD_TRANSACTION_IGNORE_ERRORS

#define APR_DBD_TRANSACTION_IGNORE_ERRORS   0x02

ignore transaction errors

Definition at line 241 of file apr_dbd.h.

APR_DBD_TRANSACTION_ROLLBACK

#define APR_DBD_TRANSACTION_ROLLBACK   0x01

rollback the transaction

Definition at line 240 of file apr_dbd.h.

Typedef Documentation

apr_dbd_driver_t

typedef struct apr_dbd_driver_t apr_dbd_driver_t

Definition at line 82 of file apr_dbd.h.

apr_dbd_prepared_t

typedef struct apr_dbd_prepared_t apr_dbd_prepared_t

Definition at line 87 of file apr_dbd.h.

apr_dbd_results_t

typedef struct apr_dbd_results_t apr_dbd_results_t

Definition at line 85 of file apr_dbd.h.

apr_dbd_row_t

typedef struct apr_dbd_row_t apr_dbd_row_t

Definition at line 86 of file apr_dbd.h.

apr_dbd_t

typedef struct apr_dbd_t apr_dbd_t

Definition at line 83 of file apr_dbd.h.

apr_dbd_transaction_t

typedef struct apr_dbd_transaction_t apr_dbd_transaction_t

Definition at line 84 of file apr_dbd.h.

Enumeration Type Documentation

apr_dbd_type_e

enum apr_dbd_type_e

Mapping of C to SQL types, used for prepared statements.

Remarks

For apr_dbd_p[v]query/select functions, in and out parameters are always const char * (i.e. regular nul terminated strings). LOB types are passed with four (4) arguments: payload, length, table and column, all as const char *, where table and column are reserved for future use by Oracle.

For apr_dbd_p[v]bquery/select functions, in and out parameters are described next to each enumeration constant and are generally native binary types or some APR data type. LOB types are passed with four (4) arguments: payload (char*), length (apr_size_t*), table (char*) and column (char*). Table and column are reserved for future use by Oracle.

Enumerator
APR_DBD_TYPE_NONE
APR_DBD_TYPE_TINY	%hhd : in, out: char*
APR_DBD_TYPE_UTINY	%hhu : in, out: unsigned char*
APR_DBD_TYPE_SHORT	%hd : in, out: short*
APR_DBD_TYPE_USHORT	%hu : in, out: unsigned short*
APR_DBD_TYPE_INT	%d : in, out: int*
APR_DBD_TYPE_UINT	%u : in, out: unsigned int*
APR_DBD_TYPE_LONG	%ld : in, out: long*
APR_DBD_TYPE_ULONG	%lu : in, out: unsigned long*
APR_DBD_TYPE_LONGLONG	%lld : in, out: apr_int64_t*
APR_DBD_TYPE_ULONGLONG	%llu : in, out: apr_uint64_t*
APR_DBD_TYPE_FLOAT	%f : in, out: float*
APR_DBD_TYPE_DOUBLE	%lf : in, out: double*
APR_DBD_TYPE_STRING	%s : in: char*, out: char**
APR_DBD_TYPE_TEXT	%pDt : in: char*, out: char**
APR_DBD_TYPE_TIME	%pDi : in: char*, out: char**
APR_DBD_TYPE_DATE	%pDd : in: char*, out: char**
APR_DBD_TYPE_DATETIME	%pDa : in: char*, out: char**
APR_DBD_TYPE_TIMESTAMP	%pDs : in: char*, out: char**
APR_DBD_TYPE_ZTIMESTAMP	%pDz : in: char*, out: char**
APR_DBD_TYPE_BLOB	%pDb : in: char* apr_size_t* char* char*, out: apr_bucket_brigade*
APR_DBD_TYPE_CLOB	%pDc : in: char* apr_size_t* char* char*, out: apr_bucket_brigade*
APR_DBD_TYPE_NULL	%pDn : in: void*, out: void**

Definition at line 55 of file apr_dbd.h.

Function Documentation

APU_DECLARE() [1/3]

apr_pool_t apr_dbd_t int apr_dbd_prepared_t apr_pool_t apr_dbd_t apr_dbd_results_t apr_dbd_prepared_t int APU_DECLARE

(

apr_status_t

)

apr_dbd_init: perform once-only initialisation. Call once only.

Parameters

pool	- pool to register any shutdown cleanups, etc

apr_dbd_get_driver: get the driver struct for a name

Parameters

pool	- (process) pool to register cleanup
name	- driver name
driver	- pointer to driver struct.

Returns

APR_SUCCESS for success

APR_ENOTIMPL for no driver (when DSO not enabled)

APR_EDSOOPEN if DSO driver file can't be opened

APR_ESYMNOTFOUND if the driver file doesn't contain a driver

apr_dbd_open_ex: open a connection to a backend

Parameters

driver	- driver struct.
pool	- working pool
params	- arguments to driver (implementation-dependent)
handle	- pointer to handle to return
error	- descriptive error.

Returns

APR_SUCCESS for success

APR_EGENERAL if driver exists but connection failed

Remarks

PostgreSQL: the params is passed directly to the PQconnectdb() function (check PostgreSQL documentation for more details on the syntax).

SQLite2: the params is split on a colon, with the first part used as the filename and second part converted to an integer and used as file mode.

SQLite3: the params is passed directly to the sqlite3_open() function as a filename to be opened (check SQLite3 documentation for more details).

Oracle: the params can have "user", "pass", "dbname" and "server" keys, each followed by an equal sign and a value. Such key/value pairs can be delimited by space, CR, LF, tab, semicolon, vertical bar or comma.

MySQL: the params can have "host", "port", "user", "pass", "dbname", "sock", "flags" "fldsz", "group" and "reconnect" keys, each followed by an equal sign and a value. Such key/value pairs can be delimited by space, CR, LF, tab, semicolon, vertical bar or comma. For now, "flags" can only recognise CLIENT_FOUND_ROWS (check MySQL manual for details). The value associated with "fldsz" determines maximum amount of memory (in bytes) for each of the fields in the result set of prepared statements. By default, this value is 1 MB. The value associated with "group" determines which group from configuration file to use (see MYSQL_READ_DEFAULT_GROUP option of mysql_options() in MySQL manual). Reconnect is set to 1 by default (i.e. true).

apr_dbd_open: open a connection to a backend

Parameters

driver	- driver struct.
pool	- working pool
params	- arguments to driver (implementation-dependent)
handle	- pointer to handle to return

Returns

APR_SUCCESS for success

APR_EGENERAL if driver exists but connection failed

See also

apr_dbd_open_ex

apr_dbd_close: close a connection to a backend

Parameters

driver	- driver struct.
handle	- handle to close

Returns

APR_SUCCESS for success or error status

check_conn: check status of a database connection

Parameters

driver	- the driver
pool	- working pool
handle	- the connection to check

Returns

APR_SUCCESS or error

apr_dbd_set_dbname: select database name. May be a no-op if not supported.

Parameters

driver	- the driver
pool	- working pool
handle	- the connection
name	- the database to select

Returns

0 for success or error code

apr_dbd_transaction_start: start a transaction. May be a no-op.

Parameters

driver	- the driver
pool	- a pool to use for error messages (if any).
handle	- the db connection
trans	- ptr to a transaction. May be null on entry

Returns

0 for success or error code

Remarks

Note that transaction modes, set by calling apr_dbd_transaction_mode_set(), will affect all query/select calls within a transaction. By default, any error in query/select during a transaction will cause the transaction to inherit the error code and any further query/select calls will fail immediately. Put transaction in "ignore errors" mode to avoid that. Use "rollback" mode to do explicit rollback.

apr_dbd_transaction_end: end a transaction (commit on success, rollback on error). May be a no-op.

Parameters

driver	- the driver
handle	- the db connection
trans	- the transaction.

Returns

0 for success or error code

apr_dbd_transaction_mode_get: get the mode of transaction

Parameters

driver	- the driver
trans	- the transaction

Returns

mode of transaction

apr_dbd_transaction_mode_set: set the mode of transaction

Parameters

driver	- the driver
trans	- the transaction
mode	- new mode of the transaction

Returns

the mode of transaction in force after the call

apr_dbd_query: execute an SQL query that doesn't return a result set

Parameters

driver	- the driver
handle	- the connection
nrows	- number of rows affected.
statement	- the SQL statement to execute

Returns

0 for success or error code

apr_dbd_select: execute an SQL query that returns a result set

Parameters

driver	- the driver
pool	- pool to allocate the result set
handle	- the connection
res	- pointer to result set pointer. May point to NULL on entry
statement	- the SQL statement to execute
random	- 1 to support random access to results (seek any row); 0 to support only looping through results in order (async access - faster)

Returns

0 for success or error code

apr_dbd_num_cols: get the number of columns in a results set

Parameters

driver	- the driver
res	- result set.

Returns

number of columns

apr_dbd_num_tuples: get the number of rows in a results set of a synchronous select

Parameters

driver	- the driver
res	- result set.

Returns

number of rows, or -1 if the results are asynchronous

apr_dbd_get_row: get a row from a result set

Parameters

driver	- the driver
pool	- pool to allocate the row
res	- result set pointer
row	- pointer to row pointer. May point to NULL on entry
rownum	- row number (counting from 1), or -1 for "next row". Ignored if random access is not supported.

Returns

0 for success, -1 for rownum out of range or data finished

apr_dbd_prepare: prepare a statement

Parameters

driver	- the driver
pool	- pool to alloc the result from
handle	- the connection
query	- the SQL query
label	- A label for the prepared statement. use NULL for temporary prepared statements (eg within a Request in httpd)
statement	- statement to prepare. May point to null on entry.

Returns

0 for success or error code

Remarks

To specify parameters of the prepared query, use %s, %d etc. (see below for full list) in place of database specific parameter syntax (e.g. for PostgreSQL, this would be $1, $2, for SQLite3 this would be ? etc.). For instance: "SELECT name FROM customers WHERE name=%s" would be a query that this function understands.

Here is the full list of format specifiers that this function understands and what they map to in SQL: %hhd (TINY INT), %hhu (UNSIGNED TINY INT), %hd (SHORT), %hu (UNSIGNED SHORT), %d (INT), %u (UNSIGNED INT), %ld (LONG), %lu (UNSIGNED LONG), %lld (LONG LONG), %llu (UNSIGNED LONG LONG), %f (FLOAT, REAL), %lf (DOUBLE PRECISION), %s (VARCHAR), %pDt (TEXT), %pDi (TIME), %pDd (DATE), %pDa (DATETIME), %pDs (TIMESTAMP), %pDz (TIMESTAMP WITH TIME ZONE), %pDb (BLOB), %pDc (CLOB) and %pDn (NULL). Not all databases have support for all these types, so the underlying driver will attempt the "best match" where possible. A % followed by any letter not in the above list will be interpreted as VARCHAR (i.e. %s).

apr_dbd_pquery: query using a prepared statement + args

Parameters

driver	- the driver
pool	- working pool
handle	- the connection
nrows	- number of rows affected.
statement	- the prepared statement to execute
nargs	- ignored (for backward compatibility only)
args	- args to prepared statement

Returns

0 for success or error code

apr_dbd_pselect: select using a prepared statement + args

Parameters

driver	- the driver
pool	- working pool
handle	- the connection
res	- pointer to query results. May point to NULL on entry
statement	- the prepared statement to execute
random	- Whether to support random-access to results
nargs	- ignored (for backward compatibility only)
args	- args to prepared statement

Returns

0 for success or error code

apr_dbd_pbquery: query using a prepared statement + binary args

Parameters

driver	- the driver
pool	- working pool
handle	- the connection
nrows	- number of rows affected.
statement	- the prepared statement to execute
args	- binary args to prepared statement

Returns

0 for success or error code

apr_dbd_pbselect: select using a prepared statement + binary args

Parameters

driver	- the driver
pool	- working pool
handle	- the connection
res	- pointer to query results. May point to NULL on entry
statement	- the prepared statement to execute
random	- Whether to support random-access to results
args	- binary args to prepared statement

Returns

0 for success or error code

apr_dbd_datum_get: get a binary entry from a row

Parameters

driver	- the driver
row	- row pointer
col	- entry number
type	- type of data to get
data	- pointer to data, allocated by the caller

Returns

APR_SUCCESS on success, APR_ENOENT if data is NULL or APR_EGENERAL

< Shared lock. More than one process or thread can hold a shared lock at any given time. Essentially, this is a "read lock", preventing writers from establishing an exclusive lock.

< Shared lock. More than one process or thread can hold a shared lock at any given time. Essentially, this is a "read lock", preventing writers from establishing an exclusive lock.

< Exclusive lock. Only one process may hold an exclusive lock at any given time. This is analogous to a "write lock".

< Exclusive lock. Only one process may hold an exclusive lock at any given time. This is analogous to a "write lock".

< Replace

< Insert with duplicates

< Shared lock. More than one process or thread can hold a shared lock at any given time. Essentially, this is a "read lock", preventing writers from establishing an exclusive lock.

< Shared lock. More than one process or thread can hold a shared lock at any given time. Essentially, this is a "read lock", preventing writers from establishing an exclusive lock.

< mask to extract lock type

< Shared lock. More than one process or thread can hold a shared lock at any given time. Essentially, this is a "read lock", preventing writers from establishing an exclusive lock.

< Exclusive lock. Only one process may hold an exclusive lock at any given time. This is analogous to a "write lock".

< Exclusive lock. Only one process may hold an exclusive lock at any given time. This is analogous to a "write lock".

< Size of the file

< Shared lock. More than one process or thread can hold a shared lock at any given time. Essentially, this is a "read lock", preventing writers from establishing an exclusive lock.

< Exclusive lock. Only one process may hold an exclusive lock at any given time. This is analogous to a "write lock".

Definition at line 358 of file apr_brigade.c.

APU_DECLARE() [2/3]

APU_DECLARE

(

const char *

)

const

apr_dbd_name: get the name of the driver

Parameters

driver

- the driver

Returns

- name

apr_dbd_get_entry: get an entry from a row

Parameters

driver	- the driver
row	- row pointer
col	- entry number

Returns

value from the row, or NULL if col is out of bounds.

apr_dbd_get_name: get an entry name from a result set

Parameters

driver	- the driver
res	- result set pointer
col	- entry number

Returns

name of the entry, or NULL if col is out of bounds.

apr_dbd_error: get current error message (if any)

Parameters

driver	- the driver
handle	- the connection
errnum	- error code from operation that returned an error

Returns

the database current error message, or message for errnum (implementation-dependent whether errnum is ignored)

apr_dbd_escape: escape a string so it is safe for use in query/select

Parameters

driver	- the driver
pool	- pool to alloc the result from
string	- the string to escape
handle	- the connection

Returns

the escaped, safe string

APU_DECLARE() [3/3]

APU_DECLARE

(

void *

)

const

apr_dbd_native_handle: get native database handle of the underlying db

Parameters

driver	- the driver
handle	- apr_dbd handle

Returns

- native handle

APU_DECLARE_NONSTD()

apr_pool_t apr_dbd_t int apr_dbd_prepared_t APU_DECLARE_NONSTD

(

int

)

const

apr_dbd_pvquery: query using a prepared statement + args

Parameters

driver	- the driver
pool	- working pool
handle	- the connection
nrows	- number of rows affected.
statement	- the prepared statement to execute
...	- varargs list

Returns

0 for success or error code

apr_dbd_pvselect: select using a prepared statement + args

Parameters

driver	- the driver
pool	- working pool
handle	- the connection
res	- pointer to query results. May point to NULL on entry
statement	- the prepared statement to execute
random	- Whether to support random-access to results
...	- varargs list

Returns

0 for success or error code

apr_dbd_pvbquery: query using a prepared statement + binary args

Parameters

driver	- the driver
pool	- working pool
handle	- the connection
nrows	- number of rows affected.
statement	- the prepared statement to execute
...	- varargs list of binary args

Returns

0 for success or error code

apr_dbd_pvbselect: select using a prepared statement + binary args

Parameters

driver	- the driver
pool	- working pool
handle	- the connection
res	- pointer to query results. May point to NULL on entry
statement	- the prepared statement to execute
random	- Whether to support random-access to results
...	- varargs list of binary args

Returns

0 for success or error code

Variable Documentation

args

apr_pool_t apr_dbd_t apr_dbd_results_t apr_dbd_prepared_t int const void ** args

Definition at line 415 of file apr_dbd.h.

col

apr_pool_t apr_dbd_t int apr_dbd_prepared_t apr_pool_t apr_dbd_t apr_dbd_results_t apr_dbd_prepared_t int apr_dbd_row_t int col

Definition at line 331 of file apr_dbd.h.

data

apr_pool_t apr_dbd_t int apr_dbd_prepared_t apr_pool_t apr_dbd_t apr_dbd_results_t apr_dbd_prepared_t int apr_dbd_row_t int apr_dbd_type_e void* data

Definition at line 541 of file apr_dbd.h.

driver

const char const apr_dbd_driver_t** driver

Definition at line 106 of file apr_dbd.h.

errnum

apr_dbd_t int errnum

Definition at line 353 of file apr_dbd.h.

error

apr_pool_t const char apr_dbd_t const char** error

Definition at line 143 of file apr_dbd.h.

handle

apr_pool_t apr_dbd_t int apr_dbd_prepared_t apr_pool_t apr_dbd_t * handle

Definition at line 142 of file apr_dbd.h.

label

apr_pool_t apr_dbd_t const char const char* label

Definition at line 397 of file apr_dbd.h.

mode

apr_dbd_transaction_t int mode

Definition at line 261 of file apr_dbd.h.

name

apr_pool_t apr_dbd_t const char * name

Definition at line 105 of file apr_dbd.h.

nargs

apr_pool_t apr_dbd_t apr_dbd_results_t apr_dbd_prepared_t int int nargs

Definition at line 414 of file apr_dbd.h.

nrows

apr_pool_t apr_dbd_t int * nrows

Definition at line 272 of file apr_dbd.h.

params

apr_pool_t const char * params

Definition at line 141 of file apr_dbd.h.

pool

apr_pool_t apr_dbd_t int apr_dbd_prepared_t apr_pool_t * pool

Definition at line 141 of file apr_dbd.h.

query

apr_pool_t apr_dbd_t const char* query

Definition at line 396 of file apr_dbd.h.

random

apr_pool_t apr_dbd_t int apr_dbd_prepared_t apr_pool_t apr_dbd_t apr_dbd_results_t apr_dbd_prepared_t int random

Definition at line 288 of file apr_dbd.h.

res

apr_pool_t apr_dbd_t int apr_dbd_prepared_t apr_pool_t apr_dbd_t apr_dbd_results_t ** res

Definition at line 287 of file apr_dbd.h.

row

apr_pool_t apr_dbd_t int apr_dbd_prepared_t apr_pool_t apr_dbd_t apr_dbd_results_t apr_dbd_prepared_t int apr_dbd_row_t * row

Definition at line 320 of file apr_dbd.h.

rownum

apr_pool_t apr_dbd_results_t apr_dbd_row_t int rownum

Definition at line 321 of file apr_dbd.h.

statement

apr_pool_t apr_dbd_t int apr_dbd_prepared_t apr_pool_t apr_dbd_t apr_dbd_results_t apr_dbd_prepared_t * statement

Definition at line 272 of file apr_dbd.h.

string

apr_pool_t const char* string

Definition at line 364 of file apr_dbd.h.

trans

apr_dbd_transaction_t * trans

Definition at line 224 of file apr_dbd.h.

type

apr_pool_t apr_dbd_t int apr_dbd_prepared_t apr_pool_t apr_dbd_t apr_dbd_results_t apr_dbd_prepared_t int apr_dbd_row_t int apr_dbd_type_e type

Definition at line 541 of file apr_dbd.h.