Expanded on AUTHORS, added dumping of Schema object if debugging, added

[dbsrgits/SQL-Translator.git] / README

                      SQL::Translator README

SQL::Translator is a group of Perl modules that converts
vendor-specific SQL table definitions into other formats, such as
other vendor-specific SQL, ER diagrams, documentation (POD and HTML),
XML, and Class::DBI classes.  The main focus of SQL::Translator is
SQL, but parsers exist for other structured data formats, including
Excel spreadsheets and arbitrarily delimited text files.  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.03, parsers exist for the following:

    Databases:
        MySQL
        Oracle
        PostgreSQL
        Sybase

    Other:
        xSV    : arbitrarily delimited text files
        Excel  : Microsoft Excel spreadsheets
        SqlfXML: SQLFairy's XML format

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

    Other:
        SqlfXML: structure of the schema described in SQLFairy's XML

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.pl
*   sqlt-graph.pl
*   sqlt-dumper.pl
*   sql_translator.cgi
*   sql_translator.pl

All scripts ending in ".pl" 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 the "sql_translator.pl" script 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 "sql" so it will be easier to
identify them on your system.  All the "*.pl" scripts will be
installed in the normal installation process, but you'll have to put
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.

SEE ALSO

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

    http://sqlfairy.sourceforge.net/