mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-07 18:14:10 +00:00
99 lines
3.4 KiB
Markdown
99 lines
3.4 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. Whether you
|
|
are using the default SQLite database or an RDBMS, such as PostgreSQL or
|
|
MySQL, the process follows similar steps.
|
|
|
|
**Before upgrading a JupyterHub deployment**, it's critical to backup your data
|
|
and configurations before shutting down the JupyterHub process and server.
|
|
|
|
## Note about upgrading the SQLite database
|
|
|
|
When used in production systems, SQLite has some disadvantages when it
|
|
comes to upgrading JupyterHub. These are:
|
|
|
|
- `upgrade-db` may not work, and you may need to start with a fresh database
|
|
- `downgrade-db` **will not** work if you want to rollback to an earlier
|
|
version, so backup the `jupyterhub.sqlite` file before upgrading
|
|
|
|
## The upgrade process
|
|
|
|
Five fundamental process steps are needed when upgrading JupyterHub and its
|
|
database:
|
|
|
|
1. Backup JupyterHub database
|
|
2. Backup JupyterHub configuration file
|
|
3. Shutdown the Hub
|
|
4. Upgrade JupyterHub
|
|
5. 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 JupyterHub database
|
|
|
|
To prevent unintended loss of data or configuration information, you should
|
|
back up the JupyterHub database (the default SQLite database or a RDBMS
|
|
database using PostgreSQL, MySQL, or others supported by SQLAlchemy):
|
|
|
|
- If using the default SQLite database, back up the `jupyterhub.sqlite`
|
|
database.
|
|
- If using an RDBMS database such as PostgreSQL, MySQL, or other supported by
|
|
SQLAlchemy, back up the JupyterHub database.
|
|
|
|
Losing the Hub database is often not a big deal. Information that resides only
|
|
in the Hub database includes:
|
|
|
|
- active login tokens (user cookies, service tokens)
|
|
- users added via GitHub UI, instead of config files
|
|
- info about running servers
|
|
|
|
If the following conditions are true, you should be fine clearing the Hub
|
|
database and starting over:
|
|
|
|
- users specified in config file
|
|
- user servers are stopped during upgrade
|
|
- don't mind causing users to login again after upgrade
|
|
|
|
### Backup JupyterHub configuration file
|
|
|
|
Additionally, backing up your configuration file, `jupyterhub_config.py`, to
|
|
a secure location.
|
|
|
|
### Shutdown JupyterHub
|
|
|
|
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`
|
|
|
|
### Upgrade JupyterHub databases
|
|
|
|
To run the upgrade process for JupyterHub databases, enter:
|
|
|
|
```
|
|
jupyterhub upgrade-db
|
|
```
|
|
|
|
## Upgrade checklist
|
|
|
|
1. Backup JupyterHub database:
|
|
- `jupyterhub.sqlite` when using the default sqlite database
|
|
- Your JupyterHub database when using an RDBMS
|
|
2. Backup JupyterHub configuration file: `jupyterhub_config.py`
|
|
3. Shutdown the Hub
|
|
4. Upgrade JupyterHub
|
|
- `pip install -U jupyterhub` when using `pip`
|
|
- `conda upgrade jupyterhub` when using `conda`
|
|
5. Upgrade the database using run `jupyterhub upgrade-db`
|