lib/SQL/Translator/Parser/DBI.pm

   1 package SQL::Translator::Parser::DBI;
   2
   3 # -------------------------------------------------------------------
   4 # Copyright (C) 2002-2009 SQLFairy Authors
   5 #
   6 # This program is free software; you can redistribute it and/or
   7 # modify it under the terms of the GNU General Public License as
   8 # published by the Free Software Foundation; version 2.
   9 #
  10 # This program is distributed in the hope that it will be useful, but
  11 # WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 # General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program; if not, write to the Free Software
  17 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  18 # 02111-1307  USA
  19 # -------------------------------------------------------------------
  20
  21 =head1 NAME
  22
  23 SQL::Translator::Parser::DBI - "parser" for DBI handles
  24
  25 =head1 SYNOPSIS
  26
  27   use DBI;
  28   use SQL::Translator;
  29
  30   my $dbh = DBI->connect('dsn', 'user', 'pass',
  31       {
  32           RaiseError       => 1,
  33           FetchHashKeyName => 'NAME_lc',
  34       }
  35   );
  36
  37   my $translator  =  SQL::Translator->new(
  38       parser      => 'DBI',
  39       dbh         => $dbh,
  40   );
  41
  42 Or:
  43
  44   use SQL::Translator;
  45
  46   my $translator      =  SQL::Translator->new(
  47       parser          => 'DBI',
  48       parser_args     => {
  49           dsn         => 'dbi:mysql:FOO',
  50           db_user     => 'guest',
  51           db_password => 'password',
  52     }
  53   );
  54
  55 =head1 DESCRIPTION
  56
  57 This parser accepts an open database handle (or the arguments to create
  58 one) and queries the database directly for the information.
  59
  60 The following are acceptable arguments:
  61
  62 =over 4
  63
  64 =item * dbh
  65
  66 An open DBI database handle.  NB:  Be sure to create the database with the
  67 "FetchHashKeyName => 'NAME_lc'" option as all the DBI parsers expect
  68 lowercased column names.
  69
  70 =item * dsn
  71
  72 The DSN to use for connecting to a database.
  73
  74 =item * db_user
  75
  76 The user name to use for connecting to a database.
  77
  78 =item * db_password
  79
  80 The password to use for connecting to a database.
  81
  82 =back
  83
  84 There is no need to specify which type of database you are querying as
  85 this is determined automatically by inspecting $dbh->{'Driver'}{'Name'}.
  86 If a parser exists for your database, it will be used automatically;
  87 if not, the code will fail automatically (and you can write the parser
  88 and contribute it to the project!).
  89
  90 Currently parsers exist for the following databases:
  91
  92 =over 4
  93
  94 =item * MySQL
  95
  96 =item * SQLite
  97
  98 =item * Sybase
  99
 100 =item * PostgreSQL (still experimental)
 101
 102 =back
 103
 104 Most of these parsers are able to query the database directly for the
 105 structure rather than parsing a text file.  For large schemas, this is
 106 probably orders of magnitude faster than traditional parsing (which
 107 uses Parse::RecDescent, an amazing module but really quite slow).
 108
 109 Though no Oracle parser currently exists, it would be fairly easy to
 110 query an Oracle database directly by using DDL::Oracle to generate a
 111 DDL for the schema and then using the normal Oracle parser on this.
 112 Perhaps future versions of SQL::Translator will include the ability to
 113 query Oracle directly and skip the parsing of a text file, too.
 114
 115 =cut
 116
 117 use strict;
 118 use DBI;
 119 use vars qw($VERSION @EXPORT);
 120 $VERSION = '1.59';
 121
 122 use constant DRIVERS => {
 123     mysql            => 'MySQL',
 124     odbc             => 'SQLServer',
 125     oracle           => 'Oracle',
 126     pg               => 'PostgreSQL',
 127     sqlite           => 'SQLite',
 128     sybase           => 'Sybase',
 129     pg               => 'PostgreSQL',
 130     db2              => 'DB2',
 131 };
 132
 133 use Exporter;
 134
 135 use SQL::Translator::Utils qw(debug);
 136
 137 use base qw(Exporter);
 138 @EXPORT = qw(parse);
 139
 140 #
 141 # Passed a SQL::Translator instance and a string containing the data
 142 #
 143 sub parse {
 144     my ( $tr, $data ) = @_;
 145
 146     my $args          = $tr->parser_args;
 147     my $dbh           = $args->{'dbh'};
 148     my $dsn           = $args->{'dsn'};
 149     my $db_user       = $args->{'db_user'};
 150     my $db_password   = $args->{'db_password'};
 151
 152     unless ( $dbh ) {
 153         die 'No DSN' unless $dsn;
 154         $dbh = DBI->connect( $dsn, $db_user, $db_password,
 155             {
 156                 FetchHashKeyName => 'NAME_lc',
 157                 LongReadLen      => 3000,
 158                 LongTruncOk      => 1,
 159                 RaiseError       => 1,
 160             }
 161         );
 162     }
 163
 164     die 'No database handle' unless defined $dbh;
 165
 166     my $db_type = $dbh->{'Driver'}{'Name'} or die 'Cannot determine DBI type';
 167     my $driver  = DRIVERS->{ lc $db_type } or die "$db_type not supported";
 168     my $pkg     = "SQL::Translator::Parser::DBI::$driver";
 169     my $sub     = $pkg.'::parse';
 170
 171     SQL::Translator::load( $pkg );
 172
 173     eval {
 174         no strict 'refs';
 175         &{ $sub }( $tr, $dbh ) or die "No result from $pkg";
 176     };
 177
 178     $dbh->disconnect if defined $dbh;
 179
 180     die $@ if $@;
 181
 182     return 1;
 183 }
 184
 185 1;
 186
 187 =pod
 188
 189 =head1 AUTHOR
 190
 191 Ken Y. Clark E<lt>kclark@cpan.orgE<gt>.
 192
 193 =head1 SEE ALSO
 194
 195 DBI, SQL::Translator.
 196
 197 =cut