Database

This article documents a Zandronum-specific ACS feature which may not be supported by ZDoom and its other child ports.

Zandronum has database support, allowing you to persist data across server restarts.

Note: You need to have port 10666 forwarded to test this online.

Database Functions

Data retrieval and saving

Function	Parameters	Return	Description
GetDBEntry	string namespace, string key	int value	Retrieve a numeric value out of the database.
SetDBEntry	string namespace, string key, int value	void	Set a database row to a specific numeric value.
GetDBEntryString	string namespace, string key	string value	Retrieve a string value out of the database.
SetDBEntryString	string namespace, string key, string value	void	Set a database row to a specific string value.
IncrementDBEntry	string namespace, string key, int value	void	Increment a database row by a specific number.

Reading and writing data to a database is done through an easy-to-use namespace/key/value system. If you put data into the database with a specific namespace and key, you can retrieve that same data by supplying the same namespace and key later.

Namespaces are intended to be roughly analogous to "tables" in other databases, used to split up different sets of data by concern. Namespaces can also be iterated through and sorted.

Iteration and Sorting

Function	Parameters	Return	Description
GetDBEntryRank	string namespace, string key, bool order	int position	Sort a namespace by value and return the position of the given key in that namespace.
GetDBEntries	string namespace	resource results	Return a resource that contains a pointer to all rows in a namespace.
SortDBEntries	string namespace, int limit, int offset, bool order	resource results	Return a resource that contains a pointer to rows in the namespace sorted by value.
CountDBResults	resource results	int count	Count the number of rows a resource contains.
GetDBResultKeyString	resource results, int row	string key	Returns the key at the specific row of a resource.
GetDBResultValueString	resource results, int row	string value	Returns the value at the specific row of a resource as a string.
GetDBResultValue	resource results, int row	int value	Returns the value at the specific row of a resource as an integer.
FreeDBResults	resource results	void	Free a resource from memory.

Most of these functions deal with a resource. A resource is simply a number that points to results of a database query. The queries that Zandronum allows you to make is either retrieving all rows in a namespace at once, or retrieving a limited subset of them in a sorted fashion. Once you have a query result as a resource, you then use functions to figure out what exactly that result contains.

Transactions

Function	Parameters	Return	Description
BeginDBTransaction	void	void	Begin a database transaction.
EndDBTransaction	void	void	Commit the database transaction.

A transaction prevents functions that normally write to the database from writing immediately. Instead, they are kept in memory until you end the transaction, at which point it writes everything at once. If you need to write lots of rows to the database, writing them all at once in a transaction is much faster than writing them one by one. Transactions are also guaranteed to be atomic, which means that if Zandronum crashes during the transaction, either everything in a transaction is written to the database or nothing gets written - the database will never be left in a state where only half the rows were written.

A word of warning

Using any ACS database function stops the entire gamesim while it runs the database query. This is normally not much of an issue, but if you start to see performance issues with your modification, looking at how many database queries you're running is a good place to start. If your database queries are causing performance issues, try batching your queries up and running them all at once with a transaction.

Remote Database support

Zandronum does not support connecting to a remote database server over a network. Due to limitations of ACS, database functions lock up the entire game simulation until a result is found - such a scheme would be unworkable over a something as fickle and with as much latency as the Internet.

However, if you know a little bit of non-ACS programming or scripting, you can connect to the on-disk database with any language that supports SQLite3 and do whatever you want with it, including sending it someplace else over a network. If this sounds like fun, but you have no programming experience aside from ACS, this author recommends Python since it works on Windows, Linux and OSX and comes with sqlite3 support out of the box.

Examples

This article lists no examples, please add one.

See also

Databases, accounts, and you. Part 1: basic tutorial.