Provided by: libdbix-dbschema-perl_0.45-1_all bug

NAME

       DBIx::DBSchema::Table - Table objects

SYNOPSIS

         use DBIx::DBSchema::Table;

         #new style (preferred), pass a hashref of parameters
         $table = new DBIx::DBSchema::Table (
           {
             name         => "table_name",
             primary_key  => "primary_key",
             columns      => \@dbix_dbschema_column_objects,
             #deprecated# unique      => $dbix_dbschema_colgroup_unique_object,
             #deprecated# 'index'     => $dbix_dbschema_colgroup_index_object,
             indices      => \@dbix_dbschema_index_objects,
             foreign_keys => \@dbix_dbschema_foreign_key_objects,
           }
         );

         #old style (VERY deprecated)
         $table = new DBIx::DBSchema::Table (
           "table_name",
           "primary_key",
           $dbix_dbschema_colgroup_unique_object,
           $dbix_dbschema_colgroup_index_object,
           @dbix_dbschema_column_objects,
         );

         $table->addcolumn ( $dbix_dbschema_column_object );

         $table_name = $table->name;
         $table->name("table_name");

         $primary_key = $table->primary_key;
         $table->primary_key("primary_key");

         #deprecated# $dbix_dbschema_colgroup_unique_object = $table->unique;
         #deprecated# $table->unique( $dbix_dbschema__colgroup_unique_object );

         #deprecated# $dbix_dbschema_colgroup_index_object = $table->index;
         #deprecated# $table->index( $dbix_dbschema_colgroup_index_object );

         %indices = $table->indices;
         $dbix_dbschema_index_object = $indices{'index_name'};
         @all_index_names = keys %indices;
         @all_dbix_dbschema_index_objects = values %indices;

         @column_names = $table->columns;

         $dbix_dbschema_column_object = $table->column("column");

         #preferred
         @sql_statements = $table->sql_create_table( $dbh );
         @sql_statements = $table->sql_create_table( $datasrc, $username, $password );

         #possible problems
         @sql_statements = $table->sql_create_table( $datasrc );
         @sql_statements = $table->sql_create_table;

DESCRIPTION

       DBIx::DBSchema::Table objects represent a single database table.

METHODS

       new HASHREF
           Creates a new DBIx::DBSchema::Table object.  The preferred usage is to pass a hash
           reference of named parameters.

             {
               name          => TABLE_NAME,
               primary_key   => PRIMARY_KEY,
               columns       => COLUMNS,
               indices       => INDICES,
               local_options => OPTIONS,
             }

           TABLE_NAME is the name of the table.

           PRIMARY_KEY is the primary key (may be empty).

           COLUMNS is a reference to an array of DBIx::DBSchema::Column objects (see
           DBIx::DBSchema::Column).

           INDICES is a reference to an array of DBIx::DBSchema::Index objects (see
           DBIx::DBSchema::Index), or a hash reference of index names (keys) and
           DBIx::DBSchema::Index objects (values).

           FOREIGN_KEYS is a references to an array of DBIx::DBSchema::ForeignKey objects (see
           DBIx::DBSchema::ForeignKey).

           OPTIONS is a scalar of database-specific table options, such as "WITHOUT OIDS" for Pg
           or "TYPE=InnoDB" for mysql.

       new_odbc DATABASE_HANDLE TABLE_NAME
           Creates a new DBIx::DBSchema::Table object from the supplied DBI database handle for
           the specified table.  This uses the experimental DBI type_info method to create a
           table with standard (ODBC) SQL column types that most closely correspond to any non-
           portable column types.   Use this to import a schema that you wish to use with many
           different database engines.  Although primary key and (unique) index information will
           only be imported from databases with DBIx::DBSchema::DBD drivers (currently MySQL and
           PostgreSQL), import of column names and attributes *should* work for any database.

           Note: the _odbc refers to the column types used and nothing else - you do not have to
           have ODBC installed or connect to the database via ODBC.

       new_native DATABASE_HANDLE TABLE_NAME
           Creates a new DBIx::DBSchema::Table object from the supplied DBI database handle for
           the specified table.  This uses database-native methods to read the schema, and will
           preserve any non-portable column types.  The method is only available if there is a
           DBIx::DBSchema::DBD for the corresponding database engine (currently, MySQL and
           PostgreSQL).

       addcolumn COLUMN
           Adds this DBIx::DBSchema::Column object.

       delcolumn COLUMN_NAME
           Deletes this column.  Returns false if no column of this name was found to remove,
           true otherwise.

       name [ TABLE_NAME ]
           Returns or sets the table name.

       local_options [ OPTIONS ]
           Returns or sets the database-specific table options string.

       primary_key [ PRIMARY_KEY ]
           Returns or sets the primary key.

       columns
           Returns a list consisting of the names of all columns.

       column COLUMN_NAME
           Returns the column object (see DBIx::DBSchema::Column) for the specified COLUMN_NAME.

       indices
           Returns a list of key-value pairs suitable for assigning to a hash.  Keys are index
           names, and values are index objects (see DBIx::DBSchema::Index).

       unique_singles
           Meet exciting and unique singles using this method!

           This method returns a list of column names that are indexed with their own, unique,
           non-compond (that's the "single" part) indices.

       sql_create_table [ DATABASE_HANDLE | DATA_SOURCE [ USERNAME PASSWORD [ ATTR ] ] ]
           Returns a list of SQL statments to create this table.

           The data source can be specified by passing an open DBI database handle, or by passing
           the DBI data source name, username and password.

           Although the username and password are optional, it is best to call this method with a
           database handle or data source including a valid username and password - a DBI
           connection will be opened and the quoting and type mapping will be more reliable.

           If passed a DBI data source (or handle) such as `DBI:mysql:database', will use MySQL-
           or PostgreSQL-specific syntax.  Non-standard syntax for other engines (if applicable)
           may also be supported in the future.

       sql_add_constraints [ DATABASE_HANDLE | DATA_SOURCE [ USERNAME PASSWORD [ ATTR ] ] ]
           Returns a list of SQL statments to add constraints (foreign keys) to this table.

           The data source can be specified by passing an open DBI database handle, or by passing
           the DBI data source name, username and password.

           Although the username and password are optional, it is best to call this method with a
           database handle or data source including a valid username and password - a DBI
           connection will be opened and the quoting and type mapping will be more reliable.

           If passed a DBI data source (or handle) such as `DBI:mysql:database', will use MySQL-
           or PostgreSQL-specific syntax.  Non-standard syntax for other engines (if applicable)
           may also be supported in the future.

       sql_alter_table PROTOTYPE_TABLE, [ DATABASE_HANDLE | DATA_SOURCE [ USERNAME PASSWORD [
       ATTR ] ] ]
           Returns a list of SQL statements to alter this table so that it is identical to the
           provided table, also a DBIx::DBSchema::Table object.

           The data source can be specified by passing an open DBI database handle, or by passing
           the DBI data source name, username and password.

           Although the username and password are optional, it is best to call this method with a
           database handle or data source including a valid username and password - a DBI
           connection will be opened and used to check the database version as well as for more
           reliable quoting and type mapping.  Note that the database connection will be used
           passively, not to actually run the CREATE statements.

           If passed a DBI data source (or handle) such as `DBI:mysql:database' or
           `DBI:Pg:dbname=database', will use syntax specific to that database engine.  Currently
           supported databases are MySQL and PostgreSQL.

           If not passed a data source (or handle), or if there is no driver for the specified
           database, will attempt to use generic SQL syntax.

       sql_alter_constraints PROTOTYPE_TABLE, [ DATABASE_HANDLE | DATA_SOURCE [ USERNAME PASSWORD
       [ ATTR ] ] ]
           Returns a list of SQL statements to alter this table's constraints (foreign keys) so
           that they are identical to the provided table, also a DBIx::DBSchema::Table object.

           The data source can be specified by passing an open DBI database handle, or by passing
           the DBI data source name, username and password.

           Although the username and password are optional, it is best to call this method with a
           database handle or data source including a valid username and password - a DBI
           connection will be opened and used to check the database version as well as for more
           reliable quoting and type mapping.  Note that the database connection will be used
           passively, not to actually run the CREATE statements.

           If passed a DBI data source (or handle) such as `DBI:mysql:database' or
           `DBI:Pg:dbname=database', will use syntax specific to that database engine.  Currently
           supported databases are MySQL and PostgreSQL.

           If not passed a data source (or handle), or if there is no driver for the specified
           database, will attempt to use generic SQL syntax.

       foreign_keys_sql
       foreign_keys
           Returns a list of foreign keys (DBIx::DBSchema::ForeignKey objects).

AUTHOR

       Ivan Kohler <ivan-dbix-dbschema@420.am>

       Thanks to Mark Ethan Trostler <mark@zzo.com> for a patch to allow tables with no indices.

COPYRIGHT

       Copyright (c) 2000-2007 Ivan Kohler Copyright (c) 2000 Mail Abuse Prevention System LLC
       Copyright (c) 2007-2013 Freeside Internet Services, Inc.  All rights reserved.  This
       program is free software; you can redistribute it and/or modify it under the same terms as
       Perl itself.

BUGS

       sql_create_table() has database-specific foo that probably ought to be abstracted into the
       DBIx::DBSchema::DBD:: modules (or no?  it doesn't anymore?).

       sql_alter_table() also has database-specific foo that ought to be abstracted into the
       DBIx::DBSchema::DBD:: modules.

       sql_create_table() may change or destroy the object's data.  If you need to use the object
       after sql_create_table, make a copy beforehand.

       Some of the logic in new_odbc might be better abstracted into Column.pm etc.

       Add methods to get and set specific indices, by name? (like column COLUMN_NAME)

       indices method should be a setter, not just a getter?

SEE ALSO

       DBIx::DBSchema, DBIx::DBSchema::Column, DBI, DBIx::DBSchema::Index,
       DBIx::DBSchema::FoeignKey