mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-15 14:03:02 +00:00
60 lines
2.0 KiB
Markdown
60 lines
2.0 KiB
Markdown
# 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 as well as some
|
|
additional information about JupyterHub databases.
|
|
|
|
### 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
|
|
```
|
|
|
|
## A note about JupyterHub databases
|
|
|
|
The default database for JupyterHub is a sqlite database. sqlite is useful for
|
|
testing, small deployments, and workshops.
|
|
|
|
When running a long term deployment or a production system, we recommend using
|
|
a database that supports ALTER_TABLE, such as Postgres or MySQL, as it will
|
|
simplify future upgrades that may change database fields.
|