Upgrading JupyterHub and its databases

Definitions

db type: sqlite, postgres, mysql, others??? db fields: individual fields in a database table

Basic use cases

Simple upgrade - no database fields changed; no db type change
Field changes - database fields added, deleted or changed by a new JHub release/functionality; no db type change

More complex use cases

Field changes - database fields added, deleted or changed by user; no db type change
db type change (i.e. sqlite to postgres) - fields may or may not change; db type does change

Process

Remind admins to back up Hub databases
Possibly remind admins to make sure single user notebook data is saved/backed up
Admin notify users (if desired) of planned upgrade

Multi-step upgrade vs all at once??

Migrate database type (Hub at same release level) user-initiated
Add/change/delete fields (Hub at same release level) user-initiated
Add/change/delete files (Hub initiated - in prep for JHub release upgrade)
Upgrade Hub to 0.7 after
Upgrade/changes to: CHP, authenticators, spawners

Tools

Using alembic for database migrations

Alembic (docs for alembic) provides change management scripts for a relational database, using SQLAlchemy as the underlying engine. This section will explain how alembic is used to upgrade JupyterHub's database.

Looking at the JupyterHub source code from the root of the repo, we see:

jupyterhub/alembic.ini This file contains configuration information for the database. It is used when the alembic command is run to access the location of the change management scripts.
jupyterhub/alembic This directory contains the migration environment used by alembic. The env.py file in this directory is a Python file that is run when alembic does a database migration and may be customized if necessary.

scripts
db tools

2.1 KiB Raw Blame History