Database functions

Data Structures
struct	rxv_spin_db_result
	Database result structure. More...
Defines
#define	RXV_SPIN_DB_INFO_DB   0x01
#define	RXV_SPIN_DB_INFO_USER   0x02
#define	RXV_SPIN_DB_INFO_PASS   0x03
#define	RXV_SPIN_DB_INFO_HOST   0x04
#define	RXV_SPIN_DB_INFO_PORT   0x05
#define	RXV_SPIN_DB_INFO_TTY   0x06
#define	RXV_SPIN_DB_INFO_OPTIONS   0x07
#define	RXV_SPIN_DB_INFO_ERROR   0x08
#define	rxv_spin_db_db(conn)   rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_DB)
#define	rxv_spin_db_user(conn)   rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_USER)
#define	rxv_spin_db_pass(conn)   rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_PASS)
#define	rxv_spin_db_host(conn)   rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_HOST)
#define	rxv_spin_db_port(conn)   rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_PORT)
#define	rxv_spin_db_tty(conn)   rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_TTY)
#define	rxv_spin_db_options(conn)   rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_OPTIONS)
#define	rxv_spin_db_error(conn)   rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_ERROR)
Typedefs
typedef rxv_spin_db_result	rxv_spin_db_result_t
Functions
rxv_spin_conn_t *	rxv_spin_db_connect (apr_pool_t *pool, rxv_spin_cpool_t *cpool, const char *conninfo, unsigned char type)
rxv_spin_db_result_t *	rxv_spin_db_exec (apr_pool_t *pool, rxv_spin_conn_t *conn, const char *query)
char *	rxv_spin_db_info (rxv_spin_conn_t *conn, unsigned char what)
apr_status_t	rxv_spin_db_status (rxv_spin_conn_t *conn)
char *	rxv_spin_db_escape (apr_pool_t *pool, rxv_spin_conn_t *conn, const char *str)
apr_status_t	rxv_spin_db_reset (rxv_spin_conn_t *conn)

---

Detailed Description

Database functions (mod_spin API)

---

Define Documentation

#define RXV_SPIN_DB_INFO_DB   0x01

database name

#define RXV_SPIN_DB_INFO_USER   0x02

database user

#define RXV_SPIN_DB_INFO_PASS   0x03

database password

#define RXV_SPIN_DB_INFO_HOST   0x04

database host

#define RXV_SPIN_DB_INFO_PORT   0x05

database port

#define RXV_SPIN_DB_INFO_TTY   0x06

database tty

#define RXV_SPIN_DB_INFO_OPTIONS   0x07

database options

#define RXV_SPIN_DB_INFO_ERROR   0x08

database error

#define rxv_spin_db_db

(

conn

)

rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_DB)

get name

#define rxv_spin_db_user

(

conn

)

rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_USER)

get user

#define rxv_spin_db_pass

(

conn

)

rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_PASS)

get password

#define rxv_spin_db_host

(

conn

)

rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_HOST)

get host

#define rxv_spin_db_port

(

conn

)

rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_PORT)

get port

#define rxv_spin_db_tty

(

conn

)

rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_TTY)

get tty

#define rxv_spin_db_options

(

conn

)

rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_OPTIONS)

get options

#define rxv_spin_db_error

(

conn

)

rxv_spin_db_info((conn),RXV_SPIN_DB_INFO_ERROR)

get error

---

Typedef Documentation

typedef struct rxv_spin_db_result rxv_spin_db_result_t

database query result type

---

Function Documentation

rxv_spin_conn_t* rxv_spin_db_connect	(	apr_pool_t *	pool,
		rxv_spin_cpool_t *	cpool,
		const char *	conninfo,
		unsigned char	type
	)

Connect to a database and optionally pool the connection.

Parameters:

	pool	Memory pool used for memory allocations
	cpool	Connection pool
	conninfo	Connection string
	type	Database type

Returns:

pointer to a database connection, NULL on error

Example:

 rxv_spin_db_connect(ctx->pool,NULL,"dbname=spintest",RXV_SPIN_DB_PGSQL);

 rxv_spin_db_connect(ctx->pool,ctx->cpool,"dbname=spintest",RXV_SPIN_DB_MYSQL);

Remarks:

If connection pooling isn't used, the cpool parameter has to be set to NULL. The pool parameter has to point to a valid APR memory pool. If pooled connections aren't used, the connection will be closed on pool (the first argument) cleanup. Meaning, if you want custom lifetime of the connection, create your own memory pool and then destroy it when you don't need the database connection any more.

IMPORTANT:

Alywas use relevant macros (such as RXV_SPIN_CONN_IS_PGSQL(c)) to enquire about the type of the connection, because the type is an unsigned char that is a combination of various binary data, including the database type and connection pooled flag.

IMPORTANT:

This function takes connection string in the form defined by PostgreSQL manual. In fact, the code for the string parsing (for databases other than PostgreSQL) has been directly lifted from PostgreSQL version 7.4.1. However, when used with database types other than PostgreSQL, not all keywords are supported. Namely, for use with MySQL, you can only use "host", "port", "dbname", "user" and "password". Anything else will cause errors.

rxv_spin_db_result_t* rxv_spin_db_exec	(	apr_pool_t *	pool,
		rxv_spin_conn_t *	conn,
		const char *	query
	)

Execute a database query of any type.

Parameters:

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

Returns:

Valid rxv_spin_db_result_t pointer, NULL on error

Example:

 result=rxv_spin_db_exec(ctx->pool,conn,"select * from spintest");

Remarks:

Depending on the nature of the query, result->data may be NULL. Only SELECT and similar queries that return tuples (rows) will have this member non-NULL. To verify if the query finished successfully, use result->status.

char* rxv_spin_db_info	(	rxv_spin_conn_t *	conn,
		unsigned char	what
	)

Get various info about the database connection.

Parameters:

	conn	Database connection
	what	The type of information to get

Returns:

string with the desired info, NULL on error

Example:

 rxv_spin_db_info(conn);

Remarks:

You can use either this function or defined macros to get specific information about this database connection. Note that some database APIs won't provide all information. In that case, an empty string might be returned.

apr_status_t rxv_spin_db_status

(

rxv_spin_conn_t *

conn

)

Get the status of the connection.

Parameters:

conn

Database connection

Returns:

APR_SUCCESS if OK, otherwise an error

Example:

 rxv_spin_db_status(conn);

char* rxv_spin_db_escape	(	apr_pool_t *	pool,
		rxv_spin_conn_t *	conn,
		const char *	str
	)

Escape a string for use within an SQL query.

Parameters:

	pool	Pool used for memory allocation
	conn	Database connection
	str	string to be escaped

Returns:

Pointer to escaped string, NULL on error

Example:

 escstr=rxv_spin_db_escape(ctx->pool,conn,"'A string to escape'");

Remarks:

The connection pointer is used to determine database type and therefore use the correct, database specific escaping function. MySQL needs a pointer to the connection in order to determine the correct character set. Therefore the second argument must be a valid connection pointer. The underlying database specific functions have slightly different behaviour, depending on the database being used. Check in the relevant manual for differences.

apr_status_t rxv_spin_db_reset

(

rxv_spin_conn_t *

conn

)

Reset a database connection (i.e. attempt to reconnect).

Parameters:

conn

Database connection to reset

Returns:

APR_SUCCESS on success, otherwise an error

Example:

 rxv_spin_db_reset(conn);

Remarks:

This function is not normally called from the application. Reset is performed automatically by mod_spin if the connection is down. However, you may choose to use this function in same rare cases.

---