.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "DBSchema::Table 3pm" .TH DBSchema::Table 3pm "2022-09-10" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" DBIx::DBSchema::Table \- Table objects .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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 => \e@dbix_dbschema_column_objects, \& #deprecated# unique => $dbix_dbschema_colgroup_unique_object, \& #deprecated# \*(Aqindex\*(Aq => $dbix_dbschema_colgroup_index_object, \& indices => \e@dbix_dbschema_index_objects, \& foreign_keys => \e@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{\*(Aqindex_name\*(Aq}; \& @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; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" DBIx::DBSchema::Table objects represent a single database table. .SH "METHODS" .IX Header "METHODS" .IP "new \s-1HASHREF\s0" 4 .IX Item "new HASHREF" Creates a new DBIx::DBSchema::Table object. The preferred usage is to pass a hash reference of named parameters. .Sp .Vb 7 \& { \& name => TABLE_NAME, \& primary_key => PRIMARY_KEY, \& columns => COLUMNS, \& indices => INDICES, \& local_options => OPTIONS, \& } .Ve .Sp \&\s-1TABLE_NAME\s0 is the name of the table. .Sp \&\s-1PRIMARY_KEY\s0 is the primary key (may be empty). .Sp \&\s-1COLUMNS\s0 is a reference to an array of DBIx::DBSchema::Column objects (see DBIx::DBSchema::Column). .Sp \&\s-1INDICES\s0 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). .Sp \&\s-1FOREIGN_KEYS\s0 is a references to an array of DBIx::DBSchema::ForeignKey objects (see DBIx::DBSchema::ForeignKey). .Sp \&\s-1OPTIONS\s0 is a scalar of database-specific table options, such as \*(L"\s-1WITHOUT OIDS\*(R"\s0 for Pg or \*(L"TYPE=InnoDB\*(R" for mysql. .IP "new_odbc \s-1DATABASE_HANDLE TABLE_NAME\s0" 4 .IX Item "new_odbc DATABASE_HANDLE TABLE_NAME" Creates a new DBIx::DBSchema::Table object from the supplied \s-1DBI\s0 database handle for the specified table. This uses the experimental \s-1DBI\s0 type_info method to create a table with standard (\s-1ODBC\s0) \s-1SQL\s0 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. .Sp Note: the _odbc refers to the column types used and nothing else \- you do not have to have \s-1ODBC\s0 installed or connect to the database via \s-1ODBC.\s0 .IP "new_native \s-1DATABASE_HANDLE TABLE_NAME\s0" 4 .IX Item "new_native DATABASE_HANDLE TABLE_NAME" Creates a new DBIx::DBSchema::Table object from the supplied \s-1DBI\s0 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). .IP "addcolumn \s-1COLUMN\s0" 4 .IX Item "addcolumn COLUMN" Adds this DBIx::DBSchema::Column object. .IP "delcolumn \s-1COLUMN_NAME\s0" 4 .IX Item "delcolumn COLUMN_NAME" Deletes this column. Returns false if no column of this name was found to remove, true otherwise. .IP "name [ \s-1TABLE_NAME\s0 ]" 4 .IX Item "name [ TABLE_NAME ]" Returns or sets the table name. .IP "local_options [ \s-1OPTIONS\s0 ]" 4 .IX Item "local_options [ OPTIONS ]" Returns or sets the database-specific table options string. .IP "primary_key [ \s-1PRIMARY_KEY\s0 ]" 4 .IX Item "primary_key [ PRIMARY_KEY ]" Returns or sets the primary key. .IP "columns" 4 .IX Item "columns" Returns a list consisting of the names of all columns. .IP "column \s-1COLUMN_NAME\s0" 4 .IX Item "column COLUMN_NAME" Returns the column object (see DBIx::DBSchema::Column) for the specified \&\s-1COLUMN_NAME.\s0 .IP "indices" 4 .IX Item "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). .IP "unique_singles" 4 .IX Item "unique_singles" Meet exciting and unique singles using this method! .Sp This method returns a list of column names that are indexed with their own, unique, non-compond (that's the \*(L"single\*(R" part) indices. .IP "sql_create_table [ \s-1DATABASE_HANDLE\s0 | \s-1DATA_SOURCE\s0 [ \s-1USERNAME PASSWORD\s0 [ \s-1ATTR\s0 ] ] ]" 4 .IX Item "sql_create_table [ DATABASE_HANDLE | DATA_SOURCE [ USERNAME PASSWORD [ ATTR ] ] ]" Returns a list of \s-1SQL\s0 statments to create this table. .Sp The data source can be specified by passing an open \s-1DBI\s0 database handle, or by passing the \s-1DBI\s0 data source name, username and password. .Sp 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 \s-1DBI\s0 connection will be opened and the quoting and type mapping will be more reliable. .Sp If passed a \s-1DBI\s0 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. .IP "sql_add_constraints [ \s-1DATABASE_HANDLE\s0 | \s-1DATA_SOURCE\s0 [ \s-1USERNAME PASSWORD\s0 [ \s-1ATTR\s0 ] ] ]" 4 .IX Item "sql_add_constraints [ DATABASE_HANDLE | DATA_SOURCE [ USERNAME PASSWORD [ ATTR ] ] ]" Returns a list of \s-1SQL\s0 statments to add constraints (foreign keys) to this table. .Sp The data source can be specified by passing an open \s-1DBI\s0 database handle, or by passing the \s-1DBI\s0 data source name, username and password. .Sp 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 \s-1DBI\s0 connection will be opened and the quoting and type mapping will be more reliable. .Sp If passed a \s-1DBI\s0 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. .IP "sql_alter_table \s-1PROTOTYPE_TABLE,\s0 [ \s-1DATABASE_HANDLE\s0 | \s-1DATA_SOURCE\s0 [ \s-1USERNAME PASSWORD\s0 [ \s-1ATTR\s0 ] ] ]" 4 .IX Item "sql_alter_table PROTOTYPE_TABLE, [ DATABASE_HANDLE | DATA_SOURCE [ USERNAME PASSWORD [ ATTR ] ] ]" Returns a list of \s-1SQL\s0 statements to alter this table so that it is identical to the provided table, also a DBIx::DBSchema::Table object. .Sp The data source can be specified by passing an open \s-1DBI\s0 database handle, or by passing the \s-1DBI\s0 data source name, username and password. .Sp 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 \s-1DBI\s0 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, \fBnot\fR to actually run the \s-1CREATE\s0 statements. .Sp If passed a \s-1DBI\s0 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. .Sp If not passed a data source (or handle), or if there is no driver for the specified database, will attempt to use generic \s-1SQL\s0 syntax. .IP "sql_alter_constraints \s-1PROTOTYPE_TABLE,\s0 [ \s-1DATABASE_HANDLE\s0 | \s-1DATA_SOURCE\s0 [ \s-1USERNAME PASSWORD\s0 [ \s-1ATTR\s0 ] ] ]" 4 .IX Item "sql_alter_constraints PROTOTYPE_TABLE, [ DATABASE_HANDLE | DATA_SOURCE [ USERNAME PASSWORD [ ATTR ] ] ]" Returns a list of \s-1SQL\s0 statements to alter this table's constraints (foreign keys) so that they are identical to the provided table, also a DBIx::DBSchema::Table object. .Sp The data source can be specified by passing an open \s-1DBI\s0 database handle, or by passing the \s-1DBI\s0 data source name, username and password. .Sp 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 \s-1DBI\s0 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, \fBnot\fR to actually run the \s-1CREATE\s0 statements. .Sp If passed a \s-1DBI\s0 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. .Sp If not passed a data source (or handle), or if there is no driver for the specified database, will attempt to use generic \s-1SQL\s0 syntax. .IP "foreign_keys_sql" 4 .IX Item "foreign_keys_sql" .PD 0 .IP "foreign_keys" 4 .IX Item "foreign_keys" .PD Returns a list of foreign keys (DBIx::DBSchema::ForeignKey objects). .SH "AUTHOR" .IX Header "AUTHOR" Ivan Kohler .PP Thanks to Mark Ethan Trostler for a patch to allow tables with no indices. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2000\-2007 Ivan Kohler Copyright (c) 2000 Mail Abuse Prevention System \s-1LLC\s0 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. .SH "BUGS" .IX Header "BUGS" \&\fBsql_create_table()\fR has database-specific foo that probably ought to be abstracted into the DBIx::DBSchema::DBD:: modules (or no? it doesn't anymore?). .PP \&\fBsql_alter_table()\fR also has database-specific foo that ought to be abstracted into the DBIx::DBSchema::DBD:: modules. .PP \&\fBsql_create_table()\fR may change or destroy the object's data. If you need to use the object after sql_create_table, make a copy beforehand. .PP Some of the logic in new_odbc might be better abstracted into Column.pm etc. .PP Add methods to get and set specific indices, by name? (like column \s-1COLUMN_NAME\s0) .PP indices method should be a setter, not just a getter? .SH "SEE ALSO" .IX Header "SEE ALSO" DBIx::DBSchema, DBIx::DBSchema::Column, \s-1DBI\s0, DBIx::DBSchema::Index, DBIx::DBSchema::FoeignKey