updated turnkey regression testing schema. added comments RE what role

[dbsrgits/SQL-Translator.git] / README

                      SQL::Translator README

SQL::Translator is a group of Perl modules that manipulate structure
data definitions (mostly database schemas) in interesting ways, such
as converting among different dialects of CREATE syntax (e.g.,
MySQL-to-Oracle), visualizations of schemas (pseudo-ER diagrams
GraphViz or GD), automatic code generation (using Class::DBI),
converting non-RDBMS files to SQL schemas (xSV text files, Excel
spreadsheets), serializing parsed schemas (via Storable, YAML and
XML), creating documentation (HTML and POD), and more.  New to version
0.03 is the ability to talk directly to a database through DBI to
query for the structures of several databases.

Through the separation of the code into parsers and producers with an
object model in between, it's possible to combine any parser with any
producer, to plug in custom parsers or producers, or to manipulate the
parsed data via the built-in object model.  Presently only the
definition parts of SQL are handled (CREATE, ALTER), not the
manipulation of data (INSERT, UPDATE, DELETE).

As of version 0.05, parsers exist for the following:

    Databases:
        MySQL
        Oracle
        PostgreSQL
        SQLite
        Sybase

        DBI-MySQL
        DBI-PostgreSQL
        DBI-SQLite
        DBI-Sybase

    Other:
        xSV          : arbitrarily delimited text files
        Excel        : Microsoft Excel spreadsheets
        XML-SQLFairy : SQLFairy's XML format
        YAML/Storable: Serialized schema objects

And the following producers exist:

    Databases:
        MySQL
        Oracle
        PostgreSQL
        SQLite
        Sybase
    
    Code Generators:
        ClassDBI     : Class::DBI classes

    Documentation:
        Diagram      : quasi-ER diagrams using libgd
        GraphViz     : ER diagrams using GraphViz
        HTML         : HTML documentation of schema
        POD          : Plain Old Documenation of schema

    Serialization:
        Storable     : using Perl's Storable module
        YAML         : YAML format
        XML-SQLFairy : structure of the schema described in SQLFairy's XML

    Other:
        TTSchema     : to any text format via Template Toolkit

Included in this distribution are a few scripts designed to be user
interfaces for the actual SQL::Translator modules.  In the "bin"
directory, you will find:

*   sqlt-diagram: interface to Diagram producer
*   sqlt-diff   : diff two schemas to generate schema mutation file 
*   sqlt-graph  : interface to GraphViz producer
*   sqlt-dumper : create a data dumper script from a schema
*   sqlt        : command-line interface for text-to-text translations
*   sqlt.cgi    : CGI interface for all SQLFairy functions

All scripts not ending in ".cgi" are meant to be run from the command
line with various switches to control the input and output of the
scripts, while the ".cgi" script is a web-form frontend.  The script
you'll probably find most useful is "sqlt" which is meant to be the
main interface for translating from text-to-text.  The graphic
producers, however, have many extra switches, so there are scripts
specific for each of the the GraphViz and ER-diagram producers.  All
scripts start with "sqlt" so it will be easier to identify them on
your system.  All the non-CGI scripts will be installed in a system
path when you "make install," but you'll have to manually place the
CGI script into your web CGI directory to use it.

If you're more interested in using the SQL::Translator modules
directly, then you might be more interested to examine some of the
test scripts in the "t" directory.  The test suite is relatively
thorough and should give you an idea of how to parse a file and
manipulate the SQL::Translator::Schema objects.

INSTALLATION

The regular method:

    $ perl Makefile.PL
    $ make
    $ make test
    $ su
    # make install

COPYRIGHT

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; version 2.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

BUGS

Please use http://rt.cpan.org/ for reporting bugs.

PRAISE

If you find this module useful, please use 
"http://cpanratings.perl.org/rate/?distribution=SQL-Translator" to rate it.

SEE ALSO

Check out the SQLFairy homepage at Sourceforge for more information,
mailing lists, etc.:

    http://sqlfairy.sourceforge.net/

AUTHORS

See the include AUTHORS file.