[DS-297] Move PostgreSQL-specific SQL into etc/postgres for greater clarity

git-svn-id: http://scm.dspace.org/svn/repo/dspace/trunk@4427 9c30dcfa-912a-0410-8fc2-9e0234be79fd

dspace/CHANGES

@@ -58,6 +58,7 @@
  - [DS-333] Adjust SWORD ingest crosswalk to store bibliographic citation
 
 (Larry Stone)
+ - [DS-297] Move PostgreSQL-specific SQL into etc/postgres for greater clarity
  - [DS-338] Disable cache advice (Expires header) on Bitstream download that requires authorization (XMLUI)
  - [DS-285] Respond to If-Modified-Since request header in XMLUI, also provide Last-Modified response header for Bitstreams
  - [DS-288] Configurable option to hide metadata fields in public UIs and OAI-PMH

dspace/docs/docbook/directories.xml

@@ -92,8 +92,12 @@
                     <para><literal>docs/</literal>  - DSpace system documentation. The technical documentation for functionality, installation, configuration, etc.</para>
                   </listitem>
                   <listitem>
-                    <para><literal>etc/</literal>  - Miscelleanous configuration need to install DSpace that isn&apos;t really to do with system configuration - e.g. the PostgreSQL database schema, and a couple of configuration files that are used during the build process but not by the live system. Also contains the deployment descriptors (<literal>web.xml</literal> files) for the Web UI and OAI-PMH support <literal>.war</literal> files. </para>
+                    <para><literal>etc/</literal>  -
+This directory contains administrative files needed for the install process and by developers, mostly database initialization and upgrade scripts. Any <literal>.xml</literal> files in <literal>etc/</literal> are common to all supported database systems.</para>
                     <itemizedlist>
+                      <listitem>
+                        <para><literal>postgres/</literal>  - Versions of the database schema and updater SQL scripts for PostgreSQL.</para>
+                      </listitem>
                       <listitem>
                         <para><literal>oracle/</literal>  - Versions of the database schema and updater SQL scripts for Oracle.</para>
                       </listitem>
@@ -417,5 +421,3 @@ Manakin)"/>Contents of XMLUI Web Application (aka Manakin)</title>
       </table>
     </section>
   </chapter>
-
-

dspace/docs/docbook/install.xml

@@ -309,14 +309,6 @@ db.url    = jdbc:oracle:thin:@//host:port/dspace
 db.driver = oracle.jdbc.OracleDriver
 </screen>
               </listitem>
-              <listitem>
-                <para> Go to <literal>[dspace-source]/dspace/etc/oracle</literal> and copy the contents to their parent directory, overwriting the versions in the parent:</para>
-                <screen>
-cd [dspace-source]/dspace/etc/oracle
-cp * ..
-</screen>
-                <para>You now have Oracle-specific <literal>.sql</literal> files in your <literal>etc</literal> directory, and your dspace.cfg is modified to point to your Oracle database.</para>
-              </listitem>
             </orderedlist>
             </listitem>
           <listitem>

dspace/docs/docbook/storage.xml

@@ -13,8 +13,18 @@
       <para>Most of the functionality that DSpace uses can be offered by any standard SQL database that supports transactions. Presently, the browse indices use some features specific to <ulink url="http://www.postgresql.org/">PostgreSQL</ulink> and <ulink url="http://www.oracle.com/database/">Oracle</ulink>, so some modification to the code would be needed before DSpace would function fully with an alternative database back-end.</para>
       <para>The <literal>org.dspace.storage.rdbms</literal> package provides access to an SQL database in a somewhat simpler form than using JDBC directly. The main class is <literal>DatabaseManager</literal>, which executes SQL queries and returns <literal>TableRow</literal> or <literal>TableRowIterator</literal> objects. The <literal>InitializeDatabase</literal> class is used to load SQL into the database via JDBC, for example to set up the schema.</para>
       <para>All calls to the <literal>Database Manager</literal> require a <link linkend="docbook-business.html-core">DSpace <literal>Context</literal> object</link>. Example use of the database manager API is given in the <literal>org.dspace.storage.rdbms</literal> package Javadoc.</para>
-      <para>The database schema used by DSpace (for PostgreSQL) is stored in <literal>[dspace-source]/dspace/etc/database_schema.sql</literal> in the source distribution. It is stored in the form of SQL that can be fed straight into the DBMS to construct the database. The schema SQL file also directly creates two e-person groups in the database that are required for the system to function properly.</para>
+
-      <para>Also in <literal>[dspace-source]/dspace/etc</literal> are various SQL files called <literal>database_schema_1x_1y</literal>. These contain the necessary SQL commands to update a live DSpace database from version 1.<literal>x</literal> to 1.<literal>y</literal>. Note that this might not be the only part of an upgrade process: see <link linkend="docbook-update.html">Updating a DSpace Installation</link> for details.</para>
+      <para>The database schema used by DSpace is created by SQL statements stored in a directory specific to each supported RDBMS platform:
+        <itemizedlist>
+          <listitem>
+            <para>PostgreSQL schemas are in <literal>[dspace-source]/dspace/etc/postgres/</literal></para>
+          </listitem>
+          <listitem>
+            <para>Oracle schemas are in <literal>[dspace-source]/dspace/etc/oracle/</literal></para>
+          </listitem>
+        </itemizedlist>
+      The SQL (DDL) statements to create the tables for the current release, starting with an empty database, aer in <literal>database_schema.sql</literal>. The schema SQL file also creates the two required e-person groups (<literal>Anonymous</literal> and <literal>Administrator</literal>) that are required for the system to function properly.</para>
+      <para>Also in <literal>[dspace-source]/dspace/etc/[database]</literal> are various SQL files called <literal>database_schema_1x_1y</literal>. These contain the necessary SQL commands to update a live DSpace database from version 1.<literal>x</literal> to 1.<literal>y</literal>. Note that this might not be the only part of an upgrade process: see <link linkend="docbook-update.html">Updating a DSpace Installation</link> for details.</para>
       <para>The DSpace database code uses an SQL function <literal>getnextid</literal> to assign primary keys to newly created rows. This SQL function must be safe to use if several JVMs are accessing the database at once; for example, the Web UI might be creating new rows in the database at the same time as the batch item importer. The PostgreSQL-specific implementation of the method uses <literal>SEQUENCES</literal> for each table in order to create new IDs. If an alternative database backend were to be used, the implementation of <literal>getnextid</literal> could be updated to operate with that specific DBMS.</para>
       <para>The <literal>etc</literal> directory in the source distribution contains two further SQL files. <literal>clean-database.sql</literal> contains the SQL necessary to completely clean out the database, so use with caution! The Ant target <literal>clean_database</literal> can be used to execute this. <literal>update-sequences.sql</literal> contains SQL to reset the primary key generation sequences to appropriate values. You&apos;d need to do this if, for example, you&apos;re restoring a backup database dump which creates rows with specific primary keys already defined. In such a case, the sequences would allocate primary keys that were already used.</para>
       <para>Versions of the <literal>*.sql*</literal> files for Oracle are stored in <literal>[dspace-source]/dspace/etc/oracle</literal>. These need to be copied over their PostgreSQL counterparts in <literal>[dspace-source]/dspace/etc</literal> prior to installation.</para>
@@ -251,5 +261,3 @@ srb.parentdir.1 = mysrbdspaceassetstore
       </section>
     </section>
   </chapter>
-
-

dspace/docs/docbook/update.xml

@@ -648,7 +648,7 @@ cp [dspace-source]/dspace/config/emails/registration_notify
             <listitem>
               <para> For PostgreSQL </para>
               <para>
-                <literal>psql -U [dspace-user] -f [dspace-source]/dspace/etc/database_schema_14-15.sql [database-name]</literal>
+                <literal>psql -U [dspace-user] -f [dspace-source]/dspace/etc/postgres/database_schema_14-15.sql [database-name]</literal>
               </para>
             </listitem>
             <listitem>
@@ -1570,5 +1570,3 @@ JAVA_OPTS=&quot;-Xmx512M -Xms64M -Dfile.encoding=UTF-8&quot;
       </orderedlist>
     </section>
   </chapter>
-
-