- NAME
- SYNOPSIS
- DESCRIPTION

- cols
- pk
- ai
- index
- unique
- fk
- search_driver
- create

- COPYRIGHT
- VERSION

# NAME

GT::SQL::Creator - an object to create SQL tables.

# SYNOPSIS

        my $creator = $DB->creator('Newtable');
        $creator->cols(
            col1 => {
                pos => 1
                type => 'CHAR',
                size => 50
            },
            col2 => {
                pos => 2,
                type => 'INT',
                not_null => 1
            }
        );
        $creator->pk('col2');
        $creator->ai('col2');
        $creator->create or die "Unable to create: $GT::SQL::error";

# DESCRIPTION

A creator object is used to build new SQL tables.

To get a new creator object, you need to call `creator()` from an existing GT::SQL object.

The object that is returned has methods to set up your table. You will need to call this method for each table you want to create.

        $creator = $obj->creator($table);

You must pass in the name of the table you want to create. This means if you have a table named `MyTable` you must call `->creator` with `'MyTable'` as the argument.

        $creator = $obj->creator('MyTable');

From this point you can call create methods on your creator object to define and create your table.

## cols

cols is used to define the columns that will be in the new table by setting properties such as the type, whether it allows null values, unsigned etc.

For detailed information on the types and options accepted, please see the GT::SQL::Types manpage. The following describes the options accepted that do not directly affect the underlying database:

values

  This specifies the values for the ENUM column type. If you are using an ENUM this must be set. The value for this should be an array reference of the possible values for the ENUM column. The values in the array that is passed in will be quoted by DBI's quote method.

regex

  This is a regex that the value must pass before being inserted into the database.

form_display

  This is a ``pretty name'' that will be used by the HTML module for creating attractive forms automatically.

form_size

  This is the form field length to be used by the HTML module.

form_type

  This is the type of form to use by the HTML module: select, checkbox radio, text, textarea or hidden.

form_names

  This is for multi select or checkboxes and is an array ref of names that get displayed.

form_values

  This is for multi select or checkboxes and is an array ref of the actual values that will be stored in the database.

time_check

  This is only useful for TIMESTAMP fields. If set to 1, the module will not allow you to update a record which has an older timestamp then what is in the database. This is very helpful for protecting against multiple updates.

weight

  By giving an item a weight, GT::SQL will maintain a search index table, and use that search index table when called using query. This is only useful for indexing large text fields and should not be used normally. The higher the weight, the more influence that column will have on the result. So if a Title was set to weight 3 and a Description to weight 1, then when doing a search, a match in the title would make the result appear before a match in the description.

So an example would look like:

        $creator->cols(
            $col1 => {
                type     => 'ENUM',
                values   => ['val1', 'val2' ... ],
                not_null => 1
            },
            $col2 => {
                ...
            }
        );

Sets the relations columns as specified via method parameters. The only required key for the has is type. However some column types require other values be set such as ENUM requires you specify the values.

## pk

`pk` lets you specify the primary keys for the current table. This method can be called with an array of primary key columns in which case all the specified column names in the array will make up the primary keys. If you call it with a single scalar value this is assumed to be the primary key for the table.

        $creator->pk($field1, $field2, ...);

## ai

This specifies the auto increment column for the current table. There can be only one auto increment column per table, it must be a numeric type, it must be not null and it must be the primary key. This limitation is checked when you call create. If it is not a numeric column type you will get a fatal error when you call create. If any of the other limitations fail the creator class will correct.

## index

`index` allows you to specify the name and the columns for you table indexes.

There are two ways to call this method.

You can set up all your indexes at once by calling it with hash reference like this:

        $creator->index({
            $index1 => [field1, field2],
            $index2 => [field3, field4]
        });

The keys to this hash reference are the index names and the values are an array reference containing the columns that are part of the named index. The order for these columns are maintained during the create.

You can also pass in one index at a time like this;

        $creator->index($index_name, $col1, ..., $coln);

The first argument is the name of the index and all the rest are treated as columns that are part of this index. Again the order of the columns are maintained.

## unique

The `unique` method allows you to specify the unique indexes for the current table. This method takes the same arguments as the `index` method.

## fk

`fk` allows you to specify foreign key relations for your tables. You CAN NOT specify foreign keys for tables that have not been created yet. There are two ways to pass in arguments to `fk`. The first way is passing in a hash reference.

        $creator->fk({
            $FOREIGN_TABLE_NAME =>
            {
                $LOCAL_TABLE_COL_1 => $FOREIGN_TABLE_COL_1,
                ...
                $LOCAL_TABLE_COL_n => $FOREIGN_TABLE_COL_n
            }
        });

The keys to the hash are the names of the tables you are relating to. The values are a hash reference that contain the name of the current tables columns as the keys and the name of the foreign tables columns that we are relating to as the values.

You cannot relate fields to your self. You also need to be careful not to create circular references. This is checked when you call this method. If there is a circular reference detected you will receive a fatal error.

Foreign keys currently effect selects only.

## search_driver

This affects how the weighted records are indexed. By default the system will attempt to use best driver for the DBMS. However, if you'd like to force the indexing system to an alternative type, such as for MYSQL you can use this.

* note: though the MYSQL driver is faster, the internal indexing system has better support for phrase searching and keyword searching.

To set the driver, call `search_driver` with the appropriate driver name. The following example will force the system into using the internally implemented indexing scheme.

        $creator->search_driver('INTERNAL');

Currently, the only other valid option is ``MYSQL''.

-note-

The MYSQL driver occasionally behaves oddly with a small number of records. In that case, set the search scheme to ``INTERNAL''.

## create

This is the method you call to create your table after you have specified all your table definitions. Several checks are made when this method is called to ensure the table is created correctly.

One of the things that is done is checking to see that the table you are trying to create does not exist. If the table does exist create will return undefined and set the error in $GT::SQL::error.

You can specify to have `create` drop the table by passing in ``force''.

        $creator->create('force');

-or-

        $creator->create;

`create` returns true on success and undef on failure.

# COPYRIGHT

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

# VERSION

Revision: $Id: Creator.pm,v 1.74 2004/09/22 02:43:29 jagerman Exp $