583 lines
15 KiB
HTML
583 lines
15 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>GT::SQL - A database independent perl interface</title>
|
|
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
|
|
|
|
<style type="text/css">
|
|
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
|
|
/* $MVD$:fontset("Arial","Arial") */
|
|
/* $MVD$:fontset("Arial Black","Arial Black") */
|
|
/* $MVD$:fontset("Algerian","Algerian") */
|
|
|
|
|
|
body {
|
|
background-color: white;
|
|
font-family: Verdana, Arial, sans-serif;
|
|
font-size: small;
|
|
color: black;
|
|
}
|
|
|
|
|
|
p {
|
|
background-color : white;
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
h1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
background-color : white;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
h2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : medium;
|
|
font-weight : bold;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h3 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : maroon;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h5 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h6 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
ul {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
ol {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
li {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
th {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
td {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dd {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dt {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
code {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
pre {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-H1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : 14.0pt;
|
|
background-color : transparent;
|
|
background-image : none;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
.mvd-H2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 12.0pt;
|
|
color : blue;
|
|
}
|
|
|
|
|
|
p.indent {
|
|
font-family : "Verdana, Arial, sans-serif";
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-indent {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
pre.programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE-programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE {
|
|
font-size : 9.0pt;
|
|
}
|
|
|
|
|
|
p.note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-H4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : normal;
|
|
font-size : 9.0pt;
|
|
color : black;
|
|
margin-left : 6.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 10.0pt;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-BODY {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
p.indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
|
|
|
|
.mvd-P-indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
<p><a name="__index__"></a></p>
|
|
<!-- INDEX BEGIN -->
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#creating_a_new_gt__sql_object">Creating a new GT::SQL object</a></li>
|
|
<li><a href="#getting_connected">Getting Connected</a></li>
|
|
<li><a href="#supported_objects">Supported Objects</a></li>
|
|
<li><a href="#table_prefixes">Table Prefixes</a></li>
|
|
<li><a href="#query_stack">Query Stack</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
<li><a href="#version">VERSION</a></li>
|
|
</ul>
|
|
<!-- INDEX END -->
|
|
|
|
<hr />
|
|
<p>
|
|
</p>
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>GT::SQL - A database independent perl interface</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
use GT::SQL;</pre>
|
|
<pre>
|
|
my $db = GT::SQL->new('/path/to/def');
|
|
my $table = $db->table('Links');
|
|
my $editor = $db->editor('Links');
|
|
my $creator = $db->creator('NewTable');
|
|
my $html = $db->html('Links', new CGI);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>GT::SQL is a perl database abstraction layer to relational databases, providing
|
|
a native Perl interface rather than a query-based interface.</p>
|
|
<p>A GT::SQL object provides the interface to the entire database by providing
|
|
objects that are able to perform the work needed.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="creating_a_new_gt__sql_object">Creating a new GT::SQL object</a></h2>
|
|
<p>There are two ways to get a GT::SQL object. First, you can simply provide the
|
|
path to the def file directory where GT::SQL stores all it's information:</p>
|
|
<pre>
|
|
$db = GT::SQL->new('/path/to/def');</pre>
|
|
<p>or you can pass in a hash or hash ref and specify options:</p>
|
|
<pre>
|
|
$db = GT::SQL->new(
|
|
def_path => '/path/to/def',
|
|
cache => 1,
|
|
debug => 1,
|
|
subclass => 1
|
|
);</pre>
|
|
<p>You must specify def_path. Setting <code>cache => 1</code> will result in all table
|
|
and relation objects being cached, which provides a performance improvement in
|
|
any situation where the same table or relation is used again.</p>
|
|
<p>Specifying <code>subclass => 0</code> or <code>subclass => 1</code> will enable or disable
|
|
the ability to subclass any of the objects GT::SQL creates. The default
|
|
value is <code>1</code>, and should not normally be changed.</p>
|
|
<p>GT::SQL has significant amounts of debugging output that can be enabled by
|
|
specifying a value of <code>1</code> to the <code>debug</code> option. Larger values can be
|
|
specified for more detailed debugging output, however a level of <code>1</code> is almost
|
|
always more than sufficient. The accepted values are as follows:</p>
|
|
<dl>
|
|
<dt><strong><a name="item_level_0">Level 0</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
This is the default, no debugging information is printed to stderr. All errors
|
|
can be obtained in $GT::SQL::error.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_level_1">Level 1</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
All queries will be displayed to stderr. This is the recommended value if
|
|
query debugging is desired.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_level_2">Level 2</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Same as level 1, but includes more detailed information. Also, when calling
|
|
query_stack you get a stack trace on what generated each query. Not
|
|
recommended except when working directly on GT::SQL.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_level_3">Level 3</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Very detailed debug logs including creation and destruction of objects.
|
|
query_stack generates a javascript page with query, stack trace, and data dump
|
|
of arguments, but can be extremely large. Not recommended except for debugging
|
|
GT::SQL internals.
|
|
</dd>
|
|
<p></p></dl>
|
|
<p><strong>Pass in a def path</strong></p>
|
|
<pre>
|
|
$obj = GT::SQL->new('/path/to/def/directory');</pre>
|
|
<p>This method of calling new is also supported, however has the drawback that
|
|
none of the above options can be provided.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="getting_connected">Getting Connected</a></h2>
|
|
<p>GT::SQL loads the database connection info from database.def which is located
|
|
in the defs directory.</p>
|
|
<p>To create this file, you call <code>set_connect()</code> as follows:</p>
|
|
<pre>
|
|
$obj->set_connect({
|
|
driver => 'mysql',
|
|
host => 'localhost',
|
|
port => 3243,
|
|
database => 'databasename',
|
|
login => 'username',
|
|
password => 'password',
|
|
PREFIX => 'prefix_'
|
|
});</pre>
|
|
<p>This will test the database information, and save it to the def file. All
|
|
future connections will automatically use this connection information.</p>
|
|
<p>Not all of the arguments in this hash are necessary; some have reasonable
|
|
defaults for the connection.</p>
|
|
<dl>
|
|
<dt><strong><a name="item_driver">driver</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
This needs to be the driver that is being used for the connection. The default
|
|
for this is <code>mysql</code>. Driver names are case-insensitive. Available drivers
|
|
are:
|
|
</dd>
|
|
<dl>
|
|
<dt><strong><a name="item_mysql">MySQL</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Driver for MySQL databases. Requires that the DBD::mysql module be installed.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_pg">Pg</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Driver for PostgreSQL databases. Requires that the DBD::Pg module be
|
|
installed.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_mssql">MSSQL</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Driver for MSSQL 7.0 and above. Requires that the DBD::ODBC module be
|
|
installed.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_oracle">Oracle</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Driver for Oracle 8 and above. Requires the DBD::Oracle module.
|
|
</dd>
|
|
<p></p></dl>
|
|
<dt><strong><a name="item_host">host</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
This will specify the host to connect to. The default, which is acceptable for
|
|
most installations, is <code>localhost</code>.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_port">port</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
This is the port on which to connect to the SQL server. The default for this
|
|
is to allow the DBI driver to choose the default, which is almost always the
|
|
appropriate choice.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_database">database</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
This is the database name to use on the SQL server. This is required to
|
|
connect. For MSSQL, this is the <em>Data Source</em> name.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_prefix">PREFIX</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
This specifies a prefix to use for table names. See the <a href="#table_prefixes">Table Prefixes</a>
|
|
section below for more information.
|
|
</dd>
|
|
<p></p></dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="supported_objects">Supported Objects</a></h2>
|
|
<p>The following objects can be obtained through a GT::SQL object:</p>
|
|
<dl>
|
|
<dt><strong><a name="item_table_2frelation">Table/Relation</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
To get a table or relation object for working with SQL tables, you should call:
|
|
</dd>
|
|
<dd>
|
|
<pre>
|
|
my $table = $db->table('table_name');</pre>
|
|
</dd>
|
|
<dd>
|
|
<p>or for a table join:</p>
|
|
</dd>
|
|
<dd>
|
|
<pre>
|
|
my $relation = $db->table('table_name', 'other_table');</pre>
|
|
</dd>
|
|
<dd>
|
|
<p>See <a href="glist.cgi?do=admin_gtdoc&topic=/GT/SQL/Table.html">the GT::SQL::Table manpage</a> for more information on how to use a table object.</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_creator">Creator</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
To create new tables, you need to use a creator. You can get one by calling:
|
|
</dd>
|
|
<dd>
|
|
<pre>
|
|
my $creator = $db->creator('new_table');</pre>
|
|
</dd>
|
|
<dd>
|
|
<p>where <code>new_table</code> is the name of the table you wish to create. See
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/SQL/Creator.html">the GT::SQL::Creator manpage</a> for more information on how to use a creator object.</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_editor">Editor</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
To edit existing tables (i.e. add/drop/change columns, add/drop indexes, etc.)
|
|
you need an editor object:
|
|
</dd>
|
|
<dd>
|
|
<pre>
|
|
my $editor = $db->editor('existing_table');</pre>
|
|
</dd>
|
|
<dd>
|
|
<p>where <code>existing_table</code> is the name of the table you wish the modify. See
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/SQL/Editor.html">the GT::SQL::Editor manpage</a> for more information on how to use an editor object.</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_html">HTML</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
To get an html object for generating forms and html output, you need to pass in
|
|
the table/relation object you want to work with, and a cgi object:
|
|
</dd>
|
|
<dd>
|
|
<pre>
|
|
my $html = $db->html($table, $cgi);</pre>
|
|
</dd>
|
|
<dd>
|
|
<p>The html object uses information found in CGI to set values, etc. See
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/SQL/Display/HTML.html">the GT::SQL::Display::HTML manpage</a> for more information on how to use a html object.</p>
|
|
</dd>
|
|
<p></p></dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="table_prefixes">Table Prefixes</a></h2>
|
|
<p>GT::SQL supports the concept of table prefixes. If you specify a prefix using
|
|
the accessor, it is saved in the database.def file and will be used in all
|
|
future calls to table(), <code>editor()</code> and creator().</p>
|
|
<p>To set a prefix:</p>
|
|
<pre>
|
|
$db->prefix("foo");</pre>
|
|
<p>to get the current prefix:</p>
|
|
<pre>
|
|
my $prefix = $db->prefix;</pre>
|
|
<p>What this will do is transparently prepend <code>foo</code> to the beginning of every
|
|
table name. This means anywhere you access the table <code>bar</code>, the actual table
|
|
stored on the SQL server will be <code>foobar</code>. Note that the prefix should <strong>not</strong>
|
|
be included when getting table/creator/editor/etc. objects - the prefix is
|
|
handled completely transparently to all public GT::SQL functionality.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="query_stack">Query Stack</a></h2>
|
|
<p>To display a list of all raw SQL queries sent to the database you can use:</p>
|
|
<pre>
|
|
my @queries = $db->query_stack;</pre>
|
|
<p>or to have them formatted try</p>
|
|
<pre>
|
|
print $db->query_stack_disp;</pre>
|
|
<p>which will join them up, displayed nicely. This is also available as a class
|
|
method:</p>
|
|
<pre>
|
|
print GT::SQL->query_stack_disp;</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/SQL/Table.html">the GT::SQL::Table manpage</a></p>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/SQL/Editor.html">the GT::SQL::Editor manpage</a></p>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/SQL/Creator.html">the GT::SQL::Creator manpage</a></p>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/SQL/Types.html">the GT::SQL::Types manpage</a></p>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/SQL/Admin.html">the GT::SQL::Admin manpage</a></p>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/SQL/Display/HTML.html">the GT::SQL::Display::HTML manpage</a></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved.
|
|
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="version">VERSION</a></h1>
|
|
<p>Revision: $Id: SQL.pm,v 1.111 2005/04/14 20:22:37 alex Exp $</p>
|
|
|
|
</body>
|
|
|
|
</html>
|