> For the complete documentation index, see [llms.txt](https://docs.ohalee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ohalee.com/products/ultimateguilds/upgrading.md).

# 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

{% hint style="danger" %}
Take a backup of your database. 3.0 migrates the schema on first start, and the migration cannot be undone.
{% endhint %}

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:

<table><thead><tr><th width="180">Stored before</th><th>Becomes</th></tr></thead><tbody><tr><td>0</td><td>master</td></tr><tr><td>1</td><td>co-leader</td></tr><tr><td>2</td><td>moderator</td></tr><tr><td>3</td><td>member</td></tr><tr><td>4</td><td>recruit</td></tr></tbody></table>

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](/products/ultimateguilds/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](/products/ultimateguilds/for-developers.md) for the services and events that replace the manager.