DBSchema/DBD.pm

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