From cc3089a87e3e6850e8cdca759206db1634daa797 Mon Sep 17 00:00:00 2001
From: Brent Moran <brentmoran@gmail.com>
Date: Fri, 24 Jan 2025 23:58:02 +0800
Subject: [PATCH] clarify upgrade instructions

---
 docs/docs/releases/0.2.0.md | 65 +++++++++++++++++++++++++++++++++++--
 1 file changed, 62 insertions(+), 3 deletions(-)

diff --git a/docs/docs/releases/0.2.0.md b/docs/docs/releases/0.2.0.md
index aa37f18af9..89a00196e8 100644
--- a/docs/docs/releases/0.2.0.md
+++ b/docs/docs/releases/0.2.0.md
@@ -494,9 +494,47 @@ After this, you're ready to proceed with the upgrade.
 
 ### For installations using Docker Compose
 
+These instructions are for if you have a Docker compose installation (including one from the guided script).
 
+We will assume you're using our provided`docker-compose.yml` file. If you have heavily modified it, you may need to change some details of the provided commands.
 
-If you have a Docker compose installation (including one from the guided script),
+1. With your old version of Mathesar still running, log into your internal database server:
+
+    ```bash
+    # This assumes your installation DB role is mathesar
+    docker exec -it mathesar_db psql -U mathesar -d mathesar_django
+    ```
+
+1. At the `psql` prompt, then run:
+
+    ```sql
+    CREATE DATABASE mathesar_temp;
+    ```
+
+1. Log out with `CTRL+D`, and log back into the `mathesar_temp` database:
+
+    ```bash
+    docker exec -it mathesar_db psql -U mathesar -d mathesar_temp
+    ```
+
+1. Then run:
+
+    ```sql
+    DROP DATABASE mathesar_django;
+    CREATE DATABASE mathesar_django OWNER mathesar;  -- or whichever role you use to run Mathesar
+    ```
+
+1. Log out with `CTRL+D`, and log into your new `mathesar_django` database:
+
+    ```
+    docker exec -it mathesar_db psql -U mathesar -d mathesar_django
+    ```
+
+1. Then run:
+
+    ```sql
+    DROP DATABASE mathesar_temp;
+    ```
 
 1. Download the newest [docker-compose.yml](https://github.com/mathesar-foundation/mathesar/raw/{{mathesar_version}}/docker-compose.yml) file.
 
@@ -504,9 +542,9 @@ If you have a Docker compose installation (including one from the guided script)
     wget https://github.com/mathesar-foundation/mathesar/raw/{{mathesar_version}}/docker-compose.yml
     ```
 
-2. Modify it as per the [installation instructions](../administration/install-via-docker-compose.md), using values from your old `docker-compose.yml` file.
+1. Modify it as per the [installation instructions](../administration/install-via-docker-compose.md), using values from your old `docker-compose.yml` file.
 
-3. Run the command below:
+1. Run the command below:
 
     ```
     docker compose -f /etc/mathesar/docker-compose.yml up --pull always -d
@@ -514,6 +552,27 @@ If you have a Docker compose installation (including one from the guided script)
 
 ### For installations done from scratch
 
+For these instructions, you'll need to be familiar enough with your setup to log into your internal Mathesar Database.
+
+1. Log into your `mathesar_django` database, and run:
+
+    ```sql
+    CREATE DATABASE mathesar_temp;
+    ```
+
+1. Log out of the database, and log into the `mathesar_temp` database. Then run:
+
+    ```sql
+    DROP DATABASE mathesar_django;
+    CREATE DATABASE mathesar_django OWNER mathesar;  -- or whichever role you use to run Mathesar
+    ```
+
+1. Log out of the database, and log into your new `mathesar_django` database. Then run:
+
+    ```sql
+    DROP DATABASE mathesar_temp;
+    ```
+
 1. Go to your Mathesar installation directory
 
     ```