Updating Evennia

When Evennia is updated to a new version you will usually see it announced in the Discussion forum and in the dev blog. You can also see the changes on github or through one of our other linked pages.

If you installed with pip

If you followed the normal install instructions, here’s what you do to upgrade:

1. Read the changelog to see what changed and if it means you need to make any changes to your game code.

2. If you use a virtualenv, make sure it’s active.

3. cd to your game dir (e.g. mygame)

4. evennia stop

5. pip install --upgrade evennia

6. cd to your game dir

7. evennia migrate - this is safe to do, but can be skipped unless the release announcement/changelog specifically tells you to do so. Ignore any warnings about running makemigrations, it should not be done!

8. evennia start

If you installed with git

This applies if you followed the git-install instructions. Before Evennia 1.0, this was the only way to install Evennia.

At any time, development is either happening in the main branch (latest stable) or develop (experimental). Which one is active and ‘latest’ at a given time depends - after a release, main will see most updates, close to a new release, develop will usually be the fastest changing.

1. Read the changelog to see what changed and if it means you need to make any changes to your game code.

2. If you use a virtualenv, make sure it’s active.

3. cd to your game dir (e.g. mygame)

4. evennia stop

5. cd to the evennia repo folder you cloned during the git installation process.

6. git pull

7. pip install --upgrade -e . (remember the . at the end!)

8. cd back to your game dir

9. evennia migrate - this is safe to do, but can be skipped unless the release announcement/changelog specifically tells you to do so. Ignore any warnings about running makemigrations, it should not be done!

10. evennia start

If you installed with docker

If you followed the docker installation instructions, you need to pull the latest docker image for the branch you want:

• docker pull evennia/evennia (main branch)

• docker pull evennia/evennia:develop (experimental develop branch)

Then restart your containers.

Resetting your database

Should you ever want to start over completely from scratch, there is no need to re-download Evennia. You just need to clear your database.

First:

1. cd to your game dir (e.g. mygame)

2. evennia stop

SQLite3 (default)

Hint

Make a copy of the evennia.db3 file once you created your superuser. When you want to reset (and as long as you haven’t had to run any new migrations), you can just stop evennia and copy that file back over evennia.db3. That way you don’t have to run the same migrations and create the superuser every time!

1. delete the file mygame/server/evennia.db3

2. evennia migrate

3. evennia start

PostgreSQL

1. evennia dbshell (opens the psql client interface)

   psql> DROP DATABASE evennia;
   psql> exit
   

2. You should now follow the PostgreSQL install instructions to create a new evennia database.

3. evennia migrate

4. evennia start

MySQL/MariaDB

1. evennia dbshell (opens the mysql client interface)

   mysql> DROP DATABASE evennia;
   mysql> exit
   

2. You should now follow the MySQL install instructions to create a new evennia database.

3. evennia migrate

4. evennia start

What are database migrations?

If and when an Evennia update modifies the database schema (that is, the under-the-hood details as to how data is stored in the database), you must update your existing database correspondingly to match the change. If you don’t, the updated Evennia will complain that it cannot read the database properly. Whereas schema changes should become more and more rare as Evennia matures, it may still happen from time to time.

One way one could handle this is to apply the changes manually to your database using the database’s command line. This often means adding/removing new tables or fields as well as possibly convert existing data to match what the new Evennia version expects. It should be quite obvious that this quickly becomes cumbersome and error-prone. If your database doesn’t contain anything critical yet it’s probably easiest to simply reset it and start over rather than to bother converting.

Enter migrations. Migrations keeps track of changes in the database schema and applies them automatically for you. Basically, whenever the schema changes we distribute small files called “migrations” with the source. Those tell the system exactly how to implement the change so you don’t have to do so manually. When a migration has been added we will tell you so on Evennia’s mailing lists and in commit messages - you then just run evennia migrate to be up-to-date again.