Database setup

Always run python tools/dbtool.py update before starting any server process. Running the server against an uninitialized or out-of-date database will cause errors.

Install MariaDB

Ubuntu / Debian
Docker
Windows

sudo apt-get update && sudo apt-get install -y mariadb-server
sudo systemctl start mariadb
sudo systemctl enable mariadb

If you are using Docker Compose, MariaDB is managed for you. See Docker deployment.To run MariaDB as a standalone container:

docker run -d \
  --name mariadb \
  -e MARIADB_ROOT_PASSWORD=root \
  -e MARIADB_DATABASE=xidb \
  -e MARIADB_USER=xiadmin \
  -e MARIADB_PASSWORD=password \
  -p 3306:3306 \
  mariadb:lts \
  --character-set-server=utf8mb4 \
  --collation-server=utf8mb4_general_ci

Create the database and user

Connect to MariaDB as root and create the database:

CREATE DATABASE xidb CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER 'xiadmin'@'%' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON xidb.* TO 'xiadmin'@'%';
FLUSH PRIVILEGES;

The default database name (xidb), user (xiadmin), and host (127.0.0.1) match settings/default/network.lua. You can change them, but must update the settings file or environment variables to match.

Configure database credentials

The server reads credentials from settings/network.lua (or environment variables). The defaults are:

xi.settings.network =
{
    SQL_HOST     = '127.0.0.1',
    SQL_PORT     = 3306,
    SQL_LOGIN    = 'root',
    SQL_PASSWORD = 'root',
    SQL_DATABASE = 'xidb',
    -- ...
}

To override without editing the file, set environment variables:

export XI_NETWORK_SQL_HOST=127.0.0.1
export XI_NETWORK_SQL_PORT=3306
export XI_NETWORK_SQL_DATABASE=xidb
export XI_NETWORK_SQL_LOGIN=xiadmin
export XI_NETWORK_SQL_PASSWORD=password

Install Python dependencies for dbtool

dbtool.py manages all database imports and migrations. Install its dependencies:

pip install -r tools/requirements.txt

Or, using a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install -r tools/requirements.txt

Run the initial database import

Import all SQL files and run any pending migrations:

python tools/dbtool.py update

On first run against an empty database, dbtool.py will:

Detect that the database is empty.
Import all sql/*.sql files in sorted order (ending with triggers.sql).
Check and run all pending migrations from tools/migrations/.
Write the current git commit hash to tools/config.yaml as db_ver.

A successful run ends with:

Finished importing!
No migrations required.

(Optional) Configure dbtool via config.yaml

tools/config.yaml controls dbtool behavior between runs. It is created automatically on first run. Key options:

- mysql_bin: ''          # Path to MySQL/MariaDB bin directory (auto-detected if on PATH)
- auto_backup: 0         # 0=off, 1=full auto-backup, 2=lite auto-backup on update
- auto_update_client: true  # Automatically update CLIENT_VER in settings/login.lua
- db_ver: 'abcd1234'     # Git hash of the last successful import (enables express updates)

In Docker, mount this file to preserve state across container restarts:

volumes:
  - ./config.yaml:/server/tools/config.yaml

dbtool.py command reference

Command	Description
`python tools/dbtool.py`	Interactive TUI menu
`python tools/dbtool.py update`	Express update: import only changed SQL files and run migrations
`python tools/dbtool.py update full`	Full update: re-import all SQL files and run migrations
`python tools/dbtool.py migrate`	Check and run pending migrations only (no SQL import)
`python tools/dbtool.py backup`	Create a full database backup in `sql/backups/`
`python tools/dbtool.py backup lite`	Back up only player-data tables
`python tools/dbtool.py dump`	Dump all non-player tables back to `.sql` files
`python tools/dbtool.py dump <table>`	Dump a single table to its `.sql` file

Introduction

Installation

Database setup

dbtool.py command reference

​dbtool.py command reference

dbtool.py command reference