Upped version numbers, cleaned up code, fixed my name.

[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.  We also
have 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.10, parsers exist for the following:

    Databases:
        Access
        DB2
        DBI-DB2
        DBI-MySQL
        DBI-Oracle
        DBI-PostgreSQL
        DBI-SQLServer
        DBI-SQLite
        DBI-Sybase
        MySQL
        Oracle
        PostgreSQL
        SQLServer
        SQLite
        Storable
        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:
        DB2
        MySQL
        Oracle
        PostgreSQL
        SQLServer
        SQLite
        Storable
        Sybase
    
    Code Generators:
        ClassDBI     : Class::DBI classes
        Dumper       : create a "mysqldump"-like dumper for database
        DBIx-Class   : see the DBIx::Class distribution

    Documentation:
        Diagram      : quasi-ER diagrams using libgd
        GraphViz     : ER diagrams using GraphViz
        HTML         : HTML documentation of schema
        POD          : Plain Old Documenation of schema
        Latex        : self-explanatory
        DiaUml       : ditto

    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         : command-line interface for text-to-text translations
*   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.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

    $ perl Makefile.PL
    $ make && make test
    $ sudo make install

MANUAL

To read the manual:

    $ perldoc SQL::Translator::Manual

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 included AUTHORS file.