Configure Databases for JupyterHub

By default, JupyterHub uses an SQLite database. For production environments, it is recommended to use a more robust database like MySQL or PostgreSQL. Below are the steps to configure each database.

Default Database (SQLite)

If no database configuration is provided, JupyterHub defaults to SQLite. No additional setup is required.

MySQL Configuration

Install MySQL (if not already installed): Install MySQL Server and ensure it is running.
Create a MySQL Database and User

CREATE DATABASE jupyterhub; CREATE USER 'jupyterhub'@'%' IDENTIFIED BY 'jupyterhub'; GRANT ALL PRIVILEGES ON jupyterhub.* TO 'jupyterhub'@'%'; FLUSH PRIVILEGES;

Configure JupyterHub to Use MySQL: Update your jupyterhub_config.py file to include the database URL.

c.JupyterHub.db_url = "mysql+pymysql:__jupyterhub:jupyterhub@10.100.6.29:3306_jupyterhub"

Replaced 10.100.6.29 with your MySQL server's IP address.

Add database configuration in the jupyerhub-conf

jupyterhub_username = jupyterhub jupyterhub_password = jupyterhub jupyterhub_database_name = jupyterhub database_type = mysql

Info

Make sure not to use any special character in the Jupyterhub database password.

PostgreSQL Configuration

Install PostgreSQL: Run the following commands to install and configure PostgreSQL 12.

sudo dnf install -y https:__download.postgresql.org_pub_repos_yum_reporpms_EL-8-x86_64_pgdg-redhat-repo-latest.noarch.rpm sudo dnf -qy module disable postgresql sudo dnf install -y postgresql12-server sudo _usr_pgsql-12_bin_postgresql-12-setup initdb sudo systemctl enable postgresql-12 sudo systemctl start postgresql-12

Create a PostgreSQL Database and User: Access the PostgreSQL prompt as the postgres user.

sudo -u postgres psql

Execute the following commands:

CREATE DATABASE jupyterhub; CREATE USER jupyterhub WITH PASSWORD 'jupyterhub'; GRANT ALL PRIVILEGES ON DATABASE jupyterhub TO jupyterhub; CREATE ROLE jupyterhub; GRANT ALL PRIVILEGES ON DATABASE jupyterhub TO jupyterhub; \\q

Configure PostgreSQL for Remote Access:
1. Open the PostgreSQL configuration file.

vi _var_lib_pgsql_12_data_postgresql.conf

b. Uncomment the listen_addresses and port settings:

listen_addresses = '*' port = 5432

c. Update the pg_hba.conf file to allow remote access for the JupyterHub user:

vi _var_lib_pgsql_12_data_pg_hba.conf

d. Add the following line:

host jupyterhub jupyterhub 10.100.6.29_32 md5

Replace 10.100.6.29 with the IP address of the JupyterHub server.

Restart PostgreSQL.

sudo systemctl restart postgresql-12

Configure JupyterHub to Use PostgreSQL: Update your jupyterhub_config.py file to include the database URL.

c.JupyterHub.db_url = "postgresql+psycopg2:__jupyterhub:jupyterhub@10.100.6.29:5432_jupyterhub"

Replace 10.100.6.29 with your PostgreSQL server's IP address.

Add the database configuration in the jupyerhub-conf.

jupyterhub_username = jupyterhub jupyterhub_password = jupyterhub jupyterhub_database_name = jupyterhub database_type = postgresql

Info

Make sure not to use any special character in the Jupyterhub password.

Note

Dependencies for MySQL: Ensure pymysql is installed for MySQL support.
Dependencies for PostgreSQL: Install the required library with:

pip3 install psycopg2-binary

Test the database connection before starting JupyterHub to confirm proper configuration.

Last updated on Sep 2, 2025

Was this page helpful?