DBIx::DBSchema::Table(3pm)

1DBSchema::Table(3)    User Contributed Perl Documentation   DBSchema::Table(3)
2
3
4

NAME

6       DBIx::DBSchema::Table - Table objects
7

SYNOPSIS

9         use DBIx::DBSchema::Table;
10
11         #new style (preferred), pass a hashref of parameters
12         $table = new DBIx::DBSchema::Table (
13           {
14             name        => "table_name",
15             primary_key => "primary_key",
16             columns     => \@dbix_dbschema_column_objects,
17             #deprecated# unique      => $dbix_dbschema_colgroup_unique_object,
18             #deprecated# 'index'     => $dbix_dbschema_colgroup_index_object,
19             indices     => \@dbix_dbschema_index_objects,
20           }
21         );
22
23         #old style (VERY deprecated)
24         $table = new DBIx::DBSchema::Table (
25           "table_name",
26           "primary_key",
27           $dbix_dbschema_colgroup_unique_object,
28           $dbix_dbschema_colgroup_index_object,
29           @dbix_dbschema_column_objects,
30         );
31
32         $table->addcolumn ( $dbix_dbschema_column_object );
33
34         $table_name = $table->name;
35         $table->name("table_name");
36
37         $primary_key = $table->primary_key;
38         $table->primary_key("primary_key");
39
40         #deprecated# $dbix_dbschema_colgroup_unique_object = $table->unique;
41         #deprecated# $table->unique( $dbix_dbschema__colgroup_unique_object );
42
43         #deprecated# $dbix_dbschema_colgroup_index_object = $table->index;
44         #deprecated# $table->index( $dbix_dbschema_colgroup_index_object );
45
46         %indices = $table->indices;
47         $dbix_dbschema_index_object = $indices{'index_name'};
48         @all_index_names = keys %indices;
49         @all_dbix_dbschema_index_objects = values %indices;
50
51         @column_names = $table->columns;
52
53         $dbix_dbschema_column_object = $table->column("column");
54
55         #preferred
56         @sql_statements = $table->sql_create_table( $dbh );
57         @sql_statements = $table->sql_create_table( $datasrc, $username, $password );
58
59         #possible problems
60         @sql_statements = $table->sql_create_table( $datasrc );
61         @sql_statements = $table->sql_create_table;
62

DESCRIPTION

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

METHODS

67       new HASHREF
68           Creates a new DBIx::DBSchema::Table object.  The preferred usage is
69           to pass a hash reference of named parameters.
70
71             {
72               name          => TABLE_NAME,
73               primary_key   => PRIMARY_KEY,
74               columns       => COLUMNS,
75               indices       => INDICES,
76               local_options => OPTIONS,
77               #deprecated# unique => UNIQUE,
78               #deprecated# index  => INDEX,
79             }
80
81           TABLE_NAME is the name of the table.  PRIMARY_KEY is the primary
82           key (may be empty).  COLUMNS is a reference to an array of
83           DBIx::DBSchema::Column objects (see DBIx::DBSchema::Column).
84           INDICES is a reference to an array of DBIx::DBSchema::Index objects
85           (see DBIx::DBSchema::Index), or a hash reference of index names
86           (keys) and DBIx::DBSchema::Index objects (values).  OPTIONS is a
87           scalar of database-specific table options, such as "WITHOUT OIDS"
88           for Pg or "TYPE=InnoDB" for mysql.
89
90           Deprecated options:
91
92           UNIQUE was a DBIx::DBSchema::ColGroup::Unique object (see
93           DBIx::DBSchema::ColGroup::Unique).  INDEX was a
94           DBIx::DBSchema::ColGroup::Index object (see DBIx::DBSchema::Col‐
95           Group::Index).
96
97       new_odbc DATABASE_HANDLE TABLE_NAME
98           Creates a new DBIx::DBSchema::Table object from the supplied DBI
99           database handle for the specified table.  This uses the experimen‐
100           tal DBI type_info method to create a table with standard (ODBC) SQL
101           column types that most closely correspond to any non-portable col‐
102           umn types.   Use this to import a schema that you wish to use with
103           many different database engines.  Although primary key and (unique)
104           index information will only be imported from databases with
105           DBIx::DBSchema::DBD drivers (currently MySQL and PostgreSQL),
106           import of column names and attributes *should* work for any data‐
107           base.
108
109           Note: the _odbc refers to the column types used and nothing else -
110           you do not have to have ODBC installed or connect to the database
111           via ODBC.
112
113       new_native DATABASE_HANDLE TABLE_NAME
114           Creates a new DBIx::DBSchema::Table object from the supplied DBI
115           database handle for the specified table.  This uses database-native
116           methods to read the schema, and will preserve any non-portable col‐
117           umn types.  The method is only available if there is a
118           DBIx::DBSchema::DBD for the corresponding database engine (cur‐
119           rently, MySQL and PostgreSQL).
120
121       addcolumn COLUMN
122           Adds this DBIx::DBSchema::Column object.
123
124       delcolumn COLUMN_NAME
125           Deletes this column.  Returns false if no column of this name was
126           found to remove, true otherwise.
127
128       name [ TABLE_NAME ]
129           Returns or sets the table name.
130
131       local_options [ OPTIONS ]
132           Returns or sets the database-specific table options string.
133
134       primary_key [ PRIMARY_KEY ]
135           Returns or sets the primary key.
136
137       unique [ UNIQUE ]
138           This method is deprecated and included for backwards-compatibility
139           only.  See "indices" for the current method to access unique and
140           non-unique index objects.
141
142           Returns or sets the DBIx::DBSchema::ColGroup::Unique object.
143
144       index [ INDEX ]
145           This method is deprecated and included for backwards-compatibility
146           only.  See "indices" for the current method to access unique and
147           non-unique index objects.
148
149           Returns or sets the DBIx::DBSchema::ColGroup::Index object.
150
151       columns
152           Returns a list consisting of the names of all columns.
153
154       column COLUMN_NAME
155           Returns the column object (see DBIx::DBSchema::Column) for the
156           specified COLUMN_NAME.
157
158       indices COLUMN_NAME
159           Returns a list of key-value pairs suitable for assigning to a hash.
160           Keys are index names, and values are index objects (see
161           DBIx::DBSchema::Index).
162
163       unique_singles
164           Meet exciting and unique singles using this method!
165
166           This method returns a list of column names that are indexed with
167           their own, unique, non-compond (that's the "single" part) indices.
168
169       sql_create_table [ DATABASE_HANDLE ⎪ DATA_SOURCE [ USERNAME PASSWORD [
170       ATTR ] ] ]
171           Returns a list of SQL statments to create this table.
172
173           Optionally, the data source can be specified by passing an open DBI
174           database handle, or by passing the DBI data source name, username
175           and password.
176
177           The data source can be specified by passing an open DBI database
178           handle, or by passing the DBI data source name, username and pass‐
179           word.
180
181           Although the username and password are optional, it is best to call
182           this method with a database handle or data source including a valid
183           username and password - a DBI connection will be opened and the
184           quoting and type mapping will be more reliable.
185
186           If passed a DBI data source (or handle) such as `DBI:mysql:data‐
187           base', will use MySQL- or PostgreSQL-specific syntax.  Non-standard
188           syntax for other engines (if applicable) may also be supported in
189           the future.
190
191       sql_alter_table PROTOTYPE_TABLE, [ DATABASE_HANDLE ⎪ DATA_SOURCE [
192       USERNAME PASSWORD [ ATTR ] ] ]
193           Returns a list of SQL statements to alter this table so that it is
194           identical to the provided table, also a DBIx::DBSchema::Table
195           object.
196
197           The data source can be specified by passing an open DBI database
198           handle, or by passing the DBI data source name, username and pass‐
199           word.
200
201           Although the username and password are optional, it is best to call
202           this method with a database handle or data source including a valid
203           username and password - a DBI connection will be opened and used to
204           check the database version as well as for more reliable quoting and
205           type mapping.  Note that the database connection will be used pas‐
206           sively, not to actually run the CREATE statements.
207
208           If passed a DBI data source (or handle) such as `DBI:mysql:data‐
209           base' or `DBI:Pg:dbname=database', will use syntax specific to that
210           database engine.  Currently supported databases are MySQL and Post‐
211           greSQL.
212
213           If not passed a data source (or handle), or if there is no driver
214           for the specified database, will attempt to use generic SQL syntax.
215

AUTHOR

217       Ivan Kohler <ivan-dbix-dbschema@420.am>
218
219       Thanks to Mark Ethan Trostler <mark@zzo.com> for a patch to allow
220       tables with no indices.
221

COPYRIGHT

223       Copyright (c) 2000-2007 Ivan Kohler Copyright (c) 2000 Mail Abuse Pre‐
224       vention System LLC Copyright (c) 2007 Freeside Internet Services, Inc.
225       All rights reserved.  This program is free software; you can redis‐
226       tribute it and/or modify it under the same terms as Perl itself.
227

BUGS

229       sql_create_table() has database-specific foo that probably ought to be
230       abstracted into the DBIx::DBSchema::DBD:: modules (or no?  it doesn't
231       anymore?).
232
233       sql_alter_table() also has database-specific foo that ought to be
234       abstracted into the DBIx::DBSchema::DBD:: modules.
235
236       sql_create_table() may change or destroy the object's data.  If you
237       need to use the object after sql_create_table, make a copy beforehand.
238
239       Some of the logic in new_odbc might be better abstracted into Column.pm
240       etc.
241
242       sql_alter_table ought to drop columns not in $new
243
244       Add methods to get and set specific indices, by name? (like column COL‐
245       UMN_NAME)
246
247       indices method should be a setter, not just a getter?
248