updated turnkey regression testing schema. added comments RE what role
[dbsrgits/SQL-Translator.git] / README
1                       SQL::Translator README
2
3 SQL::Translator is a group of Perl modules that manipulate structure
4 data definitions (mostly database schemas) in interesting ways, such
5 as converting among different dialects of CREATE syntax (e.g.,
6 MySQL-to-Oracle), visualizations of schemas (pseudo-ER diagrams
7 GraphViz or GD), automatic code generation (using Class::DBI),
8 converting non-RDBMS files to SQL schemas (xSV text files, Excel
9 spreadsheets), serializing parsed schemas (via Storable, YAML and
10 XML), creating documentation (HTML and POD), and more.  New to version
11 0.03 is the ability to talk directly to a database through DBI to
12 query for the structures of several databases.
13
14 Through the separation of the code into parsers and producers with an
15 object model in between, it's possible to combine any parser with any
16 producer, to plug in custom parsers or producers, or to manipulate the
17 parsed data via the built-in object model.  Presently only the
18 definition parts of SQL are handled (CREATE, ALTER), not the
19 manipulation of data (INSERT, UPDATE, DELETE).
20
21 As of version 0.05, parsers exist for the following:
22
23     Databases:
24         MySQL
25         Oracle
26         PostgreSQL
27         SQLite
28         Sybase
29
30         DBI-MySQL
31         DBI-PostgreSQL
32         DBI-SQLite
33         DBI-Sybase
34
35     Other:
36         xSV          : arbitrarily delimited text files
37         Excel        : Microsoft Excel spreadsheets
38         XML-SQLFairy : SQLFairy's XML format
39         YAML/Storable: Serialized schema objects
40
41 And the following producers exist:
42
43     Databases:
44         MySQL
45         Oracle
46         PostgreSQL
47         SQLite
48         Sybase
49     
50     Code Generators:
51         ClassDBI     : Class::DBI classes
52
53     Documentation:
54         Diagram      : quasi-ER diagrams using libgd
55         GraphViz     : ER diagrams using GraphViz
56         HTML         : HTML documentation of schema
57         POD          : Plain Old Documenation of schema
58
59     Serialization:
60         Storable     : using Perl's Storable module
61         YAML         : YAML format
62         XML-SQLFairy : structure of the schema described in SQLFairy's XML
63
64     Other:
65         TTSchema     : to any text format via Template Toolkit
66
67 Included in this distribution are a few scripts designed to be user
68 interfaces for the actual SQL::Translator modules.  In the "bin"
69 directory, you will find:
70
71 *   sqlt-diagram: interface to Diagram producer
72 *   sqlt-diff   : diff two schemas to generate schema mutation file 
73 *   sqlt-graph  : interface to GraphViz producer
74 *   sqlt-dumper : create a data dumper script from a schema
75 *   sqlt        : command-line interface for text-to-text translations
76 *   sqlt.cgi    : CGI interface for all SQLFairy functions
77
78 All scripts not ending in ".cgi" are meant to be run from the command
79 line with various switches to control the input and output of the
80 scripts, while the ".cgi" script is a web-form frontend.  The script
81 you'll probably find most useful is "sqlt" which is meant to be the
82 main interface for translating from text-to-text.  The graphic
83 producers, however, have many extra switches, so there are scripts
84 specific for each of the the GraphViz and ER-diagram producers.  All
85 scripts start with "sqlt" so it will be easier to identify them on
86 your system.  All the non-CGI scripts will be installed in a system
87 path when you "make install," but you'll have to manually place the
88 CGI script into your web CGI directory to use it.
89
90 If you're more interested in using the SQL::Translator modules
91 directly, then you might be more interested to examine some of the
92 test scripts in the "t" directory.  The test suite is relatively
93 thorough and should give you an idea of how to parse a file and
94 manipulate the SQL::Translator::Schema objects.
95
96 INSTALLATION
97
98 The regular method:
99
100     $ perl Makefile.PL
101     $ make
102     $ make test
103     $ su
104     # make install
105
106 COPYRIGHT
107
108 This program is free software; you can redistribute it and/or modify it
109 under the terms of the GNU General Public License as published by the
110 Free Software Foundation; version 2.
111
112 This program is distributed in the hope that it will be useful, but
113 WITHOUT ANY WARRANTY; without even the implied warranty of
114 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
115 Public License for more details.
116
117 You should have received a copy of the GNU General Public License along
118 with this program; if not, write to the Free Software Foundation, Inc.,
119 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
120
121 BUGS
122
123 Please use http://rt.cpan.org/ for reporting bugs.
124
125 PRAISE
126
127 If you find this module useful, please use 
128 "http://cpanratings.perl.org/rate/?distribution=SQL-Translator" to rate it.
129
130 SEE ALSO
131
132 Check out the SQLFairy homepage at Sourceforge for more information,
133 mailing lists, etc.:
134
135     http://sqlfairy.sourceforge.net/
136
137 AUTHORS
138
139 See the include AUTHORS file.