Generalized handle on an DBI database handle. Used to provide an instance which holds connection information and allows a higher level get_connection/ disconnect logic that persists above the specific DBI connections. Also provides a real object for use with the rest of the toolkit.
MQdb::Database provides the foundation of the MappedQuery system. Databases are primarily specified with a URL format. The URL format includes specification of a driver so this single method can select among the supported DBD drivers. Currently the system supports MYSQL , Oracle, and SQLite. The URL also allows the system to provide the foundation for doing federation of persisted objects. Each DBObject contains a pointer to the Database instance where it is stored. With the database URL and internal database ID , each object is defined in a global space.
Attributes of MQdb::Database
driver : mysql, oracle, sqlite (default mysql)
user : username if the database requires
password : password if the database requires
host : hostname of the database server machine
port : IP port of the database if required
(mysql default is 3306)
dbname : database/schema name on the database server
for sqlite, this is the database file
Example URLS
mysql://<user>:<pass>@<host>:<port>/<database_name>
mysql://<host>:<port>/<database_name>
mysql://<user>@<host>:<port>/<database_name>
mysql://<host>/<database_name>
oracle://<user>:<pass>@/<database_name>
oracle://<user>:<pass>@<host>:<port>/<database_name>
sqlite:///<database_file>
Jessica Severin <jessica DOT severin AT gmail DOT com>
* Software License Agreement (BSD License) * MappedQueryDB [MQdb] toolkit * copyright (c) 2006−2009 Jessica Severin * All rights reserved. * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * Neither the name of Jessica Severin nor the * names of its contributors may be used to endorse or promote products * derived from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS BE LIABLE FOR ANY * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
new
Description: instance creation method Parameter : a hash reference of options same as attribute methods Returntype : instance of this Class (subclass) Exceptions : none
new
Description: instance creation method Returntype : instance of this Class (subclass) Exceptions : none
init
Description: initialization method which subclasses can extend Returntype : $self Exceptions : subclass dependent
new_from_url
Description: primary instance creation method Parameter : a string in URL format Returntype : instance of MQdb::Database Examples : my $db = MQdb::Database−>new_from_url("mysql://<user>:<pass>@<host>:<port>/<database_name>"); e.g. mysql://<host>:<port>/<database_name> e.g. mysql://<user>@<host>:<port>/<database_name> e.g. mysql://<host>/<database_name> e.g. sqlite:///<database_file> my $class = shift; Exceptions : none
copy
Description: makes a copy of the database configuration. New instance will have its own database connection Returntype : instance of MQdb::Database
dbc
Description: connects to database and returns a DBI connection Returntype : DBI database handle Exceptions : none
disconnect
Description: disconnects handle from database, but retains object and all information so that it can be reconnected again at a later time. Returntype : none Exceptions : none
full_url
Description: returns the URL of this database with user and password Returntype : string Exceptions : none
url
Description: returns URL of this database but without user:password used for global referencing and federation systems Returntype : string Exceptions : none
xml
Description: returns XML of this database but without user:password used for global referencing and federation systems Returntype : string Exceptions : none
execute_sql
Description : executes SQL statement with external parameters and placeholders Example : $db−>execute_sql("insert into table1(id, value) values(?,?)", $id, $value); Parameter[1] : sql statement string Parameter[2..] : optional parameters for the SQL statement Returntype : none Exceptions : none
do_sql
Description : executes SQL statement with "do" and no external parameters Example : $db−>do_sql("insert into table1(id, value) values(null,'hello world');"); Parameter : sql statement string with no external parameters Returntype : none Exceptions : none
fetch_col_value
Arg (1) : $sql (string of SQL statement with place holders) Arg (2...) : optional parameters to map to the placehodlers within the SQL Example : $value = $self−>fetch_col_value($db, "select some_column from my_table where id=?", $id); Description: General purpose function to allow fetching of a single column from a single row. Returntype : scalar value Exceptions : none Caller : within subclasses to easy development