draft: fix(docs): revise database procedures

website/docs/installation/docker.md

@@ -45,7 +45,7 @@ This setup is recommended only if you are running TeslaMate **on your home netwo
          - POSTGRES_PASSWORD=password #insert your secure database password!
          - POSTGRES_DB=teslamate
        volumes:
-         - teslamate-db:/var/lib/postgresql/data
+         - teslamate-db-17:/var/lib/postgresql/data
 
      grafana:
        image: teslamate/grafana:latest
@@ -71,7 +71,7 @@ This setup is recommended only if you are running TeslaMate **on your home netwo
          - mosquitto-data:/mosquitto/data
 
    volumes:
-     teslamate-db:
+     teslamate-db-17:
      teslamate-grafana-data:
      mosquitto-conf:
      mosquitto-data:

website/docs/maintenance/backup_restore.md

@@ -8,18 +8,18 @@ If you are using `docker-compose`, you are using Docker Compose v1, which has be
 
 ## Backup
 
-Create backup file `teslamate.bck`:
+Create backup file:
 
 ```bash
-docker compose exec -T database pg_dump -U teslamate teslamate > ./teslamate.bck
+docker compose exec -T database pg_dump -U teslamate teslamate > teslamate_database_$(date +%F_%H-%M-%S).sql
 ```
 
 :::note
 `-T` is important if you add this line a crontab or the backup will not work because docker will generate this error `the input device is not a TTY`
 :::
 
 :::note
-Be absolutely certain to move the `teslamate.bck` file to another safe location, as you may lose that backup file if you use a docker-compose GUI to upgrade your teslamate configuration. Some GUIs delete the folder that holds the `docker-compose.yml` when updating.
+Be absolutely certain to move the backup file to another safe location, as you may lose that backup file if you use a docker-compose GUI to upgrade your teslamate configuration. Some GUIs delete the folder that holds the `docker-compose.yml` when updating.
 :::
 
 :::note
@@ -36,21 +36,36 @@ If you changed `TM_DB_USER` in the .env file from one of the advanced guides, ma
 Replace the default `teslamate` value below with the value defined in the .env file if you have one (TM_DB_USER and TM_DB_NAME)
 :::
 
-```bash
-# Stop the teslamate container to avoid write conflicts
-docker compose stop teslamate
-
-# Drop existing data and reinitialize (Don't forget to replace first teslamate if using different TM_DB_USER)
-docker compose exec -T database psql -U teslamate teslamate << .
-DROP SCHEMA public CASCADE;
-CREATE SCHEMA public;
-CREATE EXTENSION cube WITH SCHEMA public;
-CREATE EXTENSION earthdistance WITH SCHEMA public;
-.
-
-# Restore
-docker compose exec -T database psql -U teslamate -d teslamate < teslamate.bck
-
-# Restart the teslamate container
-docker compose start teslamate
-```
+1. Stop the teslamate container to avoid write conflicts
+
+   ```bash
+   docker compose stop teslamate
+   ```
+
+2. Drop existing data and reinitialize (Don't forget to replace first teslamate if using different TM_DB_USER)
+
+   ```bash
+   docker compose exec -T database psql -U teslamate teslamate << .
+   DROP SCHEMA public CASCADE;
+   CREATE SCHEMA public;
+   CREATE EXTENSION cube WITH SCHEMA public;
+   CREATE EXTENSION earthdistance WITH SCHEMA public;
+   .
+   ```
+
+3. Restore
+
+   Use the same filename that was used in the backup step.
+
+   Replace `teslamate_database_2025-05-07_07-33-48.sql` with the actual filename generated during the backup step.
+
+   ```bash
+   DATABASE="teslamate_database_2025-05-07_07-33-48.sql"
+   docker compose exec -T database psql -U teslamate -d teslamate < "$DATABASE"
+   ```
+
+4. Restart the teslamate container
+
+   ```bash
+   docker compose start teslamate
+   ```

website/docs/maintenance/upgrading_postgres.md

@@ -3,28 +3,117 @@ title: Upgrading PostgreSQL to a new major version
 sidebar_label: Upgrading PostgreSQL
 ---
 
-1. Create a [backup](backup_restore.md)
-2. Stop all TeslaMate containers
+In these instructions it is assumed you are upgrading from postgresql 16 to postgresql 17. Please update
+references to 16 to your start version and 17 to your desired version.
+
+These instructions also assume you have the standard `docker-compose.yml` file. If this is not the case
+you might need to make adjustments. For example, older installed might call the container "db" not "database".
+
+:::note
+If you are using `docker-compose`, you are using Docker Compose v1, which has been deprecated. Docker Compose commands refer to Docker Compose v2. Consider upgrading your docker setup, see [Migrate to Compose V2](https://docs.docker.com/compose/migrate/)
+:::
+
+## Upgrade
+
+1. Create a backup:
+
+   ```bash
+   docker compose exec -T database pg_dump -U teslamate teslamate > teslamate_database_$(date +%F_%H-%M-%S).sql
+   ```
+
+2. _Check to make sure there are no obvious errors in this backup file._ There should not be any errors appearing
+   on screen. The file should be more than 0 bytes long. Do not proceed if there is any doubt.
+
+3. Stop all TeslaMate containers
 
    ```bash
    docker compose down
    ```
 
-3. Delete the database volume. **Be careful**, this will delete all your previously recorded data! Make sure that your backup can be restored before you start.
+4. Make a copy of your current `docker-compose.yml`
 
    ```bash
-   docker volume rm "$(basename "$PWD")_teslamate-db"
+   cp docker-compose.yml docker-compose-16.yml
    ```
 
-4. Change the postgres version in docker-compose.yml and start the container
+5. Update the source to point to a new location that doesn't exist already and update the postgres version.
 
-   ```yml {2}
-   database:
-     image: postgres:xx
+   ```yaml
+   services:
+      [...]
+      database:
+        image: postgres:17
+        [...]
+        volumes:
+          - teslamate-db-17:/var/lib/postgresql/data
+   [...]
+   volumes:
+     teslamate-db-17:
    ```
 
+   Here we updated the image to `postgres:17` and the volume to `teslamate-db-17`.
+
+   :::note
+   There are THREE changes. All are very important.
+   :::
+
+   :::note
+   Do not delete the old volume until you are sure that the database restore is
+   working correctly and has all your data.
+   :::
+
+6. Start the container.
+
    ```bash
    docker compose up -d database
    ```
 
-5. [Restore](backup_restore.md) the backup
+7. Restore the backup.
+
+   :::note
+   database should be empty. If database contains data, then check you updated the volume correctly in step 5.
+   :::
+
+   Replace `teslamate_database_2025-05-07_07-33-48.sql` with the actual filename generated during the backup step.
+
+   ```bash
+   docker compose exec -T database psql -U teslamate teslamate << .
+   CREATE SCHEMA public;
+   CREATE EXTENSION cube WITH SCHEMA public;
+   CREATE EXTENSION earthdistance WITH SCHEMA public;
+   .
+   DATABASE="teslamate_database_2025-05-07_07-33-48.sql"
+   docker compose exec -T database psql -U teslamate -d teslamate < "$DATABASE"
+   ```
+
+   There should not be any errors.
+
+8. Start the container.
+
+   ```bash
+   docker compose up -d teslamate
+   ```
+
+9. Make sure everything is working, and all the data is intact.
+
+## Roll back on error
+
+If you cannot restore the backup for any reason, you might have to roll back to your previous version.
+
+1. Stop everything
+
+   ```bash
+   docker compose stop
+   ```
+
+2. Restore the values in `docker-compose.yml` that you changed in step 5 and step 6.
+
+   ```bash
+   cp docker-compose-16.yml docker-compose.yml
+   ```
+
+3. Start everything
+
+   ```bash
+   docker compose up -d
+   ```