Skip to content

Upgrade Mathesar to 0.1.4

The 0.1.4 release requires more upgrade steps than we hope to have for future releases! If you run into any trouble, we encourage you to open an issue or contact us for help.

For installations using Docker Compose

If you followed our Docker Compose installation instructions, then use these steps to upgrade your installation to 0.1.4.


Depending on your setup, you may need to run some commands with sudo.

  1. Find needed parts

    1. Find your .env and docker-compose.yml files. Run

      docker inspect mathesar_service 

      and look for the value of the "com.docker.compose.project.config_files" key in the resulting JSON to find the path to the docker-compose.yml file. The .env file should be in the same directory. If you have jq installed, you can run

      docker inspect mathesar_service \
        | jq '.[0].Config.Labels."com.docker.compose.project.config_files"'

      and get the path directly. The .env file should be in the same directory.

    2. Copy the path of the directory containing docker-compose.yml and .env into the box below. Do not include a trailing slash.

      Then press Enter to customize this guide with the configuration directory.

    3. If you are using a Docker container for your PostgreSQL database, Run

      docker volume inspect mathesar_postgresql_data

      and look for the "Mountpoint" in the resulting JSON.

    4. Copy the path of the directory into the box below. Do not include a trailing slash.

      Then press Enter to customize this guide with the PostgreSQL data directory.

  2. Stop Mathesar, remove old images

    docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml down --rmi all
  3. Set up new configuration


    MATHESAR_DATABASES has been deprecated as of v0.1.4 and will be removed entirely in future releases of Mathesar. If you end up deleting the variable from your .env file before starting up Mathesar after the upgrade, you can still add the connections manually through Mathesar’s UI.

    1. Back up the old configuration files:

      mv xMATHESAR_INSTALLATION_DIRx/docker-compose.yml xMATHESAR_INSTALLATION_DIRx/docker-compose.yml.backup

      (We’ll modify the old file, so we copy instead of moving it.)

    2. Download the new docker compose file:

      curl -sfL -o xMATHESAR_INSTALLATION_DIRx/docker-compose.yml
    3. Edit the xMATHESAR_INSTALLATION_DIRx/.env file to break the DJANGO_DATABASE_URL variable into its parts.

      This variable should have the form:


      You should edit the .env file to have the variables:


      If you don’t want to set those environment variables (e.g., if they’re otherwise used), you can instead edit the docker-compose.yml file directly to add those variables.

    4. Double-check the rest of the configuration:

      • You should have your SECRET_KEY variable defined.
      • If hosting on the internet, you should have a DOMAIN_NAME variable defined.
  4. Initialize new Mathesar installation

    docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml up -d

    This will pull new images, and start the Mathesar containers. Wait a few minutes, then run docker ps to verify that you have mathesar_service, mathesar-caddy-reverse-proxy-1, and mathesar_db running and that the service is healthy. The services should not be reporting errors. If you were not using Docker volumes for your Mathesar PostgreSQL data, you’re done, and you can login to Mathesar via your usual method. If you’re not sure, try to login to Mathesar. If you’re presented with a screen instructing you to create an Admin user, you likely need to proceed to the next step.

  5. Move your PostgreSQL directory

    1. Bring down the services:

      docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml down
    2. Remove scaffold database data, copy your old PostgreSQL volume to the new location:

      rm -r xMATHESAR_INSTALLATION_DIRx/msar/pgdata
    3. Bring the services back up:

      docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml up -d
  6. If things look good, then you can try to login at the usual address using your normal username and password, and you should see your data.

For installations done via our guided script

If you installed Mathesar with our (now deprecated) guided script, then you have a Docker Compose installation. See the Docker Compose upgrade steps.

For installations done from scratch

If you installed Mathesar from scratch, then use these steps to upgrade your installation to 0.1.4.


These steps have not yet been tested extensively. If you run into any trouble, we encourage you to open an issue or submit a PR proposing changes to this file.

  1. Go to your Mathesar installation directory.



    Your installation directory may be different from above if you used a different directory when installing Mathesar.

  2. Pull version 0.1.4 from the repository

    git pull
    git checkout 0.1.4
  3. Update Python dependencies

    pip install -r requirements.txt
  4. Next we will activate our virtual environment:

    source ./mathesar-venv/bin/activate
  5. Update your environment variables according to the the new configuration specification. In particular, you must put the connection info for the internal DB into new POSTGRES_* variables. The DJANGO_DATABASE_URL variable is no longer supported.

  6. Add the environment variables to the shell before running Django commands

    export $(sudo cat .env)
  7. Run the latest Django migrations

    python migrate
  8. Install the frontend dependencies

    npm ci --prefix mathesar_ui
  9. Build the Mathesar frontend app

    npm run --prefix mathesar_ui build --max_old_space_size=4096
  10. Update Mathesar functions on the database:

    python mathesar/ --skip-confirm >> /tmp/
  11. Restart the gunicorn server

    systemctl restart gunicorn