Database definition & tests organisation

* The main loader script has been updated to generate the list of files
it needs to load automatically. As a consequence, files that contained
manually-maintained lists of scripts have been removed, and definition
directories have been renamed accordingly.

* PostgreSQL extension loading and configuration has been moved to a
separate script to be loaded automatically in the main transaction.

* Data and function definition scripts that had the -data or -functions
suffix have been renamed (the suffix is unnecessary).

* Unit tests have been reorganised to follow the definition's structure.

* Documentation has been improved

legacyworlds/doc/database.txt

@@ -35,32 +35,52 @@ 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.
+definition.
 
- * 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.
+All SQL files contained in this directory, as well as all sub-directories and
+their contents, are prefixed with some number which serves as an indication of
+the order in which the scripts are to be loaded. Numbering in a directory
+should start with 010 and increase by 10 for each file in the sequence.
+However, when adding new code, it is possible to add new files with
+intermediary values.
 
- 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.
+The parts/ sub-directory contains the following elements:
+ * schema and extension loaders,
+ * the xxx-data/ sub-directory which contains most data structure definitions
+   (types, tables, indexes, constraints and some of the views).
+ * the xxx-functions/ sub-directory which 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 or are used only by functions, as well as type
+   definitions used to pass values between functions or as return values.
+ * the xxx-updates/ sub-directory which 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.
+There are three sub-directories in the tests/ directory. The admin/ directory
+contains tests that require administrative permissions on the database
+(therefore most functionality checks can be found there), while the user/
+sub-directory contains unit tests that must be executed as the standard
+user (for example privileges checks). Finally, the utils/ sub-directory 
+contains scripts used by tests from the admin/ directory to create test
+data.
  
- In order to run the database unit tests, the following steps must be taken:
+In both directories, files are organised in a manner that is parallel to the
+contents of the database creation scripts. For each actual SQL file, a
+sub-directory with the same name (minus the ".sql" extension) can be created,
+each sub-directory containing the test suites for the definitions and
+functions from the corresponding file.
  
- 1) pg_prove must be installed. This can be achieved by running the following
-    command as root:
+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
 
@@ -76,7 +96,8 @@ load other scripts from the sub-directories.
 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'`
+		pg_prove -d $DATABASE -U $USER \
+				`find $DIR/ -type f -name '*.sql' | sort`
 
 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.
@@ -87,5 +108,6 @@ 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. 
+pgTAP, then run all available unit tests: first it will execute tests from the
+admin/ sub-directory, then tests from the user/ sub-directory. A failure will
+cause the build to be aborted.