831 lines
24 KiB
HTML
831 lines
24 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>GT::SQL::Table - a perl interface to manipulate a single SQL table.</title>
|
|
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
|
|
|
|
<style type="text/css">
|
|
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
|
|
/* $MVD$:fontset("Arial","Arial") */
|
|
/* $MVD$:fontset("Arial Black","Arial Black") */
|
|
/* $MVD$:fontset("Algerian","Algerian") */
|
|
|
|
|
|
body {
|
|
background-color: white;
|
|
font-family: Verdana, Arial, sans-serif;
|
|
font-size: small;
|
|
color: black;
|
|
}
|
|
|
|
|
|
p {
|
|
background-color : white;
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
h1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
background-color : white;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
h2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : medium;
|
|
font-weight : bold;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h3 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : maroon;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h5 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h6 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
ul {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
ol {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
li {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
th {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
td {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dd {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dt {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
code {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
pre {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-H1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : 14.0pt;
|
|
background-color : transparent;
|
|
background-image : none;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
.mvd-H2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 12.0pt;
|
|
color : blue;
|
|
}
|
|
|
|
|
|
p.indent {
|
|
font-family : "Verdana, Arial, sans-serif";
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-indent {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
pre.programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE-programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE {
|
|
font-size : 9.0pt;
|
|
}
|
|
|
|
|
|
p.note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-H4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : normal;
|
|
font-size : 9.0pt;
|
|
color : black;
|
|
margin-left : 6.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 10.0pt;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-BODY {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
p.indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
|
|
|
|
.mvd-P-indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
<p><a name="__index__"></a></p>
|
|
<!-- INDEX BEGIN -->
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#query__query_sth">query, query_sth</a></li>
|
|
<li><a href="#select">select</a></li>
|
|
<li><a href="#select_options">select_options</a></li>
|
|
<li><a href="#count">count</a></li>
|
|
<li><a href="#hits">hits</a></li>
|
|
<li><a href="#get">get</a></li>
|
|
<li><a href="#add">add</a></li>
|
|
<li><a href="#insert">insert</a></li>
|
|
<li><a href="#insert_multiple">insert_multiple</a></li>
|
|
<li><a href="#modify">modify</a></li>
|
|
<li><a href="#update">update</a></li>
|
|
<li><a href="#delete">delete</a></li>
|
|
<li><a href="#delete_all">delete_all</a></li>
|
|
<li><a href="#table_properties">Table Properties</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
<li><a href="#version">VERSION</a></li>
|
|
</ul>
|
|
<!-- INDEX END -->
|
|
|
|
<hr />
|
|
<p>
|
|
</p>
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>GT::SQL::Table - a perl interface to manipulate a single SQL table.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
my $sth = $table->select(Column3 => { Column => $value, Column2 => $value2 });
|
|
$table->delete({ Column => $value });
|
|
$table->insert({ Column1 => $val, Column2 => $value2 });
|
|
$table->update({ SetCol => $val }, { WhereCol => $val2 });</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>GT::SQL::Table provides methods to add, modify, delete and search over a single
|
|
SQL table.</p>
|
|
<p>The following methods are provided.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="query__query_sth">query, query_sth</a></h2>
|
|
<p><code>query</code> provides a simple and powerful method to search a table. It takes as
|
|
input either a hash, hash ref or CGI object making it especially useful
|
|
searching from web forms.</p>
|
|
<pre>
|
|
my $results = $db->query($in);</pre>
|
|
<p>The return of <code>query</code> is an arrayref of arrayrefs. <code>query_sth</code> returns an STH
|
|
that you can fetch rows from.</p>
|
|
<p>Typical usage to go through the results is:</p>
|
|
<pre>
|
|
my $results = $db->query({ Title => 'foobar' });
|
|
if ($results) {
|
|
for my $result (@$results) {
|
|
...
|
|
}
|
|
}</pre>
|
|
<p>To specify what to search, you simply pass in column => search value. However,
|
|
you can also pass in a lot of options to enhance your search:</p>
|
|
<p>Find all rows with field_name = value:</p>
|
|
<pre>
|
|
field_name => value</pre>
|
|
<p>Find all rows with field_name > value:</p>
|
|
<pre>
|
|
field_name => ">value"</pre>
|
|
<p>Find all rows with field_name < value:</p>
|
|
<pre>
|
|
field_name => "<value"</pre>
|
|
<p>Find all rows with field_name > value:</p>
|
|
<pre>
|
|
field_name-gt => value</pre>
|
|
<p>Find all rows with field_name < value:</p>
|
|
<pre>
|
|
field_name-lt => value</pre>
|
|
<p>Find all rows where any field_name = value:</p>
|
|
<pre>
|
|
keyword => value</pre>
|
|
<p>Find all rows using indexed search (see weights):</p>
|
|
<pre>
|
|
query => value</pre>
|
|
<p>Set to 1, use '=' comparison, 0/unspecified use 'LIKE '%val%' comparision:</p>
|
|
<pre>
|
|
ww => 1</pre>
|
|
<p>Search using LIKE for column 'Title' (valid opts are '=', '>', '<' or 'LIKE'):</p>
|
|
<pre>
|
|
Title-opt => 'LIKE'</pre>
|
|
<p>Set to 1, OR match results, 0/unspecified AND match results:</p>
|
|
<pre>
|
|
ma => 1</pre>
|
|
<p>Return a max of n results, defaults to 25:</p>
|
|
<pre>
|
|
mh => n</pre>
|
|
<p>Return page n of results:</p>
|
|
<pre>
|
|
nh => n</pre>
|
|
<p>Sort by 'Title' column:</p>
|
|
<pre>
|
|
sb => 'Title'</pre>
|
|
<p>Sort in ascending (ASC) or descending (DESC) order:</p>
|
|
<pre>
|
|
so => 'ASC'</pre>
|
|
<p>
|
|
</p>
|
|
<h2><a name="select">select</a></h2>
|
|
<p>Select provides a way to implement almost any sql SELECT statement.</p>
|
|
<p>An executed statement handle is returned that you can call the normal fetchrow,
|
|
fetchrow_array, fetchrow_hashref, etc on.</p>
|
|
<pre>
|
|
my $sth = $obj->select;</pre>
|
|
<p>is equivalant to ``SELECT * FROM Table''</p>
|
|
<pre>
|
|
my $sth = $obj->select({ Col => Val });</pre>
|
|
<p>is equivalant to ``SELECT * FROM Table WHERE Col = 'Val'''.</p>
|
|
<pre>
|
|
my $sth = $obj->select('Col2', 'Col3', { Col => "Val" });</pre>
|
|
<p>is equivalant to ``SELECT Col2,Col3 FROM Table WHERE Col => 'Val'''.</p>
|
|
<p>So you can pass in a hash reference which represents the where clause, and an
|
|
array reference where represents what you want to select on.</p>
|
|
<p>If you need more complex where clauses, you should use a condition object
|
|
instead of a hash reference. See <a href="glist.cgi?do=admin_gtdoc&topic=/GT/SQL/Condition.html">the GT::SQL::Condition manpage</a> for more information.</p>
|
|
<p>Notes:</p>
|
|
<dl>
|
|
<dt><strong><a name="item_quoting_in_where">quoting in where</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
All arguments in the where clause are automatically quoted. If you don't want
|
|
quotes, you should pass in a scalar reference as in:
|
|
</dd>
|
|
<dd>
|
|
<pre>
|
|
my $sth = $obj->select({ Col => \"NOW()" });</pre>
|
|
</dd>
|
|
<dd>
|
|
<p>which turns into ``SELECT * FROM Table WHERE Col = NOW()''.</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_quoting_in_select">quoting in select</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Nothing in the select will be quoted, so to use functions, simply pass in what
|
|
you want:
|
|
</dd>
|
|
<dd>
|
|
<pre>
|
|
my $sth = $obj->select('COUNT(*)');</pre>
|
|
</dd>
|
|
<dd>
|
|
<p>which turns into ``SELECT <code>COUNT(*)</code> FROM Table''.</p>
|
|
</dd>
|
|
<p></p></dl>
|
|
<p>To specify LIMIT, or GROUP BY, or ORDER BY or other SELECT clauses that come
|
|
after the WHERE, you should use select_options below.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="select_options">select_options</a></h2>
|
|
<p>This method provides a way for you to specify select options such as LIMIT and
|
|
SORT_BY.</p>
|
|
<pre>
|
|
$obj->select_options(@OPTIONS);</pre>
|
|
<p>@OPTIONS should be a list of options you want appended to your next select.</p>
|
|
<p>For example,</p>
|
|
<pre>
|
|
$obj->select_options('ORDER BY Foo', 'LIMIT 50');
|
|
$obj->select;</pre>
|
|
<p>would turn into ``SELECT * FROM Table ORDER BY Foo LIMIT 50''. To perform a
|
|
LIMIT with an OFFSET, you should specify something like:</p>
|
|
<pre>
|
|
$obj->select_options('LIMIT 25 OFFSET 75');</pre>
|
|
<p>You can alternatively use the equivelant MySQL-specific syntax:</p>
|
|
<pre>
|
|
$obj->select_options('LIMIT 75, 25');</pre>
|
|
<p>Both will be handled correctly regardless of the database type.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="count">count</a></h2>
|
|
<p>This method will allow you to count records based on a where clause.</p>
|
|
<pre>
|
|
my $count = $obj->count($condition);</pre>
|
|
<p><code>count()</code> takes either a condition or a hash reference. If no argument is
|
|
provided, it is equivalant to ``SELECT <code>COUNT(*)</code> FROM Table'', or total number of
|
|
rows.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="hits">hits</a></h2>
|
|
<p>This method returns the number of hits from that last select query <strong>without</strong>
|
|
the limit clause if there was one.</p>
|
|
<pre>
|
|
$hits = $obj->hits;</pre>
|
|
<p>For example, to get rows 20-30 of a query result, use:</p>
|
|
<pre>
|
|
$obj->select_options("LIMIT 10 OFFSET 20"); $obj->select({ Column => 'Foo' });</pre>
|
|
<p>this translates into (in MySQL):</p>
|
|
<pre>
|
|
SELECT * FROM Table WHERE Column = 'Foo' LIMIT 20, 10</pre>
|
|
<p>To see the total number of results that the query would have retrieved without
|
|
any limit, you call:</p>
|
|
<pre>
|
|
$hits = $obj->hits;</pre>
|
|
<p>If the number of hits can be calculated, it will be returned to you without any
|
|
additional query. Otherwise, the following query will be performed
|
|
automatically, and the hit count returned to you:</p>
|
|
<pre>
|
|
SELECT COUNT(*) FROM Table WHERE Column = 'Foo'</pre>
|
|
<p><strong>NOTE</strong>: The <code>hits()</code> method _only_ applies to select queries. Most databases do
|
|
not provide enough information to get counts of rows affected for other types
|
|
of queries.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="get">get</a></h2>
|
|
<p>This method allows for a simple interface to retrieving records from the
|
|
table(s).</p>
|
|
<pre>
|
|
my $rec_hash_ref = $obj->get($val);
|
|
my $rec_hash_ref = $obj->get($val, 'HASH', ['col1', 'col2']);
|
|
my $rec_array_ref = $obj->get($val, 'ARRAY');</pre>
|
|
<p>The first argument is the primary key value of the record you want to retrieve.</p>
|
|
<p>The second argument is a format option. It can be either 'ARRAY' or 'HASH' and
|
|
determines whether you are returned a HASH reference or an ARRAY reference. The
|
|
default is 'HASH', and it is optional.</p>
|
|
<p>The last argument is a list of column names you want retrieved. <code>get</code> defaults
|
|
to returning the entire record, but if you only need specific columns, you can
|
|
ask for the ones you want.</p>
|
|
<p>For example:</p>
|
|
<pre>
|
|
my $employee = $emp_db->get('Alex');</pre>
|
|
<p>would return a hash ref of the record whose primary key is equal to 'Alex'.</p>
|
|
<pre>
|
|
my $emp_addr = $emp_db->get('Alex', 'HASH', ['City', 'State', 'ZipCode']);</pre>
|
|
<p>would return a hash ref of only the three fields City, State, ZipCode for the
|
|
record whose primary key equals Alex.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="add">add</a></h2>
|
|
<p>Method to add an entry into the database. This method can take it's arguments
|
|
one of three ways.</p>
|
|
<pre>
|
|
$obj->add($CGI_OBJECT);</pre>
|
|
<pre>
|
|
-or-</pre>
|
|
<pre>
|
|
$obj->add({
|
|
col1 => $val1,
|
|
col2 => $val2,
|
|
...
|
|
});</pre>
|
|
<pre>
|
|
-or-</pre>
|
|
<pre>
|
|
$obj->add(
|
|
col1 => $val1,
|
|
col2 => $val2,
|
|
...
|
|
);</pre>
|
|
<p>This method can take a cgi object, a hash reference or a hash. The keys of the
|
|
hash should be the names of the column and the values should be the values to
|
|
insert into the fields. The CGI Object is not different. If the table has an
|
|
auto_increment field, the value of the last inserted record will be returned.</p>
|
|
<p><code>add</code> returns undef on failure. If successful, and the table has an
|
|
auto-increment field, the auto increment value is returned. If there is no
|
|
auto increment value, then 1 is returned. Any errors will be in
|
|
$GT::SQL::error.</p>
|
|
<p>Passing in GT_SQL_SKIP_CHECK => 1 will have the table module skip any error
|
|
checking it should perform.</p>
|
|
<p>Passing in GT_SQL_SKIP_INDEX => 1 will not index the fields. You can also use
|
|
the <code>indexing</code> method to do this.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="insert">insert</a></h2>
|
|
<p><code>insert</code> is a lower level add. The main differences between <code>add</code> and
|
|
<code>insert</code> are that add performs a not null check, and add returns the id of the
|
|
just inserted value.</p>
|
|
<p><code>insert</code> does not perform a not null check. Also, insert returns the statement
|
|
handle used to do the insert (so you can call $sth->insert_id to get the auto
|
|
increment).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="insert_multiple">insert_multiple</a></h2>
|
|
<p><code>insert_multiple</code> will try to optimize the insertion of multiple rows with
|
|
simple values. Under MySQL, this uses MySQL's extended insert syntax:</p>
|
|
<pre>
|
|
INSERT INTO Table (col1, col2, col3)
|
|
VALUES ('val1', 'val2', 'val3'), ('val4', 'val5', 'val6'), ...</pre>
|
|
<p>On other databases, it attempts to perform all insertions in a single
|
|
transaction, which will also usually yield performance benefits. Note,
|
|
however, that <code>insert_multiple</code> should not be used for anything more complex
|
|
than basic column values - for example, inserting NULL to set the current date,
|
|
or using raw SQL by passing scalar references for values.</p>
|
|
<p>It takes at least two arguments - the first argument is an array ref of column
|
|
names, and the rest are array references of values. For example, to produce
|
|
the above example SQL code, you would call:</p>
|
|
<pre>
|
|
$table->insert_multiple(
|
|
['col1', 'col2', 'col3'],
|
|
['val1', 'val2', 'val3'],
|
|
['val4', 'val5', 'val6'],
|
|
...
|
|
);</pre>
|
|
<p>
|
|
</p>
|
|
<h2><a name="modify">modify</a></h2>
|
|
<p>This method is designed for modifying a single entry in the table. It takes as
|
|
input a hash, hash ref or CGI object, which is assumed to represent a single
|
|
row with all fields intact.</p>
|
|
<p><code>modify</code> will then look for the primary key in the input and set all fields
|
|
for that row equal to what was passed in.</p>
|
|
<p>You need to pass in a complete record! If you just want to update one column,
|
|
you probably want to use <code>update</code> instead, as doing:</p>
|
|
<pre>
|
|
my $result = $obj->modify(column1 => 'Foo');</pre>
|
|
<p>will blank out all the other fields and set just column1 to Foo.</p>
|
|
<p><code>modify</code> returns undef on failure, 1 on success. The error message will be
|
|
available in $GT::SQL::error.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="update">update</a></h2>
|
|
<p>This method provides a more robust way to update multiple entries in the table.</p>
|
|
<pre>
|
|
my $result = $obj->update(
|
|
{
|
|
col1 => $val1,
|
|
col2 => $val2,
|
|
...
|
|
},
|
|
$condition
|
|
);</pre>
|
|
<pre>
|
|
-or-</pre>
|
|
<pre>
|
|
my $result = $obj->update(
|
|
{
|
|
col1 => $val1,
|
|
col2 => $val2,
|
|
...
|
|
},
|
|
{
|
|
col1 => $val1,
|
|
col2 => $val2,
|
|
...
|
|
}
|
|
);</pre>
|
|
<p>In both these cases the first argument is a hash reference with the column
|
|
names as the keys and the new values you want the columns to hold as the
|
|
values. The second argument can either be a condition object or a hash
|
|
reference. If it is a hash reference the keys will be used as the column names
|
|
and the values will be taken as the current column values for the where clause
|
|
to update the table.</p>
|
|
<pre>
|
|
$obj->update({ Setme => 'NewValue'}, { WhereCol => 5 });</pre>
|
|
<p>would set the column 'Setme' to 'NewValue' where the column 'WhereCol' is 5.
|
|
This translates to:</p>
|
|
<pre>
|
|
UPDATE Table SET SetMe='NewValue' WHERE WhereCol = 5</pre>
|
|
<p>If the second argument is a GT::SQL::Condition object the condition object will
|
|
be used to build the where clause with. Please see <a href="glist.cgi?do=admin_gtdoc&topic=/GT/SQL/Condition.html">the GT::SQL::Condition manpage</a> for a
|
|
description of what you can do with a where clause.</p>
|
|
<pre>
|
|
my $condition = GT::SQL::Condition->new('WhereCol', 'LIKE', 'Foo%');
|
|
$obj->update({ Setme => 'Newvalue' }, $condition);</pre>
|
|
<p>would translate to:</p>
|
|
<pre>
|
|
UPDATE Table SET Setme = 'Newvalue' WHERE WhereCol LIKE 'Foo%'</pre>
|
|
<p>The condition can now much more complex where clauses though.</p>
|
|
<p><code>update</code> returns undef on failure and the a <a href="glist.cgi?do=admin_gtdoc&topic=/GT/SQL/Driver.html">the GT::SQL::Driver manpage</a> statement
|
|
handle on success. The error message will be available in $GT::SQL::error.</p>
|
|
<p>Passing in GT_SQL_SKIP_CHECK => 1 as a third option to <code>update</code> will have the
|
|
table module skip any error checking it should perform.</p>
|
|
<p>Passing in GT_SQL_SKIP_INDEX => 1 will not index the fields. You can also use
|
|
the <code>indexing</code> method to do this.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="delete">delete</a></h2>
|
|
<p>This method provides a robust interface to delete entries from your <code>table(s)</code>
|
|
using join and or foreign key relations.</p>
|
|
<pre>
|
|
my $result = $obj->delete($condition);</pre>
|
|
<p>You can pass into <code>delete</code> either a condition object to delete multiple
|
|
entries, or a scalar value to delete the row whose primary key equals the
|
|
value. If you have a multiple primary key, then you can pass in an array ref to
|
|
delete that row.</p>
|
|
<pre>
|
|
my $result = $obj->delete({
|
|
col1 => $val1,
|
|
col2 => $val2,
|
|
...
|
|
);</pre>
|
|
<pre>
|
|
-or-</pre>
|
|
<pre>
|
|
$obj->delete($val);</pre>
|
|
<pre>
|
|
-or-</pre>
|
|
<pre>
|
|
$obj->delete([$val1, $val2]);</pre>
|
|
<p><code>delete</code> returns undef on failure, 1 on success. The error message will be
|
|
available in $GT::SQL::error.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="delete_all">delete_all</a></h2>
|
|
<p>This method takes no arguments and will erase all entries from a table.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="table_properties">Table Properties</a></h2>
|
|
<p>Table provides a lot of methods to access information about the table:</p>
|
|
<dl>
|
|
<dt><strong><a name="item_name">name</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Provides the name of the table minus any prefix.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_ai">ai</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns the name of the auto-increment field if any.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_pk">pk</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns an <code>array(ref)</code> of primary key column names.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_fk">fk</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a hash of foreign key values.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_fk_tables">fk_tables</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a list of tables with foreign keys pointing to this table.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_index">index</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a hash ref of index name => array ref of column names that index uses.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_unique">unique</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a hash ref of unique index names => array ref of column names that
|
|
unique index uses.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_all_indexes"><strong>all_indexes</strong></a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns the joined output of index and unique and primary key.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_cols">cols</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a <code>hash(ref)</code> of column name => column definition
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_default">default</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a <code>hash(ref)</code> of column name => default value.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_size">size</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a <code>hash(ref)</code> of column name => size of column in SQL.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_type">type</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a <code>hash(ref)</code> of column name => type of column in SQL.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_form_display">form_display</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a <code>hash(ref)</code> of column name => name to display on auto generated forms
|
|
(think pretty name).
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_form_size">form_size</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a <code>hash(ref)</code> of column name => size of html form to generate.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_form_type">form_type</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a <code>hash(ref)</code> of column name => type of html form to generate (checkbox,
|
|
select, text, etc).
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_form_names">form_names</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a <code>hash(ref)</code> of column name => array ref of form names. This is used for
|
|
multi option form elements like checkboxes and multi selects. The name is what
|
|
is displayed to the user and not entered in the database.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_form_values">form_values</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a <code>hash(ref)</code> of column name => array ref of form values. Same as above,
|
|
but this is the value that actually gets entered.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_time_check">time_check</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a <code>hash(ref)</code> of column name => time check on or off. If set
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_regex">regex</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a <code>hash(ref)</code> of column name => regular expression that all input must
|
|
pass before being inserted.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_pos">pos</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a <code>hash(ref)</code> of column name => position in table.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_not_null">not_null</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns a <code>hash(ref)</code> of column name => not null (whether the field is allowed to
|
|
be null or not).
|
|
</dd>
|
|
<p></p></dl>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved.
|
|
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="version">VERSION</a></h1>
|
|
<p>Revision: $Id: Table.pm,v 1.251 2005/02/28 20:37:41 jagerman Exp $</p>
|
|
|
|
</body>
|
|
|
|
</html>
|