From f2e2517ea8e0b768945b454f85aad78bbc1f5aa7 Mon Sep 17 00:00:00 2001
From: Tim Yates <tim.yates@gmail.com>
Date: Thu, 27 Jun 2024 16:23:03 +0100
Subject: [PATCH] docs: Update troubleshooting to show db rebuild

This commit updates the troubleshooting page to show how to rebuild the database with `podman compose`.

I looked in to adding tabbed controls to the page to show the analog docker commands.
But it was an awful lot of code for a simple search and replace of `podman` for `docker`.

So I added a section to say you can just switch the word.
---
 docs/getting-started/troubleshooting/index.md | 52 ++++++++++++++++---
 1 file changed, 46 insertions(+), 6 deletions(-)

diff --git a/docs/getting-started/troubleshooting/index.md b/docs/getting-started/troubleshooting/index.md
index 371db00920..4801f228f3 100644
--- a/docs/getting-started/troubleshooting/index.md
+++ b/docs/getting-started/troubleshooting/index.md
@@ -4,7 +4,7 @@ parent: Getting Started
 nav_order: 3
 ---
 
-### Running the Server
+## Running the Server
 
 If you see the following error when running the server:
 
@@ -24,22 +24,62 @@ Then try running the server again. If necessary, you can also try restarting the
 ./gradlew --stop
 ```
 
-### Connecting to the Database
+## Connecting to the Database
 
-Your database is running in a Podman container. To connect to the database, use the following command:
+Your database is running in a container. To connect to the database, use the following command:
 
 ```shell
-podman exec -it 19a4d6a64439 psql -U postgres -d checkinsdb
+podman exec -it $(podman ps -q --filter name=checkinsdb) psql -U postgres -d checkinsdb
 ```
+(The subcommand `podman ps -q --filter name=checkinsdb` returns the ID of the container named `checkinsdb` which is running the database.)
 
-Where `19a4d6a64439` is the container ID. You can find the container ID by running the following command:
+## Finding the Container ID
+
+To find the ID of running containers, you can use the `ps` command as below:
 
 ```shell
 podman ps
 ```
 
-### Misc
+## Rebuilding the database
+
+Sometimes when switching between branches, you will start getting migration errors from Flyway that look similar to:
+
+```shell
+Migration checksum mismatch for migration version 108
+-> Applied to database : -976138718
+-> Resolved locally    : -377557062
+Either revert the changes to the migration, or run repair to update the schema history.
+```
+
+Or you may see errors like:
+
+```shell
+13:24:52.282 [main] ERROR io.micronaut.runtime.Micronaut - Error starting Micronaut server: Bean definition [javax.sql.DataSource] could not be loaded: Script R__Load_testing_data.sql failed
+--------------------------------------
+SQL State  : 23503
+Error Code : 0
+Message    : ERROR: update or delete on table "team" violates foreign key constraint "kudos_teamid_fkey" on table "kudos"
+```
+
+With errors about tables that should not exist.
+These are usually caused by one of the branches adding a migration that conflicts with the current branch that you are on.
+
+The easiest resolution is to rebuild your database from scratch.
+To do this, stop any container commands you have running in the terminal, and then you can run the following commands:
+
+```shell
+podman compose rm -f # This will stop and delete the database container
+podman compose up    # This will recreate and start the database container
+```
+
+## Misc
 
 _Note - If you are getting a error of
 `org.postgresql.util.PSQLException: FATAL: database "checkinsdb" does not exist`
 you will need to delete your local copy of postgres and only use the docker version_
+
+## I'm using Docker, not Podman!
+
+That's fine.
+All the commands above work with Docker as well, you just need to replace `podman` with `docker`.