Emmanuel BENOîT
be3106c463
* 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
91 lines
No EOL
3.3 KiB
Text
91 lines
No EOL
3.3 KiB
Text
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. |