hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-07 10:04:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove warnings about sqlite in production

Browse Source 
Closes https://github.com/jupyterhub/jupyterhub/issues/5055
This commit is contained in:
Simon Li
2025-08-09 16:14:17 +01:00
parent 83db40b01f
commit df11d83d2c
2 changed files with 13 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/source/explanation/database.md
View File

@@ -108,26 +108,29 @@ Doing so generally involves:
### Default backend: SQLite
The default database backend for JupyterHub is [SQLite](https://sqlite.org).
We have chosen SQLite as JupyterHub's default because it's simple (the 'database' is a single file) and ubiquitous (it is in the Python standard library).
It works very well for testing, small deployments, and workshops.
We have chosen SQLite as JupyterHub's default because it's simple (the 'database' is a single file), ubiquitous (it is in the Python standard library), and it does not require maintaining a separate database server.
For production systems, SQLite has some disadvantages when used with JupyterHub:
The main disadvantage of SQLite is it does not support remote backup tools or replication.
You should backup your database by taking snapshots of the file (`jupyterhub.sqlite`).
- `upgrade-db` may not always 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 (JupyterHub automatically creates a date-stamped backup file when upgrading sqlite)
SQLite is ideal for testing, small deployments, workshops, and production servers where you do not require remote backup or replication.
### Picking your database backend (PostgreSQL, MySQL)
The sqlite documentation provides a helpful page about [when to use SQLite and
where traditional RDBMS may be a better choice](https://sqlite.org/whentouse.html).
### Picking your database backend (PostgreSQL, MySQL)
When running a long term deployment or a production system, we recommend using a full-fledged relational database, such as [PostgreSQL](https://www.postgresql.org) or [MySQL](https://www.mysql.com), that supports the SQL `ALTER TABLE` statement, which is used in some database upgrade steps.
In general, you select your database backend with [](JupyterHub.db_url), and can further configure it (usually not necessary) with [](JupyterHub.db_kwargs).
## Notes and Tips
### Upgrading the JupyterHub database
[Upgrading JupyterHub to a new major release](howto:upgrading-jupyterhub) often requires an upgrade to the database schema.
- `jupyterhub upgrade-db` will execute a schema upgrade. You should backup your database before running this.
- `jupyterhub downgrade-db` may be able to revert a schema upgrade on PostgreSQL and MySQL, but this is not guaranteed to work, and is not supported.
### SQLite
The SQLite database should not be used on NFS. SQLite uses reader/writer locks

11
docs/source/howto/upgrading.md
View File

@@ -107,17 +107,6 @@ jupyterhub upgrade-db
This should find the location of your database, and run the necessary upgrades
for it.
### SQLite database disadvantages
SQLite has some disadvantages when it comes to upgrading JupyterHub. These
are:
- `upgrade-db` may not work, and you may need to delete your database
and start with a fresh one.
- `downgrade-db` **will not** work if you want to rollback to an
earlier version, so backup the `jupyterhub.sqlite` file before
upgrading.
### What happens if I delete my database?
Losing the Hub database is often not a big deal. Information that