NAME
HandySQL - a package that is very handy to be be used for regular MySQL
access.
SYNOPSIS
use HandySQL;
# connection is made on demand to
# database by configuration, specified
# in config file
$descr = &describe_table("tablename");
# now $descr is reference to array, that contains
# names of each column, that is hold inside of the
# table `tablename'
$nm = &get_rows("tablename",
"where clause", "order by",
limit, ofs)
# retrieves an nmtable object, that is got, by using
# of statement SELECT * FROM tablename WHERE where
# clause ORDER BY order by LIMIT ofs,limit
# get_rows can also be called in these ways:
$nm = &get_rows("tablename",
"where clause", "order by", limit);
$nm = &get_rows("tablename",
"where clause", "order by");
$nm = &get_rows("tablename",
"where clause");
$nm = &get_rows("tablename");
# please consider, that doing last query can
# result in enormously big table, and perl
# will drop a core dump.
$rows_updated = &update_rows("tablename",
"where clause",
{ 'field_1' => &str_sqlize('alpha'),
'field_2' => '1'
} );
# this will generate UPDATE statement for supplied
# parameters. if 0 rows are updated '0E0' is returned.
$rows_updated = &insert_rows("tablename",
{ 'field_1' => &str_sqlize('alpha'),
'field_2' => '1'
} );
# this will generate UPDATE statement for supplied
# parameters.
$rows_updated = &delete_rows("tablename",
"where clause");
# this will generate UPDATE statement for supplied
# parameters. all these functions returns number of
# rows affected.
CONFIGURATION
- config.pm
-
We encourage you to store all your project configuration data in config
module inside of hash
%cfg. All configuration for HandyCGI, HandyTemplate,
HandySQL, HandyLog, HandyMail and HandyList modules are stored in this file
by default. However, if you dislike this approach feel free to modify code
a little.
- dbdebug
-
Set it to 1 if you want to log all SQL transactions to regular log file,
that is written by HandyLog module. Otherwise set it to 0 or don't set at
all.
- connection_timeout
-
If module was unable to connect to database, it will retry after sleeping
one second. Specify here amount of seconds that this module will try to
reconnect with MySQL server.
- dbhost
-
Hostname or IP address of MySQL server.
- dbuser
-
Username that is accessing MySQL server.
- dbpass
-
Password that is used in access to MySQL server.
- dbname
-
Name of the database.
- dblog
-
Optional. If not set to undef, then it could contain path to a file, where
all database transactions will be stored. Useful to create backups of
database.
- lock_timeout
-
The time used to time out in
&sql_lock subroutine.
DESCRIPTION
- General behaviour
-
Module on demand connects to DB, using parameters that are specified in
config file, if it fails to connect - it writes logs and bails out. If
local variable
$debug is equal to 1, then all database usage
will be logged into a log files. This module is designed to connect exactly
to ONE database. Why? Just to make programming extremly handy. MOST of
request of web program is done to one database.
- $nm = get_rows($tablename, $where, $orderby, $lim, $ofs)
-
Returns an
$nm table with named columns by using select
statement. $nm has structure: $nm is a reference
to array of rows. $nm->[i] is a reference to a hash, which corresponds
to i-th row. $nm->[i]->{'colname'} is a data in i-th row, in column
named colname.
Statement is composed by this algorythm:
SELECT * FROM $tablename [WHERE $where]
[ORDER BY $orderby]
[LIMIT [$ofs,]$lim]
If $orderby or $where is equal to '' the function
considers as they're absent.
- $fields = get_row($tablename, $where, $orderby, $lim, $ofs)
-
Returns a
$fields reference to a hash by using select
statement. This function returns exactly ONE row.
Statement is composed by this algorythm:
SELECT * FROM $tablename [WHERE $where]
[ORDER BY $orderby]
LIMIT [$ofs,] 1
If $orderby or $where is equal to '' the function
considers as they're absent, so you can specify $ofs without
where and orderby clauses.
- $rows_affected = update_rows($tablename,$where,$fields)
-
Launches UPDATE statement on table
$tablename, by using $where
clause, while setting data to specified by $fields (reference
to a hash). Please, consider, that absent $tablename, $where
and/or $fields are errors. Returns how many rows affected.
'0E0' is returned if zero affected.
- $rows_affected = delete_rows($tablename,$where)
-
Launches DELETE statement on table
$tablename, by using $where
clause. Please, consider, that absent $tablename and/or
$where are errors. Returns how many rows affected.
- $rows_affected = insert_rows($tablename,$fields)
-
Launches INSERT statement on table
$tablename, by inserting a row specified
by $fields (reference to a hash). Please, consider, that
absent $tablename and/or $fields are errors.
Returns how many rows affected.
- $rows_affected = insert_rows_ifne($tablename,$fields)
-
Does the same as
insert_rows, but doesn't print error message into log
file, if inserted item already existed in database.
- $table = do_query($query)
-
Should be used to launch queries. Generally,
$query will
contain SELECT statement. The return value is a reference to array of
references to array of values. Use make_nmtable to make output like in
get_rows. Here is example:
$table = &do_query("SELECT a.column_a,b.column_b
from a,b where a.column_c = b.column_c");
&make_nmtable($table,['column_a','column_b']);
After make_nmtable call the $table will be a reference to
array of references to a hash, where actual values are stored.
- $sqlstr = str_sqlize($str)
-
Converts
$str to into SQL string format. If $str
eq 'Somebody's test', then $sqlstr eq "\'Somebody\'s
test\'".
- $str = str_unsqlize($str)
-
Action is a reversed
str_sqlize.
- $timestamp = sql_date($time)
-
Returns datetime in form YYYYMMDDHHMMSS from
$time seconds.
Current datetime is &sql_date(time). But use of now()
builtin of SQL is encouraged. Consider, that time on hosts which runs
CGI-scripts and MySQL server could be different.
- $time = sql_ts2sec($timestamp)
-
Converts timestamp (YYYYMMDDHHMMSS) to seconds.
&sql_ts2sec(&sql_date($x)) == $x.
- $timestamp = sql_date2ts($date)
-
Converts date from format YYYY-MM-DD to YYYYMMDD000000.
- $date = sql_ts2date($timestamp)
-
Converts timestamp (YYYYMMDDHHMMSS) to date YYYY-MM-DD.
- $time = sql_ts2time($timestamp)
-
Converts timestamp (YYYYMMDDHHMMSS) to time HH:MM:SS
- push_a_nmtable($nmt,$dbt,$value)
-
$nmt,$dbt,$value is references to arrays. This function typically does:
1.
Converts @$value to a hash, which contains elements of
@$dbt as keys and corresponding elements of
@$value as values. Imagine this, as you ``name'' elements of
@$value in correspondance with @$dbt.
2. Pushes resulting
reference to a hash into @$nmt array.
So $nmt is a reference to array of refferences to hashes. I
call them ``named tables''. Typical dereference is:
$nmt->[$i]->{$column_name} Where $i is row number, and
$column_name is the name of database column. Very handy.
- make_nmtable($nmt,$dbt)
-
$nmt is a reference to array of references to array. Typically
retrieved undescriben data from database by &do_query
subroutine. $dbt is a column names (ref to array). It produces
$nmt similar to describen in push_a_nmtable.
|