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.

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 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 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 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.
 
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' | 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.


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: 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.