Data Storage
MCIdentity can keep its data in five places: SQLite (the default), MySQL, PostgreSQL, MongoDB, or the MCIdentity Central Server. You pick one in the plugin's configuration file.
A single server can run entirely on the zero-configuration SQLite file. A network can share one MySQL, PostgreSQL, or MongoDB database, or point every game server at the central server so none of them touches a database directly.
Choosing a backend
A local file in the plugin's folder. Best for a single server; works out of the box with no setup.
A MySQL or MariaDB server. Best for networks that already run a MySQL-compatible database.
A PostgreSQL server. Best for networks that prefer PostgreSQL.
A MongoDB deployment. Best for document storage or existing MongoDB infrastructure.
The MCIdentity Central Server. Best for whole networks that want one authenticated service to own all identity data.
Each database backend has its own connection section in the configuration file, where you enter the host, port, database name, and login (or, for MongoDB, a connection address). The central server needs only its address, the API token it was started with, and an optional timeout.
How it works
- Every backend offers the plugin exactly the same set of operations, so gameplay behaves identically whichever one is active.
- The three SQL databases share the same logic and differ only in small dialect details. MongoDB keeps each identity as a single document holding its properties and stats.
- The central server backend sends each operation to the central server over the network, authenticated with the configured token, instead of talking to a database.
- Every read and write runs in the background on its own worker threads, so the game never pauses to wait for storage.
- Data that is in use is cached in memory, so most reads never reach the backend at all.
- If a read fails, the plugin falls back to a safe empty answer and logs the problem, so the server keeps running.
- Stat names are checked against a fixed list before they are stored, both by the plugin and, for the central server, by the server as well.
Drivers
The SQLite and MySQL drivers come with SpigotMC, PaperMC, and Folia, and the PostgreSQL and MongoDB drivers are packaged inside the plugin. No backend needs an extra download.
Setup and upgrades
The database backends create everything they need automatically the first time the server starts. The SQLite layout is the same one the central server uses, so a SQLite file can move between a game server and a central server deployment.
Upgrading from 4.0.x: the alias field is added automatically on the first start after upgrading. Nothing is removed and no data is touched; every existing identity simply starts without an alias.
Upgrading from 3.x: runes and cosmetics moved into the standalone MCIdentityRune and MCIdentityCosmetic add-ons, which keep their own data. The first start after upgrading deletes the old rune and cosmetic data from the core plugin's storage. It cannot be recovered and the add-ons do not import it, so back up your database first if you want to keep it.
Upgrading from 2.x: abilities moved into the standalone MCIdentitySkill add-on, where a skill lives on the item itself. The first start after upgrading deletes the old ability data. It cannot be recovered, so back up your database first if you want to keep it.
Identity aliases
A player can give each identity they own a name of its own, called an alias. While that identity is equipped, the alias replaces the player's Minecraft name in chat and in the tab list.
- An alias uses letters and numbers only, up to 32 characters.
- It is unique across the whole server or network, and the check ignores capital letters: once someone holds Alex, nobody else can take alex or ALEX. It is still shown exactly as it was typed.
- The uniqueness check and the save happen together, so two players can never end up with the same alias.
- A player claims an alias once and cannot rename it afterwards, and the base Player identity can never have one. Other plugins and administrative tools can still correct or release a name through the developer API.
- Showing the alias costs nothing extra, because it is read from the session already held in memory.
Data stored
| What | Contents |
|---|---|
| Professions | The shared list of professions that identities belong to. |
| Identities | Each identity's unique ID and its profession. |
| Properties | The optional alias, level, experience, unspent stat points, head texture, and the identity's own inventory and ender chest. |
| Stats | The nine attributes: energy, health, food, strength, defense, wisdom, luck, agility, and resilience. |
| Sessions | Which identity each player is wearing right now, together with the identity item itself. |
| Base identity slots | How many extra base identities each player has unlocked. |
| Audit log | A permanent record of every equip, unequip, death drop, and admin removal. |
The add-ons store their own data separately, always against the identity rather than the player.