Skip to main content
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.
1

Install MariaDB

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

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.
3

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
4

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
5

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:
  1. Detect that the database is empty.
  2. Import all sql/*.sql files in sorted order (ending with triggers.sql).
  3. Check and run all pending migrations from tools/migrations/.
  4. Write the current git commit hash to tools/config.yaml as db_ver.
A successful run ends with:
Finished importing!
No migrations required.
6

(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

CommandDescription
python tools/dbtool.pyInteractive TUI menu
python tools/dbtool.py updateExpress update: import only changed SQL files and run migrations
python tools/dbtool.py update fullFull update: re-import all SQL files and run migrations
python tools/dbtool.py migrateCheck and run pending migrations only (no SQL import)
python tools/dbtool.py backupCreate a full database backup in sql/backups/
python tools/dbtool.py backup liteBack up only player-data tables
python tools/dbtool.py dumpDump all non-player tables back to .sql files
python tools/dbtool.py dump <table>Dump a single table to its .sql file

Build docs developers (and LLMs) love

Get started for freeTalk to us