DBSchema/DBD.pm

   1 package DBIx::DBSchema::DBD;
   2
   3 use strict;
   4 use vars qw($VERSION);
   5
   6 $VERSION = '0.04';
   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_catalog
 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 =back
 156
 157 =head1 TYPE MAPPING
 158
 159 You can define a %typemap array for your driver to map "standard" data
 160 types to database-specific types.  For example, the MySQL TIMESTAMP field
 161 has non-standard auto-updating semantics; the MySQL DATETIME type is
 162 what other databases and the ODBC standard call TIMESTAMP, so one of the
 163 entries in the MySQL %typemap is:
 164
 165   'TIMESTAMP' => 'DATETIME',
 166
 167 Another example is the Pg %typemap which maps the standard types BLOB and
 168 LONG VARBINARY to the Pg-specific BYTEA:
 169
 170   'BLOB' => 'BYTEA',
 171   'LONG VARBINARY' => 'BYTEA',
 172
 173 Make sure you use all uppercase-keys.
 174
 175 =head1 AUTHOR
 176
 177 Ivan Kohler <ivan-dbix-dbschema@420.am>
 178
 179 =head1 COPYRIGHT
 180
 181 Copyright (c) 2000-2005 Ivan Kohler
 182 All rights reserved.
 183 This program is free software; you can redistribute it and/or modify it under
 184 the same terms as Perl itself.
 185
 186 =head1 BUGS
 187
 188 =head1 SEE ALSO
 189
 190 L<DBIx::DBSchema>, L<DBIx::DBSchema::DBD::mysql>, L<DBIx::DBSchema::DBD::Pg>,
 191 L<DBIx::DBSchema::Index>, L<DBI>, L<DBI::DBD>, L<perllol>,
 192 L<perldsc/"HASHES OF LISTS">
 193
 194 =cut
 195
 196 1;
 197