Database management changes

* Added in-base logging through a foreign data wrapper, which is only
possible using PostgreSQL 9.1
* Renamed database-related configuration files to indicate that they are
samples, and added the "real" names to the Git ignore list. Server
distribution modified accordingly.
* Removed PL/PgSQL registration (it was only necessary on 8.4)
* Added pgTAP SQL definitions and a script which will (hopefully) be
executed by the build system after the main Java build in order to
execute database unit tests. The script supports both admin- and user-
level testing. I also added a few tests to make sure the testing framework
actually runs them.
* Added documentation about the database definitions structure

legacyworlds/doc/TODO.txt

@@ -12,19 +12,14 @@ PROJECT:
 
   
 SERVER & DATABASE:
-  
-  ! Migrate to PostgreSQL 9.1
-		-> add logging to some of the bigger stored procedures through an
-			external connection 
 
   ! Add some form of database version control to allow easier updates
-		-> once migrated to Pg9.1, there are some interesting extensions that
-			may be satisfactory
-			
+		-> existing options were investigated, they are unsatisfactory
+
   * Replace all single-precision reals with double precision reals
 
   * Add a tool to initialise the database
-  
+
   * I18N loader: improve text file loading (use relative paths)
 
   * Replace current authentication information (pair of hashes) with a
@@ -41,6 +36,6 @@ GENERAL:
 	-> that would be "everywhere"
 	
   * Write unit tests
-	  ? Check out PostgreSQL extensions to test stored procedures
-	  * Write unit tests for new code
+	  * Write unit tests for all new Java code
+	  * Write unit tests for all new SQL code
 	  ? add more tests if possible	

legacyworlds/doc/database.txt

@@ -0,0 +1,91 @@
+Database structure and development
+===================================
+
+The database used by the Legacy Worlds server can be found in the db-structure
+directory of the legacyworlds-server-data package.
+
+
+Database configuration
+-----------------------
+
+The configuration used by the various SQL scripts must be placed in the
+db-config.txt file, at the root of the directory. This file is ignored by Git,
+which allows each developer to set up her or his own copy of the database
+without hassle. A sample is included in the repository in the
+db-config.sample.txt file.
+
+The configuration file contains a few fields, which are defined using a simple
+"<key>=<value>" syntax (warning: there should be no spaces before or after the
+'=' sign).
+
+The following fields must be defined:
+
+* admin - the name of the administrative user,
+* db - the name of the database,
+* user - the name of the user through which the server connects to the
+database,
+* password - the password used by the server to authenticate when accessing
+the database.
+
+
+Code structure
+---------------
+
+The root directory includes a "database.sql" script, which can be launched in
+psql to create the database and associated user.
+
+The parts/ sub-directory contains the various elements of the database's
+definition. It contains a few scripts, which will initialise the schemas and
+load other scripts from the sub-directories.
+
+ * parts/data/ contains all data structure definitions (types, tables,
+   indexes, constraints and some of the views).
+ * parts/functions/ contains all general function definitions; this includes
+   both functions that are called internally and functions which are called
+   by the server. It also includes view definitions that depend on functions.
+ * parts/updates/ contains all functions that implement the game's updates.
+
+ The tests/ sub-directory contains the SQL source code for the pgTAP testing
+ framework as well as the tests themselves. See below for more information.
+ 
+ 
+ Unit tests
+ ----------
+ 
+ There may be up to two sub-directories in the tests/ directory. The user/
+ sub-directory would contain unit tests that must be executed as the standard
+ user, while the admin/ directory would contain tests that required
+ administrative permissions on the database.
+ 
+ In order to run the database unit tests, the following steps must be taken:
+ 
+ 1) pg_prove must be installed. This can be achieved by running the following
+    command as root:
+ 
+ 		 cpan TAP::Parser::SourceHandler::pgTAP
+
+2) It must be possible to log on to the database through the local socket as
+   both the administrative and the standard user, without password.
+
+3) The database itself must be loaded using the aforementioned database.sql
+   script.
+
+4) The tests/pgtap.sql script must be loaded into the database as the
+   administrative user.
+
+At this point, it becomes possible to launch the test suites by issuing a
+command similar to:
+
+		pg_prove -d $DATABASE -U $USER `find $DIR/ -type f -name '*.sql'`
+
+where $DATABASE is the name of the database, $USER the name of the user that
+will execute the tests and $DIR being either admin or user.
+
+
+Build system
+-------------
+
+The build system will attempt to create the database using the scripts. It will
+stop at the first unsuccessful command. On success, it will proceed to loading
+pgTAP, then run all available unit tests. A failure will cause the build to be
+aborted.