- NAME
- SYNOPSIS
- DESCRIPTION

- add_col
- drop_col
- alter_col
- add_unique
- drop_unique
- add_index
- drop_index
- add_pk
- drop_pk
- add_fk
- drop_fk
- drop_table

- COPYRIGHT
- VERSION

# NAME

GT::SQL::Editor - an interface to modify an SQL table.

# SYNOPSIS

        my $editor = $DB->editor('Table');
        $editor->add_col(Foo => { size => 20, type => 'int' });
        $editor->export_data('/tmp/foo.txt');

# DESCRIPTION

GT::SQL::Editor is an easy way to do a lot of table maintenance functions like:

* Adding columns * Dropping columns * Changing columns * Altering keys * Importing data * Dropping data

To get an editor object, you simply call `editor` from a GT::SQL object, and specify the tablename you want to edit:

        $editor = $db->editor('TableName');

Note: You can not use Editor with relations, only tables.

## add_col

This method allows you to add a column to the current table. All attributes for the column are passed in a single hash.

        $editor->add_col($col_name,
                            {
                                size => 20,
                                type => 'int',
                                view_size => 20,
                                nice_name => "my col",
                                regex => 'myregex'
                            }
                        );

The same rules apply to this method that apply when you define a column for creating a table. You must specify the type.

## drop_col

This method drops a column from the current table. Checks are made to ensure the column is not linked to by a foreign key relation.

        $editor->drop_col($col_name);

-or-

        $editor->drop_col($col_name, "remove");

If you just specify the column name `drop_col` will check if the column is referenced in a foreign key relation. If it is `drop_col` will return undef and set the error message in $GT::SQL::error. If it is not the column will be dropped.

If you specify ``remove'' `drop_col` will remove all foreign key relations that point to the specified column.

If the specified column is itself a foreign key relation, the relation will be dropped.

## alter_col

This allows you to make changes to a columns type, null status, etc..

        $editor->alter_col($column_name,
                                    {
                                        size => 20,
                                        type => 'int'
                                    });

The first argument is the column name the second is the definitions. The column definitions are exactly the same as the column definitions from the create. The type must be specified.

You can not add attributes to the column in this way. You must specify the original definitions along with the changes you need to make.

## add_unique

This allows you to add a unique index to the current table. If the name of the unique index is the same as another index you `add_unique` will return undef and set the error in $GT::SQL::error.

        $editor->add_unique($index_name => [ $field1, $field2 .. ]);

The name of the new index is the first argument. The second argument is an array reference containing the columns that will be indexed. The order of the columns are maintained for the unique index. If you specify an index that has data in it that is not unique (yes we do a select on the database) `add_unique` will return an error and set the error in $GT::SQL::error.

## drop_unique

This method allows you to drop a unique index for the current table. If the unique index does not exist `drop_unique` will return undef and set the error in $GT::SQL::error. `drop_unique` will also check to make sure dropping the unique index will not cause problems for the database structure. If dropping the unique index will cause a problem `drop_unique` will return undef and set the error in $GT::SQL::error.

        $editor->drop_unique($index_name);

$index_name should be the name of the unique index to drop.

## add_index

This takes the same arguments as `add_unique` and return the same thing. The only difference is `add_index` has no reason to check the content of the current table because indexes are not unique. unique indexes are :)

        $editor->add_index($index_name => [ $field1, $field2 .. ]);

## drop_index

This method drops the specified index from the current table. `drop_index` will check to make sure no problems are caused from dropping the index. If there are `drop_index` will return undef and set the error in $GT::SQL::error.

        $editor->drop_index($index_name);

$index_name should be the name of the index to drop.

## add_pk

This method allows you to add a primary key to the current database.

        $editor->add_pk($field1, $field2, ...);

If there is already a primary key in the database `add_pk` will drop the key and add the this new one. The table will be check to make sure this change does not create problems for the table. I problem is auto increment not being the primary key anymore. If there is a problem this function returns undef and stores the error in $GT::SQL::error.

## drop_pk

This method drops the current primary key. If there is no primary key to drop it returns undef and sets the error in $GT::SQL::error.

        $editor->drop_pk;

If dropping the primary key will cause problems for the database this method will return undef and set the error in $GT::SQL::error.

## add_fk

This method allows you to add foreign key relations to the current table.

        $editor->add_fk($RELATION_NAME, { $SOURCE_FIELD_1 => $TARGET_FIELD });

You can not link your foreign key to tables that do not exist. Also the columns types and lengths for the two columns must be the same. Circularity is not allowed either. That is a set of foreign keys can not end up pointing back at the same table they started at. All of these things are checked when this is added. If anything does not match this method returns undef and sets the error in $GT::SQL::error.

## drop_fk

This method drops the specified foreign key relation.

        $editor->drop_fk($table);

$table should be the name of the foreign table the foreign key points to.

## drop_table

This method drops the current table. If there are any foreign keys pointing to this table this method will fail and return undef. The error will be set in $GT::SQL::error.

        $editor->drop_table;

-or-

        $editor->drop_table("remove");

If the first argument to this method is remove it will remove all the foreign key relations that point to this table.

# COPYRIGHT

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

# VERSION

Revision: $Id: Editor.pm,v 1.76 2005/04/27 22:53:24 brewt Exp $