README

   1 NAME
   2     SQL::Translator - convert schema from one database to another
   3
   4 SYNOPSIS
   5       use SQL::Translator;
   6
   7       my $translator     = SQL::Translator->new(
   8           debug          => 1, # Print debug info
   9           trace          => 0, # Print Parse::RecDescent trace
  10           no_comments    => 0, # Don't include comments in output
  11           show_warnings  => 0, # Print name mutations, conflicts
  12           add_drop_table => 1, # Add "drop table" statements
  13
  14           # Make all table names CAPS in producers which support this option
  15           format_table_name => sub {my $tablename = shift; return uc($tablename)},
  16
  17           # Null-op formatting, only here for documentation's sake
  18           format_package_name => sub {return shift},
  19           format_fk_name      => sub {return shift},
  20           format_pk_name      => sub {return shift},
  21       );
  22
  23       my $output     = $translator->translate(
  24           from       => "MySQL",
  25           to         => "Oracle",
  26           # Or an arrayref of filenames, i.e. [ $file1, $file2, $file3 ]
  27           filename   => $file,
  28       ) or die $translator->error;
  29
  30       print $output;
  31
  32 DESCRIPTION
  33     This module attempts to simplify the task of converting one database
  34     create syntax to another through the use of Parsers (which understand
  35     the source format) and Producers (which understand the destination
  36     format). The idea is that any Parser can be used with any Producer in
  37     the conversion process. So, if you wanted Postgres-to-Oracle, you would
  38     use the Postgres parser and the Oracle producer.
  39
  40 CONSTRUCTOR
  41     The constructor is called "new", and accepts a optional hash of options.
  42     Valid options are:
  43
  44     *   parser / from
  45
  46     *   parser_args
  47
  48     *   producer / to
  49
  50     *   producer_args
  51
  52     *   filename / file
  53
  54     *   data
  55
  56     *   debug
  57
  58     All options are, well, optional; these attributes can be set via
  59     instance methods. Internally, they are; no (non-syntactical) advantage
  60     is gained by passing options to the constructor.
  61
  62 METHODS
  63   add_drop_table
  64
  65     Toggles whether or not to add "DROP TABLE" statements just before the
  66     create definitions.
  67
  68   custom_translate
  69
  70     Allows the user to override default translation of fields. For example,
  71     if a MySQL "text" field would normally be converted to a "long" for
  72     Oracle, the user could specify to change it to a "CLOB." Accepts a
  73     hashref where keys are the "from" value and values are the "to," returns
  74     the current value of the field.
  75
  76   no_comments
  77
  78     Toggles whether to print comments in the output. Accepts a true or false
  79     value, returns the current value.
  80
  81   producer
  82
  83     The "producer" method is an accessor/mutator, used to retrieve or define
  84     what subroutine is called to produce the output. A subroutine defined as
  85     a producer will be invoked as a function (*not a method*) and passed 2
  86     parameters: its container "SQL::Translator" instance and a data
  87     structure. It is expected that the function transform the data structure
  88     to a string. The "SQL::Transformer" instance is provided for
  89     informational purposes; for example, the type of the parser can be
  90     retrieved using the "parser_type" method, and the "error" and "debug"
  91     methods can be called when needed.
  92
  93     When defining a producer, one of several things can be passed in: A
  94     module name (e.g., "My::Groovy::Producer"), a module name relative to
  95     the "SQL::Translator::Producer" namespace (e.g., "MySQL"), a module name
  96     and function combination ("My::Groovy::Producer::transmogrify"), or a
  97     reference to an anonymous subroutine. If a full module name is passed in
  98     (for the purposes of this method, a string containing "::" is considered
  99     to be a module name), it is treated as a package, and a function called
 100     "produce" will be invoked: "$modulename::produce". If $modulename cannot
 101     be loaded, the final portion is stripped off and treated as a function.
 102     In other words, if there is no file named
 103     My/Groovy/Producer/transmogrify.pm, "SQL::Translator" will attempt to
 104     load My/Groovy/Producer.pm and use "transmogrify" as the name of the
 105     function, instead of the default "produce".
 106
 107       my $tr = SQL::Translator->new;
 108
 109       # This will invoke My::Groovy::Producer::produce($tr, $data)
 110       $tr->producer("My::Groovy::Producer");
 111
 112       # This will invoke SQL::Translator::Producer::Sybase::produce($tr, $data)
 113       $tr->producer("Sybase");
 114
 115       # This will invoke My::Groovy::Producer::transmogrify($tr, $data),
 116       # assuming that My::Groovy::Producer::transmogrify is not a module
 117       # on disk.
 118       $tr->producer("My::Groovy::Producer::transmogrify");
 119
 120       # This will invoke the referenced subroutine directly, as
 121       # $subref->($tr, $data);
 122       $tr->producer(\&my_producer);
 123
 124     There is also a method named "producer_type", which is a string
 125     containing the classname to which the above "produce" function belongs.
 126     In the case of anonymous subroutines, this method returns the string
 127     "CODE".
 128
 129     Finally, there is a method named "producer_args", which is both an
 130     accessor and a mutator. Arbitrary data may be stored in name => value
 131     pairs for the producer subroutine to access:
 132
 133       sub My::Random::producer {
 134           my ($tr, $data) = @_;
 135           my $pr_args = $tr->producer_args();
 136
 137           # $pr_args is a hashref.
 138
 139     Extra data passed to the "producer" method is passed to "producer_args":
 140
 141       $tr->producer("xSV", delimiter => ',\s*');
 142
 143       # In SQL::Translator::Producer::xSV:
 144       my $args = $tr->producer_args;
 145       my $delimiter = $args->{'delimiter'}; # value is ,\s*
 146
 147   parser
 148
 149     The "parser" method defines or retrieves a subroutine that will be
 150     called to perform the parsing. The basic idea is the same as that of
 151     "producer" (see above), except the default subroutine name is "parse",
 152     and will be invoked as "$module_name::parse($tr, $data)". Also, the
 153     parser subroutine will be passed a string containing the entirety of the
 154     data to be parsed.
 155
 156       # Invokes SQL::Translator::Parser::MySQL::parse()
 157       $tr->parser("MySQL");
 158
 159       # Invokes My::Groovy::Parser::parse()
 160       $tr->parser("My::Groovy::Parser");
 161
 162       # Invoke an anonymous subroutine directly
 163       $tr->parser(sub {
 164         my $dumper = Data::Dumper->new([ $_[1] ], [ "SQL" ]);
 165         $dumper->Purity(1)->Terse(1)->Deepcopy(1);
 166         return $dumper->Dump;
 167       });
 168
 169     There is also "parser_type" and "parser_args", which perform analogously
 170     to "producer_type" and "producer_args"
 171
 172   show_warnings
 173
 174     Toggles whether to print warnings of name conflicts, identifier
 175     mutations, etc. Probably only generated by producers to let the user
 176     know when something won't translate very smoothly (e.g., MySQL "enum"
 177     fields into Oracle). Accepts a true or false value, returns the current
 178     value.
 179
 180   translate
 181
 182     The "translate" method calls the subroutines referenced by the "parser"
 183     and "producer" data members (described above). It accepts as arguments a
 184     number of things, in key => value format, including (potentially) a
 185     parser and a producer (they are passed directly to the "parser" and
 186     "producer" methods).
 187
 188     Here is how the parameter list to "translate" is parsed:
 189
 190     *   1 argument means it's the data to be parsed; which could be a string
 191         (filename) or a reference to a scalar (a string stored in memory),
 192         or a reference to a hash, which is parsed as being more than one
 193         argument (see next section).
 194
 195           # Parse the file /path/to/datafile
 196           my $output = $tr->translate("/path/to/datafile");
 197
 198           # Parse the data contained in the string $data
 199           my $output = $tr->translate(\$data);
 200
 201     *   More than 1 argument means its a hash of things, and it might be
 202         setting a parser, producer, or datasource (this key is named
 203         "filename" or "file" if it's a file, or "data" for a SCALAR
 204         reference.
 205
 206           # As above, parse /path/to/datafile, but with different producers
 207           for my $prod ("MySQL", "XML", "Sybase") {
 208               print $tr->translate(
 209                         producer => $prod,
 210                         filename => "/path/to/datafile",
 211                     );
 212           }
 213
 214           # The filename hash key could also be:
 215               datasource => \$data,
 216
 217         You get the idea.
 218
 219   filename, data
 220
 221     Using the "filename" method, the filename of the data to be parsed can
 222     be set. This method can be used in conjunction with the "data" method,
 223     below. If both the "filename" and "data" methods are invoked as
 224     mutators, the data set in the "data" method is used.
 225
 226         $tr->filename("/my/data/files/create.sql");
 227
 228     or:
 229
 230         my $create_script = do {
 231             local $/;
 232             open CREATE, "/my/data/files/create.sql" or die $!;
 233             <CREATE>;
 234         };
 235         $tr->data(\$create_script);
 236
 237     "filename" takes a string, which is interpreted as a filename. "data"
 238     takes a reference to a string, which is used as the data to be parsed.
 239     If a filename is set, then that file is opened and read when the
 240     "translate" method is called, as long as the data instance variable is
 241     not set.
 242
 243   trace
 244
 245     Turns on/off the tracing option of Parse::RecDescent.
 246
 247 AUTHORS
 248     Ken Y. Clark, <kclark@cpan.org>, darren chamberlain <darren@cpan.org>,
 249     Chris Mungall <cjm@fruitfly.org>, Allen Day
 250     <allenday@users.sourceforge.net>
 251
 252 COPYRIGHT
 253     This program is free software; you can redistribute it and/or modify it
 254     under the terms of the GNU General Public License as published by the
 255     Free Software Foundation; version 2.
 256
 257     This program is distributed in the hope that it will be useful, but
 258     WITHOUT ANY WARRANTY; without even the implied warranty of
 259     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 260     Public License for more details.
 261
 262     You should have received a copy of the GNU General Public License along
 263     with this program; if not, write to the Free Software Foundation, Inc.,
 264     59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 265
 266 BUGS
 267     Please use http://rt.cpan.org/ for reporting bugs.
 268
 269 SEE ALSO
 270     the perl manpage, the SQL::Translator::Parser manpage, the
 271     SQL::Translator::Producer manpage, the Parse::RecDescent manpage
 272