Database backends #

Luanti uses a database system for certain world data where the backend that stores the data can be switched out depending on the use cases needed. This page lists all databases and the backends that can be used with them.

Databases #

There are four databases that store data for each world:

• Map
• Players
• Authentication
• Mod Storage

Map database #

The map database stores mapblock data. The backend is set using the backend setting in world.mt.

To migrate it to a different backend, the --migrate argument is used.

Player database #

The player database stores information about in-world data for players. The backend is set using the player_backend setting in world.mt.

To migrate it to a different backend, the --migrate-players argument is used.

Authentication database #

The authentication database stores player credentials as well as privileges. The backend is set using the auth_backend setting in world.mt.

To migrate it to a different backend, the --migrate-auth argument is used.

Mod storage database #

The mod storage database stores per-world data that is available to mods as a key-value data store. The backend is set using the mod_storage_backend setting in world.mt.

To migrate it to a different backend, the --migrate-mod-storage argument is used.

Migrating backends #

The Luanti server is able to migrate backends when running from the command-line, meaning either luantiserver for headless server builds or luanti --server for client builds, and luanti.exe --server for Windows.

To migrate a database to a new backend, use the corresponding argument mentioned above for the database, the backend name you want to migrate to (should be lowercase), and specify the world either using --world or --worldname. For an example of migrating the players database of a world to a new backend:

luantiserver --migrate-players <name of new backend> --world <path to your world directory>

Backend comparison table #

This table is a rough estimate of what you may expect from each database backend in terms of speed, reliability and compatibility. It is elaborated on in each section, and your mileage may vary from what is listed here.

* The PostgreSQL mod storage backend is very slow, and its implementation is only intended for those who want to store everything in PostgreSQL nonetheless.

** The Compatibility with builds column is only relevant if you want to distribute the worlds.

More information about specific backends #

SQLite3 #

SQLite3 is the default backend for all Luanti backends, it is always supported by engine builds and is therefore also the standard database format that is used to distribute worlds. It is an embedded database that works out of the box without configuration or a separate database server, making it perfect for singleplayer worlds and small servers.

SQLite as a database has very high reliability and decent performance out of the box, but the performance of the SQLite databases can be further tuned beyond what Luanti does by default. See SQLite performance tuning for some advice on how to do so.

LevelDB #

LevelDB is an embedded key-value data store that can offer better speeds compared to SQLite. The persistent database is also compressed with Snappy compression leading to smaller filesizes.

LevelDB support is enabled in the official Windows builds and most Linux builds.

Redis #

Redis is an in-memory key-value datastore that can be used both as a cache and for persistent data storage. Luanti needs to be compiled with support for it and uses the libhiredis client library to communicate with the Redis server. To set up a Redis server see Installing Redis.

As of March 2024 Redis switched to a non-free license for future versions. Forks of the final free Redis version, such as Redict and Valkey, may serve as a compatible drop-in replacement for Luanti’s Redis support.

Extra world.mt settings for Redis #

• redis_address: The IP or hostname of the redis server.
• redis_port: The port of the redis server. (Optional, default is 6379)
• redis_hash: Hash where the MapBlocks are stored in, if you want multiple worlds in one redis instance this needs to be different for each world. If you don’t need that you can use e.g. IGNORED.

PostgreSQL #

PostgreSQL is an excellent alternative to SQLite for larger Luanti servers. It runs as a separate database server from the Luanti server, can more efficiently manage very large map databases, live database backups are easier to make with pg_dump, and data can be accessed by other programs to e.g. interface a website in front of your database for server players to use.

It is recommended to use PostgreSQL 9.5+ to provide UPSERT functionality. To improve PostgreSQL’s performance with Luanti servers please also configure postgresql.conf with a minimum shared_buffer of 512MB, with a maximum of 50% of your server’s available RAM.

Extra world.mt settings for PostgreSQL #

• pgsql_connection: PostgreSQL connection string for the map database.
• pgsql_player_connection: PostgreSQL connection string for the player database.
• pgsql_auth_connection: PostgreSQL connection string for the auth database.
• pgsql_mod_storage_connection: PostgreSQL connection string for mod storage database.

The connection strings all follow the same format for providing database credentials:

host=<db_host> user=<db_user> password=<db_password> dbname=<db_name>

MariaDB (WIP) #

A WIP MariaDB database backend was implemented in #13266, but was abandoned before it could be merged. The addition of a MariaDB backend is approved by the core developers and the pull request may be adopted by someone who is interested in it being available in upstream.

MariaDB allows about the same capabilities as PostgreSQL and has the same qualities as it, running as a separate database server.

To use the MariaDB database backend, the MariaDB C++ connector is required which usually is not part of the MariaDB package. You can find the source code for it here.

Dummy #

A dummy database backend, which stores all data in RAM without saving it to disk. This means that as soon the server shuts down, all data will be lost. And when you re-join, things such as the map will be re-generated from scratch. However all data will stay persistent in memory while the server is running, compared to a blackhole database.

This backend is useful for games and servers which don’t need a persistent map, such as Capture the Flag. It can also be useful for development when testing map generation capabilities. Games can configure whether new worlds should be created with the dummy backend for the map database using the map_persistent value in game.conf.

Files (Deprecated) #

A legacy backend for player and authentication data storing it in a flat file database. It’s slow, unreliable and clunky. Use of this backend is discouraged now and it’s possible this backend will be removed in the future.

For mod storage, Files uses the legacy JSON-based file storage method as opposed to a regular database system. It is slower, will keep the entire mod storage data in memory and does not support storing binary data.

Luanti will throw warnings when a server is run with the Files backend for a database, and it is recommended to migrate any worlds that use it to SQLite or another database backend.

References #

LevelDB reliability issues:

• Avoiding LevelDB in Minetest for now
• Issues · google/leveldb · GitHub
• Unrecoverable corruption in Chromium
• Corruption in syncthing
• Corruption after power loss
• Corruption in Ethereum
• LevelDB reliability?
• Does LevelDB still corrupt data?