GT::SQL::Creator - an object to create SQL tables.
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";
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 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:
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.
This is a regex that the value must pass before being inserted into the database.
This is a ``pretty name'' that will be used by the HTML module for creating attractive forms automatically.
This is the form field length to be used by the HTML module.
This is the type of form to use by the HTML module: select, checkbox radio, text, textarea or hidden.
This is for multi select or checkboxes and is an array ref of names that get displayed.
This is for multi select or checkboxes and is an array ref of the actual values that will be stored in the database.
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.
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
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, ...);
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
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.
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
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.
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''.
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 (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/
Revision: $Id: Creator.pm,v 1.74 2004/09/22 02:43:29 jagerman Exp $