fix(docs): revise database procedures

The database instructions, while technically correct, are not idiot
proof. There are so many different ways you can stuff up and end up
losing all your data.

For example, the current docs say:

docker compose exec -T database pg_dump -U teslamate teslamate > ./teslamate.bck

If anything goes wrong with this command, it might overwrite any
potentially good backup with a 0 byte file. And some of the users won't notice
until after they have deleted the current database and tried to restore. By
this stage it is too late to recover.

These instructions attempt to make the process more resilient by not
deleting the current data until after it is confirmed that the restore
is good.

The instructions also use a unique filename for every backup. So you are
not overwriting the same backup file every time.

Author: brianmay

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
+   ```