Database functions

Functions
apr_pool_t *	rxv_spin_db_pool (rxv_spin_db_t *db)
char *	rxv_spin_db_cinfo (rxv_spin_db_t *db)
const apr_dbd_driver_t *	rxv_spin_db_driver (rxv_spin_db_t *db)
apr_dbd_t *	rxv_spin_db_handle (rxv_spin_db_t *db)
apr_dbd_transaction_t *	rxv_spin_db_txn (rxv_spin_db_txn_t *txn)
rxv_spin_db_t *	rxv_spin_db_open (rxv_spin_ctx_t *ctx, const char *conninfo)
apr_status_t	rxv_spin_db_close (rxv_spin_ctx_t *ctx, rxv_spin_db_t *db)
apr_status_t	rxv_spin_db_status (rxv_spin_ctx_t *ctx, rxv_spin_db_t *db)
rxv_spin_data_t *	rxv_spin_db_data (apr_pool_t *pool, rxv_spin_db_t *db, apr_dbd_results_t *dbdres)
rxv_spin_data_t *	rxv_spin_db_select (apr_pool_t *pool, rxv_spin_db_t *db, const char *query)
int	rxv_spin_db_query (apr_pool_t *pool, rxv_spin_db_t *db, const char *query)
rxv_spin_data_t *	rxv_spin_db_pselect (apr_pool_t *pool, rxv_spin_db_t *db, const char *query,...)
int	rxv_spin_db_pquery (apr_pool_t *pool, rxv_spin_db_t *db, const char *query,...)
rxv_spin_db_txn_t *	rxv_spin_db_start (apr_pool_t *pool, rxv_spin_db_t *db)
apr_status_t	rxv_spin_db_end (rxv_spin_db_txn_t *txn)

---

Detailed Description

Database functions (mod_spin API)

---

Function Documentation

apr_pool_t* rxv_spin_db_pool

(

rxv_spin_db_t *

db

)

Retrieve database specific pool.

Parameters:

db

Database connection

Returns:

pointer to database specific pool, NULL on error

Example:

 rxv_spin_db_pool(db);

char* rxv_spin_db_cinfo

(

rxv_spin_db_t *

db

)

Retrieve database connection information.

Parameters:

db

Database connection

Returns:

pointer to connection information, NULL on error

Example:

 rxv_spin_db_cinfo(db);

const apr_dbd_driver_t* rxv_spin_db_driver

(

rxv_spin_db_t *

db

)

Retrieve database driver.

Parameters:

db

Database connection

Returns:

pointer to database driver, NULL on error

Example:

 rxv_spin_db_driver(db);

apr_dbd_t* rxv_spin_db_handle

(

rxv_spin_db_t *

db

)

Retrieve database handle.

Parameters:

db

Database connection

Returns:

pointer to database handle, NULL on error

Example:

 rxv_spin_db_handle(db);

apr_dbd_transaction_t* rxv_spin_db_txn

(

rxv_spin_db_txn_t *

txn

)

Retrieve database transaction.

Parameters:

txn

Database transaction

Returns:

pointer to database transaction, NULL on error

Example:

 rxv_spin_db_txn(txn);

Remarks:

This function returns underlying Apache Portable Runtime DBD transaction.

rxv_spin_db_t* rxv_spin_db_open	(	rxv_spin_ctx_t *	ctx,
		const char *	conninfo
	)

Connect to a database and optionally pool the connection.

Parameters:

	ctx	Context
	conninfo	Connection string

Returns:

pointer to a database connection, NULL on error

Example:

 rxv_spin_db_open(ctx,"pgsql:dbname=spintest");

Remarks:

Whether or not the connection will be pooled, depends on what has been set as connection pool value in the context. And this depends on the SpinConnPool configuration parameter (default is on). Valid database prefixes are pgsql, mysql, sqlite2, sqlite3, oracle, freetds etc., depending on the drivers that have been compiled and linked with Apache Portable Runtime Utilities Library (APU).

Connections will be pooled by using connection string as a key into the hash. So, if a connection string differs in the amount of white space or case, this will open a new connection.

Cleanup will be registered with the context pool.

apr_status_t rxv_spin_db_close	(	rxv_spin_ctx_t *	ctx,
		rxv_spin_db_t *	db
	)

Close a database connection.

Parameters:

	ctx	Context
	db	Pointer to a database connection

Returns:

APR_SUCCESS on success, otherwise an error

Example:

 rxv_spin_db_close(ctx,db);

apr_status_t rxv_spin_db_status	(	rxv_spin_ctx_t *	ctx,
		rxv_spin_db_t *	db
	)

Get the status of the connection.

Parameters:

	ctx	Context
	db	Database connection

Returns:

APR_SUCCESS if OK, otherwise an error

Example:

 if(rxv_spin_db_status(ctx,db)!=APR_SUCCESS){
   ...
 }

Remarks:

If this function returns any code other than success (for valid ctx and db), the database connection should not be used again.

rxv_spin_data_t* rxv_spin_db_data	(	apr_pool_t *	pool,
		rxv_spin_db_t *	db,
		apr_dbd_results_t *	dbdres
	)

Convert APR DBD SQL result set to mod_spin database result.

Parameters:

	pool	Pool used for memory allocation
	db	Database connection
	dbdres	APR DBD results

Returns:

Valid rxv_spin_data_t pointer, NULL on error

Example:

 rxv_spin_db_data(pool,conn,db,dbdres);

Remarks:

Make sure the pool passed into this function is the same one used for select or you will have memory allocation problems.

rxv_spin_data_t* rxv_spin_db_select	(	apr_pool_t *	pool,
		rxv_spin_db_t *	db,
		const char *	query
	)

Execute a database query that returns a result set (i.e. SELECT).

Parameters:

	pool	Pool used for memory allocation
	db	Database connection
	query	SQL query to be performed

Returns:

Valid rxv_spin_data_t pointer, NULL on error

Example:

 result=rxv_spin_db_select(pool,db,"select * from spintest");

Remarks:

If the query finished successfully, returned data will not be NULL, but a pointer to an empty data structure.

int rxv_spin_db_query	(	apr_pool_t *	pool,
		rxv_spin_db_t *	db,
		const char *	query
	)

Execute a database query that doesn't return a result set.

Parameters:

	pool	Pool used for memory allocation
	db	Database connection
	query	SQL query to be performed

Returns:

Number of rows affected, -1 on error

Example:

 nrows=rxv_spin_db_query(pool,db,"delete from spintest");

rxv_spin_data_t* rxv_spin_db_pselect	(	apr_pool_t *	pool,
		rxv_spin_db_t *	db,
		const char *	query,
			...
	)

Prepare and execute database that returns a result set (i.e. SELECT)

Parameters:

	pool	Pool used for memory allocation
	db	Database connection
	query	SQL query to be prepared and executed
	...	Parameters for prepared statement, (constant pointer to nul terminated string)

Returns:

Valid rxv_spin_data_t pointer, NULL on error

Example:

 result=rxv_spin_db_pselect(pool,db,"select * from names where name = %s",
                            "Dude",NULL);

Remarks:

Prepared statements done using this function only accept string parameters. For anything more complicated, use native database API and then convert the data so it can be used within the context. Make sure the number of paramters passed is correct, or you may be in for a nasty surprise when your program segfaults.

Warning:

Make sure you use %s where the replaced parameter is supposed to go. This is the official Apache Portable Runtime DBD way :-).

The last parameter in the list should be NULL and it has to be specified even when there are no other parameters.

int rxv_spin_db_pquery	(	apr_pool_t *	pool,
		rxv_spin_db_t *	db,
		const char *	query,
			...
	)

Prepare and execute database that doesn't return a result set.

Parameters:

	pool	Pool used for memory allocation
	db	Database connection
	query	SQL query to be prepared and executed
	...	Parameters for prepared statement, (constant pointer to nul terminated string)

Returns:

Number of rows affected, -1 on error

Example:

 nrows=rxv_spin_db_pquery(pool,db,"delete from names where name = %s",
                          "Dude",NULL);

Remarks:

Prepared statements done using this function only accept string parameters. For anything more complicated, use native database API and then convert the data so it can be used within the context. Make sure the number of paramters passed is correct, or you may be in for a nasty surprise when your program segfaults.

Warning:

Make sure you use %s where the replaced parameter is supposed to go. This is the official Apache Portable Runtime DBD way :-).

The last parameter in the list should be NULL and it has to be specified even when there are no other parameters.

rxv_spin_db_txn_t* rxv_spin_db_start	(	apr_pool_t *	pool,
		rxv_spin_db_t *	db
	)

Start a transaction.

Parameters:

	pool	Pool used for memory allocation
	db	Database connection

Returns:

Pointer to a valid transaction, NULL on error

Example:

 txn=rxv_spin_db_start(pool,db);

Remarks:

The pool is also used to register a cleanup function for the transaction. It makes little sense to have transactions more permanent than one request, so this should always be the request pool, which can be obtained from the context.

apr_status_t rxv_spin_db_end

(

rxv_spin_db_txn_t *

txn

)

End a transaction.

Parameters:

txn

Database transaction

Returns:

APR_SUCCESS on success, otherwise an error

Example:

 rxv_spin_db_end(txn);