Storage Backend

Storage Backend & Data Management

BeaconPlus is designed to handle thousands of beacons and millions of player data points. However, the performance and reliability of your server depend heavily on selecting and configuring the right storage backend. This document provides a proactive, deep-technical guide to managing your data.

---

1. Storage Backend Categories

BeaconPlus uses two separate storage definitions to allow for hybrid setups:

1. Player Storage: Stores discovered effects, activation states, and individual settings.
2. Beacon Storage: Stores the physical location, power level, tiers, and modes of every beacon in the world.

---

2. Exhaustive Backend Breakdown

WORLD (Beacon Storage Only)

• Mechanics: Data is saved as small JSON/YAML files directly within the world folder of your Minecraft server.
• Proactive Note: This is the "Gold Standard" for single-server setups. If you delete a world folder or move it to a different server, the beacon data stays with it naturally.
• Limitation: Cannot be synchronized across a network (Bungeecord/Velocity).

FILE (Flat-file / YAML)

• Mechanics: Saves all data into the plugins/BeaconPlus/Players or plugins/BeaconPlus/Beacons directories.
• Performance: Excellent for small to medium servers (up to 50 active players).
• Caution: As the number of files grows into the thousands, your OS file system might experience slowness when listing directories.

SQLITE (Local Database - Beacon Storage Only)

• Mechanics: Uses a single .db file (a relational database) to store all beacon data.
• Performance: Highly efficient. SQL allows the plugin to "search" for beacons much faster than reading individual flat files.
• Use Case: The best middle ground for large single servers that want performance without the complexity of a remote MySQL server.

MYSQL (Remote Database)

• Mechanics: Uses a dedicated database server. Required for cross-server synchronization.
• Scaling: Theoretically infinite. Can handle networks with thousands of simultaneous players.
• Requirement: Requires a stable connection. If the database goes down, your beacons stop working.

---

3. Transition Protocols (Safe Migration)

Changing your Storage.Type or Storage.Beacon Storage Type does not automatically move your data. Follow this protocol to avoid data loss:

1. Stop the Server: Never change storage settings while the server is running.
2. Full Backup: Copy your entire BeaconPlus plugin folder to a safe location.
3. Manual Migration:
   • Currently, there is no built-in "Migration Tool" for moving between SQL and FILE backends.
   • If you are moving from FILE to MYSQL, you must manually import the data or start fresh.
   • Proactive Advice: Only change backends during a server "Season Reset" unless you have high-level technical expertise in SQL data importing.
4. Update Config: Change the values in storage.yml.
5. Restart & Verify: Monitor the console for "Uses [TYPE] data storage" confirmation messages.

---

4. Scaling Recommendations

Server Type	Player Count	Recommended Player Storage	Recommended Beacon Storage
Private / SMP	1 - 20	FILE	WORLD
Large Hub / Factions	50 - 200	FILE or MYSQL	SQLITE
Massive Network	500+	MYSQL	MYSQL

---

5. MySQL Troubleshooting Guide

If the plugin prints "Failed to connect to MySQL server", check these proactively:

1. Host/Port: Ensure the address is correct and the port (standard 3306) is open in your firewall.
2. Wait Timeout: Some hosts kill inactive SQL connections. Set Auto Reconnect: true in storage.yml.
3. SSL: If your DB host requires SSL (or forbids it), toggle Use SSL.
4. Permissions: The DB user must have CREATE, SELECT, INSERT, UPDATE, and DELETE permissions on the table.

---

6. Proactive Precautions

• Avoid VOID: Setting any storage to VOID means data is only kept in RAM while the server is up. ALL PROGRESS WILL BE LOST ON RESTART. Only use this for temporary "Event" servers.
• Cleanup: If you use FILE storage and have many players who haven't logged in for years, you can safely delete their .yml files from the Players directory to save disk space.
• Hikari Pool: For SQL backends, BeaconPlus uses HikariCP for high-performance connection pooling. Do not try to manually adjust these settings in the Java code unless you are an experienced developer.