lwb6/legacyworlds/doc/database.txt

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.