⬆️Upgrading to 3.0

What changes when you move from 2.x to 3.0, and what to do before you do.

Before you start

Take a backup of your database. 3.0 migrates the schema on first start, and the migration cannot be undone.

If you run several servers on one database, upgrade them together. The message format between servers changed, and a 2.x node cannot read what a 3.0 node sends.

What happens on first start

The schema is brought up to date automatically and each step is recorded, so restarting is free and a failed step leaves the database on the last complete version rather than half-way through.

The step that matters is ranks. A member's rank used to be stored as a number — the position of a fixed five-value list — and is now stored as the key of a rank defined in ranks.yml. Existing members are mapped across on the spot:

Stored before	Becomes
0	master
1	co-leader
2	moderator
3	member
4	recruit

The old column is kept and still written for one release, so a rollback to 2.x reads its members back. Members on a rank you added after upgrading come back as recruits there, which is the closest thing 2.x can express.

ranks.yml and levels.yml are written with defaults that reproduce 2.x behaviour exactly, so nothing changes for your players until you edit them.

What changed for players

• Banning now removes the member. In 2.x /guild ban recorded the ban but left the player in the guild on the server the command was run on, so on a single server it only blocked future invites.

• Guilds level up. Experience used to sit there; it now buys levels on a curve, and levels can be worth something. See progression.md.

• Invites expire after five minutes by default. Set invites.expire-after-seconds: 0 for the old behaviour.

• Guild tag colours survive a restart. They were saved but never read back, so every guild came out of a restart white.

What changed for developers

GuildManager still exists and still works; it is deprecated and stays for the whole 3.x line. What it returns changed in one place: GuildMember#rank() is now a Rank rather than the GuildRank enum, because a rank is no longer one of five fixed things.

GuildRank is still there, deprecated, and still names the five default rank keys.

See for-developers.md for the services and events that replace the manager.