NAME

GT::SQL - A database independent perl interface

SYNOPSIS

    use GT::SQL;

    my $db      = new GT::SQL '/path/to/def';
    my $table   = $db->table ('Links');
    my $editor  = $db->editor ('Links');
    my $creator = $db->creator ('NewTable');
    my $html    = $db->html ('Links', new CGI);

DESCRIPTION

GT::SQL is a database independent perl interface to relational databases. It has been developed around Mysql, but has drivers that will port any mysql specific queries into the native format.

The GT::SQL object provides the interface to the entire database. It's only use is to provide you with objects that do the bulk of the work. See the appropriate docs for information on how to use each created object.

Creating a new GT::SQL object

There are two ways to get a GT::SQL object. First, you can simply provide the path to the def file directory where GT::SQL stores all it's information:

    $db = new GT::SQL '/path/to/def';

or you can pass in a hash or hash ref and specify options:

    $db = new GT::SQL {
                        def_path => '/path/to/def',
                        cache    => 1,
                        debug    => 1,
                        subclass => 1
                    );

You must specify def_path. Setting cache => 1, will result in all table or relation objects to be cached which can improve performance.

Setting subclass => 0 or subclass => 1 will enable or disable the ability to subclass any of the objects GT::SQL creates. The default behaviour is 1.

GT::SQL has advanced debugging, and setting it to 1 should be adequate for most operations.

Level 0: This is the default, no debugging information is printed to stderr. All errors can be obtained in $GT::SQL::error.
Level 1: All queries that get sent will be displayed to stderr.
Level 2: Same as level 1, but more detailed information. Also, when calling query_stack you get a stack trace on what generated each query.
Level 3: Very detailed debug logs including creation and destruction of objects. query_stack generates a javascript page with query, stack trace plus data dump of arguments, can be very, very large (but very cool).

Pass in a def

    $obj = GT::SQL->new ('/path/to/def/directory');

This method of calling new is also supported however you cannot pass in the debug level doing it this way.

Getting Connected

GT::SQL loads the database connection info from database.def which is located in the defs directory.

To create this file, you call set_connect() as follows:

    $obj->set_connect ({
                        driver     => "mysql",
                        host       => "localhost",
                        port       => 3243,
                        database   => "mydatabase",
                        login      => 'user',
                        password   => 'password'
                    });

This will test the database information, and save it to the def file. All future connections will automatically use this connection information.

Not all of the arguments in this hash are necessary. Some of them have reasonable defaults for the connection.

driver: This needs to be the driver that is being used for the connection. The default for this is mysql. The driver that you specify will need to be installed in the proper directory for this to work.
host: This will specify the host we are connecting to. The default for this is localhost which should be fine for most cases.
port: This is the port to connect to the SQL server on. The default for this is not to specify a port which is to let DBI specify the port to connect on.
database: This is the database to use once the connection is established. This must be specified to do any sort of queried on the database. Some databases (such as MySQL) allow you to use a database after the connection is established. In this case you would need to specify the use by doing the query with the do method.

Supported Objects

GT::SQL will create the following objects:

Table/Relation

To get a table or relation object for working with SQL tables, you should call:

    my $table = $db->table ('TableName');

or for a joined table:

    my $relation = $db->table ('Table1', 'Table2');

See the GT::SQL::Table manpage for more information on how to use a table object.

Creator

To create new tables, you need to use a creator. You can get one by calling:

    my $creator = $db->creator('Newtablename');

where Newtablename is the name of the table you want to create. See the GT::SQL::Creator manpage for more information on how to use a creator object.

Editor

To edit existing tables, add columns, import, export, etc., you need an editor object.

    my $editor = $db->editor('Tablename');

Note: you cannot use an editor on joins, one table at a time. See the GT::SQL::Editor manpage for more information on how to use an editor object.

HTML

To get an html object for generating forms and html output, you need to pass in the table/relation object you want to work with, and a cgi object:

    my $html = $db->html ($table, $cgi);

The html object uses information found in CGI to set values, etc. See the GT::SQL::Display::HTML manpage for more information on how to use a html object.

Table Prefixes

GT::SQL supports the concepts of table prefixes. If you specify a prefix using the accessor, it is saved in the database.def file and will be used in all future calls to table(), editor() and creator().

To set a prefix:

    $db->prefix("foo");

to get the current prefix:

    my $prefix = $db->prefix;

What this will do is prepend 'foo' to the beginning of every table name.

Query Stack

To display a list of all raw SQL queries sent to the database you can use:

    my @queries = $db->query_stack;

or to have them formatted try

    print $db->query_stack_disp;

which will join them up, displayed nicely. This is also available as a class method:

    print GT::SQL->query_stack_disp;

Persistent Enviroments

GT::SQL has been designed to work under persistent environments as well as regular environments. A number of optimizations have been made to achieve this.

If you are using mod_perl, no changes to the code are required. You simply load the modules in your startup file as:

    use GT::SQL;
    use GT::SQL::Admin;
    use GT::SQL::Table;
    use GT::SQL::Relation;
    use GT::SQL::Driver;
    use GT::SQL::Display::HTML;
    use GT::SQL::Display::HTML::Table;
    use GT::SQL::Display::HTML::Relation;

You can omit the Admin, Relation and HTML::Relation if you are not using them.

If you are under a persistent environment that is not mod_perl (i.e. SpeedyCGI or FastCGI), you must call GT::SQL->reset_env() at the beginning of your script. Also, under those environments you can not cache your table objects, you must set cache to 0.

COPYRIGHT

VERSION

Revision: $Id: SQL.pm,v 1.103 2004/02/28 02:31:46 jagerman Exp $