Updates to Postgres instructions and PR sectioning

Author: zackkrida

docs/docs/releases/0.2.1.md

@@ -11,30 +11,47 @@ _This page provides a comprehensive list of all changes since version [0.2.0](./
 <!-- ## Breaking changes -->
 <!-- (This section lists any breaking changes to publicly exposed and documented machine interfaces to Mathesar such as the API or DB functions) -->
 
-
 ## Improvements
 <!-- (Each feature within this section should have its own level-three heading) -->
 
 ### Database nicknames
 
+[TODO]
+
 [#4262](https://github.com/mathesar-foundation/mathesar/pull/4262 "Frontend support for databases nicknames")
 [#4244](https://github.com/mathesar-foundation/mathesar/pull/4244 "Backend support for database nicknames")
 [#4261](https://github.com/mathesar-foundation/mathesar/pull/4261 "Allow DB name/host/port to be updated")
 
 ### In-app feedback
 
+[TODO]
+
 [#4241](https://github.com/mathesar-foundation/mathesar/pull/4241 "Move feedback to app header, add mailing list link to home page")
 
 ### Column widths are persisted
 
+[TODO]
+
 [#4257](https://github.com/mathesar-foundation/mathesar/pull/4257 "Persist column width")
 [#4248](https://github.com/mathesar-foundation/mathesar/pull/4248 "Backend support to persist customized column widths")
 
+### Drop schema contents when deleting
+
+[TODO]
+
+
+It's new behavior for Mathesar.
+It's novel in the field, AFAIK. No other product (that I'm aware of) has the same combination of safety and convenience provided by this.
+It warrants a bit more description, since the difference between this and CASCADE may surprise or interest a knowledgeable user, and may make some more confident when letting their users use Mathesar to access the DB.
+
+
+[#4251](https://github.com/mathesar-foundation/mathesar/pull/4251 "Drop schema contents when deleting")
+
 ### Docker Compose installs are updated to Postgres 17
 
 !!! info "For existing users"
 
-    Existing users who would like to update to Postgres 17 should use our new docker compose file and run `cp -r msar msar.backup` prior to upgrading Postgres in the event of issues.
+    See the [upgrading Postgres](#upgrading-postgres) section for instructions on safely upgrading your Postgres version.
 
   New installs of Mathesar using our recommended [Docker Compose](../administration/install-via-docker-compose.md) installation will now use Postgres 17. Prior to 1.2.1 Mathesar installs configured via our docker compose file used version 13.
 
@@ -46,11 +63,13 @@ _This page provides a comprehensive list of all changes since version [0.2.0](./
 [#4252](https://github.com/mathesar-foundation/mathesar/pull/4252 "Partially support passwordless Database Roles")
 [#4255](https://github.com/mathesar-foundation/mathesar/pull/4255 "Copy suggestions for passwordless roles in Mathesar")
 
-## Bug fixes
+### Additional features
 
-- Drop schema contents when deleting [#4251](https://github.com/mathesar-foundation/mathesar/pull/4251 "Drop schema contents when deleting")
 - Backend changes to support CSV file imports with an id column [#4269](https://github.com/mathesar-foundation/mathesar/pull/4269 "Backend changes to support CSV file imports with an id column")
 - Allow patching records in tables with non-integer primary keys [#4246](https://github.com/mathesar-foundation/mathesar/pull/4246 "Allow patching records in tables with non-integer primary keys")
+
+## Bug fixes
+
 - Use binary reads and writes whenever possible [#4254](https://github.com/mathesar-foundation/mathesar/pull/4254 "Use binary reads and writes whenever possible") [#4272](https://github.com/mathesar-foundation/mathesar/pull/4272 "Revert read mode in mathesar_ui")
 - Fix bug in RichText parsing [#4209](https://github.com/mathesar-foundation/mathesar/pull/4209 "Fix bug in RichText parsing")
 - introduce the showLoadingSpinner prop in TableView.svelte [#4222](https://github.com/mathesar-foundation/mathesar/pull/4222 "introduce the showLoadingSpinner prop in TableView.svelte")
@@ -75,6 +94,45 @@ The following PRs represent work done to reduce technical debt, update dependenc
 [#4146](https://github.com/mathesar-foundation/mathesar/pull/4146 "Bump django from 4.2.17 to 4.2.18")
 [#4253](https://github.com/mathesar-foundation/mathesar/pull/4253 "Remove unused demo telemetry code")
 
+## Upgrading to Postgres 17 {:#upgrading-postgres}
+
+Follow these steps to upgrade Postgres to the latest version. Note that this upgrade is only necessary for existing Mathesar users who would like to switch to the latest version of Postgres.
+
+1. Navigate to your installation directory.
+2. Shut down Mathesar with `docker compose down`.
+3. Create a backup of your installation with `cp -r msar msar.backup`. Keep the `msar.backup` folder in a safe location.
+4. Back up your existing Docker Compose configuration with `cp docker-compose.yml docker-compose.yml.backup`.
+5. Download the latest Docker Compose file with:
+   ```
+   wget https://github.com/mathesar-foundation/mathesar/raw/0.2.1/docker-compose.yml
+   ```
+6. Edit the new `docker-compose.yml` file to restore any personal variables or custom configurations from your backup.
+7. Restart Mathesar with the latest images:
+   ```
+   docker compose up --pull always -d
+   ```
+8. Once you've confirmed everything is working correctly, you can delete the backup files.
+
+### Troubleshooting & rolling back
+
+If you encounter issues or the upgrade fails:
+
+1. Restore the previous `docker-compose.yml`:
+   ```
+   mv docker-compose.yml.backup docker-compose.yml
+   ```
+2. Restore your Mathesar installation:
+   ```
+   rm -rf msar && mv msar.backup msar
+   ```
+3. Start Mathesar again:
+   ```
+   docker compose up -d
+   ```
+
+For additional support, reach out to the Mathesar team via a [GitHub issue](https://github.com/mathesar-foundation/mathesar/issues/new/choose) or the [Matrix chat](https://wiki.mathesar.org/en/community/matrix).
+
+
 ## Upgrading to 0.2.1  {:#upgrading}
 
 ### For installations using Docker Compose