1 package DBIx::DBSchema::Column;
6 use DBIx::DBSchema::_util qw(_load_driver _dbh);
12 DBIx::DBSchema::Column - Column objects
16 use DBIx::DBSchema::Column;
18 #named params with a hashref (preferred)
19 $column = new DBIx::DBSchema::Column ( {
20 'name' => 'column_name',
29 $column = new DBIx::DBSchema::Column ( $name, $sql_type, $nullability, $length, $default, $local );
31 $name = $column->name;
32 $column->name( 'name' );
34 $sql_type = $column->type;
35 $column->type( 'sql_type' );
37 $null = $column->null;
38 $column->null( 'NULL' );
39 $column->null( 'NOT NULL' );
42 $length = $column->length;
43 $column->length( '10' );
44 $column->length( '8,2' );
46 $default = $column->default;
47 $column->default( 'Roo' );
49 $sql_line = $column->line;
50 $sql_line = $column->line($datasrc);
52 $sql_add_column = $column->sql_add_column;
53 $sql_add_column = $column->sql_add_column($datasrc);
57 DBIx::DBSchema::Column objects represent columns in tables (see
58 L<DBIx::DBSchema::Table>).
66 =item new [ name [ , type [ , null [ , length [ , default [ , local ] ] ] ] ] ]
68 Creates a new DBIx::DBSchema::Column object. Takes a hashref of named
69 parameters, or a list. B<name> is the name of the column. B<type> is the SQL
70 data type. B<null> is the nullability of the column (intrepreted using Perl's
71 rules for truth, with one exception: `NOT NULL' is false). B<length> is the
72 SQL length of the column. B<default> is the default value of the column.
73 B<local> is reserved for database-specific information.
75 Note: If you pass a scalar reference as the B<default> rather than a scalar value, it will be dereferenced and quoting will be forced off. This can be used to pass SQL functions such as C<$now()> or explicit empty strings as C<''> as
82 my $class = ref($proto) || $proto;
88 #carp "Old-style $class creation without named parameters is deprecated!";
89 #croak "FATAL: old-style $class creation no longer supported;".
90 # " use named parameters";
92 $self = { map { $_ => shift } qw(name type null length default local) };
95 #croak "Illegal name: ". $self->{'name'}
96 # if grep $self->{'name'} eq $_, @reserved_words;
98 $self->{'null'} =~ s/^NOT NULL$//i;
99 $self->{'null'} = 'NULL' if $self->{'null'};
101 bless ($self, $class);
107 Returns or sets the column name.
113 if ( defined($value) ) {
114 #croak "Illegal name: $name" if grep $name eq $_, @reserved_words;
115 $self->{'name'} = $value;
123 Returns or sets the column type.
129 if ( defined($value) ) {
130 $self->{'type'} = $value;
138 Returns or sets the column null flag (the empty string is equivalent to
145 if ( defined($value) ) {
146 $value =~ s/^NOT NULL$//i;
147 $value = 'NULL' if $value;
148 $self->{'null'} = $value;
154 =item length [ LENGTH ]
156 Returns or sets the column length.
162 if ( defined($value) ) {
163 $self->{'length'} = $value;
169 =item default [ LOCAL ]
171 Returns or sets the default value.
177 if ( defined($value) ) {
178 $self->{'default'} = $value;
185 =item local [ LOCAL ]
187 Returns or sets the database-specific field.
193 if ( defined($value) ) {
194 $self->{'local'} = $value;
200 =item table_obj [ TABLE_OBJ ]
202 Returns or sets the table object (see L<DBIx::DBSchema::Table>). Typically
203 set internally when a column object is added to a table object.
209 if ( defined($value) ) {
210 $self->{'table_obj'} = $value;
212 $self->{'table_obj'};
218 Returns the table name, or the empty string if this column has not yet been
225 $self->{'table_obj'} ? $self->{'table_obj'}->name : '';
228 =item line [ DATABASE_HANDLE | DATA_SOURCE [ USERNAME PASSWORD [ ATTR ] ] ]
230 Returns an SQL column definition.
232 The data source can be specified by passing an open DBI database handle, or by
233 passing the DBI data source name, username and password.
235 Although the username and password are optional, it is best to call this method
236 with a database handle or data source including a valid username and password -
237 a DBI connection will be opened and the quoting and type mapping will be more
240 If passed a DBI data source (or handle) such as `DBI:mysql:database' or
241 `DBI:Pg:dbname=database', will use syntax specific to that database engine.
242 Currently supported databases are MySQL and PostgreSQL. Non-standard syntax
243 for other engines (if applicable) may also be supported in the future.
248 my($self, $dbh) = ( shift, _dbh(@_) );
250 my $driver = $dbh ? _load_driver($dbh) : '';
257 %typemap = eval "\%DBIx::DBSchema::DBD::${driver}::typemap" if $driver;
258 my $type = defined( $typemap{uc($self->type)} )
259 ? $typemap{uc($self->type)}
263 # set default for the callback...
267 my $orig_default = $self->default;
268 if ( defined($self->default) && !ref($self->default) && $self->default ne ''
270 # false laziness: nicked from FS::Record::_quote
271 && ( $self->default !~ /^\-?\d+(\.\d+)?$/
272 || $type =~ /(char|binary|blob|text)$/i
275 $default = $dbh->quote($self->default);
277 $default = ref($self->default) ? ${$self->default} : $self->default;
279 $self->default($default);
282 # callback into the database-specific driver
285 my $dbd = "DBIx::DBSchema::DBD::$driver";
286 my $hashref = $dbd->column_callback( $dbh, $self->table_name, $self );
288 $self->default($orig_default);
290 $type = $hashref->{'effective_type'}
291 if $hashref->{'effective_type'};
293 my $null = $self->null;
295 #we seem to do this for mysql/Pg/SQLite, i think this should be the default
296 #add something to $hashref if drivers need to overrdide?
297 $null ||= "NOT NULL";
299 $null =~ s/^NULL$// unless $hashref->{'explicit_null'};
301 $default = $hashref->{'effective_default'}
302 if $hashref->{'effective_default'};
304 my $local = $self->local;
305 $local = $hashref->{'effective_local'}
306 if $hashref->{'effective_local'};
314 $type. ( ( defined($self->length) && $self->length )
315 ? '('.$self->length.')'
319 ( ( defined($default) && $default ne '' )
320 ? 'DEFAULT '. $default
323 ( defined($local) ? $local : ''),
328 =item sql_add_column [ DBH ]
330 Returns a list of SQL statements to add this column to an existing table. (To
331 create a new table, see L<DBIx::DBSchema::Table/sql_create_table> instead.)
333 The data source can be specified by passing an open DBI database handle, or by
334 passing the DBI data source name, username and password.
336 Although the username and password are optional, it is best to call this method
337 with a database handle or data source including a valid username and password -
338 a DBI connection will be opened and the quoting and type mapping will be more
341 If passed a DBI data source (or handle) such as `DBI:Pg:dbname=database', will
342 use PostgreSQL-specific syntax. Non-standard syntax for other engines (if
343 applicable) may also be supported in the future.
348 my($self, $dbh) = ( shift, _dbh(@_) );
350 die "$self: this column is not assigned to a table"
351 unless $self->table_name;
353 my $driver = $dbh ? _load_driver($dbh) : '';
356 my $table = $self->table_name;
358 my $dbd = "DBIx::DBSchema::DBD::$driver";
359 my $hashref = $dbd->add_column_callback( $dbh, $table, $self );
362 if ( $hashref->{'effective_type'} ) {
363 $real_type = $self->type;
364 $self->type($hashref->{'effective_type'});
367 my $real_null = undef;
368 if ( exists($hashref->{'effective_null'}) ) {
369 $real_null = $self->null;
370 $self->null($hashref->{'effective_null'});
373 push @sql, "ALTER TABLE $table ADD COLUMN ". $self->line($dbh);
375 push @sql, @{ $hashref->{'sql_after'} } if $hashref->{'sql_after'};
377 push @sql, "ALTER TABLE $table ADD PRIMARY KEY ( ".
378 $self->table_obj->primary_key. " )"
379 if $self->name eq $self->table_obj->primary_key;
381 $self->type($real_type) if $real_type;
382 $self->null($real_null) if defined $real_null;
388 =item sql_alter_column PROTOTYPE_COLUMN [ DATABASE_HANDLE | DATA_SOURCE [ USERNAME PASSWORD [ ATTR ] ] ]
390 Returns a list of SQL statements to alter this column so that it is identical
391 to the provided prototype column, also a DBIx::DBSchema::Column object.
393 #Optionally, the data source can be specified by passing an open DBI database
394 #handle, or by passing the DBI data source name, username and password.
396 #If passed a DBI data source (or handle) such as `DBI:Pg:dbname=database', will
397 #use PostgreSQL-specific syntax. Non-standard syntax for other engines (if
398 #applicable) may also be supported in the future.
400 #If not passed a data source (or handle), or if there is no driver for the
401 #specified database, will attempt to use generic SQL syntax.
404 Or should, someday. Right now it knows how to change NOT NULL into NULL and
409 sub sql_alter_column {
410 my( $self, $new, $dbh ) = ( shift, shift, _dbh(@_) );
412 my $table = $self->table_name;
413 die "$self: this column is not assigned to a table"
416 my $name = $self->name;
418 my $driver = $dbh ? _load_driver($dbh) : '';
422 my $dbd = "DBIx::DBSchema::DBD::$driver";
423 my $hashref = $dbd->alter_column_callback( $dbh, $table, $self, $new );
429 if ( $hashref->{'sql_alter_null' } ) {
431 push @sql, $hashref->{'sql_alter_null'};
435 # change nullability from NOT NULL to NULL
436 if ( ! $self->null && $new->null ) {
438 push @sql, "ALTER TABLE $table ALTER COLUMN $name DROP NOT NULL";
442 # change nullability from NULL to NOT NULL...
443 # this one could be more complicated, need to set a DEFAULT value and update
445 if ( $self->null && ! $new->null ) {
447 push @sql, "ALTER TABLE $table ALTER COLUMN $name SET NOT NULL";
453 # change other stuff...
458 =item sql_drop_column [ DBH ]
460 Returns a list of SQL statements to drop this column from an existing table.
462 The optional database handle or DBI data source/username/password is not yet
467 sub sql_drop_column {
468 my( $self, $dbh ) = ( shift, _dbh(@_) );
470 my $table = $self->table_name;
471 my $name = $self->name;
473 ("ALTER TABLE $table DROP COLUMN $name"); # XXX what about indexes???
480 Ivan Kohler <ivan-dbix-dbschema@420.am>
484 Copyright (c) 2000-2006 Ivan Kohler
485 Copyright (c) 2007 Freeside Internet Services, Inc.
487 This program is free software; you can redistribute it and/or modify it under
488 the same terms as Perl itself.
492 The new() method should warn that
493 "Old-style $class creation without named parameters is deprecated!"
495 Better documentation is needed for sql_add_column
497 line() and sql_add_column() hav database-specific foo that should be abstracted
498 into the DBIx::DBSchema:DBD:: modules.
502 L<DBIx::DBSchema::Table>, L<DBIx::DBSchema>, L<DBIx::DBSchema::DBD>, L<DBI>