CppDB
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator
Public Member Functions
cppdb::session Class Reference

SQL session object that represents a single connection and is the gateway to SQL database. More...

#include <cppdb/frontend.h>

List of all members.

Public Member Functions

 session ()
 session (session const &)
session const & operator= (session const &)
 ~session ()
 session (connection_info const &ci)
 session (std::string const &cs)
 session (connection_info const &ci, once_functor const &f)
 session (std::string const &cs, once_functor const &f)
 session (ref_ptr< backend::connection > conn, once_functor const &f)
 session (ref_ptr< backend::connection > conn)
void open (connection_info const &ci)
void open (std::string const &cs)
void close ()
bool is_open ()
statement prepare (std::string const &query)
statement operator<< (std::string const &q)
statement operator<< (char const *s)
statement create_statement (std::string const &q)
statement create_prepared_statement (std::string const &q)
statement create_prepared_uncached_statement (std::string const &q)
void clear_cache ()
void clear_pool ()
void begin ()
void commit ()
void rollback ()
std::string escape (char const *b, char const *e)
std::string escape (char const *s)
std::string escape (std::string const &s)
std::string driver ()
std::string engine ()
bool recyclable ()
void recyclable (bool value)
bool once_called ()
void once_called (bool state)
void once (once_functor const &f)
connection_specific_dataget_specific (std::type_info const &t)
connection_specific_datarelease_specific (std::type_info const &t)
void reset_specific (std::type_info const &t, connection_specific_data *p=0)
template<typename T >
T * get_specific ()
template<typename T >
T * release_specific ()
template<typename T >
void reset_specific (T *p=0)

Detailed Description

SQL session object that represents a single connection and is the gateway to SQL database.

It is the main class that is used for access to the DB, it uses various singleton classes to load drivers open connections and cache them.


Constructor & Destructor Documentation

Create an empty session object, it should not be used until it is opened with calling open() function.

Copy a session object, note - it copies only the reference to the underlying connection, so you should be very careful when you do it.

Destroys the session object, if connection pool is used it returns the object to connection pool.

Note: the connection would not be returned to the pool until all statement and result objects created using this session are not destroyed.

Create a session using a parsed connection string ci

The connection string format is following:

driver:[key=value;]*  

Where value can be either a sequence of characters (white space is trimmed) or it may be a general sequence encloded in a single quitation marks were double quote is used for insering a single quote value.

Key values starting with @ are reserved to be used as special cppdb keys For example:

mysql:username= root;password = 'asdf''5764dg';database=test;@use_prepared=off' 

Where driver is "mysql", username is "root", password is "asdf'5764dg", database is "test" and special value "@use_prepared" is off - internal cppdb option.

;

cppdb::session::session ( std::string const &  cs)

Create a session using a connection string cs.

The connection string format is following:

driver:[key=value;]*  

Where value can be either a sequence of characters (white space is trimmed) or it may be a general sequence encloded in a single quitation marks were double quote is used for insering a single quote value.

Key values starting with @ are reserved to be used as special cppdb keys For example:

mysql:username= root;password = 'asdf''5764dg';database=test;@use_prepared=off' 

Where driver is "mysql", username is "root", password is "asdf'5764dg", database is "test" and special value "@use_prepared" is off - internal cppdb option.

;

cppdb::session::session ( connection_info const &  ci,
once_functor const &  f 
)

Create a session using a parsed connection string ci and call f if a once() was not called yet.

It is useful for setting session specific options for new connection, not reused from the pool one.

Requirements: once_functor is an object that can be created from generic function like object func, such that func(*this) is valid expression

The connection string format is following:

driver:[key=value;]*  

Where value can be either a sequence of characters (white space is trimmed) or it may be a general sequence encloded in a single quitation marks were double quote is used for insering a single quote value.

Key values starting with @ are reserved to be used as special cppdb keys For example:

mysql:username= root;password = 'asdf''5764dg';database=test;@use_prepared=off' 

Where driver is "mysql", username is "root", password is "asdf'5764dg", database is "test" and special value "@use_prepared" is off - internal cppdb option.

;

cppdb::session::session ( std::string const &  cs,
once_functor const &  f 
)

Create a session using a connection string cs and call f if a once() was not called yet.

It is useful for setting session specific options for new connection, not reused from the pool one.

Requirements: once_functor is an object that can be created from generic function like object func, such that func(*this) is valid expression

The connection string format is following:

driver:[key=value;]*  

Where value can be either a sequence of characters (white space is trimmed) or it may be a general sequence encloded in a single quitation marks were double quote is used for insering a single quote value.

Key values starting with @ are reserved to be used as special cppdb keys For example:

mysql:username= root;password = 'asdf''5764dg';database=test;@use_prepared=off' 

Where driver is "mysql", username is "root", password is "asdf'5764dg", database is "test" and special value "@use_prepared" is off - internal cppdb option.

;

Create a session using a pointer to backend::connection and call f if a once() was not called yet.

It is useful for setting session specific options for new connection, not reused from the pool one.

Requirements: once_functor is an object that can be created from generic function like object func, such that func(*this) is valid expression

Create a session using a pointer to backend::connection.


Member Function Documentation

Begin a transaction. Don't use it directly for RAII reasons. Use transaction class instead.

Remove all statements from the cache.

Clear connections pool associated with this session's connection.

Automatically calls clear_cache();

Close current connection, note, if connection pooling is used the connection is not actually become closed but rather recycled for future use.

Commit a transaction. Don't use it directly for RAII reasons. Use transaction class instead.

Create prepared statement that will be cached for next calls.

Create prepared statement however don't use statements cache and for it. Useful for creation of custom or rarely executed statements that should be executed several times at this point in program.

statement cppdb::session::create_statement ( std::string const &  q)

Create ordinary statement it generally unprepared statement and it is never cached. It should be used when such statement is executed rarely or very customized.

std::string cppdb::session::driver ( )

Get the driver name, as mysql, postgresql, odbc, sqlite3.

std::string cppdb::session::engine ( )

Get an SQL engine name, it may be not the same as driver name for multiple engine drivers like odbc.

std::string cppdb::session::escape ( char const *  b,
char const *  e 
)

Escape a string in range [b,e) for inclusion in SQL statement. It does not add quotation marks at beginning and end. It is designed to be used with text, don't use it with generic binary data.

Some backends (odbc) may not support this.

std::string cppdb::session::escape ( char const *  s)

Escape a NULL terminated string s for inclusion in SQL statement. It does not add quotation marks at beginning and end. It is designed to be used with text, don't use it with generic binary data.

Some backends (odbc) may not support this.

std::string cppdb::session::escape ( std::string const &  s)

Escape a string s for inclusion in SQL statement. It does not add quotation marks at beginning and end. It is designed to be used with text, don't use it with generic binary data.

Some backends (odbc) may not support this.

Get connection specific object by its type t, returns 0 if not installed yet

template<typename T >
T* cppdb::session::get_specific ( ) [inline]

Get connection specific object by its type T, returns 0 if not installed yet

Check if the session was opened.

void cppdb::session::once ( once_functor const &  f)

Call the functional f on the connection only once. If the connection created first time then f would be called. If the connection is created from connection pool and thus setup functor was called, f would not be called.

Requirements: once_functor is an object that can be created from generic function like object func, such that func(*this) is valid expression

Returns true of session specific initialization is done, otherwise returns false

void cppdb::session::once_called ( bool  state)

Set flag to true if session specific initialization is done, otherwise set it to false

void cppdb::session::open ( connection_info const &  ci)

Open a session using a connection_info object - parsed connection string ci.

void cppdb::session::open ( std::string const &  cs)

Open a session using a connection string cs.

The connection string format is following:

driver:[key=value;]*  

Where value can be either a sequence of characters (white space is trimmed) or it may be a general sequence encloded in a single quitation marks were double quote is used for insering a single quote value.

Key values starting with @ are reserved to be used as special cppdb keys For example:

mysql:username= root;password = 'asdf''5764dg';database=test;@use_prepared=off' 

Where driver is "mysql", username is "root", password is "asdf'5764dg", database is "test" and special value "@use_prepared" is off - internal cppdb option.

;

statement cppdb::session::operator<< ( std::string const &  q)

Syntactic sugar, same as prepare(q)

statement cppdb::session::operator<< ( char const *  s)

Syntactic sugar, same as prepare(s)

session const& cppdb::session::operator= ( session const &  )

Assign a session object, note - it copies only the reference to the underlying connection, so you should be very careful when you do it.

statement cppdb::session::prepare ( std::string const &  query)

Create a new statement, by default is creates prepared statement - create_prepared_statement() unless @use_prepared connection string property is set to off, then it uses normal statements by calling create_statement()

This is the most convenient function to create statements with.

Check if this session's connection can be recycled for reuse in a pool.

If an exception is thrown during operation on DB this flag is reset to false by the front-end classes result, statement, session.

Default is true

void cppdb::session::recyclable ( bool  value)

Set recyclable state of the session. If some problem occurs on connection that prevents its reuse it should be called with false parameter.

Transfers ownership on the connection specific object of type t, returns 0 if not installed yet

template<typename T >
T* cppdb::session::release_specific ( ) [inline]

Transfers ownership on the connection specific object of type T, returns 0 if not installed yet

void cppdb::session::reset_specific ( std::type_info const &  t,
connection_specific_data p = 0 
)

Deletes connection specific object of type t, and sets a new one p (if not NULL)

template<typename T >
void cppdb::session::reset_specific ( T *  p = 0) [inline]

Deletes connection specific object of type T, and sets a new one p (if not NULL)

Rollback a transaction. Don't use it directly for RAII reasons. Use transaction class instead.


The documentation for this class was generated from the following file:
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator