DBSchema/DBD.pm

   1 package DBIx::DBSchema::DBD;
   2
   3 use strict;
   4
   5 our $VERSION = '0.08';
   6
   7 =head1 NAME
   8
   9 DBIx::DBSchema::DBD - DBIx::DBSchema Driver Writer's Guide and Base Class
  10
  11 =head1 SYNOPSIS
  12
  13   perldoc DBIx::DBSchema::DBD
  14
  15   package DBIx::DBSchema::DBD::FooBase
  16   use DBIx::DBSchema::DBD;
  17   @ISA = qw(DBIx::DBSchema::DBD);
  18
  19 =head1 DESCRIPTION
  20
  21 Drivers should be named DBIx::DBSchema::DBD::DatabaseName, where DatabaseName
  22 is the same as the DBD:: driver for this database.  Drivers should implement the
  23 following class methods:
  24
  25 =over 4
  26
  27 =item columns CLASS DBI_DBH TABLE
  28
  29 Given an active DBI database handle, return a listref of listrefs (see
  30 L<perllol>), each containing six elements: column name, column type,
  31 nullability, column length, column default, and a field reserved for
  32 driver-specific use.
  33
  34 =item column CLASS DBI_DBH TABLE COLUMN
  35
  36 Same as B<columns> above, except return the listref for a single column.  You
  37 can inherit from DBIx::DBSchema::DBD to provide this function.
  38
  39 =cut
  40
  41 sub column {
  42   my($proto, $dbh, $table, $column) = @_;
  43   #@a = grep { $_->[0] eq $column } @{ $proto->columns( $dbh, $table ) };
  44   #$a[0];
  45   @{ [
  46     grep { $_->[0] eq $column } @{ $proto->columns( $dbh, $table ) }
  47   ] }[0]; #force list context on grep, return scalar of first element
  48 }
  49
  50 =item primary_key CLASS DBI_DBH TABLE
  51
  52 Given an active DBI database handle, return the primary key for the specified
  53 table.
  54
  55 =item unique CLASS DBI_DBH TABLE
  56
  57 Deprecated method - see the B<indices> method for new drivers.
  58
  59 Given an active DBI database handle, return a hashref of unique indices.  The
  60 keys of the hashref are index names, and the values are arrayrefs which point
  61 a list of column names for each.  See L<perldsc/"HASHES OF LISTS"> and
  62 L<DBIx::DBSchema::Index>.
  63
  64 =item index CLASS DBI_DBH TABLE
  65
  66 Deprecated method - see the B<indices> method for new drivers.
  67
  68 Given an active DBI database handle, return a hashref of (non-unique) indices.
  69 The keys of the hashref are index names, and the values are arrayrefs which
  70 point a list of column names for each.  See L<perldsc/"HASHES OF LISTS"> and
  71 L<DBIx::DBSchema::Index>.
  72
  73 =item indices CLASS DBI_DBH TABLE
  74
  75 Given an active DBI database handle, return a hashref of all indices, both
  76 unique and non-unique.  The keys of the hashref are index names, and the values
  77 are again hashrefs with the following keys:
  78
  79 =over 8
  80
  81 =item name - Index name (redundant)
  82
  83 =item using - Optional index method
  84
  85 =item unique - Boolean indicating whether or not this is a unique index
  86
  87 =item columns - List reference of column names (or expressions)
  88
  89 =back
  90
  91 (See L<FS::DBIx::DBSchema::Index>)
  92
  93 New drivers are advised to implement this method, and existing drivers are
  94 advised to (eventually) provide this method instead of B<index> and B<unique>.
  95
  96 For backwards-compatibility with current drivers, the base DBIx::DBSchema::DBD
  97 class provides an B<indices> method which uses the old B<index> and B<unique>
  98 methods to provide this data.
  99
 100 =cut
 101
 102 sub indices {
 103   #my($proto, $dbh, $table) = @_;
 104   my($proto, @param) = @_;
 105
 106   my $unique_hr = $proto->unique( @param );
 107   my $index_hr  = $proto->index(  @param );
 108
 109   scalar(
 110     {
 111
 112       (
 113         map {
 114               $_ => { 'name'    => $_,
 115                       'unique'  => 1,
 116                       'columns' => $unique_hr->{$_},
 117                     },
 118             }
 119             keys %$unique_hr
 120       ),
 121
 122       (
 123         map {
 124               $_ => { 'name'    => $_,
 125                       'unique'  => 0,
 126                       'columns' => $index_hr->{$_},
 127                     },
 128             }
 129             keys %$index_hr
 130       ),
 131
 132     }
 133   );
 134 }
 135
 136 =item default_db_catalog
 137
 138 Returns the default database catalog for the DBI table_info command.
 139 Inheriting from DBIx::DBSchema::DBD will provide the default empty string.
 140
 141 =cut
 142
 143 sub default_db_catalog { ''; }
 144
 145 =item default_db_schema
 146
 147 Returns the default database schema for the DBI table_info command.
 148 Inheriting from DBIx::DBSchema::DBD will provide the default empty string.
 149
 150 =cut
 151
 152 sub default_db_schema { ''; }
 153
 154 =item constraints CLASS DBI_DBH TABLE
 155
 156 Given an active DBI database handle, return the constraints (currently, foreign
 157 keys) for the specified table, as a list of hash references.
 158
 159 Each hash reference has the following keys:
 160
 161 =over 8
 162
 163 =item constraint - contraint name
 164
 165 =item columns - List refrence of column names
 166
 167 =item table - Foreign taable name
 168
 169 =item references - List reference of column names in foreign table
 170
 171 =item match -
 172
 173 =item on_delete -
 174
 175 =item on_update -
 176
 177 =back
 178
 179 =cut
 180
 181 sub constraints { (); }
 182
 183 =item column_callback DBH TABLE_NAME COLUMN_OBJ
 184
 185 Optional callback for driver-specific overrides to SQL column definitions.
 186
 187 Should return a hash reference, empty for no action, or with one or more of
 188 the following keys defined:
 189
 190 effective_type - Optional type override used during column creation.
 191
 192 explicit_null - Set true to have the column definition declare NULL columns explicitly
 193
 194 effective_default - Optional default override used during column creation.
 195
 196 effective_local - Optional local override used during column creation.
 197
 198
 199 =cut
 200
 201 sub column_callback { {}; }
 202
 203 =item add_column_callback DBH TABLE_NAME COLUMN_OBJ
 204
 205 Optional callback for additional SQL statments to be called when adding columns
 206 to an existing table.
 207
 208 Should return a hash reference, empty for no action, or with one or more of
 209 the following keys defined:
 210
 211 effective_type - Optional type override used during column creation.
 212
 213 effective_null - Optional nullability override used during column creation.
 214
 215 sql_after - Array reference of SQL statements to be executed after the column is added.
 216
 217 =cut
 218
 219 sub add_column_callback { {}; }
 220
 221 =item alter_column_callback DBH TABLE_NAME OLD_COLUMN_OBJ NEW_COLUMN_OBJ
 222
 223 Optional callback for overriding the SQL statments to be called when altering
 224 columns to an existing table.
 225
 226 Should return a hash reference, empty for no action, or with one or more of
 227 the following keys defined:
 228
 229 sql_alter - Alter SQL statement(s) for changing everything about a column.  Specifying this overrides processing of individual changes (type, nullability, default, etc.).
 230
 231 sql_alter_type - Alter SQL statement(s) for changing type and length (there is no default).
 232
 233 sql_alter_null - Alter SQL statement(s) for changing nullability to be used instead of the default.
 234
 235 =cut
 236
 237 sub alter_column_callback { {}; }
 238
 239 =item column_value_needs_quoting COLUMN_OBJ
 240
 241 Optional callback for determining if a column's default value require quoting.
 242 Returns true if it does, false otherwise.
 243
 244 =cut
 245
 246 sub column_value_needs_quoting {
 247   my($proto, $col) = @_;
 248   my $class = ref($proto) || $proto;
 249
 250   # type mapping
 251   my %typemap = eval "\%${class}::typemap";
 252   my $type = defined( $typemap{uc($col->type)} )
 253                ? $typemap{uc($col->type)}
 254                : $col->type;
 255
 256   # false laziness: nicked from FS::Record::_quote
 257   $col->default !~ /^\-?\d+(\.\d+)?$/
 258     ||    $type =~ /(char|binary|blob|text)$/i;
 259
 260 }
 261
 262 =back
 263
 264 =head1 TYPE MAPPING
 265
 266 You can define a %typemap array for your driver to map "standard" data
 267 types to database-specific types.  For example, the MySQL TIMESTAMP field
 268 has non-standard auto-updating semantics; the MySQL DATETIME type is
 269 what other databases and the ODBC standard call TIMESTAMP, so one of the
 270 entries in the MySQL %typemap is:
 271
 272   'TIMESTAMP' => 'DATETIME',
 273
 274 Another example is the Pg %typemap which maps the standard types BLOB and
 275 LONG VARBINARY to the Pg-specific BYTEA:
 276
 277   'BLOB' => 'BYTEA',
 278   'LONG VARBINARY' => 'BYTEA',
 279
 280 Make sure you use all uppercase-keys.
 281
 282 =head1 AUTHOR
 283
 284 Ivan Kohler <ivan-dbix-dbschema@420.am>
 285
 286 =head1 COPYRIGHT
 287
 288 Copyright (c) 2000-2005 Ivan Kohler
 289 Copyright (c) 2007-2013 Freeside Internet Services, Inc.
 290 All rights reserved.
 291 This program is free software; you can redistribute it and/or modify it under
 292 the same terms as Perl itself.
 293
 294 =head1 BUGS
 295
 296 =head1 SEE ALSO
 297
 298 L<DBIx::DBSchema>, L<DBIx::DBSchema::DBD::mysql>, L<DBIx::DBSchema::DBD::Pg>,
 299 L<DBIx::DBSchema::Index>, L<DBI>, L<DBI::DBD>, L<perllol>,
 300 L<perldsc/"HASHES OF LISTS">
 301
 302 =cut
 303
 304 1;
 305