- NAME
- SYNOPSIS
- DESCRIPTION

- query, query_sth
- select
- select_options
- count
- hits
- get
- add
- insert
- insert_multiple
- modify
- update
- delete
- delete_all
- Table Properties

- COPYRIGHT
- VERSION

# NAME

GT::SQL::Table - a perl interface to manipulate a single SQL table.

# SYNOPSIS

        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 });

# DESCRIPTION

GT::SQL::Table provides methods to add, modify, delete and search over a single SQL table.

The following methods are provided.

## query, query_sth

`query` 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.

        my $results = $db->query($in);

The return of `query` is an arrayref of arrayrefs. `query_sth` returns an STH that you can fetch rows from.

Typical usage to go through the results is:

        my $results = $db->query({ Title => 'foobar' });
        if ($results) {
            for my $result (@$results) {
                ...
            }
        }

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:

Find all rows with field_name = value:

        field_name    => value

Find all rows with field_name > value:

        field_name    => ">value"

Find all rows with field_name < value:

        field_name    => "<value"

Find all rows with field_name > value:

        field_name-gt => value

Find all rows with field_name < value:

        field_name-lt => value

Find all rows where any field_name = value:

        keyword       => value

Find all rows using indexed search (see weights):

        query         => value

Set to 1, use '=' comparison, 0/unspecified use 'LIKE '%val%' comparision:

        ww            => 1

Search using LIKE for column 'Title' (valid opts are '=', '>', '<' or 'LIKE'):

        Title-opt     => 'LIKE'

Set to 1, OR match results, 0/unspecified AND match results:

        ma            => 1

Return a max of n results, defaults to 25:

        mh            => n

Return page n of results:

        nh            => n

Sort by 'Title' column:

        sb            => 'Title'

Sort in ascending (ASC) or descending (DESC) order:

        so            => 'ASC'

## select

Select provides a way to implement almost any sql SELECT statement.

An executed statement handle is returned that you can call the normal fetchrow, fetchrow_array, fetchrow_hashref, etc on.

        my $sth = $obj->select;

is equivalant to ``SELECT * FROM Table''

        my $sth = $obj->select({ Col => Val });

is equivalant to ``SELECT * FROM Table WHERE Col = 'Val'''.

        my $sth = $obj->select('Col2', 'Col3', { Col => "Val" });

is equivalant to ``SELECT Col2,Col3 FROM Table WHERE Col => 'Val'''.

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.

If you need more complex where clauses, you should use a condition object instead of a hash reference. See the GT::SQL::Condition manpage for more information.

Notes:

quoting in where

  All arguments in the where clause are automatically quoted. If you don't want quotes, you should pass in a scalar reference as in:

          my $sth = $obj->select({ Col => \"NOW()" });

  which turns into ``SELECT * FROM Table WHERE Col = NOW()''.

quoting in select

  Nothing in the select will be quoted, so to use functions, simply pass in what you want:

          my $sth = $obj->select('COUNT(*)');

  which turns into ``SELECT `COUNT(*)` FROM Table''.

To specify LIMIT, or GROUP BY, or ORDER BY or other SELECT clauses that come after the WHERE, you should use select_options below.

## select_options

This method provides a way for you to specify select options such as LIMIT and SORT_BY.

        $obj->select_options(@OPTIONS);

@OPTIONS should be a list of options you want appended to your next select.

For example,

        $obj->select_options('ORDER BY Foo', 'LIMIT 50');
        $obj->select;

would turn into ``SELECT * FROM Table ORDER BY Foo LIMIT 50''. To perform a LIMIT with an OFFSET, you should specify something like:

        $obj->select_options('LIMIT 25 OFFSET 75');

You can alternatively use the equivelant MySQL-specific syntax:

        $obj->select_options('LIMIT 75, 25');

Both will be handled correctly regardless of the database type.

## count

This method will allow you to count records based on a where clause.

        my $count = $obj->count($condition);

`count()` takes either a condition or a hash reference. If no argument is provided, it is equivalant to ``SELECT `COUNT(*)` FROM Table'', or total number of rows.

## hits

This method returns the number of hits from that last select query without the limit clause if there was one.

        $hits = $obj->hits;

For example, to get rows 20-30 of a query result, use:

        $obj->select_options("LIMIT 10 OFFSET 20"); $obj->select({ Column => 'Foo' });

this translates into (in MySQL):

        SELECT * FROM Table WHERE Column = 'Foo' LIMIT 20, 10

To see the total number of results that the query would have retrieved without any limit, you call:

        $hits = $obj->hits;

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:

        SELECT COUNT(*) FROM Table WHERE Column = 'Foo'

NOTE: The `hits()` method _only_ applies to select queries. Most databases do not provide enough information to get counts of rows affected for other types of queries.

## get

This method allows for a simple interface to retrieving records from the table(s).

        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');

The first argument is the primary key value of the record you want to retrieve.

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.

The last argument is a list of column names you want retrieved. `get` defaults to returning the entire record, but if you only need specific columns, you can ask for the ones you want.

For example:

        my $employee = $emp_db->get('Alex');

would return a hash ref of the record whose primary key is equal to 'Alex'.

        my $emp_addr = $emp_db->get('Alex', 'HASH', ['City', 'State', 'ZipCode']);

would return a hash ref of only the three fields City, State, ZipCode for the record whose primary key equals Alex.

## add

Method to add an entry into the database. This method can take it's arguments one of three ways.

        $obj->add($CGI_OBJECT);

        -or-

        $obj->add({
            col1 => $val1,
            col2 => $val2,
            ...
        });

        -or-

        $obj->add(
            col1 => $val1,
            col2 => $val2,
            ...
        );

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.

`add` 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.

Passing in GT_SQL_SKIP_CHECK => 1 will have the table module skip any error checking it should perform.

Passing in GT_SQL_SKIP_INDEX => 1 will not index the fields. You can also use the `indexing` method to do this.

## insert

`insert` is a lower level add. The main differences between `add` and `insert` are that add performs a not null check, and add returns the id of the just inserted value.

`insert` 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).

## insert_multiple

`insert_multiple` will try to optimize the insertion of multiple rows with simple values. Under MySQL, this uses MySQL's extended insert syntax:

        INSERT INTO Table (col1, col2, col3)
        VALUES ('val1', 'val2', 'val3'), ('val4', 'val5', 'val6'), ...

On other databases, it attempts to perform all insertions in a single transaction, which will also usually yield performance benefits. Note, however, that `insert_multiple` 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.

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:

        $table->insert_multiple(
            ['col1', 'col2', 'col3'],
            ['val1', 'val2', 'val3'],
            ['val4', 'val5', 'val6'],
            ...
        );

## modify

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.

`modify` will then look for the primary key in the input and set all fields for that row equal to what was passed in.

You need to pass in a complete record! If you just want to update one column, you probably want to use `update` instead, as doing:

        my $result = $obj->modify(column1 => 'Foo');

will blank out all the other fields and set just column1 to Foo.

`modify` returns undef on failure, 1 on success. The error message will be available in $GT::SQL::error.

## update

This method provides a more robust way to update multiple entries in the table.

        my $result = $obj->update(
            {
                col1 => $val1,
                col2 => $val2,
                ...
            },
            $condition
        );

        -or-

        my $result = $obj->update(
            {
                col1 => $val1,
                col2 => $val2,
                ...
            },
            {
                col1 => $val1,
                col2 => $val2,
                ...
            }
        );

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.

        $obj->update({ Setme => 'NewValue'}, { WhereCol => 5 });

would set the column 'Setme' to 'NewValue' where the column 'WhereCol' is 5. This translates to:

        UPDATE Table SET SetMe='NewValue' WHERE WhereCol = 5

If the second argument is a GT::SQL::Condition object the condition object will be used to build the where clause with. Please see the GT::SQL::Condition manpage for a description of what you can do with a where clause.

        my $condition = GT::SQL::Condition->new('WhereCol', 'LIKE', 'Foo%');
        $obj->update({ Setme => 'Newvalue' }, $condition);

would translate to:

        UPDATE Table SET Setme = 'Newvalue' WHERE WhereCol LIKE 'Foo%'

The condition can now much more complex where clauses though.

`update` returns undef on failure and the a the GT::SQL::Driver manpage statement handle on success. The error message will be available in $GT::SQL::error.

Passing in GT_SQL_SKIP_CHECK => 1 as a third option to `update` will have the table module skip any error checking it should perform.

Passing in GT_SQL_SKIP_INDEX => 1 will not index the fields. You can also use the `indexing` method to do this.

## delete

This method provides a robust interface to delete entries from your `table(s)` using join and or foreign key relations.

        my $result = $obj->delete($condition);

You can pass into `delete` 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.

        my $result = $obj->delete({
            col1 => $val1,
            col2 => $val2,
            ...
        );

        -or-

        $obj->delete($val);

        -or-

        $obj->delete([$val1, $val2]);

`delete` returns undef on failure, 1 on success. The error message will be available in $GT::SQL::error.

## delete_all

This method takes no arguments and will erase all entries from a table.

## Table Properties

Table provides a lot of methods to access information about the table:

name

  Provides the name of the table minus any prefix.

ai

  Returns the name of the auto-increment field if any.

pk

  Returns an `array(ref)` of primary key column names.

fk

  Returns a hash of foreign key values.

fk_tables

  Returns a list of tables with foreign keys pointing to this table.

index

  Returns a hash ref of index name => array ref of column names that index uses.

unique

  Returns a hash ref of unique index names => array ref of column names that unique index uses.

all_indexes

  Returns the joined output of index and unique and primary key.

cols

  Returns a `hash(ref)` of column name => column definition

default

  Returns a `hash(ref)` of column name => default value.

size

  Returns a `hash(ref)` of column name => size of column in SQL.

type

  Returns a `hash(ref)` of column name => type of column in SQL.

form_display

  Returns a `hash(ref)` of column name => name to display on auto generated forms (think pretty name).

form_size

  Returns a `hash(ref)` of column name => size of html form to generate.

form_type

  Returns a `hash(ref)` of column name => type of html form to generate (checkbox, select, text, etc).

form_names

  Returns a `hash(ref)` 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.

form_values

  Returns a `hash(ref)` of column name => array ref of form values. Same as above, but this is the value that actually gets entered.

time_check

  Returns a `hash(ref)` of column name => time check on or off. If set

regex

  Returns a `hash(ref)` of column name => regular expression that all input must pass before being inserted.

pos

  Returns a `hash(ref)` of column name => position in table.

not_null

  Returns a `hash(ref)` of column name => not null (whether the field is allowed to be null or not).

# COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

Revision: $Id: Table.pm,v 1.274 2008/09/17 19:35:24 brewt Exp $