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.

Note

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

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.

Stop Mathesar, remove old images

docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml down --rmi all

Set up new configuration

Warning

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
cp xMATHESAR_INSTALLATION_DIRx/.env xMATHESAR_INSTALLATION_DIRx/env.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 https://raw.githubusercontent.com/mathesar-foundation/mathesar/0.1.4/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:
```
DJANGO_DATABASE_URL=postgres://<username>:<password>@<host>:<port>/<database>
```
  You should edit the .env file to have the variables:
```
POSTGRES_USER=<username>
POSTGRES_PASSWORD=<password>
POSTGRES_HOST=<host>
POSTGRES_PORT=<port>
POSTGRES_DB=<database>
```
  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.
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.

Move your PostgreSQL directory

Bring down the services:

docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml down

Remove scaffold database data, copy your old PostgreSQL volume to the new location:

rm -r xMATHESAR_INSTALLATION_DIRx/msar/pgdata
cp -r xMATHESAR_PG_DIRx xMATHESAR_INSTALLATION_DIRx/msar/pgdata

Bring the services back up:

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

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.

Warning

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.

Go to your Mathesar installation directory.
```
cd xMATHESAR_INSTALLATION_DIRx
```
Note

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

Pull version 0.1.4 from the repository

git pull https://github.com/mathesar-foundation/mathesar.git
git checkout 0.1.4

Update Python dependencies
```
pip install -r requirements.txt
```
Next we will activate our virtual environment:
```
source ./mathesar-venv/bin/activate
```
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.
Add the environment variables to the shell before running Django commands
```
export $(sudo cat .env)
```
Run the latest Django migrations
```
python manage.py migrate
```
Install the frontend dependencies
```
npm ci --prefix mathesar_ui
```

Build the Mathesar frontend app

npm run --prefix mathesar_ui build --max_old_space_size=4096

Update Mathesar functions on the database:

python mathesar/install.py --skip-confirm >> /tmp/install.py.log

Restart the gunicorn server
```
systemctl restart gunicorn
```