README.md

   1 This is the source for **xonstatdb**, the [Xonotic][xonotic] [Statistics database][xonstat].
   2 All code herein is intended for the PostgreSQL database management server.
   3
   4 ----
   5
   6 To build, first create the user that will own all of the objects in the database.
   7 You must run this as an administrator user in your cluster.
   8 See your operating system's guidelines for how this is set up on your system.
   9
  10     create user xonstat with password 'xonstat';
  11
  12    *Note: please change this password*
  13
  14 Or from the commandline:
  15
  16     # su - postgres  (as root)
  17     postgres$ createuser -P xonstat  (this will prompt you for the users password)
  18
  19 Next, create the database itself:
  20
  21     $ psql
  22     postgres=#
  23
  24     CREATE DATABASE xonstatdb
  25       WITH ENCODING='UTF8'
  26         OWNER=xonstat
  27         CONNECTION LIMIT=-1;
  28
  29 If you intend to use the `drop_and_load.shl` script in the scripts folder, you may want to give
  30 the application user superuser within the database. To do that you can use the following command:
  31
  32     postgres=# alter user xonstat with superuser;
  33
  34 When done, exit the psql prompt:
  35
  36     postgres=# \q
  37
  38 Next, as your regular system user, log into the newly created database
  39 using the user account you just created.
  40 Do this from the root directory of your project checkout.
  41
  42     $ psql -U xonstat xonstatdb
  43
  44 You might need to force postgres to not use ident, if you get an error
  45 like *Peer authentication failed for user "xonstat"*:
  46
  47     $ psql -h localhost -U xonstat xonstatdb
  48
  49 Create the schema in which all of the xonstat tables will reside:
  50
  51     xonstatdb=>
  52
  53     CREATE SCHEMA xonstat
  54         AUTHORIZATION xonstat;
  55
  56 Create the plpgsql language, if it doesn't exist:
  57
  58     CREATE LANGUAGE plpgsql;
  59
  60 Now load the initial tables:
  61
  62     \i build/build_full.sql
  63
  64    *Note: You will see a lot of NOTICE messages. This is normal.*
  65
  66 And that's it!
  67
  68 Do note that there are a few maintenance scripts that can be used
  69 once the database begins accumulating data. These can be found in
  70 the scripts subdirectory and are intended to be implemented as cron jobs.
  71 A summary of what they do follows:
  72
  73   update\_elos.sql - will decrease player elo records by one point
  74                     day for every day after 30 days of inactivity
  75                     until they hit the elo "floor" of 100. This
  76                     prevents inactive players from staying on the
  77                     leaderboard/ranks for too long.
  78
  79   update\_ranks.sql - will populate the player\_ranks table each day
  80                      according to the elo values when it is run.
  81
  82   refresh\_$TABLE\_mv.sql - updates the "materialized view" named by $TABLE.
  83
  84   purge\_anticheat\_log.sql - deletes old anticheat data.
  85
  86 There is also a "merge players" function in the functions sub-
  87 directory. This can be used to merge two players together into one
  88 record in the presentation layer of XonStat. It can be run as follows:
  89
  90   select merge\_players(winner\_player\_id, loser\_player\_id);
  91
  92 The "winner" player ID is the account that remains active after the
  93 transaction.
  94
  95 Enjoy!
  96
  97 [xonotic]: http://www.xonotic.org/
  98 [xonstat]: http://stats.xonotic.org/
  99
 100 ----
 101
 102 Project is licensed GPLv3.