Adding New Database Drivers in Docker
Superset requires a Python database driver to be installed for each additional type of database you want to connect to.
In this example, we'll walk through how to install the MySQL connector library. The connector library installation process is the same for all additional libraries.
1. Determine the driver you need
Consult the list of database drivers and find the PyPI package needed to connect to your database. In this example, we're connecting to a MySQL database, so we'll need the
mysqlclient connector library.
2. Install the driver in the container
We need to get the
mysqlclient library installed into the Superset docker container (it doesn't matter if it's installed on the host machine). We could enter the running container with
docker exec -it <container_name> bash and run
pip install mysqlclient there, but that wouldn't persist permanently.
To address this, the Superset
docker compose deployment uses the convention of a
requirements-local.txt file. All packages listed in this file will be installed into the container from PyPI at runtime. This file will be ignored by Git for the purposes of local development.
Create the file
requirements-local.txt in a subdirectory called
docker that exists in the directory with your
# Run from the repo root:
Add the driver identified in step above. You can use a text editor or do it from the command line like:
echo "mysqlclient" >> ./docker/requirements-local.txt
If you are running a stock (non-customized) Superset image, you are done. Launch Superset with
docker compose -f docker-compose-non-dev.yml up and the driver should be present.
You can check its presence by entering the running container with
docker exec -it <container_name> bash and running
pip freeze. The PyPI package should be present in the printed list.
If you're running a customized docker image, rebuild your local image with the new driver baked in:
docker compose build --force-rm
After the rebuild of the Docker images is complete, relaunch Superset by running
docker compose up.
3. Connect to MySQL
Now that you've got a MySQL driver installed in your container, you should be able to connect to your database via the Superset web UI.
As an admin user, go to Settings -> Data: Database Connections and click the +DATABASE button. From there, follow the steps on the Using Database Connection UI page.
Consult the page for your specific database type in the Superset documentation to determine the connection string and any other parameters you need to input. For instance, on the MySQL page, we see that the connection string to a local MySQL database differs depending on whether the setup is running on Linux or Mac.
Click the “Test Connection” button, which should result in a popup message saying, "Connection looks good!".
If the test fails, review your docker logs for error messages. Superset uses SQLAlchemy to connect to databases; to troubleshoot the connection string for your database, you might start Python in the Superset application container or host environment and try to connect directly to the desired database and fetch data. This eliminates Superset for the purposes of isolating the problem.
Repeat this process for each different type of database you want Superset to be able to connect to.