Skip to content

Worlds & Databases ​

Utopia Server Panel uses a per-save SQLite database isolation architecture so switching worlds on the same server never mixes user accounts, permissions, monitoring history, or map caches.

Per-Save Data Directory ​

When the server starts and loads a world, the panel creates a utopia_server_panel directory inside the active save folder to store all data belonging to that world:

  • utopia_server_panel/utopia_server_panel.db: Standalone SQLite database holding users, roles, permissions, settings, bindings, monitoring logs, waypoints, whitelist applications, and chat history.
  • utopia_server_panel/map_cache/: Disk tile cache directory generated by the Web Minimap.

The panel also maintains a lightweight save index at config/utopia_server_panel_worlds.json recording each world's path, world name, Minecraft version, and last active timestamp so administrators can inspect database sizes and row counts in the Worlds & Databases tab.

Automatic Legacy Database Migration ​

If a legacy database exists at config/utopia_server_panel.db and the active world does not yet have its own database, the panel migrates it automatically on startup:

  1. Copies config/utopia_server_panel.db and any WAL or SHM sidecar files into utopia_server_panel/utopia_server_panel.db inside the active world directory.
  2. Renames the original config/utopia_server_panel.db to config/utopia_server_panel.db.migrated as a backup.
  3. Cleans up temporary WAL/SHM files and initializes the per-save database.

Maintenance Tips ​

  • Backing up your world folder automatically backs up the panel database and map cache together.
  • To keep database size under control, adjust monitorRetentionDays in Panel Settings and chatRetentionDays in In-Game Integration.
  • To reduce disk usage from map tiles, lower mapCacheMaxMb or clear the map cache from the minimap management controls.