confirm passwords match between .env and secrets.json (#597)

* confirm passwords match between .env and secrets.json
* add tip to test database connectivity
* move confirmation steps into tabs
* align headers with #593; add link to migrations page

Author: audreyality

docs/getting-started/server/database/ef/index.mdx

@@ -40,9 +40,9 @@ each.
 
 Our EF implementations currently support Postgres, MySQL, and SQLite3.
 
-## Setting Up EF Databases
+## Creating the database
 
-The workflow here is broadly the same as with the normal MSSQL implementation: set up the docker
+The workflow here is broadly the same as with the normal MSSQL implementation: set up the Docker
 container, configure user secrets, and run migrations against their relating databases in
 chronological order.
 
@@ -59,53 +59,6 @@ chronological order.
 You can have multiple databases configured and switch between them by changing the value of the
 `globalSettings:databaseProvider` user secret. You don’t have to delete your connection strings.
 
-### Database Setup
-
-<Tabs
-    groupId="provider"
-    values={providers}>
-<TabItem value="postgres">
-
-In the `dev` folder of your server repository, run
-
-```bash
-export POSTGRES_PASSWORD='example'
-docker compose --profile postgres up
-```
-
-:::note
-
-`POSTGRES_PASSWORD` only needs to be defined for database setup. It does not need to be defined to
-run the mysql profile.
-
-:::
-
-</TabItem>
-<TabItem value="mysql">
-
-In the `dev` folder of your server repository, run
-
-```bash
-export MYSQL_ROOT_PASSWORD='example'
-docker compose --profile mysql up
-```
-
-:::note
-
-`MYSQL_ROOT_PASSWORD` only needs to be defined for database setup. It does not need to be defined to
-run the mysql profile.
-
-:::
-
-</TabItem>
-<TabItem value="sqlite">
-
-Select a location for your database file. You can use the `dev` folder of your server repository.
-Git is configured to ignore `.db` files in this repository for this purpose.
-
-</TabItem>
-</Tabs>
-
 ### User secrets
 
 Add the following values to your API, Identity, and Admin user secrets.
@@ -138,7 +91,8 @@ sure you update the existing values instead of creating new ones
 <TabItem value="sqlite">
 
 Add the following values to your API, Identity, and Admin user secrets. Note, you must set the Data
-Source path. Use the file location selected in [Database Setup](#database-setup)
+Source path. Git is configured to ignore `.db` files in the server repository so that the sqlite
+database can be stored in `dev`. You can use any path with write permissions.
 
 ```json
 "globalSettings:databaseProvider": "sqlite",
@@ -155,6 +109,62 @@ that the changes take effect.
 
 :::
 
+### Updating the database
+
+<Tabs
+    groupId="provider"
+    values={providers}>
+<TabItem value="postgres">
+
+1. Confirm that `POSTGRES_PASSWORD` in `dev/.env` matches the password in `dev/secrets.json`.
+
+2. In the `dev` folder of your server repository, run
+
+```bash
+docker compose --profile postgres up
+```
+
+:::tip[Confirm your database connection!]
+
+If you run into connection errors, double check that your `.env` and `secrets.json` files have
+matching passwords. If they do, you may have initialized your database incorrectly. Delete the
+Docker storage volume and initialize the database from scratch.
+
+:::
+
+</TabItem>
+<TabItem value="mysql">
+
+1. Confirm that `MYSQL_ROOT_PASSWORD` in `dev/.env` matches the password in `dev/secrets.json`.
+
+2. In the `dev` folder of your server repository, run
+
+```bash
+docker compose --profile mysql up
+```
+
+:::tip[Confirm your database connection!]
+
+If you run into connection errors, double check that your `.env` and `secrets.json` files have
+matching passwords. If they do, you may have initialized your database incorrectly. Delete the
+Docker storage volume and initialize the database from scratch.
+
+:::
+
+</TabItem>
+<TabItem value="sqlite">
+
+:::tip[Confirm your database path!]
+
+The migrator creates the database file if it doesn't exist, but it does not create folders. If you
+get an error that the path doesn't exist, double check that the path exists and that the folder
+containing the sqlite database has write and/or create permissions.
+
+:::
+
+</TabItem>
+</Tabs>
+
 ### Migrations
 
 <Tabs
@@ -168,7 +178,7 @@ In the `dev` folder run the following to update the database to the latest migra
 pwsh migrate.ps1 -postgres
 ```
 
-The `-postgres` flag on `migrate.ps1` will run `dotnet ef` commands to perform the migrations.
+The `-postgres` flag on `migrate.ps1` runs `dotnet ef` commands to perform the migrations.
 
 </TabItem>
 <TabItem value="mysql">
@@ -179,7 +189,7 @@ In the `dev` folder run the following to update the database to the latest migra
 pwsh migrate.ps1 -mysql
 ```
 
-The `-mysql` flag on `migrate.ps1` will run `dotnet ef` commands to perform the migrations.
+The `-mysql` flag on `migrate.ps1` runs `dotnet ef` commands to perform the migrations.
 
 </TabItem>
 <TabItem value="sqlite">
@@ -190,7 +200,7 @@ In the `dev` folder run the following to update the database to the latest migra
 pwsh migrate.ps1 -sqlite
 ```
 
-The `-sqlite` flag on `migrate.ps1` will run `dotnet ef` commands to perform the migrations.
+The `-sqlite` flag on `migrate.ps1` runs `dotnet ef` commands to perform the migrations.
 
 :::note
 
@@ -208,7 +218,7 @@ You can also run migrations for all database providers at once using
 pwsh migrate.ps1 -all
 ```
 
-### Optional: Verify
+### Verifying changes
 
 If you would like to verify that everything worked correctly:
 
@@ -217,7 +227,7 @@ If you would like to verify that everything worked correctly:
   - Note: this requires a configured MSSQL database. You may also need to set up other EF providers
     for tests to pass.
 
-## Testing EF Changes
+## Testing changes
 
 In your `server/dev/secrets.json` file find or add this block of secrets in the root of the json
 structure: