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 docker-compose.yml or docker-compose-non-dev.yml file.

# Run from the repo root:
touch ./docker/requirements-local.txt

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!".

4. Troubleshooting

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.