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_trxv_spin_db_connect (apr_pool_t *pool, rxv_spin_cpool_t *cpool, const char *conninfo, unsigned char type)
rxv_spin_db_result_trxv_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:
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:

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


Generated on Sat Mar 10 16:30:36 2007 for mod_spin by  doxygen 1.5.1