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