# Upgrading

Here are some points to take into account while performing Pootle upgrades.

## Checklist

Before upgrading Pootle to a newer version, make sure to go through this checklist.

- Familiarize yourself with important changes in Pootle over the versions.

- If you want to change databases, which might be needed when upgrading from Pootle 1.x to Pootle 2.x, or from Pootle 2.0.x to 2.1.x, then have a look at the database migration page first, although some of the issues on this page could still be relevant.

- Check the installation instructions for the newer version, and ensure that you have all the dependencies for the newer version.

- Always make backups of all your translation files (your whole `PODIRECTORY`) and your custom settings file. You can synchronize all your translation files with the database using the sync_stores command before you make your backups.

- Make a backup of your complete database using the appropriate dump command for your database system. For example mysqldump for MySQL, or pg_dump for PostgreSQL.

- If you are upgrading from a version of Pootle that uses localsettings.py then you want to make sure your configuration file is read when Pootle starts. For more information, read about customizing settings.

- You might want to look for any new available settings in the new version that you might want to configure.

- After a successful upgrade, consider clearing your cache. For users of memcached it is enough to restart memcached. For users of the default database cache, you can drop the `pootlecache` table and recreate it with:

      $ pootle createcachetable pootlecache

- Finally run the collectstatic and assets build commands to update the static assets:

      $ pootle collectstatic --clear --noinput
      $ pootle assets build

## Performing the Database Upgrade

Changed in version 2.5.1.

Once you have the new code configured to in your server using the correct settings file, you will be ready to run the database schema and data upgrade procedure.

Since the database upgrade procedures have been growing in complexity in the last releases it was necessary to provide a simple way to upgrade Pootle using a single command. The old procedure is still available, mostly for debugging failing upgrades, but the new procedure is now the preferred one.

### Simplified database upgrade

Warning

Always make database backups before running any upgrades.

This is now the preferred way to upgrade the database.

The procedure is easy, just run:

    $ pootle setup

### Step by step database upgrade

Warning

Always make database backups before running any upgrades.

Note

Use this procedure only if the Simplified database upgrade procedure doesn’t work for you.

The step by step database upgrade procedure lets you control the upgrade process and tweak it. This is useful for debugging purposes.

Note

If you are upgrading from a Pootle version older than 2.5.0, you will need an extra step at the beginning (before running `syncdb --noinput`):

    $ pootle updatedb

The updatedb command upgrades the database schema to the state of Pootle 2.5.0. This is necessary due to the changes made to the database schema migration mechanisms after the 2.5.0 release.

In the first step, the syncdb command will create any missing database tables that don’t require any migrations:

    $ pootle syncdb --noinput

For this specific version (Pootle 2.5.1), and due to Pootle’s transitioning to South, you will need to run a fake migration action in order to let South know which is your current database schema. You can execute the fake migration by running the following commands:

    $ pootle migrate pootle_app --fake 0001
    $ pootle migrate pootle_language --fake 0001
    $ pootle migrate pootle_notifications --fake 0001
    $ pootle migrate pootle_profile --fake 0001
    $ pootle migrate pootle_project --fake 0001
    $ pootle migrate pootle_statistics --fake 0001
    $ pootle migrate pootle_store --fake 0001
    $ pootle migrate pootle_translationproject --fake 0001

Note

If you are upgrading from Pootle 2.5.0 you also have to run:

    $ pootle migrate staticpages --fake 0001

The next step will perform any pending schema migrations. You can read more about the migrate command in South’s documentation.

    $ pootle migrate

Lastly, the upgrade command will perform any extra operations needed by Pootle to finish the upgrade and will record the current code build versions for Pootle and the Translate Toolkit. Before running this command please check if you are interested on running it using any of its available flags.

    $ pootle upgrade

## Custom Changes

If you made any changes to Pootle code, templates or styling, you will want to ensure that your upgraded Pootle contains those changes. How hard that is will depend entirely on the details of these changes.

Changes made to the base template are likely to work fine, but changes to details will need individual inspection to see if they can apply cleanly or have to be reimplemented on the new version of Pootle.

Since Pootle 2.5 customization of style sheets and templates have become much easier to seperate from the standard code. If you are migrating to Pootle 2.5+ then use this opportunity to move your code to the correct customization locations.