<?xml version="1.0"?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->

<document>
 <properties>
  <title>PostgreSQL Howto</title>
  <author email="nissim@nksystems.com">Nissim Karpenstein</author>
 </properties>

<body>

  <section name="PostgreSQL versions">
    <p>
      The generator templates in Torque 3.3 are optimized for
      PostgreSQL 7.3 and later.
      To use an older version of PostgreSQL, do the following:
    </p>

    <p>
      In the generator, locate the template
      templates/sql/base/postgresql/drop.vm
      and replace the line
    </p>

    <source>
DROP TABLE $table.Name CASCADE;</source>

    <p>
      by
    </p>

    <source>
DROP TABLE $table.Name;</source>

  </section>

<section name="Note">

<p>
The following sections of this HOWTO were written some time ago
and were targeted at the version of Torque that was coupled with the
<a href="http://turbine.apache.org/">Turbine</a> application framework.
Contributions towards updating the information below can be submitted to the
<a href="mailto:torque-dev@db.apache.org">Torque Dev mailing list</a>.
</p>

</section>

<section name="PostgreSQL Howto">

<p>
Turbine comes with a default User implementation which utilizes some libraries,
and code that are not 100% compatible with <a href="http://www.postgresql.org">
PostgreSQL</a>. This document will explain  what you need to get the default
Turbine User Implementation running with PostgreSQL. The user management code is
only a small part of Turbine, and the default implementation is easily
replacable. Rather than following the steps in this document, you can always
create your own User implementation which does not require large object support.
</p>

</section>

<section name="JDBC Driver">

<p>
First of all, the TurbineUser class which comes with Turbine uses a hashtable
to store data relevant to the user.  Any data in this hashtable which does
not map to one of the columns in the visitor table is written to a large
object field in the database.  Database actions in the TurbineUserPeer and
BasePeer classes are done through the
<a href="../../releases/torque-3.3/village/index.html">Village API</a>.
The village API uses the ResultSetMetaData returned by your JDBC driver to
determine the types of the columns in a SQL result set.  Unfortunately,
in PostgreSQL large objects are referenced using an OID column (which is a
pointer to the data), and the metadata in the JDBC driver says that columns
of type OID are java.sql.Types.INTEGER.
</p>

<p>
There is also a bug in the released versions of the PostgreSQL which causes
problems when reading and writing Timestamps.  This is fixed in CVS.  So to
run Turbine with PostgreSQL you need to get the latest JDBC driver code from
the PostgreSQL CVS server: :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot
(leave the password blank).  Before compiling the driver though, you must apply
a patch so the metadata says that OID columns are java.sql.Types.VARBINARY, not
java.sql.Types.INTEGER.  <strong>Important: If you need the metadata to report
that OID columns are integers for another application, this patch will break
that app.</strong>  If you've never heard of an OID before, or you only use OID's
to reference large objects, you don't need to worry about it.
</p>

<p>
Another problem is solved in the more recent JDBC drivers.  The test case
JDBCToXMLSchema fails with the driver packaged with at least PostgreSQL
7.1.3 and maybe others.  This problem is fixed in the 7.2dev1.2 version
(build date 2001-11-25).
That and other PostgreSQL JDBC resources can be found here:
<a href="http://jdbc.postgresql.org/download.html">http://jdbc.postgresql.org/download.html</a>
</p>

</section>

<section name="Patch">
<p>
This patch may or may not be necessary. If you are having problems with
the driver, please try it out. You may also wish to try upgrading to a
more recent version of the Postgrest driver and also make sure that you
are using the latest released version of
<a href="../../releases/torque-3.3/village/index.html">Village</a>.
</p>

<source><![CDATA[
/home/projects/pgsql/cvsroot/pgsql/src/interfaces/jdbc/org/postgresql/Field.java,v
retrieving revision 1.1
diff -r1.1 Field.java
147c147
<     "int4","oid",
---
>     "int4",
158a159
>     "oid",
172c173
<     Types.INTEGER,Types.INTEGER,
---
>     Types.INTEGER,
183a185
>     Types.VARBINARY,
]]></source>

<p>
After applying that patch, compile the driver, and you should be ready to go.
One more problem though is that all actions involving large objects in
PostgreSQL require transactions.  There is code in CVS now which automatically
sets up the transaction if necessary, so make sure you're running the recent
snapshots.
</p>

</section>

</body>
</document>
