# Upgrading JupyterHub and its database

From time to time, you may wish to upgrade JupyterHub to take advantage
of new releases. Much of this process is automated using scripts,
such as those generated by alembic for database upgrades. Before upgrading a
JupyterHub deployment, it's critical to backup your data and configurations
before shutting down the JupyterHub process and server.

## The upgrade process

Four fundamental process steps are needed when upgrading JupyterHub and its
database:

1. Backup your Hub's data and configurations
2. Shutdown the Hub
3. Upgrade JupyterHub
4. Upgrade the database using run `jupyterhub upgrade-db`

Let's take a closer look at each step in the upgrade process.

### Backup

To prevent unintended loss of data or configuration information, you should
back up the Jupyterhub database (the default sqlite database or a custom
database using Postgres or MySQL). Additionally, backing up your configuration
file, `jupyterhub_config.py`, to a secure location.

### Shutdown

Prior to shutting down JupyterHub, you should notify the Hub users of the
scheduled downtime. This gives users the opportunity to finish any outstanding
work in process.

Next, shutdown the JupyterHub service.

### Upgrade JupyterHub

Follow directions that correspond to your package manager, `pip` or `conda`,
for the new JupyterHub release. These directions will guide you to the
specific command. In general, `pip install -U jupyterhub` or
`conda upgrade jupyterhub`

### Run `jupyterhub upgrade-db`

To run the upgrade process for JupyterHub databases, enter:

```
jupyterhub upgrade-db
```