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 four 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).

The dirty/ sub-directory contains tests which require actual changes to
be committed to the database; while unit tests are not supposed to be executed
on a loaded database anyway, these specific tests could cause problems with
other tests, and therefore run on copies of the database.

Finally, the utils/ sub-directory contains scripts used by tests from both the
admin/ and dirty/ sub-directories to create test data.
 
In both the admin/ and user/ 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.

The dirty/ sub-directory contains a script which can be used to run the
"dirty" test suites, as well as one directory per test suite. Each test suite
directory may contain a "prepare.sql" script, to be executed before the actual
tests, as well as a "run-test.sql" which runs the actual tests.
 
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 basic 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. The "dirty" test
suite can be launched by running:

		TEST_DATABASE=$DATABASE ./run-dirty-tests.sh

Note that the dirty tests will fail unless all existing connections to the
main database are closed.


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, and finally the
dirty tests. A failure will cause the build to be aborted.